diff --git a/api-reference/monitors.openapi.en.json b/api-reference/monitors.openapi.en.json index e7a18195..14b0e828 100644 --- a/api-reference/monitors.openapi.en.json +++ b/api-reference/monitors.openapi.en.json @@ -205,7 +205,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 Manage** (`monit`) |\n\n## Usage\n\n- `type_ident` must be one of: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `victorialogs`.\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. Don't put secrets in request fields.\n\n## Credential fields\n\nThe `info` / `create` / `update` responses include the `payload` configuration exactly as stored — `password`, `basic_auth_password`, `api_key`, `service_token`, `access_key_secret`, `tls_key`, `tls_key_pwd` and similar fields are returned as-is, not masked. Treat these responses as sensitive: avoid logging them or forwarding them to third parties.", + "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`.\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. Don't put secrets in request fields.\n\n## Credential fields\n\nThe `info` / `create` / `update` responses include the `payload` configuration exactly as stored — `password`, `basic_auth_password`, `api_key`, `service_token`, `access_key_secret`, `tls_key`, `tls_key_pwd` and similar fields are returned as-is, not masked. The one exception is `payload.tencent_cls.secret_key`, which is always masked to an empty string (an `${env:...}` reference is returned verbatim). Treat these responses as sensitive: avoid logging them or forwarding them to third parties.", "href": "/en/api-reference/monitors/data-sources/monit-datasource-write-create", "metadata": { "sidebarTitle": "Create datasource" @@ -291,7 +291,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 Manage** (`monit`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Don't put secrets in request fields.\n\n## Credential fields\n\nThe `info` / `create` / `update` responses include the `payload` configuration exactly as stored — `password`, `basic_auth_password`, `api_key`, `service_token`, `access_key_secret`, `tls_key`, `tls_key_pwd` and similar fields are returned as-is, not masked. Treat these responses as sensitive: avoid logging them or forwarding them to third parties.", + "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.\n\n## Credential fields\n\nThe `info` / `create` / `update` responses include the `payload` configuration exactly as stored — `password`, `basic_auth_password`, `api_key`, `service_token`, `access_key_secret`, `tls_key`, `tls_key_pwd` and similar fields are returned as-is, not masked. The one exception is `payload.tencent_cls.secret_key`, which is always masked to an empty string (an `${env:...}` reference is returned verbatim). Treat these responses as sensitive: avoid logging them or forwarding them to third parties.", "href": "/en/api-reference/monitors/data-sources/monit-datasource-write-update", "metadata": { "sidebarTitle": "Update datasource" @@ -602,7 +602,7 @@ "post": { "operationId": "monit-datasource-write-delete", "summary": "Delete datasource", - "description": "Delete a data source by ID. Alert rules referencing this datasource must be updated or deleted first.", + "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.", "tags": [ "Monitors/Data sources" ], @@ -778,10 +778,30 @@ }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": [ - "project-a", - "project-b" - ] + "data": { + "projects": [ + { + "projectName": "project-a", + "description": "Production logs", + "status": "Normal", + "owner": "", + "region": "cn-shanghai", + "createTime": "1710000000", + "lastModifyTime": "1712000000" + }, + { + "projectName": "project-b", + "description": "Staging logs", + "status": "Normal", + "owner": "", + "region": "cn-shanghai", + "createTime": "1710000000", + "lastModifyTime": "1712000000" + } + ], + "count": 2, + "total": 2 + } } } } @@ -817,83 +837,6 @@ } } }, - "/monit/rule/status": { - "post": { - "operationId": "monit-rule-write-status", - "summary": "Get rule trigger status under folder", - "description": "Return the rule trigger summary for all rules under a folder node and its descendants.", - "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- Set `folder_id` to `0` to get summary across all folders.\n- If the folder contains too many rules, computation is skipped for self-protection.", - "href": "/en/api-reference/monitors/alert-rules/monit-rule-write-status", - "metadata": { - "sidebarTitle": "Get rule trigger status under folder" - } - }, - "responses": { - "200": { - "description": "Success", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/RuleStatusResponse" - } - } - } - ] - }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": [ - { - "folder_id": 100, - "folder_name": "Production", - "rule_total": 10, - "triggered_rule_count": 2 - } - ] - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/Unauthorized" - }, - "429": { - "$ref": "#/components/responses/TooManyRequests" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RuleFolderIDRequest" - }, - "example": { - "folder_id": 100 - } - } - } - } - } - }, "/monit/rule/export": { "post": { "operationId": "monit-rule-read-export", @@ -939,7 +882,7 @@ "prometheus*" ], "enabled": true, - "cron_pattern": "* * * * *" + "cron_pattern": "0 * * * * *" } ] } @@ -1061,7 +1004,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## Credential fields\n\nThe `info` / `create` / `update` responses include the `payload` configuration exactly as stored — `password`, `basic_auth_password`, `api_key`, `service_token`, `access_key_secret`, `tls_key`, `tls_key_pwd` and similar fields are returned as-is, not masked. Treat these responses as sensitive: avoid logging them or forwarding them to third parties.", + "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## Credential fields\n\nThe `info` / `create` / `update` responses include the `payload` configuration exactly as stored — `password`, `basic_auth_password`, `api_key`, `service_token`, `access_key_secret`, `tls_key`, `tls_key_pwd` and similar fields are returned as-is, not masked. The one exception is `payload.tencent_cls.secret_key`, which is always masked to an empty string (an `${env:...}` reference is returned verbatim). Treat these responses as sensitive: avoid logging them or forwarding them to third parties.", "href": "/en/api-reference/monitors/data-sources/monit-datasource-read-info", "metadata": { "sidebarTitle": "Get datasource detail" @@ -1266,7 +1209,7 @@ "prometheus*" ], "enabled": true, - "cron_pattern": "* * * * *", + "cron_pattern": "0 * * * * *", "channel_ids": [ 20001 ] @@ -1523,7 +1466,7 @@ "prometheus*" ], "enabled": true, - "cron_pattern": "* * * * *", + "cron_pattern": "0 * * * * *", "rule_configs": { "queries": [ { @@ -1614,7 +1557,7 @@ "prometheus*" ], "enabled": true, - "cron_pattern": "* * * * *", + "cron_pattern": "0 * * * * *", "rule_configs": { "queries": [ { @@ -1706,7 +1649,7 @@ "prometheus*" ], "enabled": true, - "cron_pattern": "* * * * *", + "cron_pattern": "0 * * * * *", "channel_ids": [ 20001 ], @@ -2006,7 +1949,9 @@ "ds_type": "prometheus", "enabled": true, "triggered": true, - "created_at": 1710000000 + "created_at": 1710000000, + "active_alert_count": 2, + "runtime_state": "normal" } ] } @@ -2249,7 +2194,8 @@ "note": "Production Prometheus", "address": "http://prometheus.example.com:9090", "edge_cluster_name": "default", - "updated_at": 1712000000 + "updated_at": 1712000000, + "payload": null } ] } @@ -2563,92 +2509,6 @@ } } }, - "/monit/query/rows": { - "post": { - "operationId": "monit-read-query-rows", - "summary": "Query data source rows", - "description": "Deprecated. Run a synchronous ad-hoc query and return the historical flattened rows shape. Existing consumers should migrate to `/monit/query/data`, which preserves frames, records, and samples without forcing every result into legacy rows.", - "deprecated": true, - "tags": [ - "Monitors/Diagnostics" - ], - "x-mint": { - "content": "## Deprecated\n\nUse [`POST /monit/query/data`](/en/api-reference/monitors/diagnostics/monit-read-query-data) for all new integrations. This endpoint remains available only during the migration of existing UI and AI SRE consumers.\n\n## 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\n## Usage\n\n- The request is forwarded to `monit-edge` over WebSocket; the data source named by `ds_type` + `ds_name` must already exist under the calling account.\n- `account_id` in the body is optional. When supplied it must equal the authenticated account; mismatched values are rejected.\n- Validation failures use the standard error envelope. When `monit-edge` rejects a query, its `{\"error\": {\"code\": ..., \"message\": ...}}` body is preserved and the HTTP status matches the edge error code; an invalid or absent code becomes HTTP 500. Check both the status and the error body.\n- monit-edge enforces a row cap; large result sets come back as `error.message = \"too many rows\"`. Narrow the time range or aggregate at the source.\n- `args` is a polymorphic `string→string` map that is forwarded verbatim. Semantics depend on `ds_type` (SLS requires `sls.project` + `sls.logstore`; Loki / VictoriaLogs raw mode requires a time range via `*.start`/`*.end` or `*.timespan.value`/`*.timespan.unit`; Prometheus and SQL sources ignore it). See the monit-webapi query-api docs for the per-source key list.", - "href": "/en/api-reference/monitors/diagnostics/monit-read-query-rows", - "metadata": { - "sidebarTitle": "Query data source rows" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/QueryRowsRequest" - }, - "example": { - "account_id": 10001, - "ds_type": "prometheus", - "ds_name": "prod-prom", - "expr": "up", - "delay_seconds": 30 - } - } - } - }, - "responses": { - "200": { - "description": "Success", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/QueryRowsResponse" - } - } - } - ] - }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": [ - { - "fields": { - "__name__": "up", - "instance": "10.0.0.1:9100", - "job": "node" - }, - "values": { - "__value__": 1 - } - } - ] - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/Unauthorized" - }, - "429": { - "$ref": "#/components/responses/TooManyRequests" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - } - } - }, "/monit/query/diagnose": { "post": { "operationId": "monit-read-query-diagnose", @@ -2658,7 +2518,7 @@ "Monitors/Diagnostics" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **600 requests/minute**; **10 requests/second** per account |\n| Permissions | Any valid `app_key` (read-only; not gated by a specific permission class) |\n\n## Usage\n\n- This is a diagnostic / RCA endpoint, not a raw data query — pair it with `/monit/query/rows` when you need detailed rows.\n- Only three `ds_type` and `operation` pairs are supported: `loki` / `victorialogs` → `log_patterns`, and `prometheus` → `metric_trends`. Every other datasource is rejected, even when `operation` is explicit.\n- `methods` selects the analyses to run; when omitted, `log_patterns` defaults to `pattern_snapshot + pattern_compare(previous_window)` and `metric_trends` defaults to `single_window_shape + window_compare(previous_window)`.\n- `time_range` is in Unix seconds; missing or invalid values default to the last 15 minutes; a window wider than 6 hours is rejected.\n- The request is forwarded over WebSocket to `monit-edge`. Long-running: the request may take up to ~30 s on the edge side plus webapi overhead. Set client timeouts to **at least 35 s**.\n- `options.*` are upper-bounded by edge (`max_logs_scanned` ≤ 50 000, `max_patterns` ≤ 50, `examples_per_pattern` ≤ 3, `step_seconds` ∈ [15, 300], `max_series` ≤ 200, `topk` ≤ 50, `timeout_seconds` ≤ 30).\n- Two error layers as with `/monit/query/rows`: edge-level execution errors come back as HTTP 200 with an `error` object in the body — check both layers.\n- Log examples are basic-redacted before being returned; expect `warnings: [\"examples redacted\"]`. Do not treat them as raw logs.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **600 requests/minute**; **10 requests/second** per account |\n| Permissions | Any valid `app_key` (read-only; not gated by a specific permission class) |\n\n## Usage\n\n- This is a diagnostic / RCA endpoint, not a raw data query — pair it with `/monit/query/data` when you need the underlying data.\n- Only three `ds_type` and `operation` pairs are supported: `loki` / `victorialogs` → `log_patterns`, and `prometheus` → `metric_trends`. Every other datasource is rejected, even when `operation` is explicit.\n- `methods` selects the analyses to run; when omitted, `log_patterns` defaults to `pattern_snapshot + pattern_compare(previous_window)` and `metric_trends` defaults to `single_window_shape + window_compare(previous_window)`.\n- `time_range` is in Unix seconds; missing or invalid values default to the last 15 minutes; a window wider than 6 hours is rejected.\n- The request is forwarded over WebSocket to `monit-edge`. Long-running: the request may take up to ~30 s on the edge side plus webapi overhead. Set client timeouts to **at least 35 s**.\n- `options.*` are upper-bounded by edge (`max_logs_scanned` ≤ 50 000, `max_patterns` ≤ 50, `examples_per_pattern` ≤ 3, `step_seconds` ∈ [15, 300], `max_series` ≤ 200, `topk` ≤ 50, `timeout_seconds` ≤ 30).\n- The success body is a raw `{\"data\": ...}` object WITHOUT the usual `request_id` wrapper field (raw passthrough from the edge).\n- Two error layers: request-level failures return a non-200 status with the standard `error` envelope, while edge-level execution errors come back as HTTP 200 with an `error` object in the body — check both.\n- Log examples are basic-redacted before being returned; expect `warnings: [\"examples redacted\"]`. Do not treat them as raw logs.", "href": "/en/api-reference/monitors/diagnostics/monit-read-query-diagnose", "metadata": { "sidebarTitle": "Diagnose data source" @@ -2708,22 +2568,17 @@ "content": { "application/json": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/DiagnoseResponse" - } - } + "type": "object", + "required": [ + "data" + ], + "properties": { + "data": { + "$ref": "#/components/schemas/DiagnoseResponse" } - ] + } }, "example": { - "request_id": "01JZPD1PCDTN5F4YVBD2GS6S9A", "data": { "schema_version": "2", "operation": "log_patterns", @@ -3150,85 +3005,6 @@ } } }, - "/monit/preview/sync": { - "post": { - "operationId": "monit-preview-sync", - "summary": "Preview datasource query", - "description": "Execute a synchronous datasource query and return the raw result. Used to preview alert rule expressions before saving.", - "tags": [ - "Monitors/Monitor utilities" - ], - "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- `ds_type` must match the datasource type (e.g. `prometheus`, `loki`).\n- `ds_name` is the display name of the datasource as configured in the account.\n- `delay_seconds` shifts the query window backward by the specified number of seconds, useful for accommodating data ingestion latency.\n- The response body is the raw JSON returned by the datasource — its schema varies by datasource type.", - "href": "/en/api-reference/monitors/monitor-utilities/monit-preview-sync", - "metadata": { - "sidebarTitle": "Preview datasource query" - } - }, - "responses": { - "200": { - "description": "Success", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/PreviewSyncResponse" - } - } - } - ] - }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": { - "status": "success", - "data": { - "resultType": "vector", - "result": [] - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/Unauthorized" - }, - "429": { - "$ref": "#/components/responses/TooManyRequests" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PreviewSyncRequest" - }, - "example": { - "ds_type": "prometheus", - "ds_name": "Prometheus Prod", - "expr": "rate(http_requests_total[5m])", - "delay_seconds": 0 - } - } - } - } - } - }, "/monit/servicemap/status": { "post": { "operationId": "monit-servicemap-read-status", @@ -4111,7 +3887,7 @@ "items": { "type": "string" }, - "description": "Data source name patterns (supports wildcards)." + "description": "Data source name patterns (supports wildcards). At least one of `ds_list` / `ds_ids` must be non-empty; the two are merged to decide which datasources the rule monitors." }, "ds_ids": { "type": "array", @@ -4251,7 +4027,14 @@ "format": "int64", "description": "Last update time as a Unix timestamp in seconds. Generated by the server; do not provide." } - } + }, + "required": [ + "folder_id", + "name", + "ds_type", + "cron_pattern", + "rule_configs" + ] }, "AlertRuleAudit": { "type": "object", @@ -4283,7 +4066,11 @@ }, "action": { "type": "string", - "description": "Action performed, e.g. `create`, `update`." + "description": "Action performed: `create` = rule created; `update` = rule updated (covers full updates, field-batch updates, imports and moves).", + "enum": [ + "create", + "update" + ] }, "content": { "type": "string", @@ -4324,7 +4111,10 @@ "updater_name", "created_at", "updated_at", - "triggered" + "triggered", + "labels", + "timezone", + "active_alert_count" ], "properties": { "id": { @@ -4367,7 +4157,7 @@ }, "cron_pattern": { "type": "string", - "description": "5-field cron schedule, e.g. `* * * * *`. Must not start with `CRON_TZ=` or `TZ=`; use the `timezone` field instead." + "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." }, "timezone": { "type": "string", @@ -4409,6 +4199,25 @@ "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": { + "type": "string", + "enum": [ + "disabled", + "offline", + "abnormal", + "stale", + "no_datasource", + "config_pending", + "waiting", + "normal" + ], + "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. |" } } }, @@ -4939,6 +4748,10 @@ }, "victorialogs": { "$ref": "#/components/schemas/DSVictoriaLogsConfig" + }, + "tencent_cls": { + "$ref": "#/components/schemas/DSTencentCLSConfig", + "description": "Tencent CLS credentials. Required when `type_ident` is `tencent_cls`." } } }, @@ -5184,7 +4997,8 @@ "note", "address", "edge_cluster_name", - "updated_at" + "updated_at", + "payload" ], "properties": { "id": { @@ -5199,7 +5013,7 @@ }, "type_ident": { "type": "string", - "description": "Datasource type identifier. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `victorialogs`." + "description": "Datasource type identifier. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`." }, "name": { "type": "string", @@ -5218,7 +5032,15 @@ "description": "Connection address. For Prometheus/Loki/VictoriaLogs: HTTP URL. For MySQL/Oracle/Postgres/ClickHouse: `host:port`. For SLS: endpoint without http/https prefix." }, "payload": { - "$ref": "#/components/schemas/DSPayload" + "anyOf": [ + { + "$ref": "#/components/schemas/DSPayload" + }, + { + "type": "null" + } + ], + "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." }, "edge_cluster_name": { "type": "string", @@ -5237,13 +5059,13 @@ "properties": { "type": { "type": "string", - "description": "Filter by datasource type identifier. Omit to return all types. Allowed values: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `victorialogs`." + "description": "Filter by datasource type identifier. Omit to return all types. Allowed values: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`." } } }, "DataSourceListResponse": { "type": "array", - "description": "List of datasources. Sensitive credential fields are omitted.", + "description": "List of datasources. The `payload` column is not read by this endpoint, so `payload` is `null` in every item.", "items": { "$ref": "#/components/schemas/DataSourceItem" } @@ -5265,7 +5087,7 @@ }, "type_ident": { "type": "string", - "description": "Datasource type identifier. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `victorialogs`." + "description": "Datasource type identifier. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`." }, "name": { "type": "string", @@ -5277,7 +5099,7 @@ }, "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. Not required for Elasticsearch cloud deployment." + "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)." }, "payload": { "$ref": "#/components/schemas/DSPayload", @@ -5286,6 +5108,10 @@ "edge_cluster_name": { "type": "string", "description": "Monitors edge cluster name responsible for evaluating rules using this datasource." + }, + "enabled": { + "type": "boolean", + "description": "Whether the datasource is enabled for rule evaluation. When omitted on create, the datasource is created disabled (`false`)." } } }, @@ -5307,16 +5133,6 @@ "message" ] }, - "EmptyObject": { - "type": "object", - "description": "An empty object. Returned as the `data` payload by operations whose success signal is simply the absence of an error.", - "additionalProperties": false - }, - "EmptyRequest": { - "type": "object", - "description": "No parameters required.", - "additionalProperties": false - }, "EmptyResponse": { "type": "object", "description": "Empty response body. The server returns `data: null` on success.", @@ -5569,6 +5385,20 @@ "condition": { "type": "string", "description": "Recovery condition expression; required when `mode` is `threshold` or `ql`, and must be empty for `invert`." + }, + "value_fields": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Numeric result fields the recovery `condition` references as `$A.`; same semantics as the query's `value_fields`. Omitted when empty." + }, + "args": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Datasource-specific extra parameters for the recovery query, using the same `.` key convention as query `args`. Omitted when empty." } }, "description": "Recovery evaluation configuration for threshold checks." @@ -5679,7 +5509,10 @@ } } } - } + }, + "required": [ + "queries" + ] }, "RuleCounterChannelResponse": { "type": "object", @@ -5842,16 +5675,14 @@ "type": "integer", "format": "int64", "description": "Maximum number of repeated notifications. Effective only when `fields` includes `repeat_total`." - } - } - }, - "RuleFolderIDRequest": { - "type": "object", - "properties": { - "folder_id": { - "type": "integer", - "format": "uint64", - "description": "Folder ID to summarize. Obtainable via `POST /monit/folder/list`. Trigger statistics are returned grouped by direct child folder." + }, + "labels_patch": { + "$ref": "#/components/schemas/StringMapPatch", + "description": "Partial label update. Effective only when `fields` includes `labels`; takes precedence over `labels` when both are sent." + }, + "annotations_patch": { + "$ref": "#/components/schemas/StringMapPatch", + "description": "Partial annotation update. Effective only when `fields` includes `annotations`; takes precedence over `annotations` when both are sent." } } }, @@ -5918,7 +5749,21 @@ "folder_id": { "type": "integer", "format": "uint64", - "description": "Folder ID. 0 to list all accessible rules." + "description": "Folder ID. Must be an existing folder; `0` is rejected with a `folder_not_found` error." + }, + "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." + }, + "query": { + "type": "string", + "description": "Rule name fuzzy filter; only effective when `include_descendants` is `true`." + }, + "limit": { + "type": "integer", + "default": 50, + "maximum": 100, + "description": "Max number of rules returned; only effective when `include_descendants` is `true`. Defaults to 50, capped at 100." } } }, @@ -5978,7 +5823,10 @@ "type": "integer", "description": "Page size. Defaults to 200 server-side when 0." } - } + }, + "required": [ + "id" + ] }, "SLSLogstoresResponse": { "type": "array", @@ -6008,13 +5856,35 @@ "type": "integer", "description": "Page size. Defaults to 200 server-side when 0." } - } + }, + "required": [ + "id" + ] }, "SLSProjectsResponse": { - "type": "array", - "description": "List of SLS project names.", - "items": { - "type": "string" + "type": "object", + "description": "A page of Aliyun SLS projects.", + "required": [ + "projects", + "count", + "total" + ], + "properties": { + "projects": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SLSProject" + }, + "description": "Projects in the current page." + }, + "count": { + "type": "integer", + "description": "Number of projects in this page." + }, + "total": { + "type": "integer", + "description": "Total number of projects matching `query`, independent of pagination." + } } }, "StoreRulesetItem": { @@ -6052,7 +5922,7 @@ 1, 2 ], - "description": "Sharing scope. `0` = private (creator only), `1` = account-shared, `2` = public." + "description": "Sharing scope. `0` = private (visible to the creator and the account owner), `1` = account-shared, `2` = public." }, "payload": { "type": "string", @@ -6129,7 +5999,7 @@ 1, 2 ], - "description": "New sharing scope. `0` = private, `1` = account-shared, `2` = public." + "description": "New sharing scope. `0` = private (visible to the creator and the account owner), `1` = account-shared, `2` = public." }, "payload": { "type": "string", @@ -6161,7 +6031,7 @@ 1, 2 ], - "description": "Sharing scope. `0` = private (creator only), `1` = account-shared, `2` = public. Defaults to `0` if omitted." + "description": "Sharing scope. `0` = private (visible to the creator and the account owner), `1` = account-shared, `2` = public. Defaults to `0` if omitted." }, "payload": { "type": "string", @@ -6188,7 +6058,7 @@ ] }, "QueryDataRequest": { - "description": "Request for the stable structured query endpoint. It uses the same query fields as the deprecated rows endpoint.", + "description": "Request for the stable structured query endpoint. It accepts the same query fields as the retired rows endpoint.", "allOf": [ { "$ref": "#/components/schemas/QueryRowsRequest" @@ -6458,33 +6328,6 @@ } } }, - "QueryRowsResponse": { - "type": "array", - "description": "Result rows. Different data sources populate `fields` vs `values` differently — metric sources (Prometheus, *-stats) put numbers into `values`; detail sources (SQL, SLS, raw logs) put data into `fields` and may return `values: null`.", - "items": { - "$ref": "#/components/schemas/QueryRow" - } - }, - "QueryRow": { - "type": "object", - "properties": { - "fields": { - "type": "object", - "description": "String-valued fields (labels, log fields, SQL columns).", - "additionalProperties": { - "type": "string" - } - }, - "values": { - "type": "object", - "nullable": true, - "description": "Numeric fields. For metric queries the canonical key is `__value__`. May be `null` for detail-oriented sources.", - "additionalProperties": { - "type": "number" - } - } - } - }, "DiagnoseRequest": { "type": "object", "required": [ @@ -6922,6 +6765,14 @@ "type": "integer", "format": "int64", "description": "Last route-projection upsert time, Unix seconds. Treat as 'most recently observed', not a live-online indicator." + }, + "host_id": { + "type": "string", + "description": "ID of the host agent reporting this target. Omitted when the target is not associated with a host." + }, + "servicemap": { + "$ref": "#/components/schemas/TargetInventoryServiceMapCapability", + "description": "ServiceMap capability and latest status of the target's host. Omitted when the reporting agent has no ServiceMap capability." } } }, @@ -6936,47 +6787,13 @@ "type": "string", "description": "Opaque cursor for the next page. Absent / empty means this is the last page.", "x-flashduty-preserve-absence": true - } - } - }, - "PreviewSyncRequest": { - "type": "object", - "required": [ - "ds_type", - "ds_name", - "expr" - ], - "description": "Parameters for a synchronous datasource query preview.", - "properties": { - "ds_type": { - "type": "string", - "description": "Datasource type, e.g. `prometheus`, `loki`, `elasticsearch`." - }, - "ds_name": { - "type": "string", - "description": "Datasource display name as configured in the account." - }, - "expr": { - "type": "string", - "description": "Query expression. Format depends on `ds_type` (PromQL for Prometheus, LogQL for Loki, etc.)." }, - "delay_seconds": { - "type": "integer", - "description": "Shift the query window backward by this many seconds to compensate for data ingestion latency." - }, - "args": { - "type": "object", - "additionalProperties": { - "type": "string" - }, - "description": "Additional datasource-type-specific query arguments (string keys and values), e.g. `sls.project` and `sls.logstore` for SLS, `es.type` for Elasticsearch, `loki.type` and `loki.limit` for Loki." + "servicemap_coverage": { + "$ref": "#/components/schemas/TargetInventoryServiceMapCoverage", + "description": "ServiceMap status-fetch coverage for this page. Omitted when no item on the page carries ServiceMap data." } } }, - "PreviewSyncResponse": { - "type": "object", - "description": "Raw JSON response from the datasource. Schema varies by datasource type." - }, "DiagnoseEvidenceWindow": { "type": "object", "description": "Current analysis window using RFC 3339 UTC timestamps.", @@ -9226,6 +9043,226 @@ "description": "Unix timestamp in milliseconds this response was generated." } } + }, + "DSTencentCLSConfig": { + "type": "object", + "description": "Tencent CLS (Cloud Log Service) credential configuration.", + "required": [ + "secret_id" + ], + "properties": { + "secret_id": { + "type": "string", + "description": "Tencent Cloud API SecretId. Always required (create and update). Supports `${env:VAR}` references resolved on the edge." + }, + "secret_key": { + "type": "string", + "description": "Tencent Cloud API SecretKey. Required on create; on update, omit to keep the stored key. Supports `${env:VAR}` references. Never returned by read APIs: responses carry an empty string unless the stored value is an `${env:...}` reference." + } + } + }, + "SLSProject": { + "type": "object", + "description": "An Aliyun SLS project.", + "required": [ + "projectName", + "description", + "status", + "owner", + "region", + "createTime", + "lastModifyTime" + ], + "properties": { + "projectName": { + "type": "string", + "description": "Project name." + }, + "description": { + "type": "string", + "description": "Project description." + }, + "status": { + "type": "string", + "description": "Project status, e.g. `Normal`." + }, + "owner": { + "type": "string", + "description": "Owner Aliyun account ID; empty when not returned by SLS." + }, + "region": { + "type": "string", + "description": "Region ID, e.g. `cn-shanghai`." + }, + "createTime": { + "type": "string", + "description": "Creation time, Unix seconds rendered as a string, e.g. `\"1524539357\"`." + }, + "lastModifyTime": { + "type": "string", + "description": "Last modification time, Unix seconds rendered as a string." + }, + "dataRedundancyType": { + "type": "string", + "enum": [ + "LRS", + "ZRS" + ], + "description": "Data redundancy type: `LRS` = locally redundant storage, `ZRS` = zone-redundant storage. Omitted when not set." + }, + "location": { + "type": "string", + "description": "Storage location, e.g. `cn-beijing-b`. Omitted when not set." + } + } + }, + "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.", + "properties": { + "set": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Keys to insert or replace." + }, + "delete": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Keys to remove." + } + } + }, + "TargetInventoryServiceMapCapability": { + "type": "object", + "description": "ServiceMap capability and live status of a target's host.", + "required": [ + "enabled", + "status", + "snapshot_ready", + "authoritative", + "graph_available", + "node_count", + "edge_count" + ], + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether ServiceMap collection is enabled on the agent." + }, + "status": { + "type": "string", + "enum": [ + "active", + "degraded", + "stale", + "initializing", + "disabled", + "unsupported", + "no_data" + ], + "description": "ServiceMap collection status of the host.\n\n| Value | Meaning |\n|---|---|\n| `active` | Collection healthy: a fresh snapshot exists with no degradation. |\n| `degraded` | Collecting but quality is impaired: health reports are newer than the snapshot, the snapshot is truncated/degraded, or collection is failing. |\n| `stale` | A snapshot exists but is outdated (no update within 2x the report interval). |\n| `initializing` | The agent reported the capability but the first snapshot is not ready yet. |\n| `disabled` | Topology collection is disabled on this host. |\n| `unsupported` | The agent or kernel does not support collection. |\n| `no_data` | No snapshot or health data received yet. |" + }, + "capability_status": { + "type": "string", + "description": "Agent-reported capability status, e.g. `running`, `disabled`, `starting`, `failed`, `unsupported`. Omitted when the agent has not reported one." + }, + "capture_mode": { + "type": "string", + "description": "Capture mode, e.g. `ebpf` or `polling`. Omitted when unknown." + }, + "report_interval_ms": { + "type": "integer", + "format": "int64", + "description": "Configured reporting interval in milliseconds. Omitted when unknown." + }, + "snapshot_ready": { + "type": "boolean", + "description": "True if the agent has produced at least one full snapshot." + }, + "authoritative": { + "type": "boolean", + "description": "True if the current status derives from an authoritative graph snapshot." + }, + "graph_available": { + "type": "boolean", + "description": "True if a current graph can be fetched for this host right now." + }, + "freshness_status": { + "type": "string", + "enum": [ + "fresh", + "stale", + "unknown" + ], + "description": "Freshness classification of the host's graph. `fresh` = the latest snapshot was received within 2x the report interval; `stale` = no new snapshot within that window; `unknown` = not yet classified. Omitted when unknown." + }, + "max_age_ms": { + "type": "integer", + "format": "int64", + "description": "Maximum snapshot age in milliseconds tolerated before it counts as stale. Omitted when not applicable." + }, + "observed_at_ms": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp in milliseconds when the agent last observed graph generation. Omitted when unknown." + }, + "received_at_ms": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp in milliseconds when the server last received a snapshot. Omitted when unknown." + }, + "node_count": { + "type": "integer", + "description": "Number of nodes in the host's current graph." + }, + "edge_count": { + "type": "integer", + "description": "Number of edges in the host's current graph." + }, + "reason_codes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Machine-readable codes explaining the current capability status. Omitted when empty." + }, + "error_code": { + "type": "string", + "description": "Set to `status_unavailable` when the live status could not be read; other fields then fall back to inventory-derived values. Omitted otherwise." + } + } + }, + "TargetInventoryServiceMapCoverage": { + "type": "object", + "description": "ServiceMap status-fetch coverage for a targets page.", + "required": [ + "requested", + "succeeded", + "failed", + "partial" + ], + "properties": { + "requested": { + "type": "integer", + "description": "Items on this page that carry ServiceMap data." + }, + "succeeded": { + "type": "integer", + "description": "Items whose live ServiceMap status was read successfully." + }, + "failed": { + "type": "integer", + "description": "Items whose live ServiceMap status read failed (`servicemap.error_code` set)." + }, + "partial": { + "type": "boolean", + "description": "True when at least one item's status read failed." + } + } } } } diff --git a/api-reference/monitors.openapi.zh.json b/api-reference/monitors.openapi.zh.json index 796da38a..97aebc58 100644 --- a/api-reference/monitors.openapi.zh.json +++ b/api-reference/monitors.openapi.zh.json @@ -82,7 +82,7 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "id": 1, - "note": "更新后的 CPU 告警", + "note": "Updated CPU alerts", "open_flag": 2, "updated_at": 1712100000 } @@ -112,7 +112,7 @@ }, "example": { "id": 1, - "note": "更新后的 CPU 告警", + "note": "Updated CPU alerts", "open_flag": 2, "payload": "[{\"prom_ql\":\"rate(cpu_usage[5m]) > 0.9\"}]" } @@ -205,7 +205,7 @@ "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`、`victorialogs`。\n- `edge_cluster_name` 指定使用该数据源进行规则评估的 Monitors Edge 集群。\n- 对于 `elasticsearch`，`payload.elasticsearch.deployment` 须设为 `cloud` 或 `self-managed`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。\n\n## 凭据字段\n\n`info` / `create` / `update` 的响应会按原样返回 `payload` 配置——`password`、`basic_auth_password`、`api_key`、`service_token`、`access_key_secret`、`tls_key`、`tls_key_pwd` 等字段均如实返回，不做脱敏。请将这些响应视为敏感信息：避免记录日志或转发给第三方。", + "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`。\n- `edge_cluster_name` 指定使用该数据源进行规则评估的 Monitors Edge 集群。\n- 对于 `elasticsearch`，`payload.elasticsearch.deployment` 须设为 `cloud` 或 `self-managed`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。\n\n## 凭据字段\n\n`info` / `create` / `update` 的响应会按原样返回 `payload` 配置——`password`、`basic_auth_password`、`api_key`、`service_token`、`access_key_secret`、`tls_key`、`tls_key_pwd` 等字段均如实返回，不做脱敏。唯一例外是 `payload.tencent_cls.secret_key`：始终掩码为空字符串（`${env:...}` 引用则原样返回）。请将这些响应视为敏感信息：避免记录日志或转发给第三方。", "href": "/zh/api-reference/monitors/data-sources/monit-datasource-write-create", "metadata": { "sidebarTitle": "创建数据源" @@ -236,7 +236,7 @@ "data": { "id": 10, "type_ident": "prometheus", - "name": "生产 Prometheus", + "name": "Prometheus Prod", "enabled": true, "edge_cluster_name": "default", "updated_at": 1712000000 @@ -267,8 +267,8 @@ }, "example": { "type_ident": "prometheus", - "name": "生产 Prometheus", - "note": "生产环境 Prometheus", + "name": "Prometheus Prod", + "note": "Production Prometheus", "address": "http://prometheus.example.com:9090", "edge_cluster_name": "default", "payload": { @@ -291,7 +291,7 @@ "Monitors/告警数据源" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源管理**（`monit`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。\n\n## 凭据字段\n\n`info` / `create` / `update` 的响应会按原样返回 `payload` 配置——`password`、`basic_auth_password`、`api_key`、`service_token`、`access_key_secret`、`tls_key`、`tls_key_pwd` 等字段均如实返回，不做脱敏。请将这些响应视为敏感信息：避免记录日志或转发给第三方。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源管理**（`monit`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。\n\n## 凭据字段\n\n`info` / `create` / `update` 的响应会按原样返回 `payload` 配置——`password`、`basic_auth_password`、`api_key`、`service_token`、`access_key_secret`、`tls_key`、`tls_key_pwd` 等字段均如实返回，不做脱敏。唯一例外是 `payload.tencent_cls.secret_key`：始终掩码为空字符串（`${env:...}` 引用则原样返回）。请将这些响应视为敏感信息：避免记录日志或转发给第三方。", "href": "/zh/api-reference/monitors/data-sources/monit-datasource-write-update", "metadata": { "sidebarTitle": "更新数据源" @@ -322,7 +322,7 @@ "data": { "id": 10, "type_ident": "prometheus", - "name": "生产 Prometheus v2", + "name": "Prometheus Prod v2", "enabled": true, "edge_cluster_name": "default", "updated_at": 1712100000 @@ -354,8 +354,8 @@ "example": { "id": 10, "type_ident": "prometheus", - "name": "生产 Prometheus v2", - "note": "已更新", + "name": "Prometheus Prod v2", + "note": "Updated", "address": "http://prometheus-v2.example.com:9090", "edge_cluster_name": "default", "payload": { @@ -408,7 +408,7 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": [ { - "name": "CPU 过高", + "name": "CPU High", "message": "" } ] @@ -486,8 +486,8 @@ "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { - "生产环境": 10, - "预发环境": 3 + "Production": 10, + "Staging": 3 } } } @@ -561,7 +561,7 @@ "account_id": 10023, "alert_rule_id": 50001, "action": "update", - "content": "{\"id\":50001,\"name\":\"CPU 过高\"}", + "content": "{\"id\":50001,\"name\":\"CPU High\"}", "creator_id": 80011, "creator_name": "Alice", "created_at": 1712000000 @@ -602,7 +602,7 @@ "post": { "operationId": "monit-datasource-write-delete", "summary": "删除数据源", - "description": "通过 ID 删除数据源。引用该数据源的告警规则需提前更新或删除。", + "description": "通过 ID 删除数据源。引用该数据源的告警规则不会被阻塞：该数据源会从规则的监控范围中移除，规则上相关的未恢复告警会自动关闭。", "tags": [ "Monitors/告警数据源" ], @@ -778,10 +778,30 @@ }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": [ - "project-a", - "project-b" - ] + "data": { + "projects": [ + { + "projectName": "project-a", + "description": "Production logs", + "status": "Normal", + "owner": "", + "region": "cn-shanghai", + "createTime": "1710000000", + "lastModifyTime": "1712000000" + }, + { + "projectName": "project-b", + "description": "Staging logs", + "status": "Normal", + "owner": "", + "region": "cn-shanghai", + "createTime": "1710000000", + "lastModifyTime": "1712000000" + } + ], + "count": 2, + "total": 2 + } } } } @@ -817,83 +837,6 @@ } } }, - "/monit/rule/status": { - "post": { - "operationId": "monit-rule-write-status", - "summary": "查看文件夹下规则触发状态", - "description": "返回指定文件夹节点及其子孙节点下所有规则的触发情况汇总。", - "tags": [ - "Monitors/告警规则" - ], - "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- 将 `folder_id` 设为 `0` 可获取所有文件夹的汇总。\n- 若文件夹包含规则数量过多，为保护系统会跳过计算。", - "href": "/zh/api-reference/monitors/alert-rules/monit-rule-write-status", - "metadata": { - "sidebarTitle": "查看文件夹下规则触发状态" - } - }, - "responses": { - "200": { - "description": "成功", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/RuleStatusResponse" - } - } - } - ] - }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": [ - { - "folder_id": 100, - "folder_name": "生产环境", - "rule_total": 10, - "triggered_rule_count": 2 - } - ] - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/Unauthorized" - }, - "429": { - "$ref": "#/components/responses/TooManyRequests" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RuleFolderIDRequest" - }, - "example": { - "folder_id": 100 - } - } - } - } - } - }, "/monit/rule/export": { "post": { "operationId": "monit-rule-read-export", @@ -933,13 +876,13 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": [ { - "name": "CPU 过高", + "name": "CPU High", "ds_type": "prometheus", "ds_list": [ "prometheus*" ], "enabled": true, - "cron_pattern": "* * * * *" + "cron_pattern": "0 * * * * *" } ] } @@ -1061,7 +1004,7 @@ "Monitors/告警数据源" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 凭据字段\n\n`info` / `create` / `update` 的响应会按原样返回 `payload` 配置——`password`、`basic_auth_password`、`api_key`、`service_token`、`access_key_secret`、`tls_key`、`tls_key_pwd` 等字段均如实返回，不做脱敏。请将这些响应视为敏感信息：避免记录日志或转发给第三方。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 凭据字段\n\n`info` / `create` / `update` 的响应会按原样返回 `payload` 配置——`password`、`basic_auth_password`、`api_key`、`service_token`、`access_key_secret`、`tls_key`、`tls_key_pwd` 等字段均如实返回，不做脱敏。唯一例外是 `payload.tencent_cls.secret_key`：始终掩码为空字符串（`${env:...}` 引用则原样返回）。请将这些响应视为敏感信息：避免记录日志或转发给第三方。", "href": "/zh/api-reference/monitors/data-sources/monit-datasource-read-info", "metadata": { "sidebarTitle": "查看数据源详情" @@ -1093,9 +1036,9 @@ "id": 10, "account_id": 10023, "type_ident": "prometheus", - "name": "生产 Prometheus", + "name": "Prometheus Prod", "enabled": true, - "note": "生产环境 Prometheus", + "note": "Production Prometheus", "address": "http://prometheus.example.com:9090", "payload": { "prometheus": { @@ -1260,13 +1203,13 @@ "data": { "id": 50001, "folder_id": 100, - "name": "CPU 过高", + "name": "CPU High", "ds_type": "prometheus", "ds_list": [ "prometheus*" ], "enabled": true, - "cron_pattern": "* * * * *", + "cron_pattern": "0 * * * * *", "channel_ids": [ 20001 ] @@ -1517,13 +1460,13 @@ "example": { "id": 50001, "folder_id": 100, - "name": "CPU 过高 v2", + "name": "CPU High v2", "ds_type": "prometheus", "ds_list": [ "prometheus*" ], "enabled": true, - "cron_pattern": "* * * * *", + "cron_pattern": "0 * * * * *", "rule_configs": { "queries": [ { @@ -1577,7 +1520,7 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": [ { - "name": "CPU 过高", + "name": "CPU High", "message": "" } ] @@ -1608,13 +1551,13 @@ "example": [ { "folder_id": 100, - "name": "CPU 过高", + "name": "CPU High", "ds_type": "prometheus", "ds_list": [ "prometheus*" ], "enabled": true, - "cron_pattern": "* * * * *", + "cron_pattern": "0 * * * * *", "rule_configs": { "queries": [ { @@ -1670,7 +1613,7 @@ "data": { "id": 50001, "folder_id": 100, - "name": "CPU 过高", + "name": "CPU High", "ds_type": "prometheus", "created_at": 1712000000 } @@ -1700,13 +1643,13 @@ }, "example": { "folder_id": 100, - "name": "CPU 过高", + "name": "CPU High", "ds_type": "prometheus", "ds_list": [ "prometheus*" ], "enabled": true, - "cron_pattern": "* * * * *", + "cron_pattern": "0 * * * * *", "channel_ids": [ 20001 ], @@ -1775,7 +1718,7 @@ { "id": 1, "type_ident": "prometheus", - "note": "CPU 用量告警", + "note": "CPU usage alerts", "open_flag": 2, "creator_account_id": 10023, "creator_id": 80011, @@ -1926,7 +1869,7 @@ "data": [ { "folder_id": 100, - "folder_name": "生产环境", + "folder_name": "Production", "rule_total": 10, "triggered_rule_count": 2 } @@ -2002,11 +1945,13 @@ { "id": 50001, "folder_id": 100, - "name": "CPU 过高", + "name": "CPU High", "ds_type": "prometheus", "enabled": true, "triggered": true, - "created_at": 1710000000 + "created_at": 1710000000, + "active_alert_count": 2, + "runtime_state": "normal" } ] } @@ -2081,7 +2026,7 @@ "data": { "id": 1, "type_ident": "prometheus", - "note": "CPU 用量告警", + "note": "CPU usage alerts", "open_flag": 2, "payload": "[{\"prom_ql\":\"...\"}]", "creator_account_id": 10023, @@ -2162,7 +2107,7 @@ "data": { "id": 1, "type_ident": "prometheus", - "note": "CPU 用量告警", + "note": "CPU usage alerts", "open_flag": 1, "created_at": 1712000000, "updated_at": 1712000000 @@ -2193,7 +2138,7 @@ }, "example": { "type_ident": "prometheus", - "note": "CPU 用量告警", + "note": "CPU usage alerts", "open_flag": 1, "payload": "[{\"prom_ql\":\"rate(cpu_usage[5m]) > 0.8\"}]" } @@ -2244,12 +2189,13 @@ "id": 10, "account_id": 10023, "type_ident": "prometheus", - "name": "生产 Prometheus", + "name": "Prometheus Prod", "enabled": true, - "note": "生产环境 Prometheus", + "note": "Production Prometheus", "address": "http://prometheus.example.com:9090", "edge_cluster_name": "default", - "updated_at": 1712000000 + "updated_at": 1712000000, + "payload": null } ] } @@ -2323,11 +2269,11 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": [ { - "name": "CPU 过高", + "name": "CPU High", "message": "" }, { - "name": "磁盘告警", + "name": "Disk High", "message": "" } ] @@ -2408,7 +2354,7 @@ "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { - "生产": 8 + "Production": 8 } } } @@ -2563,92 +2509,6 @@ } } }, - "/monit/query/rows": { - "post": { - "operationId": "monit-read-query-rows", - "summary": "查询数据源原始行", - "description": "已弃用。执行同步即席查询并返回历史扁平 rows 结构。现有调用方应迁移到 `/monit/query/data`；新接口会保留 frames、records 和 samples 的自然语义，不再把所有结果强制压成 legacy rows。", - "deprecated": true, - "tags": [ - "Monitors/诊断分析" - ], - "x-mint": { - "content": "## 已弃用\n\n所有新集成请使用 [`POST /monit/query/data`](/zh/api-reference/monitors/diagnostics/monit-read-query-data)。本接口仅在现有前端和 AI SRE 调用方迁移期间保留。\n\n## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | 每账户 **100 次/分钟**、**5 次/秒** |\n| 权限 | 任意有效的 `app_key`（只读，不受特定权限分类限制） |\n\n## 使用说明\n\n- 请求通过 WebSocket 转发至 `monit-edge`；`ds_type` + `ds_name` 指定的数据源必须已存在于调用账户下。\n- 请求体中的 `account_id` 可选。若传入，必须与认证账户一致；不一致将被拒绝。\n- 参数校验失败使用标准错误 envelope。当 `monit-edge` 拒绝查询时，其 `{\"error\": {\"code\": ..., \"message\": ...}}` 响应体会被保留，HTTP 状态码与 Edge 错误码一致；错误码无效或缺失时返回 HTTP 500。请同时检查状态码和错误响应体。\n- monit-edge 强制行数上限；结果过多时返回 `error.message = \"too many rows\"`。请缩小时间范围或在数据源侧聚合。\n- `args` 是透传的多态 `string→string` 映射，语义取决于 `ds_type`（SLS 需要 `sls.project` + `sls.logstore`；Loki/VictoriaLogs 原始模式需要通过 `*.start`/`*.end` 或 `*.timespan.value`/`*.timespan.unit` 指定时间范围；Prometheus 和 SQL 数据源忽略该字段）。各数据源完整参数列表见 monit-webapi query-api 文档。", - "href": "/zh/api-reference/monitors/diagnostics/monit-read-query-rows", - "metadata": { - "sidebarTitle": "查询数据源原始行" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/QueryRowsRequest" - }, - "example": { - "account_id": 10001, - "ds_type": "prometheus", - "ds_name": "prod-prom", - "expr": "up", - "delay_seconds": 30 - } - } - } - }, - "responses": { - "200": { - "description": "成功", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/QueryRowsResponse" - } - } - } - ] - }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": [ - { - "fields": { - "__name__": "up", - "instance": "10.0.0.1:9100", - "job": "node" - }, - "values": { - "__value__": 1 - } - } - ] - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/Unauthorized" - }, - "429": { - "$ref": "#/components/responses/TooManyRequests" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - } - } - }, "/monit/query/diagnose": { "post": { "operationId": "monit-read-query-diagnose", @@ -2658,7 +2518,7 @@ "Monitors/诊断分析" ], "x-mint": { - "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | **600 次/分钟**;**10 次/秒** 每账户 |\n| 权限 | 任意有效的 `app_key`(只读;不受特定权限分类约束) |\n\n## 使用说明\n\n- 这是诊断 / RCA 接口,而非原始数据查询接口——如需查看明细行,请配合 `/monit/query/rows` 使用。\n- 仅支持三种 `ds_type` 与 `operation` 组合：`loki` / `victorialogs` → `log_patterns`，`prometheus` → `metric_trends`。即使显式传入 `operation`，其他数据源也会被拒绝。\n- `methods` 选择要执行的分析方法;省略时,`log_patterns` 默认为 `pattern_snapshot + pattern_compare(previous_window)`,`metric_trends` 默认为 `single_window_shape + window_compare(previous_window)`。\n- `time_range` 单位为 Unix 秒;缺失或无效时默认最近 15 分钟;窗口宽度超过 6 小时将被拒绝。\n- 请求通过 WebSocket 转发至 `monit-edge`。长耗时:边缘侧执行可能耗时约 30 秒,叠加 webapi 开销。客户端超时应至少设置为 **35 秒**。\n- `options.*` 由边缘侧设置上限(`max_logs_scanned` ≤ 50 000,`max_patterns` ≤ 50,`examples_per_pattern` ≤ 3,`step_seconds` ∈ [15, 300],`max_series` ≤ 200,`topk` ≤ 50,`timeout_seconds` ≤ 30)。\n- 与 `/monit/query/rows` 一样存在两层错误:边缘侧执行错误以 HTTP 200 返回,响应体中带 `error` 对象——务必同时检查两层。\n- 日志样例在返回前会经过基础脱敏处理,响应中会带 `warnings: [\"examples redacted\"]`。不可作为原始日志使用。", + "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | **600 次/分钟**;**10 次/秒** 每账户 |\n| 权限 | 任意有效的 `app_key`(只读;不受特定权限分类约束) |\n\n## 使用说明\n\n- 这是诊断 / RCA 接口,而非原始数据查询接口——如需查询底层数据,请配合 `/monit/query/data` 使用。\n- 仅支持三种 `ds_type` 与 `operation` 组合：`loki` / `victorialogs` → `log_patterns`，`prometheus` → `metric_trends`。即使显式传入 `operation`，其他数据源也会被拒绝。\n- `methods` 选择要执行的分析方法;省略时,`log_patterns` 默认为 `pattern_snapshot + pattern_compare(previous_window)`,`metric_trends` 默认为 `single_window_shape + window_compare(previous_window)`。\n- `time_range` 单位为 Unix 秒;缺失或无效时默认最近 15 分钟;窗口宽度超过 6 小时将被拒绝。\n- 请求通过 WebSocket 转发至 `monit-edge`。长耗时:边缘侧执行可能耗时约 30 秒,叠加 webapi 开销。客户端超时应至少设置为 **35 秒**。\n- `options.*` 由边缘侧设置上限(`max_logs_scanned` ≤ 50 000,`max_patterns` ≤ 50,`examples_per_pattern` ≤ 3,`step_seconds` ∈ [15, 300],`max_series` ≤ 200,`topk` ≤ 50,`timeout_seconds` ≤ 30)。\n- 成功响应体为原始 `{\"data\": ...}` 对象,不含通常的 `request_id` 包装字段（edge 侧原样透传）。\n- 存在两层错误:请求级失败返回非 200 状态码与标准 `error` 包装;边缘侧执行错误以 HTTP 200 返回,响应体中带 `error` 对象——务必同时检查两层。\n- 日志样例在返回前会经过基础脱敏处理,响应中会带 `warnings: [\"examples redacted\"]`。不可作为原始日志使用。", "href": "/zh/api-reference/monitors/diagnostics/monit-read-query-diagnose", "metadata": { "sidebarTitle": "数据源诊断" @@ -2708,22 +2568,17 @@ "content": { "application/json": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/DiagnoseResponse" - } - } + "type": "object", + "required": [ + "data" + ], + "properties": { + "data": { + "$ref": "#/components/schemas/DiagnoseResponse" } - ] + } }, "example": { - "request_id": "01JZPD1PCDTN5F4YVBD2GS6S9A", "data": { "schema_version": "2", "operation": "log_patterns", @@ -3150,85 +3005,6 @@ } } }, - "/monit/preview/sync": { - "post": { - "operationId": "monit-preview-sync", - "summary": "同步预览数据源查询", - "description": "同步执行数据源查询并返回原始结果，用于在保存前预览告警规则表达式的效果。", - "tags": [ - "Monitors/通用工具" - ], - "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **60 次/分钟**；**10 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `ds_type` 须与数据源类型匹配，如 `prometheus`、`loki`。\n- `ds_name` 为账户中配置的数据源显示名称。\n- `delay_seconds` 将查询窗口向前偏移指定秒数，用于补偿数据摄入延迟。\n- 响应体为数据源返回的原始 JSON，其结构随数据源类型而异。", - "href": "/zh/api-reference/monitors/monitor-utilities/monit-preview-sync", - "metadata": { - "sidebarTitle": "同步预览数据源查询" - } - }, - "responses": { - "200": { - "description": "成功", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/PreviewSyncResponse" - } - } - } - ] - }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": { - "status": "success", - "data": { - "resultType": "vector", - "result": [] - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/Unauthorized" - }, - "429": { - "$ref": "#/components/responses/TooManyRequests" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PreviewSyncRequest" - }, - "example": { - "ds_type": "prometheus", - "ds_name": "生产 Prometheus", - "expr": "rate(http_requests_total[5m])", - "delay_seconds": 0 - } - } - } - } - } - }, "/monit/servicemap/status": { "post": { "operationId": "monit-servicemap-read-status", @@ -4111,7 +3887,7 @@ "items": { "type": "string" }, - "description": "数据源名称模式（支持通配符）。" + "description": "数据源名称匹配模式（支持通配符）。`ds_list` / `ds_ids` 至少一个非空，两者合并共同决定规则监控哪些数据源。" }, "ds_ids": { "type": "array", @@ -4251,7 +4027,14 @@ "format": "int64", "description": "最近更新时间，Unix 秒级时间戳，由服务端生成，无需提供。" } - } + }, + "required": [ + "folder_id", + "name", + "ds_type", + "cron_pattern", + "rule_configs" + ] }, "AlertRuleAudit": { "type": "object", @@ -4283,7 +4066,11 @@ }, "action": { "type": "string", - "description": "操作类型，如 `create`、`update`。" + "description": "操作类型：`create` = 创建规则；`update` = 更新规则（涵盖整体更新、字段批量更新、导入和移动）。", + "enum": [ + "create", + "update" + ] }, "content": { "type": "string", @@ -4324,7 +4111,10 @@ "updater_name", "created_at", "updated_at", - "triggered" + "triggered", + "labels", + "timezone", + "active_alert_count" ], "properties": { "id": { @@ -4367,7 +4157,7 @@ }, "cron_pattern": { "type": "string", - "description": "5 字段 cron 调度，如 `* * * * *`。不允许以 `CRON_TZ=` 或 `TZ=` 开头，时区请填写到 `timezone` 字段。" + "description": "调度表达式：6 字段 cron（含秒），如 `0 * * * * *`；或 `@every 30s` 形式的间隔描述。不允许以 `CRON_TZ=` 或 `TZ=` 开头，时区请填写到 `timezone` 字段。" }, "timezone": { "type": "string", @@ -4409,6 +4199,25 @@ "triggered": { "type": "boolean", "description": "是否有当前活跃告警。" + }, + "active_alert_count": { + "type": "integer", + "format": "int64", + "description": "该规则当前活跃（未恢复）的告警数量。`triggered` 等价于 `active_alert_count > 0`。" + }, + "runtime_state": { + "type": "string", + "enum": [ + "disabled", + "offline", + "abnormal", + "stale", + "no_datasource", + "config_pending", + "waiting", + "normal" + ], + "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` | 正常评估中。 |" } } }, @@ -4939,6 +4748,10 @@ }, "victorialogs": { "$ref": "#/components/schemas/DSVictoriaLogsConfig" + }, + "tencent_cls": { + "$ref": "#/components/schemas/DSTencentCLSConfig", + "description": "腾讯云 CLS 凭证。`type_ident` 为 `tencent_cls` 时必填。" } } }, @@ -5184,7 +4997,8 @@ "note", "address", "edge_cluster_name", - "updated_at" + "updated_at", + "payload" ], "properties": { "id": { @@ -5199,7 +5013,7 @@ }, "type_ident": { "type": "string", - "description": "数据源类型标识，可选值：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`victorialogs`。" + "description": "数据源类型标识，可选值：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`tencent_cls`、`victorialogs`。" }, "name": { "type": "string", @@ -5218,7 +5032,15 @@ "description": "连接地址。Prometheus/Loki/VictoriaLogs 为 HTTP URL；MySQL/Oracle/Postgres/ClickHouse 为 `host:port`；SLS 为不含 http/https 前缀的 endpoint。" }, "payload": { - "$ref": "#/components/schemas/DSPayload" + "anyOf": [ + { + "$ref": "#/components/schemas/DSPayload" + }, + { + "type": "null" + } + ], + "description": "类型相关配置块，必须包含与 `type_ident` 匹配的键。`/monit/datasource/list` 响应中恒为 `null`（列表查询不读取 payload 列）；创建/更新/详情响应中会返回。对于 `tencent_cls`，`secret_key` 会被掩码为空字符串，除非其值为 `${env:...}` 引用。" }, "edge_cluster_name": { "type": "string", @@ -5237,13 +5059,13 @@ "properties": { "type": { "type": "string", - "description": "按数据源类型过滤，省略则返回所有类型。可选值：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`victorialogs`。" + "description": "按数据源类型标识过滤，省略则返回所有类型。可选值：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`tencent_cls`、`victorialogs`。" } } }, "DataSourceListResponse": { "type": "array", - "description": "数据源列表，不含敏感凭证字段。", + "description": "数据源列表。本接口不读取 payload 列，因此每项的 `payload` 均为 `null`。", "items": { "$ref": "#/components/schemas/DataSourceItem" } @@ -5265,7 +5087,7 @@ }, "type_ident": { "type": "string", - "description": "数据源类型标识，可选值：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`victorialogs`。" + "description": "数据源类型标识，可选值：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`tencent_cls`、`victorialogs`。" }, "name": { "type": "string", @@ -5277,7 +5099,7 @@ }, "address": { "type": "string", - "description": "连接地址。Prometheus/Loki/VictoriaLogs 为 HTTP URL；MySQL/Oracle/Postgres/ClickHouse 为 `host:port`；SLS 为不含 http/https 前缀的 endpoint；Elasticsearch cloud 部署无需填写。" + "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）。" }, "payload": { "$ref": "#/components/schemas/DSPayload", @@ -5286,7 +5108,11 @@ "edge_cluster_name": { "type": "string", "description": "负责使用该数据源评估规则的 Monitors Edge 集群名称。" - } + }, + "enabled": { + "type": "boolean", + "description": "数据源是否启用（参与规则评估）。创建时省略则默认禁用（`false`）。" + } } }, "DutyError": { @@ -5307,16 +5133,6 @@ "message" ] }, - "EmptyObject": { - "type": "object", - "description": "空对象。当操作的成功信号就是不报错时，作为 `data` 返回。", - "additionalProperties": false - }, - "EmptyRequest": { - "type": "object", - "description": "无参数。", - "additionalProperties": false - }, "EmptyResponse": { "type": "object", "description": "空响应体。成功时服务端返回 `data: null`。", @@ -5569,6 +5385,20 @@ "condition": { "type": "string", "description": "恢复条件表达式；`mode` 为 `threshold` 或 `ql` 时必填，`invert` 时必须为空。" + }, + "value_fields": { + "type": "array", + "items": { + "type": "string" + }, + "description": "恢复条件 `condition` 以 `$A.` 形式引用的数值结果字段，语义同查询的 `value_fields`。为空时不返回。" + }, + "args": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "恢复查询的数据源附加参数，键约定同查询的 `args`（`<数据源>.<参数>`）。为空时不返回。" } }, "description": "阈值检查的恢复判定配置。" @@ -5679,7 +5509,10 @@ } } } - } + }, + "required": [ + "queries" + ] }, "RuleCounterChannelResponse": { "type": "object", @@ -5842,16 +5675,14 @@ "type": "integer", "format": "int64", "description": "最大重复通知次数。仅当 `fields` 包含 `repeat_total` 时生效。" - } - } - }, - "RuleFolderIDRequest": { - "type": "object", - "properties": { - "folder_id": { - "type": "integer", - "format": "uint64", - "description": "要统计的文件夹 ID，可通过 `POST /monit/folder/list` 获取。服务端按直属子文件夹分组返回规则触发统计。" + }, + "labels_patch": { + "$ref": "#/components/schemas/StringMapPatch", + "description": "标签的增量更新，仅在 `fields` 包含 `labels` 时生效；与 `labels` 同时发送时优先使用本字段。" + }, + "annotations_patch": { + "$ref": "#/components/schemas/StringMapPatch", + "description": "注解的增量更新，仅在 `fields` 包含 `annotations` 时生效；与 `annotations` 同时发送时优先使用本字段。" } } }, @@ -5918,7 +5749,21 @@ "folder_id": { "type": "integer", "format": "uint64", - "description": "文件夹 ID，设为 0 可列出所有可访问规则。" + "description": "文件夹 ID，必须是已存在的文件夹；传 `0` 会返回 `folder_not_found` 错误。" + }, + "include_descendants": { + "type": "boolean", + "description": "是否同时包含所有子孙文件夹中的规则。为 `true` 时返回的每项仅包含 `id`、`folder_id`、`name` 三个字段；配合 `query` / `limit` 用于规则选择器场景。" + }, + "query": { + "type": "string", + "description": "规则名模糊过滤，仅在 `include_descendants` 为 `true` 时生效。" + }, + "limit": { + "type": "integer", + "default": 50, + "maximum": 100, + "description": "返回规则数量上限，仅在 `include_descendants` 为 `true` 时生效。默认 50，最大 100。" } } }, @@ -5978,7 +5823,10 @@ "type": "integer", "description": "每页大小，传 0 时服务端默认 200。" } - } + }, + "required": [ + "id" + ] }, "SLSLogstoresResponse": { "type": "array", @@ -6008,13 +5856,35 @@ "type": "integer", "description": "每页大小，传 0 时服务端默认 200。" } - } + }, + "required": [ + "id" + ] }, "SLSProjectsResponse": { - "type": "array", - "description": "SLS 项目名称列表。", - "items": { - "type": "string" + "type": "object", + "description": "一页阿里云 SLS 项目。", + "required": [ + "projects", + "count", + "total" + ], + "properties": { + "projects": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SLSProject" + }, + "description": "当前页的项目列表。" + }, + "count": { + "type": "integer", + "description": "本页项目数量。" + }, + "total": { + "type": "integer", + "description": "匹配 `query` 的项目总数，与分页无关。" + } } }, "StoreRulesetItem": { @@ -6052,7 +5922,7 @@ 1, 2 ], - "description": "共享范围：`0` 仅创建者可见，`1` 账户内共享，`2` 公开。" + "description": "共享范围：`0` 私有（创建者与账户管理员可见），`1` 账户内共享，`2` 公开。" }, "payload": { "type": "string", @@ -6129,7 +5999,7 @@ 1, 2 ], - "description": "新的共享范围：`0` 仅创建者，`1` 账户共享，`2` 公开。" + "description": "新的共享范围：`0` 私有（创建者与账户管理员可见），`1` 账户共享，`2` 公开。" }, "payload": { "type": "string", @@ -6161,7 +6031,7 @@ 1, 2 ], - "description": "共享范围：`0` 仅创建者可见，`1` 账户内共享，`2` 公开。省略时默认为 `0`。" + "description": "共享范围：`0` 私有（创建者与账户管理员可见），`1` 账户内共享，`2` 公开。省略时默认为 `0`。" }, "payload": { "type": "string", @@ -6188,7 +6058,7 @@ ] }, "QueryDataRequest": { - "description": "稳定结构化查询接口的请求。字段与已弃用的 rows 接口一致。", + "description": "稳定结构化查询接口的请求。字段与已下线的 rows 接口一致。", "allOf": [ { "$ref": "#/components/schemas/QueryRowsRequest" @@ -6458,33 +6328,6 @@ } } }, - "QueryRowsResponse": { - "type": "array", - "description": "结果行。不同数据源对 `fields` 与 `values` 的填充方式不同——指标类数据源(Prometheus、*-stats)将数字放入 `values`;明细类数据源(SQL、SLS、原始日志)将数据放入 `fields`,`values` 可能为 `null`。", - "items": { - "$ref": "#/components/schemas/QueryRow" - } - }, - "QueryRow": { - "type": "object", - "properties": { - "fields": { - "type": "object", - "description": "字符串值字段(标签、日志字段、SQL 列)。", - "additionalProperties": { - "type": "string" - } - }, - "values": { - "type": "object", - "nullable": true, - "description": "数值字段。对于指标查询,规范键名为 `__value__`。对于明细类数据源可能为 `null`。", - "additionalProperties": { - "type": "number" - } - } - } - }, "DiagnoseRequest": { "type": "object", "required": [ @@ -6922,6 +6765,14 @@ "type": "integer", "format": "int64", "description": "最近一次路由投影写入时间,Unix 秒。视为\"最近一次被观测到\",而非实时在线指标。" + }, + "host_id": { + "type": "string", + "description": "上报该目标的 host agent ID。目标未关联主机时不返回。" + }, + "servicemap": { + "$ref": "#/components/schemas/TargetInventoryServiceMapCapability", + "description": "目标所在主机的服务拓扑（ServiceMap）采集能力与最新状态。上报 agent 不具备 ServiceMap 能力时不返回。" } } }, @@ -6936,47 +6787,13 @@ "type": "string", "description": "下一页的不透明游标。缺失 / 为空表示已到末页。", "x-flashduty-preserve-absence": true - } - } - }, - "PreviewSyncRequest": { - "type": "object", - "required": [ - "ds_type", - "ds_name", - "expr" - ], - "description": "同步数据源查询预览的参数。", - "properties": { - "ds_type": { - "type": "string", - "description": "数据源类型，如 `prometheus`、`loki`、`elasticsearch`。" }, - "ds_name": { - "type": "string", - "description": "账户中配置的数据源显示名称。" - }, - "expr": { - "type": "string", - "description": "查询表达式，格式因 `ds_type` 而异（Prometheus 为 PromQL，Loki 为 LogQL 等）。" - }, - "delay_seconds": { - "type": "integer", - "description": "将查询窗口向前偏移的秒数，用于补偿数据摄入延迟。" - }, - "args": { - "type": "object", - "additionalProperties": { - "type": "string" - }, - "description": "特定数据源类型的附加查询参数（键值均为字符串），如 SLS 的 `sls.project`、`sls.logstore`，Elasticsearch 的 `es.type`，Loki 的 `loki.type`、`loki.limit`。" + "servicemap_coverage": { + "$ref": "#/components/schemas/TargetInventoryServiceMapCoverage", + "description": "本页 ServiceMap 状态拉取覆盖情况。本页没有任何条目携带 ServiceMap 数据时不返回。" } } }, - "PreviewSyncResponse": { - "type": "object", - "description": "数据源返回的原始 JSON，结构随数据源类型而异。" - }, "DiagnoseEvidenceWindow": { "type": "object", "description": "分析的当前时间窗口，使用 RFC 3339 UTC 时间戳。", @@ -9226,6 +9043,226 @@ "description": "生成本次响应的 Unix 时间戳（毫秒）。" } } + }, + "DSTencentCLSConfig": { + "type": "object", + "description": "腾讯云日志服务（CLS）凭证配置。", + "required": [ + "secret_id" + ], + "properties": { + "secret_id": { + "type": "string", + "description": "腾讯云 API SecretId，创建和更新时均必填。支持 `${env:VAR}` 引用（在 edge 侧解析）。" + }, + "secret_key": { + "type": "string", + "description": "腾讯云 API SecretKey。创建时必填；更新时省略则保留已存储的密钥。支持 `${env:VAR}` 引用。读取接口永不返回该值：响应中为空字符串，除非存储的值是 `${env:...}` 引用。" + } + } + }, + "SLSProject": { + "type": "object", + "description": "一个阿里云 SLS 项目。", + "required": [ + "projectName", + "description", + "status", + "owner", + "region", + "createTime", + "lastModifyTime" + ], + "properties": { + "projectName": { + "type": "string", + "description": "项目名称。" + }, + "description": { + "type": "string", + "description": "项目描述。" + }, + "status": { + "type": "string", + "description": "项目状态，例如 `Normal`。" + }, + "owner": { + "type": "string", + "description": "项目属主的阿里云账户 ID；SLS 未返回时为空。" + }, + "region": { + "type": "string", + "description": "地域 ID，例如 `cn-shanghai`。" + }, + "createTime": { + "type": "string", + "description": "创建时间，以字符串表示的 Unix 秒，例如 `\"1524539357\"`。" + }, + "lastModifyTime": { + "type": "string", + "description": "最后修改时间，以字符串表示的 Unix 秒。" + }, + "dataRedundancyType": { + "type": "string", + "enum": [ + "LRS", + "ZRS" + ], + "description": "数据冗余类型：`LRS` = 本地冗余存储，`ZRS` = 同城冗余存储。未设置时不返回。" + }, + "location": { + "type": "string", + "description": "存储位置，例如 `cn-beijing-b`。未设置时不返回。" + } + } + }, + "StringMapPatch": { + "type": "object", + "description": "map 字段的增量更新：`set` 中的键会被插入或覆盖，`delete` 中的键会被删除，其余键保持不变。", + "properties": { + "set": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "要插入或覆盖的键值对。" + }, + "delete": { + "type": "array", + "items": { + "type": "string" + }, + "description": "要删除的键。" + } + } + }, + "TargetInventoryServiceMapCapability": { + "type": "object", + "description": "目标主机的 ServiceMap 采集能力与实时状态。", + "required": [ + "enabled", + "status", + "snapshot_ready", + "authoritative", + "graph_available", + "node_count", + "edge_count" + ], + "properties": { + "enabled": { + "type": "boolean", + "description": "agent 是否启用了 ServiceMap 采集。" + }, + "status": { + "type": "string", + "enum": [ + "active", + "degraded", + "stale", + "initializing", + "disabled", + "unsupported", + "no_data" + ], + "description": "主机的 ServiceMap 采集状态。\n\n| 值 | 含义 |\n|---|---|\n| `active` | 采集正常：有新鲜快照且无降级。 |\n| `degraded` | 采集在进行但质量受损：健康上报晚于快照、快照被截断/降级，或采集报错。 |\n| `stale` | 有快照但已过期（超过 2× 上报间隔未更新）。 |\n| `initializing` | Agent 已上报采集能力，但首个快照尚未就绪。 |\n| `disabled` | 该主机的拓扑采集被禁用。 |\n| `unsupported` | Agent 或内核不支持该采集。 |\n| `no_data` | 未收到任何快照或健康数据。 |" + }, + "capability_status": { + "type": "string", + "description": "agent 上报的能力状态，例如 `running`、`disabled`、`starting`、`failed`、`unsupported`。agent 未上报时不返回。" + }, + "capture_mode": { + "type": "string", + "description": "采集模式，例如 `ebpf` 或 `polling`。未知时不返回。" + }, + "report_interval_ms": { + "type": "integer", + "format": "int64", + "description": "配置的上报间隔（毫秒）。未知时不返回。" + }, + "snapshot_ready": { + "type": "boolean", + "description": "agent 是否已产出至少一份完整快照。" + }, + "authoritative": { + "type": "boolean", + "description": "当前状态是否来自权威（authoritative）图快照。" + }, + "graph_available": { + "type": "boolean", + "description": "当前是否可以拉取到该主机的实时拓扑图。" + }, + "freshness_status": { + "type": "string", + "enum": [ + "fresh", + "stale", + "unknown" + ], + "description": "主机拓扑图的新鲜度分类。`fresh` = 最新快照在 2× 上报间隔内收到；`stale` = 超过该窗口未收到新快照；`unknown` = 尚未分类。未知时不返回。" + }, + "max_age_ms": { + "type": "integer", + "format": "int64", + "description": "快照被视为过期前可容忍的最大年龄（毫秒）。不适用时不返回。" + }, + "observed_at_ms": { + "type": "integer", + "format": "int64", + "description": "agent 最近一次观测到图生成的时间，Unix 毫秒时间戳。未知时不返回。" + }, + "received_at_ms": { + "type": "integer", + "format": "int64", + "description": "服务端最近一次收到快照的时间，Unix 毫秒时间戳。未知时不返回。" + }, + "node_count": { + "type": "integer", + "description": "该主机当前拓扑图中的节点数。" + }, + "edge_count": { + "type": "integer", + "description": "该主机当前拓扑图中的边数。" + }, + "reason_codes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "解释当前能力状态的机器可读原因码。为空时不返回。" + }, + "error_code": { + "type": "string", + "description": "实时状态读取失败时置为 `status_unavailable`，此时其余字段回退为清单侧的值。否则不返回。" + } + } + }, + "TargetInventoryServiceMapCoverage": { + "type": "object", + "description": "某一页目标的 ServiceMap 状态拉取覆盖情况。", + "required": [ + "requested", + "succeeded", + "failed", + "partial" + ], + "properties": { + "requested": { + "type": "integer", + "description": "本页携带 ServiceMap 数据的条目数。" + }, + "succeeded": { + "type": "integer", + "description": "实时 ServiceMap 状态读取成功的条目数。" + }, + "failed": { + "type": "integer", + "description": "实时 ServiceMap 状态读取失败的条目数（`servicemap.error_code` 已设置）。" + }, + "partial": { + "type": "boolean", + "description": "至少一个条目状态读取失败时为 true。" + } + } } } } diff --git a/api-reference/on-call.openapi.en.json b/api-reference/on-call.openapi.en.json index 47fd4c36..a50cbbad 100644 --- a/api-reference/on-call.openapi.en.json +++ b/api-reference/on-call.openapi.en.json @@ -75,7 +75,7 @@ "post": { "operationId": "channelInhibitRuleDelete", "summary": "Delete inhibit rule", - "description": "Delete an inhibit rule.", + "description": "Delete an inhibit rule. Only a `disabled` rule can be deleted.", "tags": [ "On-call/Channels" ], @@ -737,28 +737,13 @@ }, "responses": { "200": { - "description": "Success", + "description": "Success. CSV attachment, not a JSON envelope.", "content": { - "application/json": { + "text/csv": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/StatusPageSubscriberExportResponse" - } - } - } - ] + "$ref": "#/components/schemas/StatusPageSubscriberExportResponse" }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": "Method,Recipient,Components,Subscribe All,Locale\nemail,alice@example.com,,true,zh-CN\nemail,bob@example.com,,true,en-US" - } + "example": "Method,Recipient,Components,Subscribe All,Locale\nemail,alice@example.com,,Yes,zh-CN\nemail,bob@example.com,\"Core Services › API\",No,en-US" } } }, @@ -898,7 +883,7 @@ "post": { "operationId": "insightChannelExport", "summary": "Export channel insight", - "description": "Export channel insight metrics as a CSV file. CSV headers and formatted values use the request locale, falling back to the member locale and then the account locale. The response is a CSV stream delivered with `Content-Disposition: attachment` — it is not a JSON envelope.", + "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.", "tags": [ "On-call/Analytics" ], @@ -913,26 +898,13 @@ "200": { "description": "Success", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/EmptyResponse" - } - } - } - ] + "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`." }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": {} - } + "example": "channel_id,channel_name,total_incident_cnt,total_incidents_closed\n4321322010131,Production Alerts,12,10\n" } } }, @@ -1009,7 +981,7 @@ }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": {} + "data": null } } } @@ -1379,7 +1351,6 @@ "data": { "total": 1, "has_next_page": false, - "search_after_ctx": "", "items": [ { "alert_id": "663a1b2c3d4e5f6789abcdef", @@ -2561,7 +2532,7 @@ "post": { "operationId": "channelUnsubscribeRuleEnable", "summary": "Enable drop rule", - "description": "Enable a disabled drop rule.", + "description": "Enable a disabled drop rule. Only a `disabled` rule can be enabled.", "tags": [ "On-call/Channels" ], @@ -3181,7 +3152,7 @@ "duration": 132, "status": "success", "status_code": 200, - "event_time": "2026-04-12T13:31:11.357472+08:00" + "event_time": "2026-04-12 13:31:11.357472" } ], "search_after_ctx": "eyJldmVudF90aW1lIjoiMjAyNi0wNC0xMlQxMzoxNToyNi4zODI1NDcrMDg6MDAiLCJldmVudF9pZCI6IjIwMjYwNDEybUdzeFAzZHJwRmZzNFpDUWQycFNEcCJ9", @@ -3299,7 +3270,7 @@ "post": { "operationId": "channelSilenceRuleEnable", "summary": "Enable silence rule", - "description": "Enable a disabled silence rule.", + "description": "Enable a disabled silence rule. Only a `disabled` rule can be enabled.", "tags": [ "On-call/Channels" ], @@ -3687,7 +3658,7 @@ "post": { "operationId": "channelInhibitRuleEnable", "summary": "Enable inhibit rule", - "description": "Enable a disabled inhibit rule.", + "description": "Enable a disabled inhibit rule. Only a `disabled` rule can be enabled.", "tags": [ "On-call/Channels" ], @@ -3848,7 +3819,7 @@ "post": { "operationId": "channelUnsubscribeRuleDelete", "summary": "Delete drop rule", - "description": "Delete a drop rule.", + "description": "Delete a drop rule. Only a `disabled` rule can be deleted.", "tags": [ "On-call/Channels" ], @@ -4193,7 +4164,7 @@ "post": { "operationId": "insightIncidentExport", "summary": "Export insight incidents", - "description": "Export the filtered incident analytics list as a CSV file. CSV headers and formatted values use the request locale, falling back to the member locale and then the account locale. The response is a CSV stream delivered with `Content-Disposition: attachment` — it is not a JSON envelope.", + "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.", "tags": [ "On-call/Analytics" ], @@ -4208,26 +4179,13 @@ "200": { "description": "Success", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/EmptyResponse" - } - } - } - ] + "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`." }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": {} - } + "example": "incident_id,title,severity,created_at\n6a86b5d6f72de50ae1ce2ffb,CPU usage above 90%,Critical,2026-01-01 10:00:00 +0800 CST\n" } } }, @@ -4981,7 +4939,7 @@ "post": { "operationId": "channelEscalateRuleDisable", "summary": "Disable escalation rule", - "description": "Disable an escalation rule without deleting it.", + "description": "Disable an escalation rule without deleting it. Only an `enabled` rule can be disabled.", "tags": [ "On-call/Channels" ], @@ -5124,7 +5082,7 @@ "post": { "operationId": "channelDisable", "summary": "Disable channel", - "description": "Disable a channel to stop incident routing without deleting it.", + "description": "Disable a channel to stop incident routing without deleting it; a disabled channel discards incoming events. Only an `enabled` channel can be disabled.", "tags": [ "On-call/Channels" ], @@ -5243,7 +5201,7 @@ "status_code": 200, "response_headers": "{\"Content-Type\":\"application/json\"}", "response_body": "{\"ok\":true}", - "event_time": "2026-04-12T13:31:11.357472+08:00", + "event_time": "2026-04-12 13:31:11.357472", "ref_title": "High CPU Usage on host-01", "channel_name": "Production Alerts" } @@ -5454,7 +5412,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- 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-z][a-z0-9_]{0,39}$` (lowercase).\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 | **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" @@ -5791,7 +5749,7 @@ "post": { "operationId": "insightTeamExport", "summary": "Export team insight", - "description": "Export team insight metrics as a CSV file. CSV headers and formatted values use the request locale, falling back to the member locale and then the account locale. The response is a CSV stream delivered with `Content-Disposition: attachment` — it is not a JSON envelope.", + "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.", "tags": [ "On-call/Analytics" ], @@ -5806,26 +5764,13 @@ "200": { "description": "Success", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/EmptyResponse" - } - } - } - ] + "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`." }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": {} - } + "example": "team_id,team_name,total_incident_cnt,total_incidents_closed\n4295771902131,SRE Team,12,10\n" } } }, @@ -6766,6 +6711,7 @@ "incident_id": "69da451ef77b1b51f40e83ee", "account_id": 2451002751131, "channel_id": 2551105804131, + "team_id": 2477033058131, "integration_id": 2490562293131, "integration_ids": [ 2490562293131 @@ -6963,7 +6909,7 @@ "post": { "operationId": "statusPageSubscriberImport", "summary": "Import subscribers", - "description": "Bulk import subscribers for a status page.", + "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.", "tags": [ "On-call/Status pages" ], @@ -7754,7 +7700,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 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` (regex with named group `result`) or `g_json` (GJson path).\n- For `kind: composition`: `template` uses Go text/template syntax referencing `labels.*` keys.\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 | **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" @@ -7823,7 +7769,7 @@ "kind": "composition", "settings": { "result_label": "full_env", - "template": "{{.labels.region}}-{{.labels.environment}}", + "template": "{{.Labels.region}}-{{.Labels.environment}}", "override": false } } @@ -7838,7 +7784,7 @@ "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.", + "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.", "tags": [ "On-call/Alerts" ], @@ -7872,7 +7818,7 @@ "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { - "total": 1, + "total": 0, "has_next_page": false, "items": [ { @@ -7919,7 +7865,7 @@ "post": { "operationId": "channelEscalateRuleEnable", "summary": "Enable escalation rule", - "description": "Enable a disabled escalation rule.", + "description": "Enable a disabled escalation rule. Only a `disabled` rule can be enabled.", "tags": [ "On-call/Channels" ], @@ -8032,6 +7978,7 @@ "incident_id": "69da451ef77b1b51f40e83ee", "account_id": 2451002751131, "channel_id": 2551105804131, + "team_id": 2477033058131, "integration_id": 2490562293131, "integration_ids": [ 2490562293131 @@ -8422,7 +8369,7 @@ "post": { "operationId": "channelSilenceRuleDisable", "summary": "Disable silence rule", - "description": "Disable a silence rule without deleting it.", + "description": "Disable a silence rule without deleting it. Only an `enabled` rule can be disabled.", "tags": [ "On-call/Channels" ], @@ -8571,7 +8518,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. `alert_comment`, `alert_merge`).", + "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" @@ -8604,7 +8551,7 @@ "items": [ { "ref_id": "663a1b2c3d4e5f6789abcdef", - "type": "alert_comment", + "type": "a_comm", "detail": { "comment": "Investigating now." }, @@ -8651,7 +8598,7 @@ "post": { "operationId": "insightResponderExport", "summary": "Export responder insight", - "description": "Export responder insight metrics as a CSV file. CSV headers and formatted values use the request locale, falling back to the member locale and then the account locale. The response is a CSV stream delivered with `Content-Disposition: attachment` — it is not a JSON envelope.", + "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.", "tags": [ "On-call/Analytics" ], @@ -8666,26 +8613,13 @@ "200": { "description": "Success", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/EmptyResponse" - } - } - } - ] + "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`." }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": {} - } + "example": "responder_id,responder_name,total_incident_cnt,total_incidents_acknowledged\n3790925372131,alice,5,4\n" } } }, @@ -8770,6 +8704,7 @@ "incident_id": "69da451ef77b1b51f40e83ee", "account_id": 2451002751131, "channel_id": 2551105804131, + "team_id": 2477033058131, "integration_id": 2490562293131, "integration_ids": [ 2490562293131 @@ -9009,7 +8944,7 @@ "description": "Query CMDB for host metadata", "url": "https://cmdb.example.com/api/lookup", "headers": { - "X-Token": "***" + "Authorization": "Bearer eyJhbGciOiJIUzI1NiJ9.example-token" }, "timeout": 2, "retry_count": 1, @@ -9447,7 +9382,7 @@ "post": { "operationId": "channelDelete", "summary": "Delete channel", - "description": "Delete a channel and all associated configuration.", + "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.", "tags": [ "On-call/Channels" ], @@ -9986,28 +9921,15 @@ }, "responses": { "200": { - "description": "Success", + "description": "Success. CSV attachment stream, not a JSON envelope.", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/CsvFileResponse" - } - } - } - ] + "type": "string", + "format": "binary", + "description": "CSV file stream (`Content-Type: application/octet-stream`, `Content-Disposition: attachment; filename=.csv`). The header row lists the schema's source_labels followed by result_labels in order; each subsequent row is one mapping document." }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": "host,owner,team,service\nserver01,alice,sre,api\n" - } + "example": "host,owner,team\nserver01,alice,sre\nserver02,bob,backend\n" } } }, @@ -10495,7 +10417,7 @@ "post": { "operationId": "channelEnable", "summary": "Enable channel", - "description": "Enable a disabled channel to resume incident routing.", + "description": "Enable a channel to resume incident routing. Only a `disabled` channel can be enabled.", "tags": [ "On-call/Channels" ], @@ -10565,7 +10487,7 @@ "post": { "operationId": "channelEscalateRuleDelete", "summary": "Delete escalation rule", - "description": "Delete an escalation rule.", + "description": "Delete an escalation rule. Only a `disabled` rule can be deleted.", "tags": [ "On-call/Channels" ], @@ -10871,16 +10793,48 @@ "requestBody": { "required": true, "content": { - "application/json": { + "multipart/form-data": { "schema": { - "$ref": "#/components/schemas/MappingDataUploadRequest" - }, - "example": { - "schema_id": "665f1a2b3c4d5e6f7a8b9c01" + "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" + ] } } } - } + }, + "parameters": [ + { + "name": "schema_id", + "in": "query", + "required": true, + "schema": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$" + }, + "description": "ID of the target mapping schema (ObjectID hex).", + "example": "665f1a2b3c4d5e6f7a8b9c01" + }, + { + "name": "do_not_truncate_first", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "TRUE" + ] + }, + "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." + } + ] } }, "/alert/info": { @@ -11040,7 +10994,7 @@ "post": { "operationId": "channelInhibitRuleDisable", "summary": "Disable inhibit rule", - "description": "Disable an inhibit rule without deleting it.", + "description": "Disable an inhibit rule without deleting it. Only an `enabled` rule can be disabled.", "tags": [ "On-call/Channels" ], @@ -11294,7 +11248,7 @@ "post": { "operationId": "channelSilenceRuleDelete", "summary": "Delete silence rule", - "description": "Delete a silence rule.", + "description": "Delete a silence rule. Only a `disabled` rule can be deleted.", "tags": [ "On-call/Channels" ], @@ -12068,12 +12022,12 @@ "get": { "operationId": "statusPageChangeList", "summary": "List status page events", - "description": "List status page events with only publicly visible affected components.", + "description": "List status page events for console management. Unlike the public display endpoints, the response includes 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- Hidden affected components are omitted. Events remain in the result when none are visible, with an empty `affected_components` array.", + "content": "## Restrictions\n\n| Aspect | Value |\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", "metadata": { "sidebarTitle": "List status page events" @@ -12190,7 +12144,7 @@ "type": "integer", "format": "int64" }, - "description": "Filter events started at or after this unix timestamp (seconds)." + "description": "Lower bound of the event activity window: only events still open at, or closed at or after, this Unix timestamp (seconds) are returned." }, { "name": "end_at_seconds", @@ -12200,7 +12154,7 @@ "type": "integer", "format": "int64" }, - "description": "Filter events started at or before this unix timestamp (seconds)." + "description": "Upper bound of the event activity window: only events started at or before this Unix timestamp (seconds) are returned." }, { "name": "type", @@ -12231,7 +12185,7 @@ "completed" ] }, - "description": "Event status filter. Required. Must be a status valid for the given `type` (e.g. `investigating`/`identified`/`monitoring`/`resolved` for incidents; `scheduled`/`ongoing`/`completed` for maintenances)." + "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`)." } ] } @@ -12921,7 +12875,7 @@ "post": { "operationId": "channelUnsubscribeRuleDisable", "summary": "Disable drop rule", - "description": "Disable a drop rule without deleting it.", + "description": "Disable a drop rule without deleting it. Only an `enabled` rule can be disabled.", "tags": [ "On-call/Channels" ], @@ -13207,7 +13161,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- Only fields whose status is not `deleted` are returned; a deleted or unknown `field_id` yields a 400 error.\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 | **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" @@ -13297,7 +13251,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` and `display_name`; 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 | **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" @@ -13697,7 +13651,7 @@ "account_id": 10001, "channel_id": 5001, "channel_name": "Production", - "channel_status": "active", + "channel_status": "enabled", "integration_id": 362, "integration_name": "GitHub Deploy", "title": "Deploy api-server v2.3.1", @@ -14064,7 +14018,7 @@ "updated_by": 20001, "created_at": 1716962400, "updated_at": 1716962700, - "last_time": 1716963000, + "last_time": 0, "exclusive_data_source_id": 0, "integration_id": 362 } @@ -14212,7 +14166,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- If no member can be linked, the response contains an empty `new_linked_person_ids` array.", + "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" @@ -15173,7 +15127,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/StatusPageItem" + "$ref": "#/components/schemas/StatusPageInfoResponse" } } } @@ -15223,7 +15177,8 @@ "email": true, "im": false }, - "template_preference": "message" + "template_preference": "message", + "managed_domain_feature_enabled": true } } } @@ -15248,9 +15203,10 @@ "in": "query", "required": true, "schema": { - "type": "string" + "type": "integer", + "format": "int64" }, - "description": "Status page ID" + "description": "Status page ID." } ] } @@ -15854,9 +15810,9 @@ "type": "pre_defined", "template": { "title": "Service Disruption", - "event_type": "incident", "status": "investigating", - "description": "We are investigating a service disruption affecting some users." + "description": "We are investigating a service disruption affecting some users.", + "type": "incident" } } } @@ -15965,7 +15921,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/EmptyResponse" + "$ref": "#/components/schemas/ListStatusPageTemplatesResponse" } } } @@ -16840,7 +16796,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/EmptyResponse" + "$ref": "#/components/schemas/WorkItemMutationResult" } } } @@ -17430,7 +17386,8 @@ "properties": { "total": { "type": "integer", - "description": "Number of people holding an active license." + "description": "Number of people holding an active license.", + "format": "int64" }, "items": { "type": "array", @@ -17579,11 +17536,11 @@ "properties": { "component_id": { "type": "string", - "description": "Component ID." + "description": "Component ID. Omitted when empty." }, "section_id": { "type": "string", - "description": "Parent section ID." + "description": "Parent section ID. Omitted when the component sits at the top level." }, "name": { "type": "string", @@ -17591,25 +17548,25 @@ }, "description": { "type": "string", - "description": "Component description." + "description": "Component description. Omitted when empty." }, "available_since_seconds": { "type": "integer", "format": "int64", - "description": "Timestamp when the component was first available, in unix seconds." + "description": "Time the component became available, as a Unix timestamp in seconds. Omitted when 0." }, "order_id": { "type": "integer", "format": "int64", - "description": "Display order within its section." + "description": "Display order within its section. Omitted when 0." }, "hide_uptime": { "type": "boolean", - "description": "When true, uptime data is hidden from summary responses." + "description": "When true, uptime data is hidden from summary responses. Omitted when false." }, "hide_all": { "type": "boolean", - "description": "When true, the component is hidden entirely from summary endpoints." + "description": "When true, the component is hidden entirely from summary endpoints. Omitted when false." }, "status": { "type": "string", @@ -17629,27 +17586,46 @@ "description": "Filter and pagination criteria for the global raw event list.", "properties": { "start_time": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "Start of search window, Unix epoch seconds." + "description": "Start of the search window, Unix epoch seconds. Must be greater than 0 when provided.", + "exclusiveMinimum": 0 }, "end_time": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "End of search window, Unix epoch seconds." + "description": "End of the search window, Unix epoch seconds. Must be greater than `start_time` when provided." }, "p": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "Page number, starting at 1. Used when `search_after_ctx` is not provided." + "description": "Page number, starting at 1. Used when `search_after_ctx` is not provided.", + "minimum": 0 }, "limit": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "Page size, max 100, default 20." + "description": "Page size, max 100, default 20.", + "minimum": 0, + "maximum": 100 }, "search_after_ctx": { - "type": "string", + "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": { @@ -17673,11 +17649,12 @@ "type": "integer", "format": "int64" }, - "description": "Filter by channel IDs. Max 100." + "description": "Filter by channel IDs. At most 100 entries.", + "maxItems": 100 }, "severities": { "type": "string", - "description": "Comma-separated severity filter, e.g. `Critical,Warning`." + "description": "Comma-separated severity filter, e.g. `Critical,Warning`. Accepted values: `Critical`, `Warning`, `Info`, `Ok`." }, "orderby": { "type": "string", @@ -17706,7 +17683,7 @@ }, "search_after_ctx": { "type": "string", - "description": "Cursor for the next page — the ObjectID of the last event on this page; pass it back as `search_after_ctx`. Omitted when there are no more results or the result is empty." + "description": "Cursor for the next page — the ObjectID of the last event 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", @@ -17776,10 +17753,9 @@ "enum": [ "Critical", "Warning", - "Info", - "Ok" + "Info" ], - "description": "Severity of this event." + "description": "Severity of this event: `Critical`, `Warning`, or `Info`. An event never carries `Ok` as severity — `Ok` appears only as `event_status`." }, "event_status": { "type": "string", @@ -17789,7 +17765,7 @@ "Info", "Ok" ], - "description": "Status of this event." + "description": "Status carried by this event: `Critical`/`Warning`/`Info` for a firing event, `Ok` for a recovery event." }, "event_time": { "type": "integer", @@ -17823,7 +17799,7 @@ "deleted_at": { "type": "integer", "format": "int64", - "description": "Soft-delete timestamp (seconds). Zero if not deleted." + "description": "Soft-delete time, Unix epoch seconds. Omitted when the event is not deleted." } } }, @@ -17844,7 +17820,10 @@ "description": "When true, return events oldest-first. Defaults to newest-first." }, "limit": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", "minimum": 0, "maximum": 100, @@ -17852,14 +17831,20 @@ "description": "Page size. Defaults to 20 and cannot exceed 100." }, "p": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", "minimum": 0, "default": 1, "description": "Page number starting at 1. Used when `search_after_ctx` is omitted." }, "search_after_ctx": { - "type": "string", + "type": [ + "string", + "null" + ], "pattern": "^[0-9a-fA-F]{24}$", "description": "Cursor returned by the previous page. When supplied, cursor pagination is used instead of page-number pagination." } @@ -17883,7 +17868,7 @@ "total": { "type": "integer", "format": "int64", - "description": "Total matching event count." + "description": "Total matching event count, capped at 1000." }, "has_next_page": { "type": "boolean", @@ -17891,7 +17876,7 @@ }, "search_after_ctx": { "type": "string", - "description": "Cursor to pass as `search_after_ctx` for the next page." + "description": "Cursor to pass as `search_after_ctx` for the next page. Omitted when the page is empty; in cursor mode also omitted when there is no next page." } } }, @@ -17903,18 +17888,22 @@ "properties": { "alert_id": { "type": "string", - "description": "Alert ID; obtain it from `POST /alert/list`." + "description": "Alert ID (ObjectID hex string); obtain it from `POST /alert/list`.", + "pattern": "^[0-9a-fA-F]{24}$" }, "p": { "type": "integer", "format": "int64", "description": "Page number, starting at 1.", - "default": 1 + "default": 1, + "minimum": 1 }, "limit": { "type": "integer", "format": "int64", - "description": "Page size, max 100, default 20." + "description": "Page size, max 100, default 20.", + "minimum": 1, + "maximum": 100 }, "asc": { "type": "boolean", @@ -17925,7 +17914,7 @@ "items": { "type": "string" }, - "description": "Filter by feed type codes (e.g. `a_new`, `a_close`, `a_ack`)." + "description": "Filter by feed type codes — see the `type` field of the response items for the full list (e.g. `a_new`, `a_comm`, `a_merge`)." } } }, @@ -17947,14 +17936,17 @@ }, "AlertFeedType": { "type": "string", - "description": "Alert activity feed entry type. Each value identifies one alert lifecycle event; the matching `detail` payload shape is determined by this field.\n\n| Type | Meaning |\n|---|---|\n| `a_new` | Alert triggered. |\n| `a_update` | Alert updated by an incoming event (e.g. severity or status change). |\n| `a_merge` | Alert merged. |\n| `a_comm` | Comment added on the alert. |\n| `a_m_silence` | Alert muted by a silence rule. |\n| `a_m_inhibit` | Alert muted by an inhibit rule. |\n| `a_close` | Alert closed (historical data only; no longer produced). |", + "description": "Alert activity feed entry type. Each value identifies one alert lifecycle event; the matching `detail` payload shape is determined by this field.\n\n| Type | Meaning |\n|---|---|\n| `a_new` | Alert triggered by an incoming event. |\n| `a_update` | Alert severity or status changed on an incoming event. |\n| `a_comm` | Comment added on the alert. |\n| `a_merge` | Alert merged into an incident. |\n| `a_m_silence` | Alert muted by a silence rule. |\n| `a_m_inhibit` | Alert muted by an inhibit rule. |\n| `a_m_flapping` | Alert muted by flapping detection (historical data only; no longer produced). |\n| `a_ack` | Alert acknowledged (historical data only; alert-level acknowledgement has been removed). |\n| `a_unack` | Alert acknowledgement revoked (historical data only). |\n| `a_close` | Alert closed (historical data only; no longer produced). |", "enum": [ "a_new", "a_update", - "a_merge", "a_comm", + "a_merge", "a_m_silence", "a_m_inhibit", + "a_m_flapping", + "a_ack", + "a_unack", "a_close" ] }, @@ -18189,7 +18181,8 @@ "properties": { "alert_id": { "type": "string", - "description": "Alert ID (ObjectID hex string)." + "description": "Alert ID (ObjectID hex string).", + "pattern": "^[0-9a-fA-F]{24}$" } } }, @@ -18209,7 +18202,7 @@ "data_source_id": { "type": "integer", "format": "int64", - "description": "Deprecated. Use `integration_id` instead. Deprecated: use `integration_id` instead.", + "description": "Deprecated: use `integration_id` instead.", "deprecated": true }, "channel_id": { @@ -18239,10 +18232,9 @@ "enum": [ "Critical", "Warning", - "Info", - "Ok" + "Info" ], - "description": "Current severity." + "description": "Current severity — the highest severity ever seen on this alert: `Critical`, `Warning`, or `Info`." }, "alert_status": { "type": "string", @@ -18252,7 +18244,7 @@ "Info", "Ok" ], - "description": "Current status." + "description": "Current status: `Critical`/`Warning`/`Info` while firing, `Ok` once recovered." }, "alert_key": { "type": "string", @@ -18312,15 +18304,19 @@ }, "channel_status": { "type": "string", - "description": "Status of the channel (e.g. `enabled`, `disabled`)." + "description": "Status of the channel: `enabled` or `disabled`.", + "enum": [ + "enabled", + "disabled" + ] }, "responder_name": { "type": "string", - "description": "Display name of the current responder (from the associated incident)." + "description": "Responder display name. Always empty in this response — responder tracking lives on the associated incident." }, "responder_email": { "type": "string", - "description": "Email of the current responder (from the associated incident)." + "description": "Responder email. Always empty in this response — responder tracking lives on the associated incident." }, "event_cnt": { "type": "integer", @@ -18336,7 +18332,7 @@ "items": { "$ref": "#/components/schemas/AlertEventItem" }, - "description": "Recent raw events attached to this alert. Populated only by some endpoints." + "description": "Raw events of this alert. Omitted here; populated only by `POST /incident/alert/list`." }, "images": { "type": "array", @@ -18347,15 +18343,23 @@ }, "data_source_name": { "type": "string", - "description": "Deprecated. Use `integration_name` instead." + "description": "Deprecated: use `integration_name` instead.", + "deprecated": true }, "data_source_type": { "type": "string", - "description": "Deprecated. Use `integration_type` instead." + "description": "Deprecated: use `integration_type` instead. Omitted when empty.", + "deprecated": true }, "data_source_ref_id": { "type": "string", - "description": "Deprecated. Use `integration_ref_id` instead." + "description": "Deprecated: use `integration_ref_id` instead.", + "deprecated": true + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "Soft-delete time, Unix epoch seconds. Omitted when the alert is not deleted." } } }, @@ -18370,7 +18374,8 @@ "items": { "type": "string" }, - "description": "List of alert IDs (ObjectID hex strings)." + "description": "Alert IDs (ObjectID hex strings) to fetch.", + "minItems": 1 } } }, @@ -18390,20 +18395,32 @@ "end_time": { "type": "integer", "format": "int64", - "description": "End of the search window, Unix epoch seconds. Max span 31 days." + "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." }, "p": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "Page number, starting at 1. Used when `search_after_ctx` is not provided." + "description": "Page number, starting at 1. Used when `search_after_ctx` is not provided; `p * limit` must stay within 10,000 records.", + "minimum": 0 }, "limit": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "Page size. Max 100, default 20." + "description": "Page size. Max 100, default 20.", + "minimum": 0, + "maximum": 100 }, "search_after_ctx": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "Opaque cursor from the previous response for the next page." }, "is_active": { @@ -18411,7 +18428,7 @@ "boolean", "null" ], - "description": "Filter by active (`true`) or resolved (`false`) status." + "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." }, "ever_muted": { "type": [ @@ -18445,7 +18462,7 @@ "items": { "type": "string" }, - "description": "Filter to specific alert IDs (ObjectID hex strings)." + "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", @@ -18454,17 +18471,9 @@ }, "description": "Filter by alert deduplication keys." }, - "orderby": { - "type": "string", - "enum": [ - "created_at", - "updated_at" - ], - "description": "Sort field." - }, "asc": { "type": "boolean", - "description": "Sort ascending when `true`. Default descending." + "description": "Sort ascending by `start_time` when `true`; default is descending." }, "by_updated_at": { "type": "boolean", @@ -18479,7 +18488,7 @@ "total": { "type": "integer", "format": "int64", - "description": "Total matching alerts." + "description": "Total matching alerts, capped at 1000." }, "has_next_page": { "type": "boolean", @@ -18487,7 +18496,7 @@ }, "search_after_ctx": { "type": "string", - "description": "Cursor for the next page." + "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." }, "items": { "type": "array", @@ -18510,19 +18519,23 @@ "items": { "type": "string" }, - "description": "Alert IDs to merge; obtain them from `POST /alert/list`." + "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 }, "incident_id": { "type": "string", - "description": "Target incident ID; obtain it from `POST /incident/list`." + "description": "Target incident ID (ObjectID hex string); obtain it from `POST /incident/list`.", + "pattern": "^[0-9a-fA-F]{24}$" }, "comment": { "type": "string", - "description": "Optional comment on the merge action." + "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." + "description": "Optional new title for the target incident. At most 512 characters.", + "maxLength": 512 }, "owner_id": { "type": "integer", @@ -18547,11 +18560,14 @@ "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", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/FilterCondition" }, - "description": "Optional AND-filter list — the rule applies only when every condition matches. Omit to apply the rule to all alerts." + "description": "AND-filter list — the rule applies only when every condition matches. `null` or omitted means the rule applies to all events." }, "settings": { "type": "object", @@ -18574,7 +18590,10 @@ } ] } - } + }, + "required": [ + "kind" + ] }, "AlertPipelineInfoRequest": { "type": "object", @@ -18585,7 +18604,8 @@ "integration_id": { "type": "integer", "format": "int64", - "description": "Integration ID." + "description": "Integration ID. Must be greater than 0.", + "exclusiveMinimum": 0 } } }, @@ -18607,7 +18627,10 @@ }, "status": { "type": "string", - "description": "Pipeline status. Possible values: `enabled`, `disabled`." + "description": "Pipeline status. Always `enabled` in these responses — deleted pipelines are filtered out.", + "enum": [ + "enabled" + ] }, "creator_id": { "type": "integer", @@ -18628,6 +18651,11 @@ "type": "integer", "format": "int64", "description": "Last update timestamp, Unix epoch seconds." + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "Soft-delete time, Unix epoch seconds. Omitted when not deleted." } } }, @@ -18643,7 +18671,8 @@ "type": "integer", "format": "int64" }, - "description": "Integration IDs." + "description": "Integration IDs. At least one entry is required.", + "minItems": 1 } } }, @@ -18676,8 +18705,9 @@ "items": { "$ref": "#/components/schemas/AlertPipeline" }, - "description": "Rules to apply. Max 50.", - "maxItems": 50 + "description": "Rules to apply, evaluated in array order. Between 1 and 50 entries.", + "maxItems": 50, + "minItems": 1 } } }, @@ -18995,7 +19025,8 @@ }, "total": { "type": "integer", - "description": "Total number of events returned." + "description": "Total number of events returned.", + "format": "int64" } } }, @@ -19039,10 +19070,7 @@ "description": "Event end date in YYYY-MM-DD (exclusive)." }, "is_off": { - "type": [ - "boolean", - "null" - ], + "type": "boolean", "description": "Whether the event marks a non-working day. true = day off, false = working day override." } } @@ -19095,7 +19123,7 @@ }, "team_id": { "type": "integer", - "format": "int64", + "format": "uint64", "description": "Owning team ID. 0 means no team." }, "workdays": { @@ -19212,14 +19240,14 @@ "minimum": 0, "maximum": 6 }, - "description": "Workday numbers (0 = Sunday, 6 = Saturday)." + "description": "Workday numbers (0 = Sunday, 6 = Saturday). Omitted when empty." }, "extra_cal_ids": { "type": "array", "items": { "type": "string" }, - "description": "Inherited public-holiday calendar IDs." + "description": "Inherited public-holiday calendar IDs. Omitted when empty." }, "created_at": { "type": "integer", @@ -19286,7 +19314,8 @@ }, "total": { "type": "integer", - "description": "Total number of calendars returned." + "description": "Total number of calendars returned.", + "format": "int64" } } }, @@ -19330,7 +19359,7 @@ "integer", "null" ], - "format": "int64", + "format": "uint64", "description": "New owning team ID; obtain it from `POST /team/list`." }, "workdays": { @@ -19360,7 +19389,7 @@ "properties": { "job_id": { "type": "string", - "description": "Migration job ID, returned when the migration job is created; check progress via `POST /status-page/migration/status`." + "description": "Migration job ID, returned when the migration job is created; check progress via `GET /status-page/migration/status`." } } }, @@ -19504,17 +19533,17 @@ "deleted_at": { "type": "integer", "format": "int64", - "description": "Deletion timestamp (unix seconds). Non-zero only for soft-deleted channels." + "description": "Deletion time, Unix timestamp in seconds. Non-zero only for soft-deleted channels." }, "created_at": { "type": "integer", "format": "int64", - "description": "Creation timestamp (unix seconds)." + "description": "Creation time, Unix timestamp in seconds." }, "updated_at": { "type": "integer", "format": "int64", - "description": "Last update timestamp (unix seconds)." + "description": "Last update time, Unix timestamp in seconds." }, "auto_resolve_timeout": { "type": "integer", @@ -19542,26 +19571,34 @@ "description": "When true, automatic incident closing is disabled." }, "group": { - "$ref": "#/components/schemas/Group" + "$ref": "#/components/schemas/Group", + "description": "Alert grouping configuration." }, "flapping": { - "$ref": "#/components/schemas/Flapping" + "$ref": "#/components/schemas/Flapping", + "description": "Flapping detection configuration." }, "progress_to_incident_cnts": { - "$ref": "#/components/schemas/IncProgressCnts" + "$ref": "#/components/schemas/IncProgressCnts", + "description": "Incident counts by progress over the last 30 days." }, "is_starred": { "type": "boolean", - "description": "Whether the current user has starred this channel." + "description": "Whether the current user has starred this channel. Present only in `POST /channel/list` responses." }, "active_incident_highest_severity": { "type": "string", - "description": "Highest severity among active incidents in the channel." + "enum": [ + "Critical", + "Warning", + "Info" + ], + "description": "Highest severity among the channel's active (triggered or processing) incidents: `Critical`, `Warning` or `Info`. Omitted when there are no active incidents." }, "last_incident_at": { "type": "integer", "format": "int64", - "description": "Timestamp of the most recent incident (unix seconds)." + "description": "Time of the most recent incident, Unix timestamp in seconds." }, "is_external_report_enabled": { "type": "boolean", @@ -19569,7 +19606,11 @@ }, "external_report_token": { "type": "string", - "description": "Token granted to external reporters when external reporting is enabled." + "description": "Token granted to external reporters. Omitted unless external reporting is enabled on the channel." + }, + "event_group": { + "$ref": "#/components/schemas/EventGroup", + "description": "Alert event merge configuration." } } }, @@ -19625,9 +19666,10 @@ "type": "string", "enum": [ "enabled", - "disabled" + "disabled", + "deleted" ], - "description": "Channel status." + "description": "Channel status: `enabled` processes events normally; `disabled` discards incoming events; `deleted` is soft-deleted." } } }, @@ -19635,7 +19677,8 @@ "type": "object", "description": "Parameters for adding a comment to one or more incidents.", "required": [ - "incident_ids" + "incident_ids", + "comment" ], "properties": { "incident_ids": { @@ -19771,21 +19814,21 @@ "items": { "type": "string" }, - "description": "Channels for Critical events (e.g. `voice`, `sms`, `email`, `feishu`)." + "description": "Notify channels used for Critical severity. Personal channels: `sms`, `voice`, `email`, `push`; IM group-chat channels: `feishu_app:`, `dingtalk_app:`, `wecom_app:`, `slack_app:`, `teams_app:`." }, "warning": { "type": "array", "items": { "type": "string" }, - "description": "Channels for Warning events." + "description": "Notify channels used for Warning severity. Values as for `critical`." }, "info": { "type": "array", "items": { "type": "string" }, - "description": "Channels for Info events." + "description": "Notify channels used for Info severity. Values as for `critical`." } } }, @@ -19801,7 +19844,7 @@ "properties": { "type": { "type": "string", - "description": "Webhook type (e.g. `feishu`, `dingtalk_app`, `wecom_app`, `slack`, `teams`, `custom`)." + "description": "Webhook type, one of `feishu`, `feishu_app`, `dingtalk`, `dingtalk_app`, `wecom`, `slack`, `slack_app`, `teams_app`, `telegram`, `zoom`." }, "settings": { "type": "object", @@ -19847,7 +19890,30 @@ "maxItems": 100, "description": "Per-filter grouping overrides.", "items": { - "type": "object" + "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.`." + } + } } }, "all_equals_required": { @@ -19964,6 +20030,10 @@ "is_external_report_enabled": { "type": "boolean", "description": "Allow external reporters to file incidents into this channel." + }, + "event_group": { + "$ref": "#/components/schemas/EventGroup", + "description": "Alert event merge configuration. Omit to use the default (merge enabled, 1440-minute window)." } } }, @@ -19993,7 +20063,7 @@ }, "filters": { "type": "array", - "description": "Or-of-and filter tree. Each outer element is an AND group; within each group, all conditions must match.", + "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": { @@ -20149,21 +20219,21 @@ "items": { "type": "string" }, - "description": "Channels for Critical events (e.g. `voice`, `sms`, `email`, `feishu`)." + "description": "Notify channels used for Critical severity. Personal channels: `sms`, `voice`, `email`, `push`; IM group-chat channels: `feishu_app:`, `dingtalk_app:`, `wecom_app:`, `slack_app:`, `teams_app:`." }, "warning": { "type": "array", "items": { "type": "string" }, - "description": "Channels for Warning events." + "description": "Notify channels used for Warning severity. Values as for `critical`." }, "info": { "type": "array", "items": { "type": "string" }, - "description": "Channels for Info events." + "description": "Notify channels used for Info severity. Values as for `critical`." } } }, @@ -20179,7 +20249,7 @@ "properties": { "type": { "type": "string", - "description": "Webhook type (e.g. `feishu`, `dingtalk_app`, `wecom_app`, `slack`, `teams`, `custom`)." + "description": "Webhook type, one of `feishu`, `feishu_app`, `dingtalk`, `dingtalk_app`, `wecom`, `slack`, `slack_app`, `teams_app`, `telegram`, `zoom`." }, "settings": { "type": "object", @@ -20239,7 +20309,7 @@ }, "filters": { "type": "array", - "description": "Or-of-and filter tree. Each outer element is an AND group; within each group, all conditions must match.", + "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": { @@ -20431,11 +20501,11 @@ "items": { "type": "string" }, - "description": "Label keys used to pair source and target alerts." + "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`." }, "source_filters": { "type": "array", - "description": "Or-of-and filter tree. Each outer element is an AND group; within each group, all conditions must match.", + "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.`. Empty makes the rule inert.", "items": { "type": "array", "items": { @@ -20471,7 +20541,7 @@ }, "target_filters": { "type": "array", - "description": "Or-of-and filter tree. Each outer element is an AND group; within each group, all conditions must match.", + "description": "Conditions the incoming target alert event must match to be suppressed; empty means every event is a target.", "items": { "type": "array", "items": { @@ -20507,7 +20577,7 @@ }, "is_directly_discard": { "type": "boolean", - "description": "When true, suppressed target alerts are dropped instead of merged." + "description": "When true, matching alert events are discarded entirely; when false, alerts are still recorded but marked as muted by this rule." } } }, @@ -20537,7 +20607,8 @@ }, "from_incident_id": { "type": "string", - "description": "Source incident ID when the silence was created from an incident." + "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}$" }, "time_filters": { "type": "array", @@ -20583,18 +20654,20 @@ "start_time": { "type": "integer", "format": "int64", - "description": "Window start (unix seconds). Must be less than `end_time`." + "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 seconds)." + "description": "Window end, Unix timestamp in seconds. Must be greater than 0.", + "exclusiveMinimum": 0 } } }, "filters": { "type": "array", - "description": "Or-of-and filter tree. Each outer element is an AND group; within each group, all conditions must match.", + "description": "Alert event match conditions (OR-of-AND). Required and must contain at least one condition.", "items": { "type": "array", "items": { @@ -20630,7 +20703,7 @@ }, "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 muted by this rule." }, "is_auto_delete": { "type": "boolean", @@ -20645,6 +20718,7 @@ "page_id", "type", "title", + "description", "status", "updates" ], @@ -20652,7 +20726,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "type": { "type": "string", @@ -20669,7 +20743,7 @@ }, "description": { "type": "string", - "description": "Event description (Markdown). Required by the validator." + "description": "Event description (Markdown). Must not be empty." }, "status": { "type": "string", @@ -20687,7 +20761,7 @@ "start_at_seconds": { "type": "integer", "format": "int64", - "description": "Event start time in unix seconds. Defaults to now when omitted." + "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`." }, "responders": { "type": "array", @@ -20695,7 +20769,7 @@ "type": "integer", "format": "int64" }, - "description": "Member IDs responsible for the change; obtain member IDs from `POST /member/list`." + "description": "Member IDs responsible for the event." }, "linked_changes": { "type": "array", @@ -20707,7 +20781,7 @@ "close_at_seconds": { "type": "integer", "format": "int64", - "description": "Scheduled close time for retrospective events. Must be greater than `start_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." }, "updates": { "type": "array", @@ -20722,10 +20796,13 @@ "at_seconds": { "type": "integer", "format": "int64", - "description": "Update timestamp in unix seconds." + "description": "Update timestamp in Unix seconds. When omitted or 0 on the first update, defaults to the current time." }, "status": { - "type": "string", + "type": [ + "string", + "null" + ], "enum": [ "investigating", "identified", @@ -20735,10 +20812,13 @@ "ongoing", "completed" ], - "description": "Change status after this update. May be omitted 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": "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", + "type": [ + "string", + "null" + ], "description": "Update description (Markdown)." }, "component_changes": { @@ -20752,7 +20832,7 @@ "properties": { "component_id": { "type": "string", - "description": "Component ID; obtain it from `POST /status-page/info`." + "description": "Component ID; obtain it from `GET /status-page/info`." }, "status": { "type": "string", @@ -20771,7 +20851,8 @@ } } }, - "description": "Timeline updates. Immediate events normally pass one update; retrospective events must pass all historical 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.", + "minItems": 1 }, "notify_subscribers": { "type": "boolean", @@ -20793,23 +20874,24 @@ "required": [ "page_id", "change_id", - "status" + "status", + "description" ], "properties": { "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "change_id": { "type": "integer", "format": "int64", - "description": "Target change ID; obtain it from `POST /status-page/change/list`." + "description": "Target change ID; obtain it from `GET /status-page/change/list`." }, "at_seconds": { "type": "integer", "format": "int64", - "description": "Update timestamp in unix seconds. Defaults to now when omitted." + "description": "Update timestamp in Unix seconds. Defaults to the current time when omitted or 0." }, "status": { "type": "string", @@ -20822,11 +20904,11 @@ "ongoing", "completed" ], - "description": "Change status after this update; must match 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| `scheduled` | Scheduled (maintenance). |\n| `ongoing` | In progress (maintenance). |" + "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": { "type": "string", - "description": "Update description (Markdown). Required." + "description": "Update description (Markdown). Must not be empty." }, "component_changes": { "type": "array", @@ -20839,7 +20921,7 @@ "properties": { "component_id": { "type": "string", - "description": "Component ID; obtain it from `POST /status-page/info`." + "description": "Component ID; obtain it from `GET /status-page/info`." }, "status": { "type": "string", @@ -20890,10 +20972,6 @@ } } }, - "CsvFileResponse": { - "type": "string", - "description": "CSV file content returned as an attachment download." - }, "DeletePostMortemRequest": { "type": "object", "description": "Parameters for deleting a post-mortem report.", @@ -20918,12 +20996,12 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "change_id": { "type": "integer", "format": "int64", - "description": "Target change ID; obtain it from `POST /status-page/change/list`." + "description": "Target change ID; obtain it from `GET /status-page/change/list`." } } }, @@ -20939,16 +21017,16 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "change_id": { "type": "integer", "format": "int64", - "description": "Owning change ID; obtain it from `POST /status-page/change/list`." + "description": "Owning change ID; obtain it from `GET /status-page/change/list`." }, "update_id": { "type": "string", - "description": "Timeline update ID to delete; obtain it from `POST /status-page/change/info`." + "description": "Timeline update ID to delete; obtain it from `GET /status-page/change/info`." } } }, @@ -21059,22 +21137,22 @@ "mean_seconds_to_ack": { "type": "number", "format": "double", - "description": "Mean time to first acknowledgement in seconds." + "description": "Mean time to first acknowledgement in seconds; 0 when no incident in the bucket was acknowledged." }, "mean_seconds_to_close": { "type": "number", "format": "double", - "description": "Mean time to close in seconds." + "description": "Mean time to close in seconds; 0 when no incident in the bucket was closed." }, "noise_reduction_pct": { "type": "number", "format": "double", - "description": "Noise reduction ratio (%): `100 − incidents ÷ alert events × 100`; 0 when no alert-event comparison data exists." + "description": "Noise reduction ratio (%): 100 − incidents ÷ alert events × 100, rounded to two decimals; 0 when there is no alert-event data or alert events do not exceed incidents." }, "acknowledgement_pct": { "type": "number", "format": "double", - "description": "Acknowledgement rate (%): acknowledged incidents ÷ total incidents × 100, rounded to two decimals; 100 when there are no incidents." + "description": "Acknowledgement rate (%): acknowledged incidents ÷ total incidents × 100, rounded to two decimals and capped at 100; 0 when the bucket has no incidents." }, "total_alert_cnt": { "type": "integer", @@ -21115,7 +21193,8 @@ "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, - "description": "Incident IDs whose automatic merge should be disabled." + "description": "Incident IDs whose automatic merge should be disabled.", + "minItems": 1 } } }, @@ -21193,7 +21272,8 @@ "properties": { "key": { "type": "string", - "description": "Alert label key." + "description": "Event key to match on (e.g. `labels.severity`, `title`). Must be non-empty.", + "minLength": 1 }, "oper": { "type": "string", @@ -21208,7 +21288,8 @@ "items": { "type": "string" }, - "description": "Values to match against." + "description": "Values to match against. Must contain at least one value.", + "minItems": 1 } } }, @@ -21228,14 +21309,17 @@ "mapping", "drop" ], - "description": "Rule type. `extraction` extracts a label via regex or GJson. `composition` builds a label from a template. `mapping` looks up values from a schema or API. `drop` removes labels." + "description": "Rule type.\n| Value | Meaning |\n|---|---|\n| `extraction` | Extract a value from the alert's `title`, `description`, or a `labels.*` key via regex or GJson, and write it to a label. |\n| `composition` | Render a Go `text/template` against the event and write the result to a label. |\n| `mapping` | Look up labels from a mapping schema or an external mapping API. |\n| `drop` | Remove the listed labels from the alert. |" }, "if": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/EnrichFilter" }, - "description": "Optional AND-filter list. The rule is skipped if the condition does not match." + "description": "Optional AND-filter list; the rule is skipped unless every filter matches. `null` when the rule has no condition. Filter keys come from the alert/change event vocabulary (e.g. `title`, `labels.severity`)." }, "settings": { "description": "Rule-kind–specific settings. The shape depends on `kind`.", @@ -21297,7 +21381,11 @@ }, "status": { "type": "string", - "description": "Rule set status." + "enum": [ + "enabled", + "deleted" + ], + "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", @@ -21318,6 +21406,11 @@ "type": "integer", "format": "int64", "description": "Last update timestamp, Unix seconds." + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "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": [ @@ -21342,7 +21435,8 @@ "type": "integer", "format": "int64" }, - "description": "List of integration IDs to query." + "description": "List of integration IDs to query. Must contain at least one ID.", + "minItems": 1 } } }, @@ -21459,12 +21553,14 @@ "properties": { "result_label": { "type": "string", - "description": "Destination label key to write the composed value into. Must match `^[a-z][a-z0-9_]{0,62}$`." + "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_]*$" }, "template": { "type": "string", "maxLength": 500, - "description": "Go `text/template` string. Alert fields are available as `{{.title}}`, `{{.description}}`, and `{{.labels.key}}`. Example: `{{.labels.region}}-{{.labels.env}}`." + "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", @@ -21502,11 +21598,12 @@ }, "result_label": { "type": "string", - "description": "Destination label key to write the extracted value into. Must match `^[a-z][a-z0-9_]{0,62}$`." + "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": { "type": "string", - "description": "RE2 regular expression. Use a named capture group `(?P...)` to extract a sub-match; without a named group the full match is used. Mutually exclusive with `g_json`." + "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`." }, "g_json": { "type": "string", @@ -21528,9 +21625,10 @@ "result_labels": { "type": "array", "items": { - "type": "string" + "type": "string", + "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, - "description": "Label keys to populate from the mapping lookup result." + "description": "Label keys to populate from the mapping lookup result. Each must match `^[a-zA-Z_][a-zA-Z0-9_]*$`." }, "mapping_type": { "type": "string", @@ -21650,15 +21748,17 @@ "description": "Recurring time windows during which the rule applies." }, "filters": { - "$ref": "#/components/schemas/FilterGroup" + "$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." }, "status": { "type": "string", "enum": [ "enabled", - "disabled" + "disabled", + "deleted" ], - "description": "Rule 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)." }, "template_id": { "type": "string", @@ -21678,17 +21778,17 @@ "deleted_at": { "type": "integer", "format": "int64", - "description": "Deletion timestamp (unix seconds). Emitted only for soft-deleted rules." + "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 timestamp (unix seconds)." + "description": "Creation time, Unix timestamp in seconds." }, "updated_at": { "type": "integer", "format": "int64", - "description": "Last update timestamp (unix seconds)." + "description": "Last update time, Unix timestamp in seconds." }, "channel_name": { "type": "string", @@ -21748,21 +21848,21 @@ "items": { "type": "string" }, - "description": "Channels for Critical events (e.g. `voice`, `sms`, `email`, `feishu`)." + "description": "Notify channels used for Critical severity. Personal channels: `sms`, `voice`, `email`, `push`; IM group-chat channels: `feishu_app:`, `dingtalk_app:`, `wecom_app:`, `slack_app:`, `teams_app:`." }, "warning": { "type": "array", "items": { "type": "string" }, - "description": "Channels for Warning events." + "description": "Notify channels used for Warning severity. Values as for `critical`." }, "info": { "type": "array", "items": { "type": "string" }, - "description": "Channels for Info events." + "description": "Notify channels used for Info severity. Values as for `critical`." } } }, @@ -21778,7 +21878,7 @@ "properties": { "type": { "type": "string", - "description": "Webhook type (e.g. `feishu`, `dingtalk_app`, `wecom_app`, `slack`, `teams`, `custom`)." + "description": "Webhook type, one of `feishu`, `feishu_app`, `dingtalk`, `dingtalk_app`, `wecom`, `slack`, `slack_app`, `teams_app`, `telegram`, `zoom`." }, "settings": { "type": "object", @@ -21800,7 +21900,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "component_ids": { "type": "array", @@ -21846,7 +21946,7 @@ }, "locale": { "type": "string", - "description": "Preferred locale for notifications." + "description": "Preferred locale for notifications. Omitted when empty." } } }, @@ -21888,6 +21988,17 @@ "progress": { "type": "string", "description": "Progress note entered at acknowledgement." + }, + "comment": { + "type": "string", + "description": "Form summary recorded as a timeline comment. Omitted when no acknowledgement form summary was submitted." + }, + "images": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Image" + }, + "description": "Images from the acknowledgement form, recorded on the timeline entry only. Omitted when none were submitted." } }, "title": "i_ack" @@ -22230,6 +22341,17 @@ "escalation" ], "description": "Source that triggered the resolve.\n| Value | Meaning |\n|---|---|\n| `voice` | Phone-call (voice DTMF) action. |\n| `console` | Console (Web UI) action. |\n| `card` | IM notification card button (DingTalk/Feishu/Slack/Teams). |\n| `wcard` | WeCom notification card button. |\n| `event` | Event-driven: auto-close when all related alerts recover to Ok, or a close synced from an external ITSM system. |\n| `autorslv` | Auto-resolve: closed by the system after no new alerts within the channel's auto-resolve timeout. |\n| `autorefresh` | Card auto-refresh (reserved; never appears on resolve feeds). |\n| `escalation` | Escalation flow (reserved; never appears on resolve feeds). |" + }, + "comment": { + "type": "string", + "description": "Form summary recorded as a timeline comment on resolution. Omitted when no resolve form summary was submitted." + }, + "images": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Image" + }, + "description": "Images from the resolve form, recorded on the timeline entry only. Omitted when none were submitted." } }, "title": "i_rslv" @@ -22362,14 +22484,35 @@ "$ref": "#/components/schemas/AlertFeedType" }, "detail": { - "description": "Type-specific payload. The concrete shape is determined by `type`.", + "description": "Type-specific payload; the concrete shape is determined by `type`. May be `null` for entries stored without detail.", "oneOf": [ { "$ref": "#/components/schemas/FeedDetailAlertTrigger" }, + { + "$ref": "#/components/schemas/FeedDetailAlertUpdate" + }, { "$ref": "#/components/schemas/FeedDetailAlertComment" }, + { + "$ref": "#/components/schemas/FeedDetailAlertMerge" + }, + { + "$ref": "#/components/schemas/FeedDetailAlertMuteBySilence" + }, + { + "$ref": "#/components/schemas/FeedDetailAlertMuteByInhibit" + }, + { + "$ref": "#/components/schemas/FeedDetailAlertMuteByFlapping" + }, + { + "$ref": "#/components/schemas/FeedDetailAlertAck" + }, + { + "$ref": "#/components/schemas/FeedDetailAlertUnack" + }, { "$ref": "#/components/schemas/FeedDetailAlertClose" } @@ -22378,7 +22521,14 @@ "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" } } @@ -22402,6 +22552,11 @@ "type": "integer", "format": "int64", "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." } } }, @@ -22546,7 +22701,30 @@ "maxItems": 100, "description": "Per-filter grouping overrides.", "items": { - "type": "object" + "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.`." + } + } } }, "all_equals_required": { @@ -22666,7 +22844,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Target status page ID; obtain it from `POST /status-page/list`." + "description": "Target status page ID; obtain it from `GET /status-page/list`." }, "method": { "type": "string", @@ -22726,7 +22904,7 @@ "$ref": "#/components/schemas/IncidentFeedType" }, "detail": { - "description": "Type-specific payload. The concrete shape is determined by `type`.", + "description": "Type-specific payload. The concrete shape is determined by `type`; `null` when the entry has no structured detail.", "oneOf": [ { "$ref": "#/components/schemas/FeedDetailIncidentNew" @@ -22826,6 +23004,9 @@ }, { "$ref": "#/components/schemas/FeedDetailWorkItemDeleted" + }, + { + "$ref": "#/components/schemas/FeedDetailAlertMerge" } ], "discriminator": { @@ -22863,7 +23044,8 @@ "i_wi_completed": "#/components/schemas/FeedDetailWorkItemCompleted", "i_wi_converted": "#/components/schemas/FeedDetailWorkItemConverted", "i_wi_bound": "#/components/schemas/FeedDetailWorkItemBound", - "i_wi_deleted": "#/components/schemas/FeedDetailWorkItemDeleted" + "i_wi_deleted": "#/components/schemas/FeedDetailWorkItemDeleted", + "a_merge": "#/components/schemas/FeedDetailAlertMerge" } } }, @@ -22941,6 +23123,7 @@ "incident_id", "account_id", "channel_id", + "team_id", "integration_id", "integration_ids", "integration_types", @@ -23003,6 +23186,11 @@ "format": "int64", "description": "Channel ID. 0 for standalone incidents." }, + "team_id": { + "type": "integer", + "format": "int64", + "description": "ID of the team that owns the incident's channel. 0 when the channel has no team." + }, "integration_id": { "type": "integer", "format": "int64", @@ -23401,7 +23589,12 @@ }, "progress": { "type": "string", - "description": "Incident progress state — one of `Triggered`, `Processing`, `Closed`." + "description": "Incident progress state — one of `Triggered`, `Processing`, `Closed`.", + "enum": [ + "Triggered", + "Processing", + "Closed" + ] }, "severity": { "type": "string", @@ -23445,11 +23638,11 @@ "owner_id": { "type": "integer", "format": "int64", - "description": "Member ID of the incident owner." + "description": "Member ID of the incident owner. Omitted when 0 (no owner)." }, "owner_name": { "type": "string", - "description": "Display name of the incident owner." + "description": "Display name of the incident owner. Omitted when empty." }, "creator_id": { "type": "integer", @@ -23463,11 +23656,11 @@ "closer_id": { "type": "integer", "format": "int64", - "description": "Member ID of the person who closed the incident." + "description": "Member ID of the person who closed the incident. Omitted when 0 (not closed manually)." }, "closer_name": { "type": "string", - "description": "Display name of the person who closed the incident." + "description": "Display name of the person who closed the incident. Omitted when empty." }, "seconds_to_ack": { "type": "integer", @@ -23496,11 +23689,11 @@ "snoozed_before": { "type": "integer", "format": "int64", - "description": "Unix timestamp in seconds until which the incident is snoozed." + "description": "Unix timestamp in seconds until which the incident is snoozed. Omitted when the incident is not snoozed." }, "ever_muted": { "type": "boolean", - "description": "Whether the incident was ever muted by flapping-based noise reduction." + "description": "Whether the incident was ever muted by noise reduction. Omitted when false." }, "frequency": { "type": "string", @@ -23508,7 +23701,7 @@ "frequent", "rare" ], - "description": "Frequency classification: `frequent` or `rare`." + "description": "Frequency classification: `frequent` or `rare`. Omitted when not classified." }, "responders": { "type": "array", @@ -23547,8 +23740,11 @@ } }, "assigned_to": { - "type": "object", - "description": "Current assignment target for the incident.", + "type": [ + "object", + "null" + ], + "description": "Current assignment target for the incident; `null` when the incident has no assignment record.", "properties": { "person_ids": { "type": "array", @@ -23597,12 +23793,12 @@ "additionalProperties": { "type": "string" }, - "description": "Incident labels as key-value pairs. Omitted when empty." + "description": "Incident labels as key-value pairs. Always omitted in this response (reserved for export)." }, "fields": { "type": "object", "additionalProperties": true, - "description": "Custom fields of the incident. Omitted when empty." + "description": "Custom fields of the incident. Always omitted in this response (reserved for export)." }, "notifications": { "type": "integer", @@ -23701,21 +23897,23 @@ "description": "Rule description." }, "source_filters": { - "$ref": "#/components/schemas/FilterGroup" + "$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.`. Empty makes the rule inert." }, "target_filters": { - "$ref": "#/components/schemas/FilterGroup" + "$ref": "#/components/schemas/FilterGroup", + "description": "Conditions the incoming target alert event must match to be suppressed; empty means every event is a target." }, "equals": { "type": "array", "items": { "type": "string" }, - "description": "Label keys used to pair source and target alerts." + "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`." }, "is_directly_discard": { "type": "boolean", - "description": "When true, the inhibited target alert is discarded outright; when false, the alert is still created but muted — no incident is triggered and no notification is sent." + "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", @@ -23744,6 +23942,11 @@ "type": "integer", "format": "int64", "description": "Last update time, Unix timestamp in seconds." + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "Deletion time, Unix timestamp in seconds. Omitted unless the rule is soft-deleted; deleted rules are excluded from list responses." } } }, @@ -23756,7 +23959,12 @@ }, "hours": { "type": "string", - "description": "Hour bucket when `split_hours` is enabled." + "description": "Hour bucket when `split_hours` is enabled: `work`, `sleep`, or `off`. Omitted when `split_hours` is false.", + "enum": [ + "work", + "sleep", + "off" + ] }, "total_alert_cnt": { "type": "integer", @@ -23793,7 +24001,8 @@ "start_time": { "type": "integer", "format": "int64", - "description": "Start time, Unix seconds. Must be greater than 0." + "description": "Start time, Unix seconds. Must be greater than 0.", + "exclusiveMinimum": 0 }, "end_time": { "type": "integer", @@ -23806,7 +24015,8 @@ "type": "integer", "format": "int64" }, - "description": "Filter by team IDs. At most 100 entries." + "description": "Filter by team IDs. At most 100 entries.", + "maxItems": 100 }, "channel_ids": { "type": "array", @@ -23814,7 +24024,8 @@ "type": "integer", "format": "int64" }, - "description": "Filter by channel IDs. At most 100 entries." + "description": "Filter by channel IDs. At most 100 entries.", + "maxItems": 100 }, "responder_ids": { "type": "array", @@ -23822,7 +24033,8 @@ "type": "integer", "format": "int64" }, - "description": "Filter by responder person IDs. At most 100 entries." + "description": "Filter by responder person IDs. At most 100 entries.", + "maxItems": 100 }, "severities": { "type": "array", @@ -23835,7 +24047,8 @@ "Ok" ] }, - "description": "Filter by severity. At most 3 entries." + "description": "Filter by severity. At most 3 entries.", + "maxItems": 3 }, "incident_ids": { "type": "array", @@ -23843,11 +24056,12 @@ "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, - "description": "Filter by incident IDs (MongoDB ObjectIDs). At most 100 entries." + "description": "Filter by incident IDs (MongoDB ObjectIDs). At most 100 entries.", + "maxItems": 100 }, "query": { "type": "string", - "description": "Full-text query applied to incident title and description." + "description": "Substring match on the incident title (SQL `LIKE %query%`)." }, "labels": { "type": "object", @@ -23866,11 +24080,11 @@ "enum": [ "created_at" ], - "description": "Sort field of the underlying incident set. Currently only `created_at` (incident creation time) is supported." + "description": "Sort field of the incident list; only `created_at` (incident creation time) is supported. Used by `/insight/incident/list` only." }, "asc": { "type": "boolean", - "description": "Sort ascending when `true`, descending otherwise." + "description": "Sort ascending when `true`, descending otherwise. Only used by `/insight/incident/list`." }, "is_my_team": { "type": "boolean", @@ -23878,65 +24092,39 @@ }, "time_zone": { "type": "string", - "description": "IANA time zone name used to interpret the time range (e.g. `Asia/Shanghai`). Defaults to the account 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`." }, "seconds_to_close_from": { "type": "integer", "format": "int64", - "description": "Lower bound (inclusive) on time-to-close, in seconds." + "description": "Lower bound (inclusive) on time-to-close, in seconds.", + "minimum": 0 }, "seconds_to_close_to": { "type": "integer", "format": "int64", - "description": "Upper bound (exclusive) on time-to-close, in seconds. Must be greater than `seconds_to_close_from` when both are set." + "description": "Upper bound (exclusive) on time-to-close, in seconds. Must be greater than `seconds_to_close_from` when both are set.", + "minimum": 0 }, "seconds_to_ack_from": { "type": "integer", "format": "int64", - "description": "Lower bound (inclusive) on time-to-acknowledge, in seconds." + "description": "Lower bound (inclusive) on time-to-acknowledge, in seconds.", + "minimum": 0 }, "seconds_to_ack_to": { "type": "integer", "format": "int64", - "description": "Upper bound (exclusive) on time-to-acknowledge, in seconds. Must be greater than `seconds_to_ack_from` when both are set." + "description": "Upper bound (exclusive) on time-to-acknowledge, in seconds. Must be greater than `seconds_to_ack_from` when both are set.", + "minimum": 0 }, "export_fields": { "type": "array", "items": { - "type": "string", - "enum": [ - "incident_id", - "title", - "severity", - "progress", - "channel_id", - "channel_name", - "team_id", - "team_name", - "created_at", - "seconds_to_ack", - "seconds_to_close", - "closed_by", - "engaged_seconds", - "hours", - "notifications", - "interruptions", - "acknowledgements", - "assignments", - "reassignments", - "escalations", - "manual_escalations", - "timeout_escalations", - "assigned_to", - "responders", - "description", - "labels", - "fields", - "creator_id", - "creator_name" - ] + "type": "string" }, - "description": "Subset of CSV column keys to include in the export. At most 50 entries. Only used by the export endpoints." + "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 }, "description_html_to_text": { "type": "boolean", @@ -23961,21 +24149,30 @@ "description": "Paged incident list request. Extends InsightFilter with pagination.", "properties": { "p": { - "type": "integer", - "minimum": 1, + "type": [ + "integer", + "null" + ], + "minimum": 0, "default": 1, - "description": "Page number, starting at 1. Defaults to 1." + "description": "Page number, starting at 1. Used when `search_after_ctx` is not provided; `p * limit` must stay within 10,000 records." }, "limit": { - "type": "integer", - "minimum": 1, + "type": [ + "integer", + "null" + ], + "minimum": 0, "maximum": 100, "default": 20, - "description": "Page size, between 1 and 100. Defaults to 20." + "description": "Page size, max 100, default 20." }, "search_after_ctx": { - "type": "string", - "description": "Cursor token returned by a previous page. Pass it back to fetch the next page." + "type": [ + "string", + "null" + ], + "description": "Cursor token returned by a previous page (the incident ID of its last row). Pass it back to fetch the next page." } } } @@ -23995,7 +24192,7 @@ }, "search_after_ctx": { "type": "string", - "description": "Cursor token to fetch the next page. Pass it back in the next request's `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." }, "items": { "type": "array", @@ -24053,7 +24250,10 @@ }, "k": { "type": "integer", - "description": "Number of top entries to return, between 1 and 100." + "description": "Number of top entries to return, between 1 and 100. Defaults to 20.", + "minimum": 1, + "maximum": 100, + "default": 20 }, "orderby": { "type": "string", @@ -24061,7 +24261,7 @@ "total_alert_cnt", "total_alert_event_cnt" ], - "description": "Sort field. `total_alert_cnt` sorts by alert count; `total_alert_event_cnt` sorts by raw alert event count." + "description": "Sort field. `total_alert_cnt` sorts by alert count; `total_alert_event_cnt` sorts by raw alert event count (default)." }, "asc": { "type": "boolean", @@ -24122,11 +24322,11 @@ "channel_name", "last_incident_at" ], - "description": "Field used to order results." + "description": "Field used to order results. Defaults to `created_at`." }, "asc": { "type": "boolean", - "description": "When true, sort ascending." + "description": "When true, sort ascending; defaults to false (descending)." }, "is_my_managed": { "type": "boolean", @@ -24138,7 +24338,7 @@ }, "is_brief": { "type": "boolean", - "description": "When true, return only brief fields (`channel_id`, `channel_name`, `description`, `status`)." + "description": "When true, return only `channel_id`, `channel_name`, `description` and `status`, and return all matches without pagination." }, "is_my_team": { "type": "boolean", @@ -24154,7 +24354,7 @@ }, "query": { "type": "string", - "description": "Free-text query against channel name/description." + "description": "Case-insensitive regular expression matched against channel name and description; invalid regex syntax falls back to a literal match." }, "channel_ids": { "type": "array", @@ -24567,7 +24767,7 @@ "drafting", "published" ], - "description": "Post-mortem status filter; the server defaults to `published` when omitted. `drafting` returns only drafts; `published` returns only published post-mortems." + "description": "Optional status filter: `drafting` returns only drafts, `published` returns only published post-mortems. When omitted, post-mortems in all statuses are returned." }, "team_ids": { "type": "array", @@ -24673,7 +24873,8 @@ "type": "integer", "format": "int64" }, - "description": "Integration IDs to fetch routing rules for." + "description": "Integration IDs to fetch routing rules for.", + "minItems": 1 } } }, @@ -24833,7 +25034,8 @@ }, "total": { "type": "integer", - "description": "Total number of matching records." + "description": "Total number of matching records.", + "format": "int64" }, "search_after_ctx": { "type": "string", @@ -24855,7 +25057,7 @@ }, "description": { "type": "string", - "description": "Optional description." + "description": "Optional description. Values longer than 500 characters are silently truncated." }, "url": { "type": "string", @@ -24872,15 +25074,19 @@ "additionalProperties": { "type": "string" }, - "description": "Custom HTTP request headers." + "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." }, "timeout": { "type": "integer", - "description": "Request timeout in seconds (1–3). Default 2." + "description": "Request timeout in seconds (1–3). Default 2.", + "minimum": 1, + "maximum": 3 }, "retry_count": { "type": "integer", - "description": "Number of retries on failure (0–1). Default 0." + "description": "Number of retries on failure (0–1). Default 0.", + "minimum": 0, + "maximum": 1 }, "team_id": { "type": "integer", @@ -24939,11 +25145,14 @@ "description": "Endpoint URL." }, "headers": { - "type": "object", + "type": [ + "object", + "null" + ], "additionalProperties": { "type": "string" }, - "description": "Custom request headers." + "description": "Custom request headers. `null` when none are configured." }, "timeout": { "type": "integer", @@ -24959,7 +25168,11 @@ }, "status": { "type": "string", - "description": "API status." + "enum": [ + "enabled", + "deleted" + ], + "description": "API status: `enabled` or `deleted` (soft-deleted). The list endpoint excludes `deleted` items; the info endpoint may return them." }, "team_id": { "type": "integer", @@ -24979,12 +25192,17 @@ "created_at": { "type": "integer", "format": "int64", - "description": "Creation timestamp, Unix seconds." + "description": "Creation time, Unix seconds. Omitted when 0 (legacy records)." }, "updated_at": { "type": "integer", "format": "int64", - "description": "Last update timestamp, Unix seconds." + "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": [ @@ -25068,21 +25286,25 @@ "additionalProperties": { "type": "string" }, - "description": "New headers map (replaces existing)." + "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." }, "timeout": { "type": [ "integer", "null" ], - "description": "New timeout in seconds." + "description": "New timeout in seconds.", + "minimum": 1, + "maximum": 3 }, "retry_count": { "type": [ "integer", "null" ], - "description": "New retry count." + "description": "New retry count.", + "minimum": 0, + "maximum": 1 }, "team_id": { "type": [ @@ -25121,24 +25343,24 @@ "properties": { "key": { "type": "string", - "description": "Composite key derived from source label values." + "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 for this row." + "description": "All label key-value pairs of this row. Omitted when empty." }, "created_at": { "type": "integer", "format": "int64", - "description": "Creation timestamp, Unix seconds." + "description": "Creation time, Unix seconds. Omitted when 0." }, "updated_at": { "type": "integer", "format": "int64", - "description": "Last update timestamp, Unix seconds." + "description": "Last update time, Unix seconds. Omitted when 0." } } }, @@ -25157,7 +25379,7 @@ "additionalProperties": { "type": "string" }, - "description": "Exact-match filter on source label values. All source labels must be provided if any are specified." + "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": { "type": "string", @@ -25165,25 +25387,37 @@ "created_at", "updated_at" ], - "description": "Sort field." + "description": "Sort field. Defaults to `updated_at`." }, "asc": { "type": "boolean", "description": "Sort ascending when `true`." }, "p": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "Page number (1-based). Used for offset-based pagination." + "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 }, "limit": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "Page size (1–100, default 20)." + "description": "Page size (0–100); defaults to 20 when omitted, `null`, or 0.", + "minimum": 0, + "maximum": 100 }, "search_after_ctx": { - "type": "string", - "description": "Opaque cursor token for cursor-based pagination." + "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." } } }, @@ -25208,7 +25442,7 @@ }, "search_after_ctx": { "type": "string", - "description": "Cursor token for the next page." + "description": "Cursor token (ObjectID hex of this page's last row) for fetching the next page. Omitted when there is no next page." } }, "required": [ @@ -25217,21 +25451,6 @@ "has_next_page" ] }, - "MappingDataUploadRequest": { - "type": "object", - "description": "Multipart form-data upload request. `schema_id` is passed as a query parameter; `file` is the CSV file field.", - "properties": { - "schema_id": { - "type": "string", - "description": "Mapping schema ID (passed as a query parameter); obtain it from `POST /enrichment/mapping/schema/list`." - }, - "file": { - "type": "string", - "format": "binary", - "description": "CSV file to upload." - } - } - }, "MappingDataUpsertRequest": { "type": "object", "required": [ @@ -25252,7 +25471,7 @@ } }, "maxItems": 1000, - "description": "Rows to insert or update. Each row must include all source and result labels." + "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." } } }, @@ -25297,18 +25516,22 @@ "source_labels": { "type": "array", "items": { - "type": "string" + "type": "string", + "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "maxItems": 3, - "description": "Lookup key label names (1–3). Must not overlap with `result_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`.", + "uniqueItems": true }, "result_labels": { "type": "array", "items": { - "type": "string" + "type": "string", + "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "maxItems": 10, - "description": "Output label names (1–10). Must not overlap with `source_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`.", + "uniqueItems": true } } }, @@ -25373,7 +25596,11 @@ }, "status": { "type": "string", - "description": "Schema status." + "enum": [ + "enabled", + "deleted" + ], + "description": "Schema status: `enabled` or `deleted` (soft-deleted). The list endpoint excludes `deleted` items; the info endpoint may return them." }, "team_id": { "type": "integer", @@ -25393,12 +25620,17 @@ "created_at": { "type": "integer", "format": "int64", - "description": "Creation timestamp, Unix seconds." + "description": "Creation time, Unix seconds. Omitted when 0 (legacy records)." }, "updated_at": { "type": "integer", "format": "int64", - "description": "Last update timestamp, Unix seconds." + "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": [ @@ -25505,7 +25737,7 @@ "owner_id": { "type": "integer", "format": "int64", - "description": "Optional new owner member ID for the target incident." + "description": "Accepted for compatibility but currently ignored by the server; the merge does not change the target incident owner." }, "remove_source_incidents": { "type": "boolean", @@ -25524,12 +25756,12 @@ "sleep", "off" ], - "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`)." + "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." }, "ts": { "type": "integer", "format": "int64", - "description": "Aggregation bucket start time, Unix seconds. Present when `aggregate_unit` is used." + "description": "Start of the aggregation bucket, Unix epoch seconds. Equals `start_time` when no `aggregate_unit` is given." }, "channel_id": { "type": "integer", @@ -25605,7 +25837,8 @@ "string", "null" ], - "description": "Target URL name for the migrated status page. When omitted, the source page's URL name is reused." + "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 } } }, @@ -25644,6 +25877,10 @@ "failed_reason": { "type": "string", "description": "Failure reason if delivery did not succeed." + }, + "sms_content": { + "type": "string", + "description": "SMS text delivered to the recipient; present on SMS deliveries." } } }, @@ -25676,13 +25913,13 @@ "start_time": { "type": "integer", "format": "int64", - "description": "Window start (unix seconds). Must be > 0 and less than `end_time`.", + "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 seconds). Must be > 0.", + "description": "Window end, Unix timestamp in seconds. Must be greater than 0.", "exclusiveMinimum": 0 } } @@ -25981,7 +26218,8 @@ "pattern": "^[0-9a-fA-F]{24}$" }, "maxItems": 100, - "description": "Incident IDs to remove. At most 100 per call. The caller must have access to every channel the incidents belong to." + "description": "Incident IDs to remove. At most 100 per call. The caller must have access to every channel the incidents belong to.", + "minItems": 1 } } }, @@ -26065,7 +26303,10 @@ "description": "Optional resolution note applied to every resolved incident." }, "description": { - "type": "string", + "type": [ + "string", + "null" + ], "maxLength": 6144, "description": "New incident description, up to 6,144 characters. When set, it replaces the current description before the incident closes." }, @@ -26187,12 +26428,12 @@ "mean_seconds_to_ack": { "type": "number", "format": "double", - "description": "This responder's mean time to acknowledgement in seconds." + "description": "This responder's mean time to acknowledgement in seconds; 0 when the responder acknowledged nothing." }, "acknowledgement_pct": { "type": "number", "format": "double", - "description": "This responder's acknowledgement rate (%): acknowledged incidents ÷ involved incidents × 100, rounded to two decimals." + "description": "This responder's acknowledgement rate (%): acknowledged incidents ÷ involved incidents × 100, rounded to two decimals and capped at 100; 0 when the responder has no incidents." } } } @@ -26214,9 +26455,7 @@ "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", - "channel_ids", - "fallthrough" + "if" ], "properties": { "if": { @@ -26227,12 +26466,15 @@ } }, "channel_ids": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "type": "integer", "format": "int64" }, - "description": "Target channel IDs. Required when `routing_mode` is `standard` (or empty)." + "description": "Target channel IDs. Required when `routing_mode` is `standard` (or empty); returned as `null` for `name_mapping`." }, "fallthrough": { "type": "boolean", @@ -26276,7 +26518,8 @@ "integration_id": { "type": "integer", "format": "int64", - "description": "Integration ID. Must be greater than 0." + "description": "Integration ID. Must be greater than 0.", + "exclusiveMinimum": 0 } } }, @@ -26440,11 +26683,14 @@ "description": "Layer mode: 0 = common rotation, 1 = override." }, "schedules": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleCalculatedSchedule" }, - "description": "Computed shifts." + "description": "Computed shifts; null when the layer produces none." } } }, @@ -26469,7 +26715,8 @@ "description": "Shift end timestamp (Unix seconds)." }, "group": { - "$ref": "#/components/schemas/ScheduleGroup" + "$ref": "#/components/schemas/ScheduleGroup", + "description": "Oncall group covering the shift; null marks a coverage gap." }, "index": { "type": "integer", @@ -26482,11 +26729,16 @@ "description": "Day-of-week mask for a rotation layer.", "properties": { "repeat": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { - "type": "integer" + "type": "integer", + "minimum": 0, + "maximum": 6 }, - "description": "Weekday numbers (0 = Sunday) included in the rotation." + "description": "Weekday numbers (0 = Sunday) included in the rotation. Conflicts with restrict_mode = 2 (week)." } } }, @@ -26505,11 +26757,14 @@ "properties": { "cycle": { "type": "string", - "description": "Notification cycle." + "description": "Notification cycle; only `day` is supported.", + "enum": [ + "day" + ] }, "start": { "type": "string", - "description": "Notification start time within the cycle." + "description": "Time of day to send, format `HH:MM` (24-hour)." } } }, @@ -26525,8 +26780,11 @@ ], "properties": { "group_name": { - "type": "string", - "description": "Group display name." + "type": [ + "string", + "null" + ], + "description": "Group display name. Null when only the legacy name is set." }, "name": { "type": "string", @@ -26612,7 +26870,8 @@ "description": "IM provider type (for example feishu_app, dingtalk_app, wecom_app, teams_app, slack_app)." }, "settings": { - "$ref": "#/components/schemas/ScheduleImNotifySettings" + "$ref": "#/components/schemas/ScheduleImNotifySettings", + "description": "Webhook channel settings." } } }, @@ -26767,22 +27026,28 @@ "description": "Last updater person ID." }, "layers": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleLayer" }, - "description": "Rotation layers defined on the schedule." + "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", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleCalculatedLayer" }, - "description": "Computed layers for the requested window." + "description": "Computed per-layer schedules for the requested window. Null when not computed." }, "final_schedule": { "$ref": "#/components/schemas/ScheduleCalculatedLayer", @@ -26791,20 +27056,24 @@ "start": { "type": "integer", "format": "int64", - "description": "Window start (Unix seconds)." + "description": "Window start (Unix seconds). Omitted when 0 (no window requested)." }, "end": { "type": "integer", "format": "int64", - "description": "Window end (Unix seconds)." + "description": "Window end (Unix seconds). Omitted when 0 (no window requested)." }, "notify": { - "$ref": "#/components/schemas/ScheduleNotify" + "$ref": "#/components/schemas/ScheduleNotify", + "description": "Notification configuration. Null when the schedule has none." }, "schedule_id": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "Schedule ID." + "description": "Schedule ID. Null when returned from `/schedule/preview`." }, "schedule_name": { "type": [ @@ -26829,11 +27098,14 @@ "description": "Schedule description. null when returned from /schedule/preview." }, "layer_schedules": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleCalculatedLayer" }, - "description": "Alias of schedule_layers returned for compatibility." + "description": "Alias of schedule_layers returned for compatibility. Null when not computed." }, "status": { "type": [ @@ -26913,11 +27185,14 @@ "description": "Layer weight for ordering." }, "groups": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleGroup" }, - "description": "Oncall groups participating in the rotation." + "description": "Oncall groups participating in the rotation. Null when not set." }, "rotation_duration": { "type": "integer", @@ -26927,7 +27202,7 @@ "handoff_time": { "type": "integer", "format": "int64", - "description": "Rotation handoff time, as a Unix timestamp in seconds." + "description": "Rotation handoff time as a weekly offset in seconds (weekday x 86400 + seconds since midnight), not an absolute Unix timestamp." }, "enable_time": { "type": "integer", @@ -26959,11 +27234,14 @@ "description": "Legacy end offset inside the restriction window (seconds)." }, "restrict_periods": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleRestrictPeriod" }, - "description": "Restriction windows inside each rotation cycle." + "description": "Restriction windows inside each rotation cycle. Null when not set." }, "day_mask": { "$ref": "#/components/schemas/ScheduleDayMask", @@ -26990,17 +27268,23 @@ "description": "Last updater person ID." }, "layer_name": { - "type": "string", - "description": "User-facing layer name." + "type": [ + "string", + "null" + ], + "description": "User-facing layer name. Null when not set." }, "fair_rotation": { "type": "boolean", "description": "Whether fair rotation is enabled." }, "layer_start": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "Layer start timestamp (Unix seconds)." + "description": "Layer effective start (Unix seconds). Null when not set." }, "layer_end": { "type": [ @@ -27023,7 +27307,8 @@ "rotation_value": { "type": "integer", "format": "int64", - "description": "Rotation quantity (number of rotation_unit per cycle)." + "description": "Rotation quantity (number of rotation_unit per cycle).", + "minimum": 0 }, "mask_continuous_enabled": { "type": "boolean", @@ -27037,7 +27322,7 @@ "properties": { "query": { "type": "string", - "description": "Search keyword matched against schedule names." + "description": "Search keyword matched against schedule name or description." }, "p": { "type": "integer", @@ -27087,11 +27372,14 @@ ], "properties": { "items": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleItem" }, - "description": "Schedules on this page." + "description": "Schedules on this page; null when no schedule matches." }, "total": { "type": "integer", @@ -27111,7 +27399,8 @@ "role_id": { "type": "integer", "format": "int64", - "description": "Oncall role ID." + "description": "Oncall role ID.", + "minimum": 0 }, "person_ids": { "type": "array", @@ -27119,7 +27408,8 @@ "type": "integer", "format": "int64" }, - "description": "Person IDs in this slot." + "description": "Person IDs in this slot.", + "minItems": 1 } } }, @@ -27141,10 +27431,12 @@ "description": "Advance notification lead time in seconds. `0` notifies exactly at shift start; omitting disables advance notification." }, "fixed_time": { - "$ref": "#/components/schemas/ScheduleFixedTimeNotifyInfo" + "$ref": "#/components/schemas/ScheduleFixedTimeNotifyInfo", + "description": "Fixed-time notification config; null when not configured." }, "by": { - "$ref": "#/components/schemas/ScheduleNotifyBy" + "$ref": "#/components/schemas/ScheduleNotifyBy", + "description": "Recipient notification preference; null when not configured." }, "im": { "type": "object", @@ -27154,11 +27446,14 @@ "description": "Legacy IM-type to token map." }, "webhooks": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleImNotify" }, - "description": "IM webhook notification channels." + "description": "IM webhook notification channels; null when not configured." } } }, @@ -27206,7 +27501,8 @@ "description": "Shift end timestamp (Unix seconds)." }, "group": { - "$ref": "#/components/schemas/ScheduleGroup" + "$ref": "#/components/schemas/ScheduleGroup", + "description": "Oncall group on duty for the shift." }, "update_at": { "type": "integer", @@ -27225,7 +27521,7 @@ }, "ScheduleRestrictPeriod": { "type": "object", - "description": "Restrict window inside a rotation cycle.", + "description": "Restrict window inside a rotation cycle. restrict_start and restrict_end are second offsets and cannot be equal unless both are 0.", "required": [ "restrict_start", "restrict_end" @@ -27245,19 +27541,23 @@ }, "ScheduleSelfRequest": { "type": "object", - "description": "Query parameters for listing the current user's schedules. Both start and end are Unix timestamps (seconds). If omitted they default to 0. The window must not exceed 30 days.", + "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.", "properties": { "start": { "type": "integer", "format": "int64", - "description": "Window start (Unix seconds, 10 digits)." + "description": "Window start (Unix seconds, 10 digits). Required." }, "end": { "type": "integer", "format": "int64", - "description": "Window end (Unix seconds, 10 digits). Must be within 30 days of start." + "description": "Window end (Unix seconds, 10 digits). Required. Must be within 45 days of start." } - } + }, + "required": [ + "start", + "end" + ] }, "ScheduleSelfResponse": { "type": "object", @@ -27267,17 +27567,20 @@ ], "properties": { "items": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleItem" }, - "description": "Schedules assigned to the current user (or matching the requested IDs)." + "description": "Schedules assigned to the current user (or matching the requested IDs); null when none." } } }, "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. For update, set schedule_id. For preview, start and end are required.", + "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.", "properties": { "schedule_id": { "type": [ @@ -27339,6 +27642,13 @@ "type": "integer", "format": "int64", "description": "Preview window end (Unix seconds, 10 digits). Required for /schedule/preview. Max 45 days after start." + }, + "disabled": { + "type": [ + "integer", + "null" + ], + "description": "0 = enabled, 1 = disabled. Defaults to enabled when omitted." } } }, @@ -27382,20 +27692,22 @@ "from_incident_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", - "description": "Source incident ID when the silence was created from an incident." + "description": "Incident the rule is attached to. Always present; the zero ObjectID `000000000000000000000000` means the rule was not created from an incident." }, "time_filters": { "type": "array", "items": { "$ref": "#/components/schemas/TimeFilter" }, - "description": "Recurring time windows." + "description": "Recurring silence windows. Empty when the rule uses a one-off `time_filter`." }, "time_filter": { - "$ref": "#/components/schemas/OnceTimeFilter" + "$ref": "#/components/schemas/OnceTimeFilter", + "description": "One-off silence window. Present with zero values when the rule uses recurring `time_filters` instead." }, "filters": { - "$ref": "#/components/schemas/FilterGroup" + "$ref": "#/components/schemas/FilterGroup", + "description": "Alert event match conditions; matching events are silenced within the time window." }, "is_directly_discard": { "type": "boolean", @@ -27431,11 +27743,16 @@ }, "is_effective": { "type": "boolean", - "description": "Whether the rule is currently in effect." + "description": "Whether the rule's time window covers the current moment, evaluated at response time." }, "is_auto_delete": { "type": "boolean", "description": "When true, the silence rule is automatically deleted after its time window expires. Defaults to false." + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "Deletion time, Unix timestamp in seconds. Omitted unless the rule is soft-deleted; deleted rules are excluded from list responses." } } }, @@ -27454,14 +27771,15 @@ "pattern": "^[0-9a-fA-F]{24}$" }, "maxItems": 100, - "description": "Incident IDs to snooze. At most 100 per call." + "description": "Incident IDs to snooze. At most 100 per call.", + "minItems": 1 }, "minutes": { "type": "integer", "format": "int64", "exclusiveMinimum": 0, - "maximum": 1440, - "description": "Duration in minutes. Must be greater than 0 and at most 1440 (24h)." + "maximum": 43200, + "description": "Duration in minutes. Must be greater than 0 and at most 43,200 (30 days)." } } }, @@ -27501,7 +27819,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Parent status page ID." + "description": "Parent status page ID. Omitted when 0 (never for stored events)." }, "type": { "type": "string", @@ -27517,7 +27835,7 @@ }, "description": { "type": "string", - "description": "Event description (Markdown)." + "description": "Event description (Markdown). Omitted when empty." }, "status": { "type": "string", @@ -27530,14 +27848,14 @@ "ongoing", "completed" ], - "description": "Current event status. Incident statuses: `investigating`/`identified`/`monitoring`/`resolved`. Maintenance statuses: `scheduled`/`ongoing`/`completed`." + "description": "Current event status. Incident statuses: `investigating`/`identified`/`monitoring`/`resolved`. Maintenance statuses: `scheduled`/`ongoing`/`completed`. Omitted when empty (never for stored events)." }, "affected_components": { "type": "array", "items": { "$ref": "#/components/schemas/AffectedStatusPageComponentItem" }, - "description": "Components currently affected by this event, with their resulting status." + "description": "Components currently affected by this event, with their resulting status. Omitted when no components are affected." }, "responder_ids": { "type": "array", @@ -27545,43 +27863,43 @@ "type": "integer", "format": "int64" }, - "description": "Member IDs responsible for this event." + "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.)." + "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." + "description": "Event start time in Unix seconds, derived from the first timeline update. Omitted when 0." }, "close_at_seconds": { "type": "integer", "format": "int64", - "description": "Scheduled close time in unix seconds. Set for retrospective and maintenance events." + "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." + "description": "Whether this event is a retrospective (historical) one. Omitted when false." }, "updates": { "type": "array", "items": { "$ref": "#/components/schemas/StatusPageChangeUpdateItem" }, - "description": "Timeline updates attached to this event, ordered by time." + "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." + "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." + "description": "Maintenance only: whether the status advances automatically based on the scheduled window. Omitted when false." } } }, @@ -27629,7 +27947,7 @@ "at_seconds": { "type": "integer", "format": "int64", - "description": "Update timestamp in unix seconds." + "description": "Update timestamp in Unix seconds." }, "status": { "type": "string", @@ -27646,14 +27964,14 @@ }, "description": { "type": "string", - "description": "Update description (Markdown)." + "description": "Update description (Markdown). Omitted when empty." }, "component_changes": { "type": "array", "items": { "$ref": "#/components/schemas/StatusPageComponentChangeItem" }, - "description": "Component status transitions applied by this update." + "description": "Component status transitions applied by this update. Omitted when the update changes no component statuses." } } }, @@ -27671,7 +27989,7 @@ }, "component_name": { "type": "string", - "description": "Component display name. Populated by the backend on read; ignored on write." + "description": "Component display name. Populated by the backend on read; ignored on write. Omitted when empty." }, "status": { "type": "string", @@ -27695,11 +28013,11 @@ "properties": { "component_id": { "type": "string", - "description": "Component ID." + "description": "Component ID. Omitted when empty." }, "section_id": { "type": "string", - "description": "Parent section ID." + "description": "Parent section ID. Omitted when the component sits at the top level." }, "name": { "type": "string", @@ -27707,25 +28025,25 @@ }, "description": { "type": "string", - "description": "Component description." + "description": "Component description. Omitted when empty." }, "available_since_seconds": { "type": "integer", "format": "int64", - "description": "Timestamp when the component was first available, in unix seconds." + "description": "Time the component became available, as a Unix timestamp in seconds. Omitted when 0." }, "order_id": { "type": "integer", "format": "int64", - "description": "Display order within its section." + "description": "Display order within its section. Omitted when 0." }, "hide_uptime": { "type": "boolean", - "description": "When true, uptime data is hidden from summary responses." + "description": "When true, uptime data is hidden from summary responses. Omitted when false." }, "hide_all": { "type": "boolean", - "description": "When true, the component is hidden entirely from summary endpoints." + "description": "When true, the component is hidden entirely from summary endpoints. Omitted when false." } } }, @@ -27774,13 +28092,12 @@ "status": { "type": "string", "enum": [ - "pending", "running", "completed", "failed", "cancelled" ], - "description": "Current job status.\n| Value | Meaning |\n|---|---|\n| `pending` | Created, waiting to run. |\n| `running` | In progress. |\n| `completed` | Finished successfully. |\n| `failed` | Failed; the `error` field holds the reason. |\n| `cancelled` | Canceled by request. |" + "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. |" }, "progress": { "$ref": "#/components/schemas/StatusPageMigrationProgress", @@ -27788,17 +28105,17 @@ }, "error": { "type": "string", - "description": "Terminal error message when `status` is `failed`." + "description": "Terminal error message when `status` is `failed`. Omitted when the job has not failed." }, "created_at": { "type": "integer", "format": "int64", - "description": "Job creation time, unix seconds." + "description": "Job creation time as a Unix timestamp in seconds." }, "updated_at": { "type": "integer", "format": "int64", - "description": "Last status update time, unix seconds." + "description": "Last status update time as a Unix timestamp in seconds." } } }, @@ -27858,7 +28175,7 @@ "items": { "type": "string" }, - "description": "Non-fatal warnings recorded during the job." + "description": "Non-fatal warnings recorded during the job. Omitted when empty." } } }, @@ -28035,7 +28352,8 @@ "description": "Template name echoed from the request.", "example": "Prod incident default" } - } + }, + "description": "Create template response." }, "TemplateIDRequest": { "type": "object", @@ -28046,10 +28364,11 @@ "template_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", - "description": "Target template ID. Pass `000000000000000000000001` to address the built-in preset.", + "description": "Target template ID. Pass `6321aad26c12104586a88916` to address the built-in preset.", "example": "6605a1b2c3d4e5f6a7b8c9d0" } - } + }, + "description": "Request body carrying a template ID." }, "TemplateItem": { "type": "object", @@ -28079,7 +28398,8 @@ "creator_id", "updated_by", "created_at", - "updated_at" + "updated_at", + "incident_card_hidden_fields" ], "properties": { "account_id": { @@ -28167,7 +28487,8 @@ "description": "Zoom bot message template source." }, "incident_card_hidden_fields": { - "$ref": "#/components/schemas/IncidentCardHiddenFields" + "$ref": "#/components/schemas/IncidentCardHiddenFields", + "description": "Incident card fields hidden per IM app type; an empty object when none are configured." }, "status": { "type": "string", @@ -28276,7 +28597,7 @@ "total": { "type": "integer", "format": "int64", - "description": "Total number of templates matching the filter, across all pages.", + "description": "Total number of templates matching the filter, across all pages (including the built-in preset template).", "example": 47 }, "has_next_page": { @@ -28455,7 +28776,9 @@ "repeat": { "type": "array", "items": { - "type": "integer" + "type": "integer", + "minimum": 0, + "maximum": 6 }, "description": "Days of the week this window repeats on. Empty means every day." }, @@ -28523,7 +28846,8 @@ "description": "Rule description." }, "filters": { - "$ref": "#/components/schemas/FilterGroup" + "$ref": "#/components/schemas/FilterGroup", + "description": "Alert event match conditions (OR-of-AND); matching events are discarded entirely. Empty means the rule matches nothing." }, "status": { "type": "string", @@ -28552,6 +28876,11 @@ "type": "integer", "format": "int64", "description": "Last update time, Unix timestamp in seconds." + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "Deletion time, Unix timestamp in seconds. Omitted unless the rule is soft-deleted; deleted rules are excluded from list responses." } } }, @@ -28617,7 +28946,7 @@ "trigger", "update" ], - "description": "Auto-resolve timing mode: `trigger` starts the timer when the incident triggers, `update` restarts it on every alert 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." }, "is_private": { "type": [ @@ -28654,6 +28983,10 @@ "null" ], "description": "Allow external reporters to file incidents into this channel." + }, + "event_group": { + "$ref": "#/components/schemas/EventGroup", + "description": "Alert event merge configuration. Updated only when present." } } }, @@ -28699,7 +29032,7 @@ }, "filters": { "$ref": "#/components/schemas/FilterGroup", - "description": "Matching alerts are dropped and generate no notification." + "description": "Alert event match conditions (OR-of-AND); matching events are discarded entirely. When empty, the rule matches nothing." } } }, @@ -28767,7 +29100,7 @@ }, "filters": { "$ref": "#/components/schemas/FilterGroup", - "description": "Match conditions for alerts this rule applies to; omit to apply it to all alerts in the channel." + "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." } } }, @@ -28860,19 +29193,19 @@ "items": { "type": "string" }, - "description": "Label keys used to pair source and target alerts." + "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`." }, "source_filters": { "$ref": "#/components/schemas/FilterGroup", - "description": "Match conditions for source alerts; together with `equals`, determines which target alerts are suppressed." + "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.`. Empty makes the rule inert." }, "target_filters": { "$ref": "#/components/schemas/FilterGroup", - "description": "Match conditions for target (suppressed) alerts." + "description": "Conditions the incoming target alert event must match to be suppressed; empty means every event is a target." }, "is_directly_discard": { "type": "boolean", - "description": "When true, suppressed target alerts are dropped instead of merged." + "description": "When true, matching alert events are discarded entirely; when false, alerts are still recorded but marked as muted by this rule." } } }, @@ -28923,7 +29256,7 @@ }, "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 muted by this rule." }, "is_auto_delete": { "type": "boolean", @@ -28942,12 +29275,12 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "change_id": { "type": "integer", "format": "int64", - "description": "Target change ID; obtain it from `POST /status-page/change/list`." + "description": "Target change ID; obtain it from `GET /status-page/change/list`." }, "title": { "type": [ @@ -28976,7 +29309,7 @@ }, "UpdateStatusPageChangeTimelineRequest": { "type": "object", - "description": "Parameters for updating an existing timeline entry on a status page event.", + "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", @@ -28986,21 +29319,21 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "change_id": { "type": "integer", "format": "int64", - "description": "Owning change ID; obtain it from `POST /status-page/change/list`." + "description": "Owning change ID; obtain it from `GET /status-page/change/list`." }, "update_id": { "type": "string", - "description": "Target timeline update ID; obtain it from `POST /status-page/change/info`." + "description": "Target timeline update ID; obtain it from `GET /status-page/change/info`." }, "at_seconds": { "type": "integer", "format": "int64", - "description": "New update timestamp in unix seconds." + "description": "New update timestamp in Unix seconds." }, "description": { "type": "string", @@ -29041,7 +29374,7 @@ "version": { "type": "integer", "format": "int64", - "description": "Expected current version for optimistic concurrency control. Pass the value returned by the latest read." + "description": "Reserved for optimistic concurrency control; currently ignored — the server increments `version` automatically on every upsert." } } }, @@ -29127,7 +29460,11 @@ }, "status": { "type": "string", - "description": "War room status." + "description": "War room record status: `enabled` active, `deleted` disbanded.", + "enum": [ + "enabled", + "deleted" + ] }, "created_at": { "type": "integer", @@ -29142,7 +29479,7 @@ }, "WebhookHistoryDetail": { "type": "object", - "description": "Full detail for a webhook delivery attempt. Extends `WebhookHistoryItem` with human-friendly reference metadata resolved at query time.", + "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", @@ -29167,11 +29504,15 @@ }, "webhook_type": { "type": "string", - "description": "Source object kind. `incident` or `alert`." + "description": "Source object kind: `incident` or `alert`.", + "enum": [ + "incident", + "alert" + ] }, "event_type": { "type": "string", - "description": "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)." }, "channel_id": { "type": "integer", @@ -29228,7 +29569,7 @@ }, "event_time": { "type": "string", - "description": "Event time as a formatted timestamp string." + "description": "Event time formatted as `YYYY-MM-DD HH:MM:SS.ffffff`." }, "ref_title": { "type": "string", @@ -29267,11 +29608,15 @@ }, "webhook_type": { "type": "string", - "description": "Source object kind. `incident` or `alert`." + "description": "Source object kind: `incident` or `alert`.", + "enum": [ + "incident", + "alert" + ] }, "event_type": { "type": "string", - "description": "Event type (e.g. `created`, `acknowledged`, `closed`)." + "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)." }, "channel_id": { "type": "integer", @@ -29328,7 +29673,7 @@ }, "event_time": { "type": "string", - "description": "Event time as a formatted timestamp string." + "description": "Event time formatted as `YYYY-MM-DD HH:MM:SS.ffffff`." } } }, @@ -29413,7 +29758,12 @@ }, "status": { "type": "string", - "description": "Field status (e.g. `enabled`, `deleted`)." + "enum": [ + "enabled", + "disabled", + "deleted" + ], + "description": "Field status: `enabled` (active), `disabled` (set only via internal helpers, not via the API), or `deleted` (soft-deleted). `/field/list` excludes `deleted`; `/field/info` may return it." }, "creator_id": { "type": "integer", @@ -29452,7 +29802,10 @@ "creator_id", "updated_by", "created_at", - "updated_at" + "updated_at", + "description", + "options", + "default_value" ] }, "FieldInfoRequest": { @@ -29477,7 +29830,7 @@ "created_at", "updated_at" ], - "description": "Sort key. Defaults to backend ordering when omitted." + "description": "Sort key. Defaults to `created_at` when omitted." }, "asc": { "type": "boolean", @@ -29493,7 +29846,7 @@ }, "query": { "type": "string", - "description": "Regex filter against `field_name` and `display_name`. Invalid regex is auto-escaped to literal substring match." + "description": "Regex filter matched against `field_name` only. An invalid regex is auto-escaped to a literal substring match." } } }, @@ -29545,7 +29898,7 @@ "single_select", "text" ], - "description": "Field type, immutable after creation: `text`, `single_select`, `multi_select` or `checkbox`." + "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", @@ -29610,7 +29963,7 @@ "items": { "type": "string" }, - "description": "Replacement options list. Must obey the same per-type rules as create." + "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`.", @@ -29739,7 +30092,7 @@ "deleted_at": { "type": "integer", "format": "int64", - "description": "Unix timestamp in seconds when the change event was deleted." + "description": "Unix timestamp in seconds when the change event was deleted. Omitted when not deleted." } } }, @@ -29766,7 +30119,11 @@ }, "channel_status": { "type": "string", - "description": "Status of the collaboration channel." + "description": "Status of the collaboration channel: `enabled` or `disabled`.", + "enum": [ + "enabled", + "disabled" + ] }, "integration_id": { "type": "integer", @@ -29791,7 +30148,14 @@ }, "change_status": { "type": "string", - "description": "Current lifecycle status of the change." + "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. |", + "enum": [ + "Planned", + "Ready", + "Processing", + "Canceled", + "Done" + ] }, "start_time": { "type": "integer", @@ -29834,12 +30198,14 @@ "start_time": { "type": "integer", "format": "int64", - "description": "Unix timestamp in seconds for the start of the query window." + "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.", + "minimum": 0 }, "end_time": { "type": "integer", "format": "int64", - "description": "Unix timestamp in seconds for the end of the query window." + "description": "End of the query window, Unix epoch seconds. See `start_time` for defaults and constraints.", + "minimum": 0 }, "p": { "type": "integer", @@ -29871,11 +30237,12 @@ "description": "", "format": "int64" }, - "description": "Filter by reporting integration IDs." + "description": "Filter by reporting integration IDs. At least 1 entry when provided.", + "minItems": 1 }, "orderby": { "type": "string", - "description": "Field to sort the result by.", + "description": "Sort field: `start_time` or `last_time`. Defaults to `start_time`.", "enum": [ "start_time", "last_time" @@ -29883,7 +30250,7 @@ }, "asc": { "type": "boolean", - "description": "Sort in ascending order when true." + "description": "Sort in ascending order when true; default is descending." }, "include_events": { "type": "boolean", @@ -29891,7 +30258,39 @@ }, "query": { "type": "string", - "description": "Free-text or regular-expression search over change fields." + "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." + }, + "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": 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." } } }, @@ -29961,7 +30360,11 @@ "type": "string", "description": "Current status of the person." } - } + }, + "required": [ + "account_id", + "person_id" + ] }, "GetWarRoomDefaultObserversRequest": { "type": "object", @@ -30003,7 +30406,6 @@ "type": "array", "items": { "type": "integer", - "description": "", "format": "int64" }, "description": "Person IDs to add to the war room." @@ -30024,11 +30426,12 @@ }, "type": { "type": "string", - "description": "Template channel type that selects the rendering engine." + "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`." }, "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 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}$" }, "incident_card_hidden_fields": { "$ref": "#/components/schemas/IncidentCardHiddenFields", @@ -30038,7 +30441,8 @@ "required": [ "content", "type" - ] + ], + "description": "Template preview request." }, "PreviewTemplateResponse": { "type": "object", @@ -30062,7 +30466,13 @@ }, "description": "Fixed incident-card fields returned for supported IM previews after the requested hiding rules are applied." } - } + }, + "required": [ + "success", + "content", + "message" + ], + "description": "Template preview result." }, "WarRoomDataSourceItem": { "type": "object", @@ -30093,15 +30503,19 @@ }, "status": { "type": "string", - "description": "Current status of the integration." + "description": "Integration status: `enabled` or `disabled`. Deleted integrations are never returned.", + "enum": [ + "enabled", + "disabled" + ] }, "category": { "type": "string", - "description": "Category of the integration plugin." + "description": "Plugin category; `im` for the IM integrations returned here." }, "plugin_type": { "type": "string", - "description": "Type identifier of the integration plugin." + "description": "Plugin type identifier of the IM integration, for example `feishu_app`, `dingtalk_app`, `wecom_app`, `slack_app`, or `teams_app`." }, "plugin_type_name": { "type": "string", @@ -30151,11 +30565,11 @@ "last_time": { "type": "integer", "format": "int64", - "description": "Unix timestamp in seconds of the most recent activity on the integration." + "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": "Exclusive integration ID associated with this integration.", + "description": "Legacy exclusive-integration linkage; deprecated.", "format": "int64" }, "integration_id": { @@ -30163,7 +30577,31 @@ "description": "Integration ID, alias of data_source_id.", "format": "int64" } - } + }, + "required": [ + "data_source_id", + "account_id", + "team_id", + "plugin_id", + "name", + "status", + "category", + "plugin_type", + "plugin_type_name", + "description", + "integration_key", + "ref_id", + "settings", + "no_editable", + "creator_id", + "updated_by", + "created_at", + "updated_at", + "last_time", + "exclusive_data_source_id", + "integration_id" + ], + "description": "An IM integration (data source) entry." }, "ListWarRoomEnabledResponse": { "type": "object", @@ -30175,14 +30613,18 @@ }, "description": "IM integrations with the war-room feature enabled." } - } + }, + "required": [ + "items" + ], + "description": "War-room-enabled IM integration list response." }, "StatusPageSectionItem": { "type": "object", "properties": { "section_id": { "type": "string", - "description": "Section ID." + "description": "Section ID. Omitted when empty." }, "name": { "type": "string", @@ -30194,7 +30636,7 @@ }, "order_id": { "type": "integer", - "description": "Display order of the section.", + "description": "Display order of the section. Omitted when 0.", "format": "int64" }, "hide_uptime": { @@ -30205,7 +30647,13 @@ "type": "boolean", "description": "Whether the section and its components are hidden from summary endpoints." } - } + }, + "required": [ + "name", + "description", + "hide_uptime", + "hide_all" + ] }, "StatusPageSubscriptionItem": { "type": "object", @@ -30218,7 +30666,11 @@ "type": "boolean", "description": "Whether IM subscription is enabled." } - } + }, + "required": [ + "email", + "im" + ] }, "StatusPageItem": { "type": "object", @@ -30246,35 +30698,35 @@ }, "custom_domain": { "type": "string", - "description": "Custom domain pointing to the status page." + "description": "Custom domain pointing to the status page. Omitted when not set." }, "logo": { "type": "string", - "description": "Logo image of the status page." + "description": "Logo image of the status page. Omitted when not set." }, "dark_logo": { "type": "string", - "description": "Dark-mode logo image of the status page." + "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." + "description": "URL opened when the logo is clicked. Omitted when not set." }, "favicon": { "type": "string", - "description": "Favicon of the status page." + "description": "Favicon of the status page. Omitted when not set." }, "page_header": { "type": "string", - "description": "Header content of the status page." + "description": "Header content of the status page. Omitted when not set." }, "page_footer": { "type": "string", - "description": "Footer content of the status page." + "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.", + "description": "How the timeline displays change dates. `calendar` uses a calendar view; `list` uses a list view. Omitted when not set.", "enum": [ "calendar", "list" @@ -30282,7 +30734,7 @@ }, "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.", + "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", @@ -30297,11 +30749,11 @@ "type": "string" } }, - "description": "Custom navigation links shown on the status page." + "description": "Custom navigation links shown on the status page. Omitted when not set." }, "contact_info": { "type": "string", - "description": "Get-in-touch contact, a mailto or website URL." + "description": "Get-in-touch contact, a mailto or website URL. Omitted when not set." }, "components": { "type": "array", @@ -30318,16 +30770,26 @@ "description": "Sections grouping the components." }, "subscription": { - "$ref": "#/components/schemas/StatusPageSubscriptionItem" + "$ref": "#/components/schemas/StatusPageSubscriptionItem", + "description": "Subscription channel toggles." }, "template_preference": { "type": "string", - "description": "Preferred change-event template type." + "description": "Preferred event template type: `pre_defined` or `message`. Omitted when never set." } - } - }, - "ListStatusPageResponse": { - "type": "object", + }, + "required": [ + "page_id", + "name", + "url_name", + "type", + "components", + "sections", + "subscription" + ] + }, + "ListStatusPageResponse": { + "type": "object", "properties": { "items": { "type": "array", @@ -30336,7 +30798,10 @@ }, "description": "Status pages owned by the account." } - } + }, + "required": [ + "items" + ] }, "DeletePostMortemTemplateRequest": { "type": "object", @@ -30512,7 +30977,13 @@ }, "incidents_highest_severity": { "type": "string", - "description": "Highest severity among linked incidents." + "description": "Highest severity among linked incidents: `Critical`, `Warning`, `Info`, or `Ok`.", + "enum": [ + "Critical", + "Warning", + "Info", + "Ok" + ] }, "incidents_earliest_start_seconds": { "type": "integer", @@ -30650,7 +31121,7 @@ }, "TryLinkPersonResponse": { "type": "object", - "description": "People linked by this attempt.", + "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.", "required": [ "new_linked_person_ids" ], @@ -30711,14 +31182,15 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "component_ids": { "type": "array", "items": { "type": "string" }, - "description": "Component IDs to delete; obtain them from `POST /status-page/info`." + "description": "Component IDs to delete; obtain them from `GET /status-page/info`.", + "minItems": 1 } } }, @@ -30733,14 +31205,15 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "section_ids": { "type": "array", "items": { "type": "string" }, - "description": "Section IDs to delete; obtain them from `POST /status-page/info`." + "description": "Section IDs to delete; obtain them from `GET /status-page/info`.", + "minItems": 1 } } }, @@ -30756,7 +31229,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "type": { "type": "string", @@ -30768,7 +31241,7 @@ }, "template_id": { "type": "string", - "description": "ID of the template to delete; obtain it from `POST /status-page/template/list`." + "description": "ID of the template to delete; obtain it from `GET /status-page/template/list`." } } }, @@ -30783,7 +31256,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "components": { "type": "array", @@ -30822,9 +31295,15 @@ "hide_all": { "type": "boolean", "description": "When true, the component is hidden entirely from summary endpoints." + }, + "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." } } - } + }, + "minItems": 1 } } }, @@ -30855,7 +31334,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "sections": { "type": "array", @@ -30892,7 +31371,8 @@ "description": "When true, the entire section is hidden from summary endpoints." } } - } + }, + "minItems": 1 } } }, @@ -30924,7 +31404,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "type": { "type": "string", @@ -30935,48 +31415,15 @@ "description": "Template category. `pre_defined` for predefined event templates; `message` for notification message templates." }, "template": { - "type": "object", - "description": "Template content.", - "required": [ - "title", - "event_type", - "status" - ], - "properties": { - "template_id": { - "type": "string", - "description": "Template ID. Omit to create; supply to update." - }, - "title": { - "type": "string", - "description": "Template title." - }, - "event_type": { - "type": "string", - "enum": [ - "incident", - "maintenance" - ], - "description": "Change type this template applies to: `incident` unplanned incident, `maintenance` planned maintenance." - }, - "status": { - "type": "string", - "enum": [ - "investigating", - "identified", - "monitoring", - "resolved", - "scheduled", - "ongoing", - "completed" - ], - "description": "Change status this template maps to. Incidents use `investigating`/`identified`/`monitoring`/`resolved`; maintenances use `scheduled`/`ongoing`/`completed`." + "oneOf": [ + { + "$ref": "#/components/schemas/StatusPagePreDefinedTemplate" }, - "description": { - "type": "string", - "description": "Template body text (Markdown)." + { + "$ref": "#/components/schemas/StatusPageMessageTemplate" } - } + ], + "description": "Template content. Shape depends on `type`: a predefined event template for `pre_defined`, a message template for `message`." } } }, @@ -31100,7 +31547,7 @@ }, "UpdateStatusPageRequest": { "type": "object", - "description": "Parameters for updating an existing status page. All fields except `page_id` are optional; omit a field to keep its existing value.", + "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" ], @@ -31108,53 +31555,87 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "name": { - "type": "string", - "description": "Display name of the status page. Omit to keep the existing value.", + "type": [ + "string", + "null" + ], + "description": "Display name of the status page. Omit or pass null to keep the existing value.", "maxLength": 255 }, "url_name": { - "type": "string", - "description": "URL-safe slug, unique per account and page type. Omit to keep the existing value.", + "type": [ + "string", + "null" + ], + "description": "URL-safe slug, unique per account and page type. Omit or pass null to keep the existing value.", "maxLength": 255 }, "custom_domain": { - "type": "string", - "description": "Custom domain for a public status page. Omit to keep the existing value.", + "type": [ + "string", + "null" + ], + "description": "Custom domain for a public status page. Omit or pass null to keep the existing value.", "maxLength": 255 }, "page_title": { - "type": "string", - "description": "Browser title shown for the status page. Omit to keep the existing value." + "type": [ + "string", + "null" + ], + "description": "Browser title shown for the status page. Omit or pass null to keep the existing value." }, "logo": { - "type": "string", - "description": "Logo image of the status page. Omit to keep the existing value." + "type": [ + "string", + "null" + ], + "description": "Logo image of the status page. Omit or pass null to keep the existing value." }, "dark_logo": { - "type": "string", - "description": "Dark-mode logo image of the status page. Omit to keep the existing value." + "type": [ + "string", + "null" + ], + "description": "Dark-mode logo image of the status page. Omit or pass null to keep the existing value." }, "logo_url": { - "type": "string", - "description": "URL opened when the logo is clicked. Omit to keep the existing value." + "type": [ + "string", + "null" + ], + "description": "URL opened when the logo is clicked. Omit or pass null to keep the existing value.", + "maxLength": 255 }, "favicon": { - "type": "string", - "description": "Favicon of the status page. Omit to keep the existing value." + "type": [ + "string", + "null" + ], + "description": "Favicon of the status page. Omit or pass null to keep the existing value." }, "page_header": { - "type": "string", - "description": "Header content shown on the status page. Omit to keep the existing value." + "type": [ + "string", + "null" + ], + "description": "Header content shown on the status page. Omit or pass null to keep the existing value." }, "page_footer": { - "type": "string", - "description": "Footer content shown on the status page. Omit to keep the existing value." + "type": [ + "string", + "null" + ], + "description": "Footer content shown on the status page. Omit or pass null to keep the existing value." }, "date_view": { - "type": "string", + "type": [ + "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.", "enum": [ "calendar", @@ -31162,7 +31643,10 @@ ] }, "display_uptime_mode": { - "type": "string", + "type": [ + "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.", "enum": [ "chart_and_percentage", @@ -31172,7 +31656,7 @@ }, "custom_links": { "type": "array", - "description": "Custom navigation links shown on the status page. Omit to keep the existing value.", + "description": "Custom navigation links shown on the status page. Omit or pass an empty array to keep the current links.", "items": { "type": "object", "additionalProperties": { @@ -31181,16 +31665,22 @@ } }, "contact_info": { - "type": "string", - "description": "Get-in-touch contact, such as a mailto or website URL. Omit to keep the existing value." + "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." + "description": "Subscription channel toggles. Omit or pass null to keep the existing value." }, "template_preference": { - "type": "string", - "description": "Preferred change-event template type. Omit to keep the existing value." + "type": [ + "string", + "null" + ], + "description": "Preferred event template type: `pre_defined` or `message`. Omit or pass null to keep the existing value." } } }, @@ -31204,7 +31694,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." } } }, @@ -31305,7 +31795,7 @@ }, "name": { "type": "string", - "description": "Display name of the referencing custom form." + "description": "Human label of the referencing custom form's type (a Chinese label, e.g. `解决故障` for the resolve form)." }, "href": { "type": "string", @@ -31564,7 +32054,18 @@ "format": "int64", "description": "Last update time as a Unix timestamp in seconds." } - } + }, + "required": [ + "comment_type_id", + "account_id", + "name", + "color", + "position", + "creator_id", + "updated_by", + "created_at", + "updated_at" + ] }, "ListIncidentCommentTypesRequest": { "type": "object", @@ -31586,7 +32087,7 @@ }, "CreateIncidentCommentTypeRequest": { "type": "object", - "description": "Parameters for creating a comment type.", + "description": "Parameters for creating a comment type. At most 10 comment types per account.", "required": [ "name", "color" @@ -31616,7 +32117,11 @@ "item": { "$ref": "#/components/schemas/IncidentCommentTypeItem" } - } + }, + "required": [ + "comment_type_id", + "item" + ] }, "UpdateIncidentCommentTypeRequest": { "type": "object", @@ -31906,7 +32411,7 @@ "limit": { "type": "integer", "format": "int64", - "minimum": 1, + "minimum": 0, "maximum": 200, "default": 50, "description": "Page size, at most 200. Defaults to 50." @@ -32460,6 +32965,264 @@ } }, "title": "i_wi_deleted" + }, + "FeedDetailAlertMerge": { + "type": "object", + "title": "a_merge", + "description": "Detail payload for `a_merge`: an alert merged into an incident.", + "properties": { + "comment": { + "type": "string", + "description": "Comment recorded with the merge. Omitted when empty." + }, + "target_incident": { + "$ref": "#/components/schemas/IncidentShort", + "description": "Incident the alerts were merged into. Omitted when not recorded." + }, + "source_alerts": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AlertShort" + }, + "description": "Source alerts merged into the target incident. Omitted when empty." + }, + "owner_id": { + "type": "integer", + "format": "int64", + "description": "New owner member ID set on the target incident. Omitted when unchanged." + }, + "title": { + "type": "string", + "description": "New title set on the target incident. Omitted when unchanged." + } + } + }, + "AlertShort": { + "type": "object", + "description": "Brief alert reference.", + "properties": { + "alert_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "Alert ID (ObjectID hex string)." + }, + "title": { + "type": "string", + "description": "Alert title, resolved at read time. Omitted when empty." + } + } + }, + "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": { + "type": "boolean", + "description": "When true, repeated events merge into the existing alert; when false, every event creates a separate alert. Defaults to true." + }, + "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." + } + } + }, + "StatusPageInfoResponse": { + "type": "object", + "description": "Status page detail returned by `GET /status-page/info`: the full page configuration plus feature flags.", + "allOf": [ + { + "$ref": "#/components/schemas/StatusPageItem" + }, + { + "type": "object", + "properties": { + "managed_domain_feature_enabled": { + "type": "boolean", + "description": "Whether the managed custom-domain feature is enabled for this page. `true` for public pages, always `false` for internal pages." + } + }, + "required": [ + "managed_domain_feature_enabled" + ] + } + ] + }, + "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": { + "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." + }, + "status": { + "type": "string", + "enum": [ + "investigating", + "identified", + "monitoring", + "resolved", + "scheduled", + "ongoing", + "completed" + ], + "description": "Change status the template maps to. Incidents use `investigating`/`identified`/`monitoring`/`resolved`; maintenances use `scheduled`/`ongoing`/`completed`." + }, + "description": { + "type": "string", + "description": "Template body text (Markdown)." + } + } + }, + "StatusPageMessageTemplate": { + "type": "object", + "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.", + "properties": { + "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." + }, + "messages": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Notification text (Markdown) per event status. Keys are change statuses valid for the template's `type` (for example `investigating` or `resolved` for incidents); the value is the text used when the event reaches that status." + } + } + }, + "ListStatusPageTemplatesResponse": { + "type": "object", + "description": "Event template list. Item shape depends on the requested `type`: predefined event templates for `pre_defined`, message templates for `message`.", + "required": [ + "items" + ], + "properties": { + "items": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/StatusPagePreDefinedTemplate" + }, + { + "$ref": "#/components/schemas/StatusPageMessageTemplate" + } + ] + }, + "description": "Templates of the requested category." + } + } + }, + "FeedDetailAlertUpdate": { + "type": "object", + "title": "a_update", + "description": "Detail payload for `a_update`: severity/status after the update.", + "properties": { + "severity": { + "$ref": "#/components/schemas/FeedSeverity" + }, + "status": { + "$ref": "#/components/schemas/FeedSeverity" + } + } + }, + "FeedDetailAlertMuteBySilence": { + "type": "object", + "title": "a_m_silence", + "description": "Detail payload for `a_m_silence`: the alert was muted by a silence rule.", + "properties": { + "rule_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "Silence rule ID that muted the alert. Omitted when empty." + }, + "rule_name": { + "type": "string", + "description": "Silence rule name, resolved at read time. Omitted when empty." + } + } + }, + "FeedDetailAlertMuteByInhibit": { + "type": "object", + "title": "a_m_inhibit", + "description": "Detail payload for `a_m_inhibit`: the alert was inhibited by an inhibit rule because of a source alert.", + "properties": { + "rule_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "Inhibit rule ID that muted the alert. Omitted when empty." + }, + "rule_name": { + "type": "string", + "description": "Inhibit rule name, resolved at read time. Omitted when empty." + }, + "source_alert_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "ID of the source alert that triggered the inhibition. Omitted when empty." + }, + "source_alert_title": { + "type": "string", + "description": "Title of the source alert, resolved at read time. Omitted when empty." + } + } + }, + "FeedDetailAlertMuteByFlapping": { + "type": "object", + "title": "a_m_flapping", + "description": "Detail payload for `a_m_flapping` (historical): the alert was muted by flapping detection.", + "properties": { + "max_changes": { + "type": "integer", + "description": "State-change count threshold that triggered flapping detection. Omitted when zero." + }, + "in_secs": { + "type": "integer", + "description": "Window in seconds over which the state changes were counted. Omitted when zero." + }, + "mute_secs": { + "type": "integer", + "description": "Mute duration in seconds. Omitted when zero." + } + } + }, + "FeedDetailAlertAck": { + "type": "object", + "title": "a_ack", + "description": "Detail payload for `a_ack` (historical). No fields.", + "properties": {} + }, + "FeedDetailAlertUnack": { + "type": "object", + "title": "a_unack", + "description": "Detail payload for `a_unack` (historical). No fields.", + "properties": {} } } } diff --git a/api-reference/on-call.openapi.zh.json b/api-reference/on-call.openapi.zh.json index d85c1989..04f7fd60 100644 --- a/api-reference/on-call.openapi.zh.json +++ b/api-reference/on-call.openapi.zh.json @@ -75,7 +75,7 @@ "post": { "operationId": "channelInhibitRuleDelete", "summary": "删除抑制策略", - "description": "删除指定的抑制策略。", + "description": "删除抑制策略。仅 `disabled` 状态的策略可删除。", "tags": [ "On-call/协作空间" ], @@ -737,28 +737,13 @@ }, "responses": { "200": { - "description": "成功", + "description": "成功。CSV 附件，非 JSON 信封。", "content": { - "application/json": { + "text/csv": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/StatusPageSubscriberExportResponse" - } - } - } - ] + "$ref": "#/components/schemas/StatusPageSubscriberExportResponse" }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": "Method,Recipient,Components,Subscribe All,Locale\nemail,alice@example.com,,true,zh-CN\nemail,bob@example.com,,true,en-US" - } + "example": "Method,Recipient,Components,Subscribe All,Locale\nemail,alice@example.com,,Yes,zh-CN\nemail,bob@example.com,\"Core Services › API\",No,en-US" } } }, @@ -898,7 +883,7 @@ "post": { "operationId": "insightChannelExport", "summary": "导出协作空间洞察", - "description": "将协作空间洞察指标以 CSV 文件形式导出。CSV 列名和格式化值优先使用请求语言，其次使用成员语言和账户语言。响应为 CSV 字节流（`Content-Disposition: attachment`），不是 JSON 响应包。", + "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 也可传入，但导出为空列。", "tags": [ "On-call/分析看板" ], @@ -911,28 +896,15 @@ }, "responses": { "200": { - "description": "成功", + "description": "Success", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/EmptyResponse" - } - } - } - ] + "type": "string", + "format": "binary", + "description": "CSV 字节流（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename=channel_export_yyyyMMdd_HHmmss.csv`）。首行为本地化列名。列默认为完整字段集，或由 `export_fields` 指定。" }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": {} - } + "example": "channel_id,channel_name,total_incident_cnt,total_incidents_closed\n4321322010131,Production Alerts,12,10\n" } } }, @@ -1009,7 +981,7 @@ }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": {} + "data": null } } } @@ -1379,14 +1351,13 @@ "data": { "total": 1, "has_next_page": false, - "search_after_ctx": "", "items": [ { "alert_id": "663a1b2c3d4e5f6789abcdef", "integration_id": 10001, "channel_id": 20001, "account_id": 10023, - "title": "CPU 使用率 > 90%", + "title": "CPU usage > 90%", "alert_severity": "Critical", "alert_status": "Critical", "start_time": 1712650000, @@ -1400,7 +1371,7 @@ "updated_at": 1712655000, "integration_name": "Prometheus", "integration_type": "prometheus", - "channel_name": "生产", + "channel_name": "Production", "event_cnt": 3 } ] @@ -1595,7 +1566,7 @@ { "event_id": "69da451df77b1b51f40e83df", "alert_id": "69da451df77b1b51f40e83de", - "title": "CPU 使用率 > 90%", + "title": "CPU usage > 90%", "event_severity": "Critical", "event_status": "Critical", "event_time": 1712650000, @@ -2073,7 +2044,7 @@ { "event_id": "663a1b2c3d4e5f6789abc001", "alert_id": "663a1b2c3d4e5f6789abcdef", - "title": "CPU 使用率 > 90%", + "title": "CPU usage > 90%", "event_severity": "Critical", "event_status": "Critical", "event_time": 1712650000, @@ -2561,7 +2532,7 @@ "post": { "operationId": "channelUnsubscribeRuleEnable", "summary": "启用排除规则", - "description": "启用已禁用的排除规则。", + "description": "启用已禁用的排除规则。仅 `disabled` 状态的规则可启用。", "tags": [ "On-call/协作空间" ], @@ -2672,12 +2643,12 @@ "items": [ { "incident_id": "6a86b5d6f72de50ae1ce2ffb", - "title": "prod-web-01 CPU 使用率超过 90%", - "description": "CPU 使用率连续 5 分钟超过阈值", + "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_name": "SRE Team", "channel_id": 3047621227131, - "channel_name": "生产环境告警", + "channel_name": "Production Alerts", "progress": "Closed", "severity": "Critical", "created_at": 1787213270, @@ -2686,9 +2657,9 @@ "alert_event_cnt": 5, "closed_by": "manually", "creator_id": 2477273692131, - "creator_name": "张三", + "creator_name": "alice", "closer_id": 2477273692131, - "closer_name": "张三", + "closer_name": "alice", "seconds_to_ack": 14, "seconds_to_close": 1830, "engaged_seconds": 1816, @@ -2698,8 +2669,8 @@ "person_id": 2477273692131, "assigned_at": 1787213270, "acknowledged_at": 1787213284, - "person_name": "张三", - "email": "zhangsan@example.com" + "person_name": "alice", + "email": "alice@example.com" } ], "assigned_to": { @@ -2708,7 +2679,7 @@ "type": "assign", "assigned_at": 1787213270, "id": "b8tyUoRvCv4wsPndFRpmNL", - "escalate_rule_name": "值班策略" + "escalate_rule_name": "On-call Policy" }, "notifications": 2, "interruptions": 1, @@ -3181,7 +3152,7 @@ "duration": 132, "status": "success", "status_code": 200, - "event_time": "2026-04-12T13:31:11.357472+08:00" + "event_time": "2026-04-12 13:31:11.357472" } ], "search_after_ctx": "eyJldmVudF90aW1lIjoiMjAyNi0wNC0xMlQxMzoxNToyNi4zODI1NDcrMDg6MDAiLCJldmVudF9pZCI6IjIwMjYwNDEybUdzeFAzZHJwRmZzNFpDUWQycFNEcCJ9", @@ -3299,7 +3270,7 @@ "post": { "operationId": "channelSilenceRuleEnable", "summary": "启用静默策略", - "description": "启用已禁用的静默策略。", + "description": "启用已禁用的静默策略。仅 `disabled` 状态的策略可启用。", "tags": [ "On-call/协作空间" ], @@ -3687,7 +3658,7 @@ "post": { "operationId": "channelInhibitRuleEnable", "summary": "启用抑制策略", - "description": "启用已禁用的抑制策略。", + "description": "启用已禁用的抑制策略。仅 `disabled` 状态的策略可启用。", "tags": [ "On-call/协作空间" ], @@ -3796,8 +3767,8 @@ "items": [ { "schema_id": "665f1a2b3c4d5e6f7a8b9c01", - "schema_name": "CMDB 查询", - "description": "用 CMDB 数据富化告警", + "schema_name": "CMDB Lookup", + "description": "Enrich alerts with CMDB data", "source_labels": [ "host" ], @@ -3848,7 +3819,7 @@ "post": { "operationId": "channelUnsubscribeRuleDelete", "summary": "删除排除规则", - "description": "删除指定的排除规则。", + "description": "删除排除规则。仅 `disabled` 状态的规则可删除。", "tags": [ "On-call/协作空间" ], @@ -4193,7 +4164,7 @@ "post": { "operationId": "insightIncidentExport", "summary": "导出洞察故障", - "description": "将故障分析列表以 CSV 文件形式导出。CSV 列名和格式化值优先使用请求语言，其次使用成员语言和账户语言。响应为 CSV 字节流（`Content-Disposition: attachment`），不是 JSON 响应包。", + "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` 时导出全部列。", "tags": [ "On-call/分析看板" ], @@ -4206,28 +4177,15 @@ }, "responses": { "200": { - "description": "成功", + "description": "Success", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/EmptyResponse" - } - } - } - ] + "type": "string", + "format": "binary", + "description": "CSV 字节流（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename=incident_export_yyyyMMdd_HHmmss.csv`）。首行为本地化列名。列默认为完整故障字段集，或由 `export_fields` 指定。" }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": {} - } + "example": "incident_id,title,severity,created_at\n6a86b5d6f72de50ae1ce2ffb,CPU usage above 90%,Critical,2026-01-01 10:00:00 +0800 CST\n" } } }, @@ -4662,8 +4620,8 @@ }, "example": { "template_id": "6605a1b2c3d4e5f6a7b8c9d0", - "template_name": "生产环境默认模板", - "description": "已更新的描述。", + "template_name": "Prod incident default", + "description": "Updated description.", "email": "Incident {{ .IncidentName }} on {{ .Severity }}", "sms": "[Flashduty] {{ .IncidentName }} — {{ .Severity }}" } @@ -4923,7 +4881,7 @@ "account_id": 10023, "team_id": 0, "template_id": "6605a1b2c3d4e5f6a7b8c9d0", - "template_name": "生产环境默认模板", + "template_name": "Prod incident default", "description": "Default template for production incidents.", "email": "Incident {{ .IncidentName }} on {{ .Severity }}", "sms": "[Flashduty] {{ .IncidentName }} — {{ .Severity }}", @@ -4981,7 +4939,7 @@ "post": { "operationId": "channelEscalateRuleDisable", "summary": "禁用分派策略", - "description": "禁用分派策略而不删除。", + "description": "禁用分派策略而不删除。仅 `enabled` 状态的策略可禁用。", "tags": [ "On-call/协作空间" ], @@ -5124,7 +5082,7 @@ "post": { "operationId": "channelDisable", "summary": "禁用协作空间", - "description": "禁用协作空间以停止故障路由，而不删除该空间。", + "description": "禁用协作空间以停止故障路由（不删除）；禁用后新事件会被直接丢弃。仅 `enabled` 状态的协作空间可禁用。", "tags": [ "On-call/协作空间" ], @@ -5243,7 +5201,7 @@ "status_code": 200, "response_headers": "{\"Content-Type\":\"application/json\"}", "response_body": "{\"ok\":true}", - "event_time": "2026-04-12T13:31:11.357472+08:00", + "event_time": "2026-04-12 13:31:11.357472", "ref_title": "High CPU Usage on host-01", "channel_name": "Production Alerts" } @@ -5454,7 +5412,7 @@ "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-z][a-z0-9_]{0,39}$`（小写）。\n- `source_labels` 与 `result_labels` 不得重叠。\n- 账户最多可创建 20 个映射规则。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", + "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": "创建映射规则" @@ -5484,7 +5442,7 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "schema_id": "665f1a2b3c4d5e6f7a8b9c01", - "schema_name": "CMDB 查询" + "schema_name": "CMDB Lookup" } } } @@ -5511,8 +5469,8 @@ "$ref": "#/components/schemas/MappingSchemaCreateRequest" }, "example": { - "schema_name": "CMDB 查询", - "description": "用 CMDB 数据富化告警", + "schema_name": "CMDB Lookup", + "description": "Enrich alerts with CMDB data", "source_labels": [ "host" ], @@ -5791,7 +5749,7 @@ "post": { "operationId": "insightTeamExport", "summary": "导出团队洞察", - "description": "将团队洞察指标以 CSV 文件形式导出。CSV 列名和格式化值优先使用请求语言，其次使用成员语言和账户语言。响应为 CSV 字节流（`Content-Disposition: attachment`），不是 JSON 响应包。", + "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 也可传入，但导出为空列。", "tags": [ "On-call/分析看板" ], @@ -5804,28 +5762,15 @@ }, "responses": { "200": { - "description": "成功", + "description": "Success", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/EmptyResponse" - } - } - } - ] + "type": "string", + "format": "binary", + "description": "CSV 字节流（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename=team_export_yyyyMMdd_HHmmss.csv`）。首行为本地化列名。列默认为完整字段集，或由 `export_fields` 指定。" }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": {} - } + "example": "team_id,team_name,total_incident_cnt,total_incidents_closed\n4295771902131,SRE Team,12,10\n" } } }, @@ -6766,6 +6711,7 @@ "incident_id": "69da451ef77b1b51f40e83ee", "account_id": 2451002751131, "channel_id": 2551105804131, + "team_id": 2477033058131, "integration_id": 2490562293131, "integration_ids": [ 2490562293131 @@ -6911,8 +6857,8 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "schema_id": "665f1a2b3c4d5e6f7a8b9c01", - "schema_name": "CMDB 查询", - "description": "用 CMDB 数据富化告警", + "schema_name": "CMDB Lookup", + "description": "Enrich alerts with CMDB data", "source_labels": [ "host" ], @@ -6963,7 +6909,7 @@ "post": { "operationId": "statusPageSubscriberImport", "summary": "批量导入订阅者", - "description": "批量导入状态页的订阅者。", + "description": "批量导入状态页订阅者。账户需开通订阅者导入白名单，否则将被拒绝（返回权限不足错误）。", "tags": [ "On-call/状态页" ], @@ -7089,7 +7035,7 @@ { "event_id": "663a1b2c3d4e5f6789abc001", "alert_id": "663a1b2c3d4e5f6789abcdef", - "title": "CPU 使用率 > 90%", + "title": "CPU usage > 90%", "event_severity": "Critical", "event_time": 1712650000 } @@ -7754,7 +7700,7 @@ "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`（正则，须包含命名分组 `result`）和 `g_json`（GJson 路径）二选一。\n- `kind: composition`：`template` 使用 Go text/template 语法，可引用 `labels.*` 键。\n- `kind: mapping`：`mapping_type` 为 `schema`（默认）或 `api`；分别提供 `schema_id` 或 `api_id`。\n- `kind: drop`：`drop_labels` 列出要删除的标签键名。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", + "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": "创建或替换富化规则" @@ -7818,6 +7764,14 @@ "pattern": "(?Pprod|staging|dev)", "override": true } + }, + { + "kind": "composition", + "settings": { + "result_label": "full_env", + "template": "{{.Labels.region}}-{{.Labels.environment}}", + "override": false + } } ] } @@ -7830,7 +7784,7 @@ "post": { "operationId": "alert-read-list-by-ids", "summary": "批量查询告警", - "description": "通过多个告警 ID 一次性返回多条告警详情。", + "description": "通过多个告警 ID 一次性返回多条告警详情。 注意：本接口不分页——`total`、`has_next_page` 恒为 `0`/`false`，`search_after_ctx` 不会返回。", "tags": [ "On-call/告警管理" ], @@ -7864,12 +7818,12 @@ "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { - "total": 1, + "total": 0, "has_next_page": false, "items": [ { "alert_id": "663a1b2c3d4e5f6789abcdef", - "title": "CPU 使用率 > 90%" + "title": "CPU usage > 90%" } ] } @@ -7911,7 +7865,7 @@ "post": { "operationId": "channelEscalateRuleEnable", "summary": "启用分派策略", - "description": "启用已禁用的分派策略。", + "description": "启用已禁用的分派策略。仅 `disabled` 状态的策略可启用。", "tags": [ "On-call/协作空间" ], @@ -8024,6 +7978,7 @@ "incident_id": "69da451ef77b1b51f40e83ee", "account_id": 2451002751131, "channel_id": 2551105804131, + "team_id": 2477033058131, "integration_id": 2490562293131, "integration_ids": [ 2490562293131 @@ -8414,7 +8369,7 @@ "post": { "operationId": "channelSilenceRuleDisable", "summary": "禁用静默策略", - "description": "禁用静默策略而不删除。", + "description": "禁用静默策略而不删除。仅 `enabled` 状态的策略可禁用。", "tags": [ "On-call/协作空间" ], @@ -8563,7 +8518,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` 过滤特定动态类型（如 `alert_comment`、`alert_merge`）。", + "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": "查询告警动态" @@ -8596,9 +8551,9 @@ "items": [ { "ref_id": "663a1b2c3d4e5f6789abcdef", - "type": "alert_comment", + "type": "a_comm", "detail": { - "comment": "正在排查中。" + "comment": "Investigating now." }, "creator_id": 80011, "created_at": 1712651000 @@ -8643,7 +8598,7 @@ "post": { "operationId": "insightResponderExport", "summary": "导出处理人员洞察", - "description": "将处理人员洞察指标以 CSV 文件形式导出。CSV 列名和格式化值优先使用请求语言，其次使用成员语言和账户语言。响应为 CSV 字节流（`Content-Disposition: attachment`），不是 JSON 响应包。", + "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 也可传入，但导出为空列。", "tags": [ "On-call/分析看板" ], @@ -8656,28 +8611,15 @@ }, "responses": { "200": { - "description": "成功", + "description": "Success", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/EmptyResponse" - } - } - } - ] + "type": "string", + "format": "binary", + "description": "CSV 字节流（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename=responder_export_yyyyMMdd_HHmmss.csv`）。首行为本地化列名。列默认为完整字段集，或由 `export_fields` 指定。" }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": {} - } + "example": "responder_id,responder_name,total_incident_cnt,total_incidents_acknowledged\n3790925372131,alice,5,4\n" } } }, @@ -8762,6 +8704,7 @@ "incident_id": "69da451ef77b1b51f40e83ee", "account_id": 2451002751131, "channel_id": 2551105804131, + "team_id": 2477033058131, "integration_id": 2490562293131, "integration_ids": [ 2490562293131 @@ -8998,10 +8941,10 @@ { "api_id": "665f1a2b3c4d5e6f7a8b9c02", "api_name": "CMDB API", - "description": "查询 CMDB 主机元数据", + "description": "Query CMDB for host metadata", "url": "https://cmdb.example.com/api/lookup", "headers": { - "X-Token": "***" + "Authorization": "Bearer eyJhbGciOiJIUzI1NiJ9.example-token" }, "timeout": 2, "retry_count": 1, @@ -9180,8 +9123,8 @@ }, "example": { "schema_id": "665f1a2b3c4d5e6f7a8b9c01", - "schema_name": "CMDB 查询 v2", - "description": "更新后的描述" + "schema_name": "CMDB Lookup v2", + "description": "Updated description" } } } @@ -9439,7 +9382,7 @@ "post": { "operationId": "channelDelete", "summary": "删除协作空间", - "description": "删除协作空间及其所有关联配置。", + "description": "删除协作空间。仅 `disabled` 状态的协作空间可删除，其下的分派、静默、排除和抑制策略会一并删除。当仍有集成路由引用该空间时调用失败。", "tags": [ "On-call/协作空间" ], @@ -9978,28 +9921,15 @@ }, "responses": { "200": { - "description": "成功", + "description": "成功。返回 CSV 附件流，不是 JSON envelope。", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/CsvFileResponse" - } - } - } - ] + "type": "string", + "format": "binary", + "description": "CSV 文件流（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename=.csv`）。首行为表头，按 schema 的 source_labels + result_labels 顺序排列；之后每行一条映射数据。" }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": "host,owner,team,service\nserver01,alice,sre,api\n" - } + "example": "host,owner,team\nserver01,alice,sre\nserver02,bob,backend\n" } } }, @@ -10475,8 +10405,8 @@ }, "example": { "channel_id": 1001, - "channel_name": "生产告警（v2）", - "description": "更新后的描述" + "channel_name": "Production Alerts (v2)", + "description": "Updated description" } } } @@ -10487,7 +10417,7 @@ "post": { "operationId": "channelEnable", "summary": "启用协作空间", - "description": "启用已禁用的协作空间以恢复故障路由。", + "description": "启用协作空间以恢复故障路由。仅 `disabled` 状态的协作空间可启用。", "tags": [ "On-call/协作空间" ], @@ -10557,7 +10487,7 @@ "post": { "operationId": "channelEscalateRuleDelete", "summary": "删除分派策略", - "description": "删除指定的分派策略。", + "description": "删除分派策略。仅 `disabled` 状态的策略可删除。", "tags": [ "On-call/协作空间" ], @@ -10863,16 +10793,48 @@ "requestBody": { "required": true, "content": { - "application/json": { + "multipart/form-data": { "schema": { - "$ref": "#/components/schemas/MappingDataUploadRequest" - }, - "example": { - "schema_id": "665f1a2b3c4d5e6f7a8b9c01" + "type": "object", + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "CSV 文件，最大 100 MB。表头必须包含 schema 的全部 source/result label 名称。" + } + }, + "required": [ + "file" + ] } } } - } + }, + "parameters": [ + { + "name": "schema_id", + "in": "query", + "required": true, + "schema": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$" + }, + "description": "目标映射 schema 的 ID（ObjectID hex）。", + "example": "665f1a2b3c4d5e6f7a8b9c01" + }, + { + "name": "do_not_truncate_first", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "TRUE" + ] + }, + "description": "传 `TRUE`（大小写不敏感）时追加导入；不传且 schema 已有数据时，服务端先清空再导入。" + } + ] } }, "/alert/info": { @@ -10914,7 +10876,7 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "alert_id": "663a1b2c3d4e5f6789abcdef", - "title": "CPU 使用率 > 90%", + "title": "CPU usage > 90%", "alert_severity": "Critical", "alert_status": "Critical", "start_time": 1712650000, @@ -11032,7 +10994,7 @@ "post": { "operationId": "channelInhibitRuleDisable", "summary": "禁用抑制策略", - "description": "禁用抑制策略而不删除。", + "description": "禁用抑制策略而不删除。仅 `enabled` 状态的策略可禁用。", "tags": [ "On-call/协作空间" ], @@ -11286,7 +11248,7 @@ "post": { "operationId": "channelSilenceRuleDelete", "summary": "删除静默策略", - "description": "删除指定的静默策略。", + "description": "删除静默策略。仅 `disabled` 状态的策略可删除。", "tags": [ "On-call/协作空间" ], @@ -11539,7 +11501,7 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "template_id": "6605a1b2c3d4e5f6a7b8c9d0", - "template_name": "生产环境默认模板" + "template_name": "Prod incident default" } } } @@ -11567,8 +11529,8 @@ }, "example": { "team_id": 0, - "template_name": "生产环境默认模板", - "description": "生产环境故障的默认模板。", + "template_name": "Prod incident default", + "description": "Default template for production incidents.", "email": "Incident {{ .IncidentName }} on {{ .Severity }}", "sms": "[Flashduty] {{ .IncidentName }} — {{ .Severity }}" } @@ -11901,7 +11863,7 @@ "account_id": 10023, "team_id": 0, "template_id": "6605a1b2c3d4e5f6a7b8c9d0", - "template_name": "生产环境默认模板", + "template_name": "Prod incident default", "description": "Default template for production incidents.", "email": "Incident {{ .IncidentName }} on {{ .Severity }}", "sms": "[Flashduty] {{ .IncidentName }} — {{ .Severity }}", @@ -12060,12 +12022,12 @@ "get": { "operationId": "statusPageChangeList", "summary": "查询状态页事件列表", - "description": "查询状态页事件列表；响应仅包含对外可见的受影响组件。", + "description": "查询状态页事件列表（管理端）。与公开展示接口不同，响应包含隐藏组件在内的完整数据。", "tags": [ "On-call/状态页" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 响应会过滤隐藏的受影响组件。若事件没有任何可见组件，事件仍会保留，但 `affected_components` 为空数组。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |", "href": "/zh/api-reference/on-call/status-pages/status-page-change-list", "metadata": { "sidebarTitle": "查询状态页事件列表" @@ -12182,7 +12144,7 @@ "type": "integer", "format": "int64" }, - "description": "Filter events started at or after this unix timestamp (seconds)." + "description": "Lower bound of the event activity window: only events still open at, or closed at or after, this Unix timestamp (seconds) are returned." }, { "name": "end_at_seconds", @@ -12192,7 +12154,7 @@ "type": "integer", "format": "int64" }, - "description": "Filter events started at or before this unix timestamp (seconds)." + "description": "Upper bound of the event activity window: only events started at or before this Unix timestamp (seconds) are returned." }, { "name": "type", @@ -12223,7 +12185,7 @@ "completed" ] }, - "description": "Event status filter. Required. Must be a status valid for the given `type` (e.g. `investigating`/`identified`/`monitoring`/`resolved` for incidents; `scheduled`/`ongoing`/`completed` for maintenances)." + "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`)." } ] } @@ -12415,7 +12377,7 @@ }, "example": { "api_name": "CMDB API", - "description": "查询 CMDB 主机元数据", + "description": "Query CMDB for host metadata", "url": "https://cmdb.example.com/api/lookup", "headers": { "X-Token": "mytoken" @@ -12654,7 +12616,7 @@ { "host": "server02", "owner": "bob", - "team": "平台", + "team": "platform", "service": "gateway" } ] @@ -12913,7 +12875,7 @@ "post": { "operationId": "channelUnsubscribeRuleDisable", "summary": "禁用排除规则", - "description": "禁用排除规则而不删除。", + "description": "禁用排除规则而不删除。仅 `enabled` 状态的规则可禁用。", "tags": [ "On-call/协作空间" ], @@ -13199,7 +13161,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。\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` 不存在时返回 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": "查看自定义字段" @@ -13289,7 +13251,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` 与 `display_name`；非法正则会自动转义为字面量子串匹配。", + "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": "查看自定义字段列表" @@ -13689,7 +13651,7 @@ "account_id": 10001, "channel_id": 5001, "channel_name": "Production", - "channel_status": "active", + "channel_status": "enabled", "integration_id": 362, "integration_name": "GitHub Deploy", "title": "Deploy api-server v2.3.1", @@ -14056,7 +14018,7 @@ "updated_by": 20001, "created_at": 1716962400, "updated_at": 1716962700, - "last_time": 1716963000, + "last_time": 0, "exclusive_data_source_id": 0, "integration_id": 362 } @@ -14204,7 +14166,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` 为空数组。", + "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 人员" @@ -15165,7 +15127,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/StatusPageItem" + "$ref": "#/components/schemas/StatusPageInfoResponse" } } } @@ -15215,7 +15177,8 @@ "email": true, "im": false }, - "template_preference": "message" + "template_preference": "message", + "managed_domain_feature_enabled": true } } } @@ -15240,9 +15203,10 @@ "in": "query", "required": true, "schema": { - "type": "string" + "type": "integer", + "format": "int64" }, - "description": "Status page ID" + "description": "Status page ID." } ] } @@ -15846,9 +15810,9 @@ "type": "pre_defined", "template": { "title": "Service Disruption", - "event_type": "incident", "status": "investigating", - "description": "We are investigating a service disruption affecting some users." + "description": "We are investigating a service disruption affecting some users.", + "type": "incident" } } } @@ -15957,7 +15921,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/EmptyResponse" + "$ref": "#/components/schemas/ListStatusPageTemplatesResponse" } } } @@ -16832,7 +16796,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/EmptyResponse" + "$ref": "#/components/schemas/WorkItemMutationResult" } } } @@ -17422,7 +17386,8 @@ "properties": { "total": { "type": "integer", - "description": "持有有效许可的人员数量。" + "description": "持有有效许可的人员数量。", + "format": "int64" }, "items": { "type": "array", @@ -17571,11 +17536,11 @@ "properties": { "component_id": { "type": "string", - "description": "组件 ID。" + "description": "组件 ID。为空时不返回。" }, "section_id": { "type": "string", - "description": "所属区域 ID。" + "description": "所属区域 ID。组件位于顶层时不返回。" }, "name": { "type": "string", @@ -17583,25 +17548,25 @@ }, "description": { "type": "string", - "description": "组件描述。" + "description": "组件描述。为空时不返回。" }, "available_since_seconds": { "type": "integer", "format": "int64", - "description": "组件首次可用时间（Unix 秒）。" + "description": "组件可用起始时间（Unix 时间戳，秒）。为 0 时不返回。" }, "order_id": { "type": "integer", "format": "int64", - "description": "在所属区域内的显示顺序。" + "description": "在所属区域内的显示顺序。为 0 时不返回。" }, "hide_uptime": { "type": "boolean", - "description": "为 true 时在摘要响应中隐藏可用率数据。" + "description": "为 true 时在摘要响应中隐藏可用率数据。为 false 时不返回。" }, "hide_all": { "type": "boolean", - "description": "为 true 时从摘要接口中完全隐藏该组件。" + "description": "为 true 时从摘要接口中完全隐藏该组件。为 false 时不返回。" }, "status": { "type": "string", @@ -17621,28 +17586,47 @@ "description": "全局原始事件列表的过滤和分页条件。", "properties": { "start_time": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "检索窗口开始时间，Unix 时间戳（秒）。" + "description": "查询窗口起点，Unix 时间戳（秒）。提供时必须大于 0。", + "exclusiveMinimum": 0 }, "end_time": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "检索窗口结束时间，Unix 时间戳（秒）。" + "description": "查询窗口终点，Unix 时间戳（秒）。提供时必须大于 `start_time`。" }, "p": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "页码，从 1 开始。未提供 `search_after_ctx` 时使用。" + "description": "页码，从 1 开始。仅在未提供 `search_after_ctx` 时生效。", + "minimum": 0 }, "limit": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "每页条数，最大 100，默认 20。" + "description": "每页条数，最大 100，默认 20。", + "minimum": 0, + "maximum": 100 }, "search_after_ctx": { - "type": "string", - "description": "分页游标：首页留空，翻页时传上一页响应中的 `search_after_ctx`。" + "type": [ + "string", + "null" + ], + "description": "分页游标：首页留空，之后传入上一次响应返回的 `search_after_ctx`。" }, "integration_ids": { "type": "array", @@ -17665,11 +17649,12 @@ "type": "integer", "format": "int64" }, - "description": "按协作空间 ID 过滤，最多 100 个。" + "description": "按协作空间 ID 过滤，最多 100 个。", + "maxItems": 100 }, "severities": { "type": "string", - "description": "逗号分隔的严重程度过滤，如 `Critical,Warning`。" + "description": "逗号分隔的严重级别过滤，如 `Critical,Warning`。可选值：`Critical`、`Warning`、`Info`、`Ok`。" }, "orderby": { "type": "string", @@ -17698,7 +17683,7 @@ }, "search_after_ctx": { "type": "string", - "description": "下一页游标，为本页最后一条事件的 ObjectID，传入下次请求的 `search_after_ctx`；无更多数据或结果为空时不返回。" + "description": "下一页游标——本页最后一条事件的 ObjectID，请求下一页时作为 `search_after_ctx` 传入。本页为空时不返回；游标分页模式下没有下一页时也不返回。" }, "items": { "type": "array", @@ -17768,10 +17753,9 @@ "enum": [ "Critical", "Warning", - "Info", - "Ok" + "Info" ], - "description": "事件严重程度。" + "description": "事件严重级别：`Critical`、`Warning` 或 `Info`。事件级别不会取 `Ok`，`Ok` 只出现在 `event_status` 字段。" }, "event_status": { "type": "string", @@ -17781,7 +17765,7 @@ "Info", "Ok" ], - "description": "事件状态。" + "description": "事件状态：`Critical`/`Warning`/`Info` 表示触发事件，`Ok` 表示恢复事件。" }, "event_time": { "type": "integer", @@ -17815,7 +17799,7 @@ "deleted_at": { "type": "integer", "format": "int64", - "description": "软删除时间戳（秒），未删除时为 0。" + "description": "软删除时间，Unix 时间戳（秒）。未删除时不返回该字段。" } } }, @@ -17836,7 +17820,10 @@ "description": "为 true 时按最早事件优先返回；默认按最新事件优先返回。" }, "limit": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", "minimum": 0, "maximum": 100, @@ -17844,14 +17831,20 @@ "description": "分页大小，默认 20，最大 100。" }, "p": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", "minimum": 0, "default": 1, "description": "页码，从 1 开始；未传 `search_after_ctx` 时生效。" }, "search_after_ctx": { - "type": "string", + "type": [ + "string", + "null" + ], "pattern": "^[0-9a-fA-F]{24}$", "description": "上一页响应返回的游标；传入后使用游标分页而非页码分页。" } @@ -17875,7 +17868,7 @@ "total": { "type": "integer", "format": "int64", - "description": "命中的事件总数。" + "description": "匹配的事件总数，最多统计 1000 条。" }, "has_next_page": { "type": "boolean", @@ -17883,7 +17876,7 @@ }, "search_after_ctx": { "type": "string", - "description": "下一页请求可作为 `search_after_ctx` 传入的游标。" + "description": "下一页游标，请求下一页时作为 `search_after_ctx` 传入。本页为空时不返回；游标分页模式下没有下一页时也不返回。" } } }, @@ -17895,18 +17888,22 @@ "properties": { "alert_id": { "type": "string", - "description": "告警 ID，可通过 `POST /alert/list` 获取。" + "description": "告警 ID（ObjectID 十六进制字符串），可从 `POST /alert/list` 获取。", + "pattern": "^[0-9a-fA-F]{24}$" }, "p": { "type": "integer", "format": "int64", "description": "页码，从 1 开始。", - "default": 1 + "default": 1, + "minimum": 1 }, "limit": { "type": "integer", "format": "int64", - "description": "每页条数，最大 100，默认 20。" + "description": "每页条数，最大 100，默认 20。", + "minimum": 1, + "maximum": 100 }, "asc": { "type": "boolean", @@ -17917,7 +17914,7 @@ "items": { "type": "string" }, - "description": "按动态类型过滤，取值为动态类型代码（如 `a_new`、`a_close`、`a_ack`）。" + "description": "按动态类型码过滤——完整取值见响应条目的 `type` 字段（如 `a_new`、`a_comm`、`a_merge`）。" } } }, @@ -17939,14 +17936,17 @@ }, "AlertFeedType": { "type": "string", - "description": "告警动态记录类型。每个值标识一个告警生命周期事件；`detail` 的具体结构由该字段决定。\n\n| 类型 | 含义 |\n|---|---|\n| `a_new` | 告警触发。 |\n| `a_update` | 告警被新事件更新（如严重程度、状态变化）。 |\n| `a_merge` | 告警被合并。 |\n| `a_comm` | 在告警上添加了评论。 |\n| `a_m_silence` | 告警被静默规则收敛。 |\n| `a_m_inhibit` | 告警被抑制规则收敛。 |\n| `a_close` | 告警关闭（仅历史数据，当前版本不再产生）。 |", + "description": "告警动态记录类型。每个值标识一个告警生命周期事件；`detail` 的具体结构由该字段决定。\n\n| 类型 | 含义 |\n|---|---|\n| `a_new` | 告警被新事件触发。 |\n| `a_update` | 告警严重程度或状态随新事件变化。 |\n| `a_comm` | 在告警上添加了评论。 |\n| `a_merge` | 告警被合并到故障。 |\n| `a_m_silence` | 告警被静默规则收敛。 |\n| `a_m_inhibit` | 告警被抑制规则收敛。 |\n| `a_m_flapping` | 告警被抖动检测收敛（仅历史数据，当前版本不再产生）。 |\n| `a_ack` | 告警被认领（仅历史数据；告警级认领已移除）。 |\n| `a_unack` | 告警认领被撤销（仅历史数据）。 |\n| `a_close` | 告警关闭（仅历史数据，当前版本不再产生）。 |", "enum": [ "a_new", "a_update", - "a_merge", "a_comm", + "a_merge", "a_m_silence", "a_m_inhibit", + "a_m_flapping", + "a_ack", + "a_unack", "a_close" ] }, @@ -18181,7 +18181,8 @@ "properties": { "alert_id": { "type": "string", - "description": "告警 ID（ObjectID 十六进制字符串）。" + "description": "告警 ID（ObjectID 十六进制字符串）。", + "pattern": "^[0-9a-fA-F]{24}$" } } }, @@ -18201,7 +18202,7 @@ "data_source_id": { "type": "integer", "format": "int64", - "description": "已废弃，请使用 `integration_id`。 Deprecated: use `integration_id` instead.", + "description": "已废弃：请使用 `integration_id`。", "deprecated": true }, "channel_id": { @@ -18231,10 +18232,9 @@ "enum": [ "Critical", "Warning", - "Info", - "Ok" + "Info" ], - "description": "当前严重程度。" + "description": "当前严重级别，取该告警出现过的最高级别：`Critical`、`Warning` 或 `Info`。" }, "alert_status": { "type": "string", @@ -18244,7 +18244,7 @@ "Info", "Ok" ], - "description": "当前状态。" + "description": "当前状态：未恢复时为 `Critical`/`Warning`/`Info`，恢复后为 `Ok`。" }, "alert_key": { "type": "string", @@ -18304,15 +18304,19 @@ }, "channel_status": { "type": "string", - "description": "协作空间状态（如 `enabled`、`disabled`）。" + "description": "协作空间状态：`enabled`（启用）或 `disabled`（禁用）。", + "enum": [ + "enabled", + "disabled" + ] }, "responder_name": { "type": "string", - "description": "当前处理人姓名（来自关联故障）。" + "description": "响应人名称。本接口恒为空字符串——响应人信息记录在关联故障上。" }, "responder_email": { "type": "string", - "description": "当前处理人邮箱（来自关联故障）。" + "description": "响应人邮箱。本接口恒为空字符串——响应人信息记录在关联故障上。" }, "event_cnt": { "type": "integer", @@ -18328,7 +18332,7 @@ "items": { "$ref": "#/components/schemas/AlertEventItem" }, - "description": "附加到该告警的最近原始事件，仅部分接口返回。" + "description": "告警的原始事件列表。本接口不返回；仅 `POST /incident/alert/list` 填充该字段。" }, "images": { "type": "array", @@ -18339,15 +18343,23 @@ }, "data_source_name": { "type": "string", - "description": "已废弃，请使用 `integration_name`。" + "description": "已废弃：请使用 `integration_name`。", + "deprecated": true }, "data_source_type": { "type": "string", - "description": "已废弃，请使用 `integration_type`。" + "description": "已废弃：请使用 `integration_type`。为空时不返回。", + "deprecated": true }, "data_source_ref_id": { "type": "string", - "description": "已废弃，请使用 `integration_ref_id`。" + "description": "已废弃：请使用 `integration_ref_id`。", + "deprecated": true + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "软删除时间，Unix 时间戳（秒）。未删除时不返回该字段。" } } }, @@ -18362,7 +18374,8 @@ "items": { "type": "string" }, - "description": "告警 ID 列表（十六进制字符串）。" + "description": "要查询的告警 ID 列表（ObjectID 十六进制字符串）。", + "minItems": 1 } } }, @@ -18382,28 +18395,40 @@ "end_time": { "type": "integer", "format": "int64", - "description": "检索窗口结束时间，Unix 时间戳（秒）。最大跨度 31 天。" + "description": "查询窗口终点，Unix 时间戳（秒）。必须大于 `start_time`；跨度不超过 31 天，且需在账户数据保留期内。" }, "p": { - "type": "integer", - "format": "int64", - "description": "页码，从 1 开始。未提供 `search_after_ctx` 时使用。" - }, - "limit": { - "type": "integer", + "type": [ + "integer", + "null" + ], + "format": "int64", + "description": "页码，从 1 开始。仅在未提供 `search_after_ctx` 时生效；`p * limit` 不能超过 10,000 条。", + "minimum": 0 + }, + "limit": { + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "每页条数，最大 100，默认 20。" + "description": "每页条数，最大 100，默认 20。", + "minimum": 0, + "maximum": 100 }, "search_after_ctx": { - "type": "string", - "description": "上次响应返回的不透明游标，用于获取下一页。" + "type": [ + "string", + "null" + ], + "description": "上一页响应返回的分页游标，用于获取下一页。" }, "is_active": { "type": [ "boolean", "null" ], - "description": "过滤活跃（true）或已恢复（false）状态告警。" + "description": "按生命周期过滤：`true` 只返回未恢复告警（状态 `Critical`/`Warning`/`Info`），`false` 只返回已恢复告警（状态 `Ok`）。不传或传 `null` 返回全部。" }, "ever_muted": { "type": [ @@ -18437,7 +18462,7 @@ "items": { "type": "string" }, - "description": "按告警 ID（ObjectID 十六进制字符串）过滤。" + "description": "只查询指定告警 ID（ObjectID 十六进制字符串）。非法 ID 会被忽略；全部非法时结果为空。" }, "alert_keys": { "type": "array", @@ -18446,17 +18471,9 @@ }, "description": "按告警去重键过滤。" }, - "orderby": { - "type": "string", - "enum": [ - "created_at", - "updated_at" - ], - "description": "排序字段。" - }, "asc": { "type": "boolean", - "description": "为 true 时升序排序，默认降序。" + "description": "为 `true` 时按 `start_time` 升序排序；默认降序。" }, "by_updated_at": { "type": "boolean", @@ -18471,7 +18488,7 @@ "total": { "type": "integer", "format": "int64", - "description": "符合条件的告警总数。" + "description": "匹配的告警总数，最多统计 1000 条。" }, "has_next_page": { "type": "boolean", @@ -18479,7 +18496,7 @@ }, "search_after_ctx": { "type": "string", - "description": "下一页的游标。" + "description": "下一页游标——本页最后一条告警的 ObjectID 十六进制字符串，请求下一页时作为 `search_after_ctx` 传入。仅在 `has_next_page` 为 true 时返回。" }, "items": { "type": "array", @@ -18502,19 +18519,23 @@ "items": { "type": "string" }, - "description": "要合并的告警 ID 列表，可通过 `POST /alert/list` 获取。" + "description": "要合并的告警 ID 列表（ObjectID 十六进制字符串），可从 `POST /alert/list` 获取。所有 ID 必须属于当前账户。", + "minItems": 1 }, "incident_id": { "type": "string", - "description": "目标故障 ID，可通过 `POST /incident/list` 获取。" + "description": "目标故障 ID（ObjectID 十六进制字符串），可从 `POST /incident/list` 获取。", + "pattern": "^[0-9a-fA-F]{24}$" }, "comment": { "type": "string", - "description": "合并操作的可选评论。" + "description": "可选评论，记录在合并动态中。最长 1024 字符。", + "maxLength": 1024 }, "title": { "type": "string", - "description": "目标故障的可选新标题。" + "description": "可选，目标故障的新标题。最长 512 字符。", + "maxLength": 512 }, "owner_id": { "type": "integer", @@ -18539,11 +18560,14 @@ "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", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/FilterCondition" }, - "description": "可选 AND 过滤条件列表，全部条件匹配时规则才生效；省略时对所有告警生效。" + "description": "AND 条件列表——仅当所有条件都匹配时规则生效。为 `null` 或不传表示规则对所有事件生效。" }, "settings": { "type": "object", @@ -18566,7 +18590,10 @@ } ] } - } + }, + "required": [ + "kind" + ] }, "AlertPipelineInfoRequest": { "type": "object", @@ -18577,7 +18604,8 @@ "integration_id": { "type": "integer", "format": "int64", - "description": "集成 ID。" + "description": "集成 ID。必须大于 0。", + "exclusiveMinimum": 0 } } }, @@ -18599,7 +18627,10 @@ }, "status": { "type": "string", - "description": "规则状态（如 `active`）。" + "description": "规则状态。接口响应中恒为 `enabled`——已删除的规则会被过滤。", + "enum": [ + "enabled" + ] }, "creator_id": { "type": "integer", @@ -18620,6 +18651,11 @@ "type": "integer", "format": "int64", "description": "最后更新时间，Unix 时间戳（秒）。" + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "软删除时间，Unix 时间戳（秒）。未删除时不返回该字段。" } } }, @@ -18635,7 +18671,8 @@ "type": "integer", "format": "int64" }, - "description": "集成 ID 列表。" + "description": "集成 ID 列表，至少 1 个。", + "minItems": 1 } } }, @@ -18668,8 +18705,9 @@ "items": { "$ref": "#/components/schemas/AlertPipeline" }, - "description": "处理规则列表，最多 50 条。", - "maxItems": 50 + "description": "要应用的规则，按数组顺序执行。1 到 50 条。", + "maxItems": 50, + "minItems": 1 } } }, @@ -18987,7 +19025,8 @@ }, "total": { "type": "integer", - "description": "返回的事件总数。" + "description": "返回的事件总数。", + "format": "int64" } } }, @@ -19031,10 +19070,7 @@ "description": "事件结束日期（不含），格式 YYYY-MM-DD。" }, "is_off": { - "type": [ - "boolean", - "null" - ], + "type": "boolean", "description": "是否为非工作日。true = 休息日，false = 工作日覆盖。" } } @@ -19087,7 +19123,7 @@ }, "team_id": { "type": "integer", - "format": "int64", + "format": "uint64", "description": "所属团队 ID，0 表示不关联团队。" }, "workdays": { @@ -19204,14 +19240,14 @@ "minimum": 0, "maximum": 6 }, - "description": "工作日（0 = 周日，6 = 周六）。" + "description": "工作日（0 = 周日，6 = 周六）。为空时省略。" }, "extra_cal_ids": { "type": "array", "items": { "type": "string" }, - "description": "继承的公共节假日日历 ID 列表。" + "description": "继承的公共节假日日历 ID 列表。为空时省略。" }, "created_at": { "type": "integer", @@ -19278,7 +19314,8 @@ }, "total": { "type": "integer", - "description": "返回的日历总数。" + "description": "返回的日历总数。", + "format": "int64" } } }, @@ -19322,7 +19359,7 @@ "integer", "null" ], - "format": "int64", + "format": "uint64", "description": "新的所属团队 ID，可通过 `POST /team/list` 获取。" }, "workdays": { @@ -19352,7 +19389,7 @@ "properties": { "job_id": { "type": "string", - "description": "迁移任务 ID，创建迁移任务时返回；可通过 `POST /status-page/migration/status` 查询进度。" + "description": "迁移任务 ID，创建迁移任务时返回；可通过 `GET /status-page/migration/status` 查询进度。" } } }, @@ -19534,21 +19571,29 @@ "description": "为 true 时禁用故障自动关闭。" }, "group": { - "$ref": "#/components/schemas/Group" + "$ref": "#/components/schemas/Group", + "description": "告警聚合配置。" }, "flapping": { - "$ref": "#/components/schemas/Flapping" + "$ref": "#/components/schemas/Flapping", + "description": "抖动检测配置。" }, "progress_to_incident_cnts": { - "$ref": "#/components/schemas/IncProgressCnts" + "$ref": "#/components/schemas/IncProgressCnts", + "description": "近 30 天按进度统计的故障数量。" }, "is_starred": { "type": "boolean", - "description": "当前用户是否已收藏该协作空间。" + "description": "当前用户是否已收藏该协作空间。仅在 `POST /channel/list` 响应中返回。" }, "active_incident_highest_severity": { "type": "string", - "description": "协作空间内活跃故障的最高严重程度。" + "enum": [ + "Critical", + "Warning", + "Info" + ], + "description": "协作空间内活跃（已触发或处理中）故障的最高严重程度：`Critical`、`Warning` 或 `Info`。无活跃故障时不返回。" }, "last_incident_at": { "type": "integer", @@ -19561,7 +19606,11 @@ }, "external_report_token": { "type": "string", - "description": "启用外部上报时授予外部上报人的 token。" + "description": "授予外部上报人的 token。仅在协作空间启用外部上报时返回。" + }, + "event_group": { + "$ref": "#/components/schemas/EventGroup", + "description": "告警事件合并配置。" } } }, @@ -19617,9 +19666,10 @@ "type": "string", "enum": [ "enabled", - "disabled" + "disabled", + "deleted" ], - "description": "协作空间状态。" + "description": "协作空间状态：`enabled` 正常处理事件；`disabled` 丢弃新事件；`deleted` 已删除。" } } }, @@ -19627,7 +19677,8 @@ "type": "object", "description": "为故障添加评论的参数。", "required": [ - "incident_ids" + "incident_ids", + "comment" ], "properties": { "incident_ids": { @@ -19763,21 +19814,21 @@ "items": { "type": "string" }, - "description": "Critical 级别使用的通知渠道(如 `voice`、`sms`、`email`、`feishu`)。" + "description": "Critical 级别使用的通知渠道。个人通知渠道：`sms`、`voice`、`email`、`push`；IM 群聊渠道：`feishu_app:`、`dingtalk_app:`、`wecom_app:`、`slack_app:`、`teams_app:`。" }, "warning": { "type": "array", "items": { "type": "string" }, - "description": "Warning 级别使用的通知渠道。" + "description": "Warning 级别使用的通知渠道。取值同 `critical`。" }, "info": { "type": "array", "items": { "type": "string" }, - "description": "Info 级别使用的通知渠道。" + "description": "Info 级别使用的通知渠道。取值同 `critical`。" } } }, @@ -19793,7 +19844,7 @@ "properties": { "type": { "type": "string", - "description": "Webhook 类型(如 `feishu`、`dingtalk_app`、`wecom_app`、`slack`、`teams`、`custom`)。" + "description": "Webhook 类型，可选值：`feishu`、`feishu_app`、`dingtalk`、`dingtalk_app`、`wecom`、`slack`、`slack_app`、`teams_app`、`telegram`、`zoom`。" }, "settings": { "type": "object", @@ -19839,7 +19890,30 @@ "maxItems": 100, "description": "按过滤条件的聚合策略覆盖。", "items": { - "type": "object" + "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.`。" + } + } } }, "all_equals_required": { @@ -19956,6 +20030,10 @@ "is_external_report_enabled": { "type": "boolean", "description": "允许外部上报人向该协作空间上报故障。" + }, + "event_group": { + "$ref": "#/components/schemas/EventGroup", + "description": "告警事件合并配置。不传时使用默认配置（启用合并，窗口 1440 分钟）。" } } }, @@ -19985,7 +20063,7 @@ }, "filters": { "type": "array", - "description": "或-与组合条件树。每个外层元素为一组 AND 条件,组内所有条件需同时满足。", + "description": "告警事件匹配条件（OR-of-AND 结构）；命中的事件被完全丢弃——不产生告警、故障或通知。不传或为空时，规则不匹配任何事件。", "items": { "type": "array", "items": { @@ -20141,21 +20219,21 @@ "items": { "type": "string" }, - "description": "Critical 级别使用的通知渠道(如 `voice`、`sms`、`email`、`feishu`)。" + "description": "Critical 级别使用的通知渠道。个人通知渠道：`sms`、`voice`、`email`、`push`；IM 群聊渠道：`feishu_app:`、`dingtalk_app:`、`wecom_app:`、`slack_app:`、`teams_app:`。" }, "warning": { "type": "array", "items": { "type": "string" }, - "description": "Warning 级别使用的通知渠道。" + "description": "Warning 级别使用的通知渠道。取值同 `critical`。" }, "info": { "type": "array", "items": { "type": "string" }, - "description": "Info 级别使用的通知渠道。" + "description": "Info 级别使用的通知渠道。取值同 `critical`。" } } }, @@ -20171,7 +20249,7 @@ "properties": { "type": { "type": "string", - "description": "Webhook 类型(如 `feishu`、`dingtalk_app`、`wecom_app`、`slack`、`teams`、`custom`)。" + "description": "Webhook 类型，可选值：`feishu`、`feishu_app`、`dingtalk`、`dingtalk_app`、`wecom`、`slack`、`slack_app`、`teams_app`、`telegram`、`zoom`。" }, "settings": { "type": "object", @@ -20231,7 +20309,7 @@ }, "filters": { "type": "array", - "description": "或-与组合条件树。每个外层元素为一组 AND 条件,组内所有条件需同时满足。", + "description": "故障级匹配条件（OR-of-AND 结构）：策略匹配的是告警聚合而成的故障，而不是告警本身。不传或为空时对空间内所有故障生效。", "items": { "type": "array", "items": { @@ -20423,11 +20501,11 @@ "items": { "type": "string" }, - "description": "用于匹配源告警与目标告警的 label 键列表。" + "description": "源（抑制方）告警与目标（被抑制）告警之间必须取值相等的字段键，例如 `data_source_id` 或 `labels.cluster`。" }, "source_filters": { "type": "array", - "description": "或-与组合条件树。每个外层元素为一组 AND 条件,组内所有条件需同时满足。", + "description": "源告警需要满足的条件，针对已存的活跃告警求值。支持的键：`status`、`incident_status`、`alert_status`、`severity`、`incident_severity`、`alert_severity`、`title`、`description` 或任意 `labels.`。为空时策略不生效。", "items": { "type": "array", "items": { @@ -20463,7 +20541,7 @@ }, "target_filters": { "type": "array", - "description": "或-与组合条件树。每个外层元素为一组 AND 条件,组内所有条件需同时满足。", + "description": "目标（被抑制）告警事件需要满足的条件；为空表示所有事件都是抑制目标。", "items": { "type": "array", "items": { @@ -20499,7 +20577,7 @@ }, "is_directly_discard": { "type": "boolean", - "description": "为 true 时被抑制的目标告警将直接丢弃而非合并。" + "description": "为 true 时，命中的告警事件被完全丢弃；为 false 时，告警仍会被记录，但标记为被本策略静默。" } } }, @@ -20529,7 +20607,8 @@ }, "from_incident_id": { "type": "string", - "description": "当静默策略从故障创建时对应的源故障 ID。" + "description": "策略关联的故障 ID（ObjectID 十六进制）。可选；设置后每个故障最多存在一条启用中的静默策略。", + "pattern": "^[0-9a-fA-F]{24}$" }, "time_filters": { "type": "array", @@ -20575,18 +20654,20 @@ "start_time": { "type": "integer", "format": "int64", - "description": "窗口起始时间戳(Unix 秒),需小于 `end_time`。" + "description": "窗口起始时间，Unix 秒时间戳。必须大于 0 且小于 `end_time`。", + "exclusiveMinimum": 0 }, "end_time": { "type": "integer", "format": "int64", - "description": "窗口结束时间戳(Unix 秒)。" + "description": "窗口结束时间，Unix 秒时间戳。必须大于 0。", + "exclusiveMinimum": 0 } } }, "filters": { "type": "array", - "description": "或-与组合条件树。每个外层元素为一组 AND 条件,组内所有条件需同时满足。", + "description": "告警事件匹配条件（OR-of-AND 结构）。必填且至少包含一个条件。", "items": { "type": "array", "items": { @@ -20622,7 +20703,7 @@ }, "is_directly_discard": { "type": "boolean", - "description": "为 true 时被静默的告警将直接丢弃而非并入故障。" + "description": "为 true 时，命中的告警事件被完全丢弃；为 false 时，告警仍会被记录，但标记为被本策略静默。" }, "is_auto_delete": { "type": "boolean", @@ -20637,6 +20718,7 @@ "page_id", "type", "title", + "description", "status", "updates" ], @@ -20644,7 +20726,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "type": { "type": "string", @@ -20661,7 +20743,7 @@ }, "description": { "type": "string", - "description": "事件描述(支持 Markdown),必填。" + "description": "事件描述（支持 Markdown），必填，不能为空。" }, "status": { "type": "string", @@ -20679,7 +20761,7 @@ "start_at_seconds": { "type": "integer", "format": "int64", - "description": "事件开始时间(Unix 秒)。留空时默认为当前时间。" + "description": "事件开始时间（Unix 秒）。存储的开始时间始终以第一条更新的 `at_seconds` 为准（该字段缺省时取当前时间）；对于开启 `auto_update_by_schedule` 的维护事件，本字段用于调度自动切换为 `ongoing` 的任务。" }, "responders": { "type": "array", @@ -20687,7 +20769,7 @@ "type": "integer", "format": "int64" }, - "description": "事件负责成员 ID 列表，可通过 `POST /member/list` 获取。" + "description": "事件负责成员的 ID 列表。" }, "linked_changes": { "type": "array", @@ -20699,7 +20781,7 @@ "close_at_seconds": { "type": "integer", "format": "int64", - "description": "回溯事件的结束时间,需大于 `start_at_seconds`。" + "description": "事件结束时间（Unix 秒），必须大于或等于第一条更新的 `at_seconds`。回溯事件用它表示结束时间；对于开启 `auto_update_by_schedule` 的维护事件，它用于调度自动切换为 `completed` 的任务，且距当前时间不能超过 30 天。" }, "updates": { "type": "array", @@ -20714,10 +20796,13 @@ "at_seconds": { "type": "integer", "format": "int64", - "description": "更新时间戳(Unix 秒)。" + "description": "更新时间戳（Unix 秒）。第一条更新缺省或为 0 时取当前时间。" }, "status": { - "type": "string", + "type": [ + "string", + "null" + ], "enum": [ "investigating", "identified", @@ -20730,7 +20815,10 @@ "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", + "type": [ + "string", + "null" + ], "description": "更新说明(支持 Markdown)。" }, "component_changes": { @@ -20744,7 +20832,7 @@ "properties": { "component_id": { "type": "string", - "description": "组件 ID，可通过 `POST /status-page/info` 获取。" + "description": "组件 ID，可通过 `GET /status-page/info` 获取。" }, "status": { "type": "string", @@ -20763,7 +20851,8 @@ } } }, - "description": "时间线更新列表。即时事件一般只传一条;回溯事件需传入全部历史更新。" + "description": "时间线更新列表。至少传 1 条，且至少有一条必须包含 `component_changes`。即时事件一般只传一条；回溯事件需传入全部历史更新。", + "minItems": 1 }, "notify_subscribers": { "type": "boolean", @@ -20785,23 +20874,24 @@ "required": [ "page_id", "change_id", - "status" + "status", + "description" ], "properties": { "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "change_id": { "type": "integer", "format": "int64", - "description": "目标事件 ID，可通过 `POST /status-page/change/list` 获取。" + "description": "目标事件 ID，可通过 `GET /status-page/change/list` 获取。" }, "at_seconds": { "type": "integer", "format": "int64", - "description": "更新时间戳(Unix 秒),留空时默认为当前时间。" + "description": "更新时间戳（Unix 秒），缺省或为 0 时取当前时间。" }, "status": { "type": "string", @@ -20814,11 +20904,11 @@ "ongoing", "completed" ], - "description": "更新后的事件状态,需与事件类型匹配。当状态切换为 `resolved` 或 `completed` 时,所有关联组件必须恢复为 `operational`。\n| 值 | 含义 |\n|---|---|\n| `investigating` | 排查中（incident）。 |\n| `identified` | 已定位原因（incident）。 |\n| `monitoring` | 已修复，观察中（incident）。 |\n| `scheduled` | 已计划（maintenance）。 |\n| `ongoing` | 进行中（maintenance）。 |" + "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": { "type": "string", - "description": "更新说明(支持 Markdown),必填。" + "description": "更新说明（支持 Markdown），必填，不能为空。" }, "component_changes": { "type": "array", @@ -20831,7 +20921,7 @@ "properties": { "component_id": { "type": "string", - "description": "组件 ID，可通过 `POST /status-page/info` 获取。" + "description": "组件 ID，可通过 `GET /status-page/info` 获取。" }, "status": { "type": "string", @@ -20882,10 +20972,6 @@ } } }, - "CsvFileResponse": { - "type": "string", - "description": "以附件形式返回的 CSV 文件内容。" - }, "DeletePostMortemRequest": { "type": "object", "description": "删除复盘报告的参数。", @@ -20910,12 +20996,12 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "change_id": { "type": "integer", "format": "int64", - "description": "目标事件 ID，可通过 `POST /status-page/change/list` 获取。" + "description": "目标事件 ID，可通过 `GET /status-page/change/list` 获取。" } } }, @@ -20931,16 +21017,16 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "change_id": { "type": "integer", "format": "int64", - "description": "所属事件 ID，可通过 `POST /status-page/change/list` 获取。" + "description": "所属事件 ID，可通过 `GET /status-page/change/list` 获取。" }, "update_id": { "type": "string", - "description": "要删除的时间线更新 ID，可通过 `POST /status-page/change/info` 获取。" + "description": "要删除的时间线更新 ID，可通过 `GET /status-page/change/info` 获取。" } } }, @@ -21051,22 +21137,22 @@ "mean_seconds_to_ack": { "type": "number", "format": "double", - "description": "平均首次认领耗时（秒）。" + "description": "平均首次认领耗时（秒）；桶内无已认领故障时为 0。" }, "mean_seconds_to_close": { "type": "number", "format": "double", - "description": "平均关闭耗时（秒）。" + "description": "平均关闭耗时（秒）；桶内无已关闭故障时为 0。" }, "noise_reduction_pct": { "type": "number", "format": "double", - "description": "降噪比（%）：`100 − 故障数 ÷ 告警事件数 × 100`；无告警事件对比数据时为 0。" + "description": "降噪比（%）：100 − 故障数 ÷ 告警事件数 × 100，保留两位小数；无告警事件数据或告警事件数不超过故障数时为 0。" }, "acknowledgement_pct": { "type": "number", "format": "double", - "description": "认领率（%）：认领过的故障数 ÷ 故障总数 × 100，保留两位小数；故障总数为 0 时为 100。" + "description": "认领率（%）：已认领故障数 ÷ 故障总数 × 100，保留两位小数且不超过 100；桶内无故障时为 0。" }, "total_alert_cnt": { "type": "integer", @@ -21107,7 +21193,8 @@ "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, - "description": "需禁用自动合并的故障 ID 列表。" + "description": "需禁用自动合并的故障 ID 列表。", + "minItems": 1 } } }, @@ -21185,7 +21272,8 @@ "properties": { "key": { "type": "string", - "description": "告警标签键。" + "description": "要匹配的事件键（如 `labels.severity`、`title`），不能为空。", + "minLength": 1 }, "oper": { "type": "string", @@ -21200,7 +21288,8 @@ "items": { "type": "string" }, - "description": "待匹配的值列表。" + "description": "匹配值列表，至少包含 1 个。", + "minItems": 1 } } }, @@ -21220,14 +21309,17 @@ "mapping", "drop" ], - "description": "规则类型。`extraction` 通过正则或 GJson 提取标签；`composition` 通过模板组合标签；`mapping` 通过映射规则或 API 查找填充标签；`drop` 删除标签。" + "description": "规则类型。\n| 值 | 含义 |\n|---|---|\n| `extraction` | 通过正则或 GJson 从告警的 `title`、`description` 或 `labels.*` 键提取值并写入标签。 |\n| `composition` | 用 Go `text/template` 对事件渲染模板，结果写入标签。 |\n| `mapping` | 从映射规则或外部映射 API 查找标签。 |\n| `drop` | 从告警中删除指定标签。 |" }, "if": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/EnrichFilter" }, - "description": "可选 AND 过滤条件列表，不匹配时跳过该规则。" + "description": "可选的 AND 过滤条件列表；所有条件都匹配时才执行该规则。无条件时为 `null`。过滤键来自告警/变更事件的键集合（如 `title`、`labels.severity`）。" }, "settings": { "description": "与规则类型对应的配置，具体结构由 `kind` 字段决定。", @@ -21289,7 +21381,11 @@ }, "status": { "type": "string", - "description": "规则集状态。" + "enum": [ + "enabled", + "deleted" + ], + "description": "规则集状态：`enabled`（生效）或 `deleted`（已软删除）。读取接口会过滤软删除的规则集，响应中始终为 `enabled`。" }, "updated_by": { "type": "integer", @@ -21310,6 +21406,11 @@ "type": "integer", "format": "int64", "description": "最后更新时间，Unix 时间戳（秒）。" + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "删除时间，Unix 时间戳（秒）。规则集未删除时省略；读取接口不会返回已软删除的规则集，因此实际上始终省略。" } }, "required": [ @@ -21334,7 +21435,8 @@ "type": "integer", "format": "int64" }, - "description": "待查询的集成 ID 列表。" + "description": "待查询的集成 ID 列表，至少包含 1 个。", + "minItems": 1 } } }, @@ -21451,12 +21553,14 @@ "properties": { "result_label": { "type": "string", - "description": "写入组合值的目标标签键，须符合 `^[a-z][a-z0-9_]{0,62}$`。" + "description": "组合值写入的目标标签键名，须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`。", + "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "template": { "type": "string", "maxLength": 500, - "description": "Go `text/template` 字符串，可引用告警字段 `{{.title}}`、`{{.description}}`、`{{.labels.key}}`。示例：`{{.labels.region}}-{{.labels.env}}`。" + "description": "Go `text/template` 模板串（1–500 字符），基于事件结构体渲染，如 `{{.Title}}`、`{{.Description}}`、`{{.Labels.key}}`。示例：`{{.Labels.region}}-{{.Labels.env}}`。", + "minLength": 1 }, "override": { "type": "boolean", @@ -21494,11 +21598,12 @@ }, "result_label": { "type": "string", - "description": "写入提取值的目标标签键，须符合 `^[a-z][a-z0-9_]{0,62}$`。" + "description": "提取值写入的目标标签键名，须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`。", + "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "pattern": { "type": "string", - "description": "RE2 正则表达式。使用命名捕获组 `(?P...)` 提取子匹配；无命名组时取全匹配。与 `g_json` 互斥。" + "description": "应用于源值的 RE2 正则表达式，须至少包含一个捕获组；所有捕获组用空格连接后写入 `result_label`。与 `g_json` 互斥。" }, "g_json": { "type": "string", @@ -21520,9 +21625,10 @@ "result_labels": { "type": "array", "items": { - "type": "string" + "type": "string", + "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, - "description": "从映射查找结果中填充的目标标签键列表。" + "description": "映射查找结果要填充的标签键名，每个须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`。" }, "mapping_type": { "type": "string", @@ -21642,15 +21748,17 @@ "description": "策略生效的周期性时间窗口。" }, "filters": { - "$ref": "#/components/schemas/FilterGroup" + "$ref": "#/components/schemas/FilterGroup", + "description": "故障级匹配条件（OR-of-AND 结构）：策略匹配的是告警聚合而成的故障，而不是告警本身。不传或为空时对空间内所有故障生效。" }, "status": { "type": "string", "enum": [ "enabled", - "disabled" + "disabled", + "deleted" ], - "description": "策略状态。" + "description": "策略状态：`enabled` 生效中，`disabled` 已暂停，`deleted` 已软删除（仅详情接口可能返回；列表接口不会返回已删除策略）。" }, "template_id": { "type": "string", @@ -21670,17 +21778,17 @@ "deleted_at": { "type": "integer", "format": "int64", - "description": "删除时间（Unix 秒），仅软删除时返回。" + "description": "删除时间，Unix 秒时间戳。仅在策略被软删除时返回；已删除的策略不会出现在列表响应中。" }, "created_at": { "type": "integer", "format": "int64", - "description": "创建时间（Unix 秒）。" + "description": "创建时间，Unix 秒时间戳。" }, "updated_at": { "type": "integer", "format": "int64", - "description": "最近更新时间（Unix 秒）。" + "description": "最近更新时间，Unix 秒时间戳。" }, "channel_name": { "type": "string", @@ -21740,21 +21848,21 @@ "items": { "type": "string" }, - "description": "Critical 级别使用的通知渠道（如 `voice`、`sms`、`email`、`feishu`）。" + "description": "Critical 级别使用的通知渠道。个人通知渠道：`sms`、`voice`、`email`、`push`；IM 群聊渠道：`feishu_app:`、`dingtalk_app:`、`wecom_app:`、`slack_app:`、`teams_app:`。" }, "warning": { "type": "array", "items": { "type": "string" }, - "description": "Warning 级别使用的通知渠道。" + "description": "Warning 级别使用的通知渠道。取值同 `critical`。" }, "info": { "type": "array", "items": { "type": "string" }, - "description": "Info 级别使用的通知渠道。" + "description": "Info 级别使用的通知渠道。取值同 `critical`。" } } }, @@ -21770,7 +21878,7 @@ "properties": { "type": { "type": "string", - "description": "Webhook 类型（如 `feishu`、`dingtalk_app`、`wecom_app`、`slack`、`teams`、`custom`）。" + "description": "Webhook 类型，可选值：`feishu`、`feishu_app`、`dingtalk`、`dingtalk_app`、`wecom`、`slack`、`slack_app`、`teams_app`、`telegram`、`zoom`。" }, "settings": { "type": "object", @@ -21792,7 +21900,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "component_ids": { "type": "array", @@ -21838,7 +21946,7 @@ }, "locale": { "type": "string", - "description": "通知的首选语言。" + "description": "通知的首选语言。为空时不返回。" } } }, @@ -21880,6 +21988,17 @@ "progress": { "type": "string", "description": "认领时记录的处理进展。" + }, + "comment": { + "type": "string", + "description": "写入时间线评论的表单摘要。未提交认领表单摘要时省略。" + }, + "images": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Image" + }, + "description": "认领表单提交的图片，仅写入时间线记录。未提交时省略。" } }, "title": "i_ack" @@ -22222,6 +22341,17 @@ "escalation" ], "description": "触发恢复操作的来源。\n| 值 | 含义 |\n|---|---|\n| `voice` | 语音电话按键操作。 |\n| `console` | 控制台（Web UI）操作。 |\n| `card` | IM 通知卡片按钮（钉钉/飞书/Slack/Teams）。 |\n| `wcard` | 企业微信通知卡片按钮。 |\n| `event` | 事件驱动：关联告警全部恢复 Ok 自动关闭，或外部 ITSM 系统同步的关闭。 |\n| `autorslv` | 自动恢复：超过协作空间配置的自动恢复时长无新告警，由系统关闭。 |\n| `autorefresh` | 卡片自动刷新（保留值，恢复动态中不会出现）。 |\n| `escalation` | 升级流程（保留值，恢复动态中不会出现）。 |" + }, + "comment": { + "type": "string", + "description": "写入解决时间线评论的表单摘要。未提交解决表单摘要时省略。" + }, + "images": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Image" + }, + "description": "解决表单提交的图片，仅写入时间线记录。未提交时省略。" } }, "title": "i_rslv" @@ -22354,14 +22484,35 @@ "$ref": "#/components/schemas/AlertFeedType" }, "detail": { - "description": "类型特定的详情数据，结构依 `type` 而定。", + "description": "类型特定的详情数据，结构由 `type` 决定。对未存储详情的条目可能为 `null`。", "oneOf": [ { "$ref": "#/components/schemas/FeedDetailAlertTrigger" }, + { + "$ref": "#/components/schemas/FeedDetailAlertUpdate" + }, { "$ref": "#/components/schemas/FeedDetailAlertComment" }, + { + "$ref": "#/components/schemas/FeedDetailAlertMerge" + }, + { + "$ref": "#/components/schemas/FeedDetailAlertMuteBySilence" + }, + { + "$ref": "#/components/schemas/FeedDetailAlertMuteByInhibit" + }, + { + "$ref": "#/components/schemas/FeedDetailAlertMuteByFlapping" + }, + { + "$ref": "#/components/schemas/FeedDetailAlertAck" + }, + { + "$ref": "#/components/schemas/FeedDetailAlertUnack" + }, { "$ref": "#/components/schemas/FeedDetailAlertClose" } @@ -22370,7 +22521,14 @@ "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" } } @@ -22394,6 +22552,11 @@ "type": "integer", "format": "int64", "description": "最后更新时间，Unix 毫秒时间戳。" + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "软删除时间，Unix 时间戳（毫秒）。未删除时不返回该字段。" } } }, @@ -22538,7 +22701,30 @@ "maxItems": 100, "description": "按过滤条件的聚合策略覆盖。", "items": { - "type": "object" + "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.`。" + } + } } }, "all_equals_required": { @@ -22658,7 +22844,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "目标状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "目标状态页 ID，可通过 `GET /status-page/list` 获取。" }, "method": { "type": "string", @@ -22718,7 +22904,7 @@ "$ref": "#/components/schemas/IncidentFeedType" }, "detail": { - "description": "类型相关的负载，具体结构由 `type` 决定。", + "description": "由 `type` 决定的具体载荷；条目无结构化详情时为 `null`。", "oneOf": [ { "$ref": "#/components/schemas/FeedDetailIncidentNew" @@ -22818,6 +23004,9 @@ }, { "$ref": "#/components/schemas/FeedDetailWorkItemDeleted" + }, + { + "$ref": "#/components/schemas/FeedDetailAlertMerge" } ], "discriminator": { @@ -22855,7 +23044,8 @@ "i_wi_completed": "#/components/schemas/FeedDetailWorkItemCompleted", "i_wi_converted": "#/components/schemas/FeedDetailWorkItemConverted", "i_wi_bound": "#/components/schemas/FeedDetailWorkItemBound", - "i_wi_deleted": "#/components/schemas/FeedDetailWorkItemDeleted" + "i_wi_deleted": "#/components/schemas/FeedDetailWorkItemDeleted", + "a_merge": "#/components/schemas/FeedDetailAlertMerge" } } }, @@ -22933,6 +23123,7 @@ "incident_id", "account_id", "channel_id", + "team_id", "integration_id", "integration_ids", "integration_types", @@ -22995,6 +23186,11 @@ "format": "int64", "description": "协作空间 ID，独立故障为 0。" }, + "team_id": { + "type": "integer", + "format": "int64", + "description": "故障所属协作空间的团队 ID；协作空间无团队时为 0。" + }, "integration_id": { "type": "integer", "format": "int64", @@ -23174,7 +23370,8 @@ "description": "自定义字段取值，按字段名索引。" }, "assigned_to": { - "$ref": "#/components/schemas/AssignedTo" + "$ref": "#/components/schemas/AssignedTo", + "description": "故障当前的指派对象。" }, "reporter_email": { "type": "string", @@ -23392,7 +23589,12 @@ }, "progress": { "type": "string", - "description": "故障处理进度——`Triggered`、`Processing`、`Closed` 之一。" + "description": "故障处理状态——`Triggered`（触发）、`Processing`（处理中）、`Closed`（已关闭）之一。", + "enum": [ + "Triggered", + "Processing", + "Closed" + ] }, "severity": { "type": "string", @@ -23436,11 +23638,11 @@ "owner_id": { "type": "integer", "format": "int64", - "description": "故障负责人的成员 ID。" + "description": "故障负责人的成员 ID。为 0（无负责人）时不返回。" }, "owner_name": { "type": "string", - "description": "故障负责人的显示名称。" + "description": "故障负责人的显示名。为空时不返回。" }, "creator_id": { "type": "integer", @@ -23454,11 +23656,11 @@ "closer_id": { "type": "integer", "format": "int64", - "description": "关闭该故障的成员 ID。" + "description": "关闭人的成员 ID。为 0（非人工关闭）时不返回。" }, "closer_name": { "type": "string", - "description": "关闭该故障的成员显示名称。" + "description": "关闭人的显示名。为空时不返回。" }, "seconds_to_ack": { "type": "integer", @@ -23487,11 +23689,11 @@ "snoozed_before": { "type": "integer", "format": "int64", - "description": "故障被暂缓到何时的 Unix 时间戳（秒）。" + "description": "故障静默到的截止时间，Unix 时间戳（秒）。未静默时不返回该字段。" }, "ever_muted": { "type": "boolean", - "description": "该故障是否曾因抖动（flapping）被收敛静默。" + "description": "故障是否曾被降噪收敛。为 false 时不返回。" }, "frequency": { "type": "string", @@ -23499,7 +23701,7 @@ "frequent", "rare" ], - "description": "故障频次分类：`frequent` 高频、`rare` 低频。" + "description": "频率分类：`frequent`（高频）或 `rare`（低频）。未分类时不返回。" }, "responders": { "type": "array", @@ -23538,8 +23740,11 @@ } }, "assigned_to": { - "type": "object", - "description": "故障的当前分派目标。", + "type": [ + "object", + "null" + ], + "description": "故障的当前分派信息；无分派记录时为 `null`。", "properties": { "person_ids": { "type": "array", @@ -23588,12 +23793,12 @@ "additionalProperties": { "type": "string" }, - "description": "故障标签，键值对形式；无标签时不返回。" + "description": "故障标签键值对。本接口响应中始终不返回（仅供导出使用）。" }, "fields": { "type": "object", "additionalProperties": true, - "description": "故障自定义字段；无自定义字段时不返回。" + "description": "故障自定义字段。本接口响应中始终不返回（仅供导出使用）。" }, "notifications": { "type": "integer", @@ -23692,21 +23897,23 @@ "description": "规则描述。" }, "source_filters": { - "$ref": "#/components/schemas/FilterGroup" + "$ref": "#/components/schemas/FilterGroup", + "description": "源告警需要满足的条件，针对已存的活跃告警求值。支持的键：`status`、`incident_status`、`alert_status`、`severity`、`incident_severity`、`alert_severity`、`title`、`description` 或任意 `labels.`。为空时策略不生效。" }, "target_filters": { - "$ref": "#/components/schemas/FilterGroup" + "$ref": "#/components/schemas/FilterGroup", + "description": "目标（被抑制）告警事件需要满足的条件；为空表示所有事件都是抑制目标。" }, "equals": { "type": "array", "items": { "type": "string" }, - "description": "用于配对源告警与目标告警的 label 键列表。" + "description": "源（抑制方）告警与目标（被抑制）告警之间必须取值相等的字段键，例如 `data_source_id` 或 `labels.cluster`。" }, "is_directly_discard": { "type": "boolean", - "description": "为 true 时被抑制的目标告警直接丢弃；为 false 时告警仍会创建但被静音，不触发故障与通知。" + "description": "为 true 时，命中的告警事件被完全丢弃；为 false 时，告警仍会被记录，但标记为被本策略静默。" }, "status": { "type": "string", @@ -23735,6 +23942,11 @@ "type": "integer", "format": "int64", "description": "最近更新时间，Unix 时间戳（秒）。" + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "删除时间，Unix 秒时间戳。仅在策略被软删除时返回；已删除的策略不会出现在列表响应中。" } } }, @@ -23747,7 +23959,12 @@ }, "hours": { "type": "string", - "description": "启用 `split_hours` 时的时段桶。" + "description": "启用 `split_hours` 时的小时桶：`work`、`sleep` 或 `off`。`split_hours` 为 false 时不返回。", + "enum": [ + "work", + "sleep", + "off" + ] }, "total_alert_cnt": { "type": "integer", @@ -23784,7 +24001,8 @@ "start_time": { "type": "integer", "format": "int64", - "description": "起始时间，Unix 秒，必须大于 0。" + "description": "起始时间，Unix 秒。必须大于 0。", + "exclusiveMinimum": 0 }, "end_time": { "type": "integer", @@ -23797,7 +24015,8 @@ "type": "integer", "format": "int64" }, - "description": "按团队 ID 过滤，至多 100 项。" + "description": "按团队 ID 过滤，至多 100 项。", + "maxItems": 100 }, "channel_ids": { "type": "array", @@ -23805,7 +24024,8 @@ "type": "integer", "format": "int64" }, - "description": "按协作空间 ID 过滤，至多 100 项。" + "description": "按协作空间 ID 过滤，至多 100 项。", + "maxItems": 100 }, "responder_ids": { "type": "array", @@ -23813,7 +24033,8 @@ "type": "integer", "format": "int64" }, - "description": "按处理人员 ID 过滤，至多 100 项。" + "description": "按处理人员 ID 过滤，至多 100 项。", + "maxItems": 100 }, "severities": { "type": "array", @@ -23826,7 +24047,8 @@ "Ok" ] }, - "description": "按严重程度过滤，至多 3 项。" + "description": "按严重程度过滤，至多 3 项。", + "maxItems": 3 }, "incident_ids": { "type": "array", @@ -23834,11 +24056,12 @@ "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, - "description": "按故障 ID（MongoDB ObjectID）过滤，至多 100 项。" + "description": "按故障 ID（MongoDB ObjectID）过滤，至多 100 项。", + "maxItems": 100 }, "query": { "type": "string", - "description": "作用于故障标题与描述的全文关键字。" + "description": "对故障标题做子串匹配（SQL `LIKE %query%`）。" }, "labels": { "type": "object", @@ -23857,11 +24080,11 @@ "enum": [ "created_at" ], - "description": "底层故障集合的排序字段。当前仅支持 `created_at`（按故障创建时间）。" + "description": "故障列表的排序字段，目前仅支持 `created_at`（故障创建时间）。仅 `/insight/incident/list` 使用。" }, "asc": { "type": "boolean", - "description": "为 `true` 时升序，否则降序。" + "description": "为 `true` 时升序，否则降序。仅 `/insight/incident/list` 使用。" }, "is_my_team": { "type": "boolean", @@ -23869,65 +24092,39 @@ }, "time_zone": { "type": "string", - "description": "IANA 时区名（如 `Asia/Shanghai`），用于解释时间范围。默认使用账户时区。" + "description": "用于划分 日/周/月 聚合桶的 IANA 时区名（如 `Asia/Shanghai`）。可选，默认 UTC；仅 `/insight/incident/export` 例外：缺省时依次回退到账户时区、`Asia/Shanghai`。" }, "seconds_to_close_from": { "type": "integer", "format": "int64", - "description": "解决时长下界（秒，包含）。" + "description": "解决时长下界（秒，包含）。", + "minimum": 0 }, "seconds_to_close_to": { "type": "integer", "format": "int64", - "description": "解决时长上界（秒，不包含）。两端同时设置时，必须大于 `seconds_to_close_from`。" + "description": "解决时长上界（秒，不包含）。两端同时设置时，必须大于 `seconds_to_close_from`。", + "minimum": 0 }, "seconds_to_ack_from": { "type": "integer", "format": "int64", - "description": "认领时长下界（秒，包含）。" + "description": "认领时长下界（秒，包含）。", + "minimum": 0 }, "seconds_to_ack_to": { "type": "integer", "format": "int64", - "description": "认领时长上界（秒，不包含）。两端同时设置时，必须大于 `seconds_to_ack_from`。" + "description": "认领时长上界（秒，不包含）。两端同时设置时，必须大于 `seconds_to_ack_from`。", + "minimum": 0 }, "export_fields": { "type": "array", "items": { - "type": "string", - "enum": [ - "incident_id", - "title", - "severity", - "progress", - "channel_id", - "channel_name", - "team_id", - "team_name", - "created_at", - "seconds_to_ack", - "seconds_to_close", - "closed_by", - "engaged_seconds", - "hours", - "notifications", - "interruptions", - "acknowledgements", - "assignments", - "reassignments", - "escalations", - "manual_escalations", - "timeout_escalations", - "assigned_to", - "responders", - "description", - "labels", - "fields", - "creator_id", - "creator_name" - ] + "type": "string" }, - "description": "导出 CSV 时要包含的列键子集，至多 50 项。仅导出接口会读取。" + "description": "导出 CSV 的列 key 列表，按给定顺序输出；未知或重复的 key 会被拒绝。各导出接口支持的 key 集合不同，见对应接口的描述。仅导出接口使用；最多 50 个。", + "maxItems": 50 }, "description_html_to_text": { "type": "boolean", @@ -23952,21 +24149,30 @@ "description": "故障分页列表请求。在 InsightFilter 基础上增加分页字段。", "properties": { "p": { - "type": "integer", - "minimum": 1, + "type": [ + "integer", + "null" + ], + "minimum": 0, "default": 1, - "description": "页码，从 1 开始，默认 1。" + "description": "页码，从 1 开始。仅在未提供 `search_after_ctx` 时生效；`p * limit` 不能超过 10,000 条。" }, "limit": { - "type": "integer", - "minimum": 1, + "type": [ + "integer", + "null" + ], + "minimum": 0, "maximum": 100, "default": 20, - "description": "每页条数，范围 1-100，默认 20。" + "description": "每页条数，最大 100，默认 20。" }, "search_after_ctx": { - "type": "string", - "description": "上一页返回的游标 token，下一页请求时回传。" + "type": [ + "string", + "null" + ], + "description": "上一页返回的分页游标（该页最后一行的故障 ID），传入以获取下一页。" } } } @@ -23986,7 +24192,7 @@ }, "search_after_ctx": { "type": "string", - "description": "用于翻下一页的游标 token，下次请求时通过 `search_after_ctx` 回传。" + "description": "下一页游标——本页最后一行的故障 ID。仅在 `has_next_page` 为 true 时返回。" }, "items": { "type": "array", @@ -24044,7 +24250,10 @@ }, "k": { "type": "integer", - "description": "返回前 K 条记录，取值范围 1-100。" + "description": "返回的前 K 条记录数，1 到 100，默认 20。", + "minimum": 1, + "maximum": 100, + "default": 20 }, "orderby": { "type": "string", @@ -24052,7 +24261,7 @@ "total_alert_cnt", "total_alert_event_cnt" ], - "description": "排序字段。`total_alert_cnt` 按告警数量排序；`total_alert_event_cnt` 按原始告警事件数量排序。" + "description": "排序字段。`total_alert_cnt` 按告警数排序；`total_alert_event_cnt` 按原始告警事件数排序（默认）。" }, "asc": { "type": "boolean", @@ -24113,11 +24322,11 @@ "channel_name", "last_incident_at" ], - "description": "排序字段。" + "description": "排序字段。默认为 `created_at`。" }, "asc": { "type": "boolean", - "description": "为 true 时升序排序。" + "description": "为 true 时升序排列；默认为 false（降序）。" }, "is_my_managed": { "type": "boolean", @@ -24129,7 +24338,7 @@ }, "is_brief": { "type": "boolean", - "description": "为 true 时仅返回简要字段（`channel_id`、`channel_name`、`description`、`status`）。" + "description": "为 true 时仅返回 `channel_id`、`channel_name`、`description` 和 `status` 字段，且不分页，一次返回全部匹配结果。" }, "is_my_team": { "type": "boolean", @@ -24145,7 +24354,7 @@ }, "query": { "type": "string", - "description": "按名称/描述的全文查询串。" + "description": "针对协作空间名称和描述的不区分大小写正则匹配；正则语法非法时按字面量匹配。" }, "channel_ids": { "type": "array", @@ -24558,7 +24767,7 @@ "drafting", "published" ], - "description": "复盘状态，缺省时服务端默认按 `published` 过滤。`drafting` 仅返回草稿中的复盘；`published` 仅返回已发布的复盘。" + "description": "可选的复盘状态过滤：`drafting` 仅返回草稿，`published` 仅返回已发布。缺省时返回全部状态的复盘。" }, "team_ids": { "type": "array", @@ -24664,7 +24873,8 @@ "type": "integer", "format": "int64" }, - "description": "需要查询路由规则的集成 ID 列表。" + "description": "需要查询路由规则的集成 ID 列表。", + "minItems": 1 } } }, @@ -24824,7 +25034,8 @@ }, "total": { "type": "integer", - "description": "匹配记录总数。" + "description": "匹配记录总数。", + "format": "int64" }, "search_after_ctx": { "type": "string", @@ -24846,7 +25057,7 @@ }, "description": { "type": "string", - "description": "可选描述。" + "description": "可选描述，超过 500 字符会被静默截断。" }, "url": { "type": "string", @@ -24863,15 +25074,19 @@ "additionalProperties": { "type": "string" }, - "description": "自定义 HTTP 请求头。" + "description": "自定义 HTTP 请求头。SaaS 模式下安全敏感的请求头名（`authorization`、`cookie`、`x-forwarded-for` 等）会被拒绝；键须为 RFC 7230 token 字符（最长 1024），值最长 4096 字符。" }, "timeout": { "type": "integer", - "description": "请求超时秒数（1–3），默认 2。" + "description": "请求超时秒数（1–3），默认 2。", + "minimum": 1, + "maximum": 3 }, "retry_count": { "type": "integer", - "description": "失败重试次数（0–1），默认 0。" + "description": "失败重试次数（0–1），默认 0。", + "minimum": 0, + "maximum": 1 }, "team_id": { "type": "integer", @@ -24930,11 +25145,14 @@ "description": "端点 URL。" }, "headers": { - "type": "object", + "type": [ + "object", + "null" + ], "additionalProperties": { "type": "string" }, - "description": "自定义请求头。" + "description": "自定义请求头，未配置时为 `null`。" }, "timeout": { "type": "integer", @@ -24950,7 +25168,11 @@ }, "status": { "type": "string", - "description": "API 状态。" + "enum": [ + "enabled", + "deleted" + ], + "description": "API 状态：`enabled`（生效）或 `deleted`（已软删除）。list 接口不返回 `deleted`，info 接口可能返回。" }, "team_id": { "type": "integer", @@ -24970,12 +25192,17 @@ "created_at": { "type": "integer", "format": "int64", - "description": "创建时间，Unix 时间戳（秒）。" + "description": "创建时间，Unix 时间戳（秒）。为 0（历史数据）时省略。" }, "updated_at": { "type": "integer", "format": "int64", - "description": "最后更新时间，Unix 时间戳（秒）。" + "description": "最后更新时间，Unix 时间戳（秒）。为 0（历史数据）时省略。" + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "删除时间，Unix 时间戳（秒）。未软删除时省略。" } }, "required": [ @@ -25059,21 +25286,25 @@ "additionalProperties": { "type": "string" }, - "description": "新请求头映射（覆盖原有值）。" + "description": "自定义 HTTP 请求头。SaaS 模式下安全敏感的请求头名（`authorization`、`cookie`、`x-forwarded-for` 等）会被拒绝；键须为 RFC 7230 token 字符（最长 1024），值最长 4096 字符。" }, "timeout": { "type": [ "integer", "null" ], - "description": "新超时秒数。" + "description": "新超时秒数。", + "minimum": 1, + "maximum": 3 }, "retry_count": { "type": [ "integer", "null" ], - "description": "新重试次数。" + "description": "新重试次数。", + "minimum": 0, + "maximum": 1 }, "team_id": { "type": [ @@ -25112,24 +25343,24 @@ "properties": { "key": { "type": "string", - "description": "由来源标签值组合生成的唯一键。" + "description": "数据行的组合键——来源标签值（按标签名排序、以 `:` 连接）的 MD5。为空时省略。" }, "fields": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "该行所有标签的键值对。" + "description": "该行的全部标签键值对，为空时省略。" }, "created_at": { "type": "integer", "format": "int64", - "description": "创建时间，Unix 时间戳（秒）。" + "description": "创建时间，Unix 时间戳（秒），为 0 时省略。" }, "updated_at": { "type": "integer", "format": "int64", - "description": "最后更新时间，Unix 时间戳（秒）。" + "description": "最后更新时间，Unix 时间戳（秒），为 0 时省略。" } } }, @@ -25148,7 +25379,7 @@ "additionalProperties": { "type": "string" }, - "description": "按来源标签值精确过滤。若指定 query，须包含全部来源标签。" + "description": "按来源标签值精确过滤。不属于来源标签的键会被静默忽略；一旦指定，必须包含全部来源标签。" }, "orderby": { "type": "string", @@ -25156,25 +25387,37 @@ "created_at", "updated_at" ], - "description": "排序字段。" + "description": "排序字段，默认 `updated_at`。" }, "asc": { "type": "boolean", "description": "为 `true` 时升序排列。" }, "p": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "页码（从 1 开始），用于页码分页。" + "description": "页码（从 1 开始），用于页码分页；省略、`null` 或 0 时默认为 1。设置 `search_after_ctx` 时忽略该参数。页码分页最多可取 10,000 行（`p * limit <= 10000`）。", + "minimum": 0 }, "limit": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "每页数量（1–100，默认 20）。" + "description": "每页数量（0–100）；省略、`null` 或 0 时默认为 20。", + "minimum": 0, + "maximum": 100 }, "search_after_ctx": { - "type": "string", - "description": "用于游标分页的不透明游标令牌。" + "type": [ + "string", + "null" + ], + "description": "游标分页使用的不透明游标——传入上一次响应中的 `search_after_ctx`。须为 MongoDB ObjectID 十六进制字符串；设置后忽略 `p`。" } } }, @@ -25199,7 +25442,7 @@ }, "search_after_ctx": { "type": "string", - "description": "用于获取下一页的游标令牌。" + "description": "下一页游标（本页最后一行的 ObjectID 十六进制）。没有下一页时省略。" } }, "required": [ @@ -25208,21 +25451,6 @@ "has_next_page" ] }, - "MappingDataUploadRequest": { - "type": "object", - "description": "Multipart form-data 上传请求。`schema_id` 通过查询参数传入，`file` 为 CSV 文件字段。", - "properties": { - "schema_id": { - "type": "string", - "description": "映射规则 ID（以查询参数传递），可通过 `POST /enrichment/mapping/schema/list` 获取。" - }, - "file": { - "type": "string", - "format": "binary", - "description": "待上传的 CSV 文件。" - } - } - }, "MappingDataUpsertRequest": { "type": "object", "required": [ @@ -25243,7 +25471,7 @@ } }, "maxItems": 1000, - "description": "待插入或更新的数据行，每行须包含所有来源标签和结果标签的值。" + "description": "待插入或更新的数据行。每行须包含所有来源标签和结果标签；未知标签会被静默丢弃；单个值超过 2048 字符将被拒绝。" } } }, @@ -25288,18 +25516,22 @@ "source_labels": { "type": "array", "items": { - "type": "string" + "type": "string", + "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "maxItems": 3, - "description": "查找键标签名（1–3 个），不得与 `result_labels` 重叠。" + "description": "查找键标签名（1–3 个）。每个须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`；列表内不得重复，且不得与 `result_labels` 重叠。", + "uniqueItems": true }, "result_labels": { "type": "array", "items": { - "type": "string" + "type": "string", + "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "maxItems": 10, - "description": "输出标签名（1–10 个），不得与 `source_labels` 重叠。" + "description": "匹配后写入的输出标签名（1–10 个）。每个须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`；列表内不得重复，且不得与 `source_labels` 重叠。", + "uniqueItems": true } } }, @@ -25364,7 +25596,11 @@ }, "status": { "type": "string", - "description": "映射规则状态。" + "enum": [ + "enabled", + "deleted" + ], + "description": "映射规则状态：`enabled`（生效）或 `deleted`（已软删除）。list 接口不返回 `deleted`，info 接口可能返回。" }, "team_id": { "type": "integer", @@ -25384,12 +25620,17 @@ "created_at": { "type": "integer", "format": "int64", - "description": "创建时间，Unix 时间戳（秒）。" + "description": "创建时间，Unix 时间戳（秒）。为 0（历史数据）时省略。" }, "updated_at": { "type": "integer", "format": "int64", - "description": "最后更新时间，Unix 时间戳（秒）。" + "description": "最后更新时间，Unix 时间戳（秒）。为 0（历史数据）时省略。" + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "删除时间，Unix 时间戳（秒）。未软删除时省略。" } }, "required": [ @@ -25496,7 +25737,7 @@ "owner_id": { "type": "integer", "format": "int64", - "description": "可选，为目标故障设置新负责人。" + "description": "仅为兼容保留，服务端当前忽略该字段；合并不会修改目标故障的负责人。" }, "remove_source_incidents": { "type": "boolean", @@ -25515,12 +25756,12 @@ "sleep", "off" ], - "description": "启用 `split_hours` 时的时段桶。`work` 为周一至周五 08:00–19:00，`sleep` 为每日 23:00–08:00，`off` 为其余时间，均按账户时区判定（`sleep` 优先于 `work` 判定）。" + "description": "启用 `split_hours` 时的小时桶。`work` 为周一至周五 08:00–19:00，`sleep` 为每天 23:00–08:00，`off` 为其余时间，均按账户时区计算（`sleep` 优先于 `work`）。`split_hours` 为 false 时不返回。" }, "ts": { "type": "integer", "format": "int64", - "description": "聚合桶的起始时间（Unix 秒）。在使用 `aggregate_unit` 时返回。" + "description": "聚合桶的起始时间，Unix 时间戳（秒）。未使用 `aggregate_unit` 时等于 `start_time`。" }, "channel_id": { "type": "integer", @@ -25596,7 +25837,8 @@ "string", "null" ], - "description": "迁移后状态页的目标 URL 名称。省略时沿用源状态页的 URL 名称。" + "description": "新状态页的目标 URL 名称，会被规范化为 URL 安全的别名（最长 255 字符）。省略或传 null 时根据源状态页名称生成；显式传空字符串会被拒绝。", + "maxLength": 255 } } }, @@ -25635,6 +25877,10 @@ "failed_reason": { "type": "string", "description": "投递失败原因。" + }, + "sms_content": { + "type": "string", + "description": "短信投递时发送的短信内容。" } } }, @@ -25972,7 +26218,8 @@ "pattern": "^[0-9a-fA-F]{24}$" }, "maxItems": 100, - "description": "待删除的故障 ID 列表，单次最多 100 条。调用方必须拥有所有故障所在协作空间的访问权限。" + "description": "待删除的故障 ID 列表，单次最多 100 条。调用方必须拥有所有故障所在协作空间的访问权限。", + "minItems": 1 } } }, @@ -26056,7 +26303,10 @@ "description": "可选，应用到所有故障的解决方案说明。" }, "description": { - "type": "string", + "type": [ + "string", + "null" + ], "maxLength": 6144, "description": "新的故障描述，最多 6,144 个字符。提供后会在故障关闭前替换当前描述。" }, @@ -26178,12 +26428,12 @@ "mean_seconds_to_ack": { "type": "number", "format": "double", - "description": "该人员的平均认领耗时（秒）。" + "description": "该响应人的平均认领耗时（秒）；无认领记录时为 0。" }, "acknowledgement_pct": { "type": "number", "format": "double", - "description": "该人员的认领率（%）：认领过的故障数 ÷ 参与的故障数 × 100，保留两位小数。" + "description": "该响应人的认领率（%）：已认领故障数 ÷ 涉及故障数 × 100，保留两位小数且不超过 100；无故障时为 0。" } } } @@ -26205,9 +26455,7 @@ "type": "object", "description": "路由规则中的单个 case 分支。当其全部条件命中后,告警将分发到所配置的协作空间。", "required": [ - "if", - "channel_ids", - "fallthrough" + "if" ], "properties": { "if": { @@ -26218,12 +26466,15 @@ } }, "channel_ids": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "type": "integer", "format": "int64" }, - "description": "目标协作空间 ID。当 `routing_mode` 为 `standard`(或为空)时必填。" + "description": "目标协作空间 ID。当 `routing_mode` 为 `standard`（或为空）时必填；`name_mapping` 模式下返回 `null`。" }, "fallthrough": { "type": "boolean", @@ -26267,7 +26518,8 @@ "integration_id": { "type": "integer", "format": "int64", - "description": "集成 ID,必须大于 0。" + "description": "集成 ID,必须大于 0。", + "exclusiveMinimum": 0 } } }, @@ -26431,11 +26683,14 @@ "description": "分层模式：0 = 普通轮转，1 = 覆盖。" }, "schedules": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleCalculatedSchedule" }, - "description": "计算出的值班时段。" + "description": "计算出的班次；该层无排班时为 null。" } } }, @@ -26460,7 +26715,8 @@ "description": "时段结束时间（Unix 秒）。" }, "group": { - "$ref": "#/components/schemas/ScheduleGroup" + "$ref": "#/components/schemas/ScheduleGroup", + "description": "覆盖该班次的值班组；null 表示覆盖空档。" }, "index": { "type": "integer", @@ -26473,11 +26729,16 @@ "description": "按星期几生效的掩码配置。", "properties": { "repeat": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { - "type": "integer" + "type": "integer", + "minimum": 0, + "maximum": 6 }, - "description": "生效的星期几（0 = 周日）。" + "description": "参与轮转的星期数（0 = 周日）。与 restrict_mode = 2（按周）互斥。" } } }, @@ -26496,11 +26757,14 @@ "properties": { "cycle": { "type": "string", - "description": "通知周期。" + "description": "通知周期，仅支持 `day`（按天）。", + "enum": [ + "day" + ] }, "start": { "type": "string", - "description": "周期内的通知开始时间。" + "description": "发送时间，格式 `HH:MM`（24 小时制）。" } } }, @@ -26516,8 +26780,11 @@ ], "properties": { "group_name": { - "type": "string", - "description": "值班组显示名称。" + "type": [ + "string", + "null" + ], + "description": "值班组显示名称，仅设置旧字段 name 时为 null。" }, "name": { "type": "string", @@ -26603,7 +26870,8 @@ "description": "IM 提供方类型（如 feishu_app、dingtalk_app、wecom_app、teams_app、slack_app）。" }, "settings": { - "$ref": "#/components/schemas/ScheduleImNotifySettings" + "$ref": "#/components/schemas/ScheduleImNotifySettings", + "description": "Webhook 渠道配置。" } } }, @@ -26758,22 +27026,28 @@ "description": "更新人 ID。" }, "layers": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleLayer" }, - "description": "值班表的轮转分层。" + "description": "值班表定义的轮转层。未加载层信息时为 null（例如 `/schedule/infos`，或未传 start/end 的 `/schedule/list`）。" }, "field": { "type": "string", "description": "旧版字段更新接口使用的字段名。" }, "schedule_layers": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleCalculatedLayer" }, - "description": "按窗口计算出的分层值班结果。" + "description": "按请求时间窗口计算出的各层排班，未计算时为 null。" }, "final_schedule": { "$ref": "#/components/schemas/ScheduleCalculatedLayer", @@ -26782,20 +27056,24 @@ "start": { "type": "integer", "format": "int64", - "description": "窗口开始时间（Unix 秒）。" + "description": "时间窗口开始（Unix 秒）。为 0（未请求窗口）时省略。" }, "end": { "type": "integer", "format": "int64", - "description": "窗口结束时间（Unix 秒）。" + "description": "时间窗口结束（Unix 秒）。为 0（未请求窗口）时省略。" }, "notify": { - "$ref": "#/components/schemas/ScheduleNotify" + "$ref": "#/components/schemas/ScheduleNotify", + "description": "通知配置，未配置时为 null。" }, "schedule_id": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "值班表 ID。" + "description": "值班表 ID。`/schedule/preview` 返回时为 null。" }, "schedule_name": { "type": [ @@ -26820,11 +27098,14 @@ "description": "值班表描述。/schedule/preview 返回时为 null。" }, "layer_schedules": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleCalculatedLayer" }, - "description": "与 schedule_layers 等价，用于旧版兼容。" + "description": "schedule_layers 的兼容别名，未计算时为 null。" }, "status": { "type": [ @@ -26904,11 +27185,14 @@ "description": "分层权重，用于排序。" }, "groups": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleGroup" }, - "description": "参与轮转的值班组。" + "description": "参与轮转的值班组，未设置时为 null。" }, "rotation_duration": { "type": "integer", @@ -26918,7 +27202,7 @@ "handoff_time": { "type": "integer", "format": "int64", - "description": "值班交接时间，Unix 时间戳（秒）。" + "description": "轮转交接时间，以一周内的秒数偏移表示（星期 x 86400 + 当日秒数），不是 Unix 绝对时间戳。" }, "enable_time": { "type": "integer", @@ -26950,11 +27234,14 @@ "description": "旧版限制区间结束偏移（秒）。" }, "restrict_periods": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleRestrictPeriod" }, - "description": "每个值班周期内的限制区间集合。" + "description": "每个轮转周期内的限制时段，未设置时为 null。" }, "day_mask": { "$ref": "#/components/schemas/ScheduleDayMask", @@ -26981,17 +27268,23 @@ "description": "更新人 ID。" }, "layer_name": { - "type": "string", - "description": "分层显示名称。" + "type": [ + "string", + "null" + ], + "description": "面向用户的层名称，未设置时为 null。" }, "fair_rotation": { "type": "boolean", "description": "是否启用公平轮转。" }, "layer_start": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "分层开始时间（Unix 秒）。" + "description": "层生效时间（Unix 秒），未设置时为 null。" }, "layer_end": { "type": [ @@ -27014,7 +27307,8 @@ "rotation_value": { "type": "integer", "format": "int64", - "description": "轮转数量（每周期的 rotation_unit 个数）。" + "description": "轮转数量（每周期的 rotation_unit 个数）。", + "minimum": 0 }, "mask_continuous_enabled": { "type": "boolean", @@ -27028,7 +27322,7 @@ "properties": { "query": { "type": "string", - "description": "搜索关键字，匹配值班表名称。" + "description": "按值班表名称或描述匹配的关键字。" }, "p": { "type": "integer", @@ -27078,11 +27372,14 @@ ], "properties": { "items": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleItem" }, - "description": "当前页的值班表列表。" + "description": "当前页的值班表；无匹配时为 null。" }, "total": { "type": "integer", @@ -27102,7 +27399,8 @@ "role_id": { "type": "integer", "format": "int64", - "description": "值班角色 ID。" + "description": "值班角色 ID。", + "minimum": 0 }, "person_ids": { "type": "array", @@ -27110,7 +27408,8 @@ "type": "integer", "format": "int64" }, - "description": "该角色下的用户 ID 列表。" + "description": "该角色下的用户 ID 列表。", + "minItems": 1 } } }, @@ -27132,10 +27431,12 @@ "description": "提前通知时间（秒）；为 `0` 时在排班开始时通知；不传则不发送提前通知。" }, "fixed_time": { - "$ref": "#/components/schemas/ScheduleFixedTimeNotifyInfo" + "$ref": "#/components/schemas/ScheduleFixedTimeNotifyInfo", + "description": "定时通知配置，未配置时为 null。" }, "by": { - "$ref": "#/components/schemas/ScheduleNotifyBy" + "$ref": "#/components/schemas/ScheduleNotifyBy", + "description": "接收人通知偏好，未配置时为 null。" }, "im": { "type": "object", @@ -27145,11 +27446,14 @@ "description": "旧版 IM 类型到 token 的映射。" }, "webhooks": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleImNotify" }, - "description": "IM Webhook 通知通道。" + "description": "IM Webhook 通知渠道，未配置时为 null。" } } }, @@ -27197,7 +27501,8 @@ "description": "时段结束时间（Unix 秒）。" }, "group": { - "$ref": "#/components/schemas/ScheduleGroup" + "$ref": "#/components/schemas/ScheduleGroup", + "description": "该班次正在值班的值班组。" }, "update_at": { "type": "integer", @@ -27216,7 +27521,7 @@ }, "ScheduleRestrictPeriod": { "type": "object", - "description": "单个值班周期内的限制区间。", + "description": "轮转周期内的限制时段。restrict_start 与 restrict_end 为秒级偏移，除非都为 0，否则不能相等。", "required": [ "restrict_start", "restrict_end" @@ -27236,19 +27541,23 @@ }, "ScheduleSelfRequest": { "type": "object", - "description": "查询当前用户值班表的参数。start 和 end 为 Unix 时间戳（秒），缺省时默认为 0。时间窗口不得超过 30 天。", + "description": "查询当前用户值班表的参数。start 和 end 为必填的 10 位 Unix 秒级时间戳，时间窗口不得超过 45 天。", "properties": { "start": { "type": "integer", "format": "int64", - "description": "时间窗口开始时间（Unix 秒，10 位）。" + "description": "时间窗口开始时间（Unix 秒，10 位），必填。" }, "end": { "type": "integer", "format": "int64", - "description": "时间窗口结束时间（Unix 秒，10 位），与 start 的差值不得超过 30 天。" + "description": "时间窗口结束时间（Unix 秒，10 位），必填，与 start 的差值不得超过 45 天。" } - } + }, + "required": [ + "start", + "end" + ] }, "ScheduleSelfResponse": { "type": "object", @@ -27258,17 +27567,20 @@ ], "properties": { "items": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleItem" }, - "description": "当前用户被分配到的值班表（或请求指定的 ID 对应的值班表）。" + "description": "分配给当前用户的值班表（或匹配请求 ID 的值班表）；无时为 null。" } } }, "ScheduleUpsertRequest": { "type": "object", - "description": "值班表创建/更新/预览共用的请求体，结构与值班表详情一致，此处仅列出常用字段。更新时需要 schedule_id；预览时 start、end 必填。", + "description": "值班表创建/更新/预览请求体。服务端接受与值班表详情模型相同的结构，此处仅列出关键字段。创建时必填 `schedule_name`（或旧字段 `name`），更新时必填 `schedule_id`，预览时必填 `start` 和 `end`。", "properties": { "schedule_id": { "type": [ @@ -27330,6 +27642,13 @@ "type": "integer", "format": "int64", "description": "预览窗口结束时间（Unix 秒，10 位），/schedule/preview 必填，且距 start 不超过 45 天。" + }, + "disabled": { + "type": [ + "integer", + "null" + ], + "description": "0 = 启用，1 = 禁用。缺省时为启用。" } } }, @@ -27373,20 +27692,22 @@ "from_incident_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", - "description": "从故障创建静默时的源故障 ID。" + "description": "策略关联的故障 ID。始终返回；零值 ObjectID `000000000000000000000000` 表示该策略并非从故障创建。" }, "time_filters": { "type": "array", "items": { "$ref": "#/components/schemas/TimeFilter" }, - "description": "周期性时间窗口。" + "description": "周期性静默窗口。当策略使用一次性 `time_filter` 时为空。" }, "time_filter": { - "$ref": "#/components/schemas/OnceTimeFilter" + "$ref": "#/components/schemas/OnceTimeFilter", + "description": "一次性静默窗口。当策略使用周期性 `time_filters` 时，该字段以零值返回。" }, "filters": { - "$ref": "#/components/schemas/FilterGroup" + "$ref": "#/components/schemas/FilterGroup", + "description": "告警事件匹配条件；命中的事件在时间窗口内被静默。" }, "is_directly_discard": { "type": "boolean", @@ -27422,11 +27743,16 @@ }, "is_effective": { "type": "boolean", - "description": "当前是否正在生效。" + "description": "策略的时间窗口是否覆盖当前时刻（按响应时刻计算）。" }, "is_auto_delete": { "type": "boolean", "description": "为 true 时，静默规则在时间窗结束后会被自动删除；默认为 false。" + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "删除时间，Unix 秒时间戳。仅在策略被软删除时返回；已删除的策略不会出现在列表响应中。" } } }, @@ -27445,14 +27771,15 @@ "pattern": "^[0-9a-fA-F]{24}$" }, "maxItems": 100, - "description": "待暂停的故障 ID 列表，单次最多 100 条。" + "description": "待暂停的故障 ID 列表，单次最多 100 条。", + "minItems": 1 }, "minutes": { "type": "integer", "format": "int64", "exclusiveMinimum": 0, - "maximum": 1440, - "description": "暂停时长（分钟），必须大于 0 且不超过 1440（24 小时）。" + "maximum": 43200, + "description": "暂停时长（分钟），必须大于 0 且不超过 43,200（30 天）。" } } }, @@ -27492,7 +27819,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "所属状态页 ID。" + "description": "所属状态页 ID。为 0 时不返回（已存储事件必有值）。" }, "type": { "type": "string", @@ -27508,7 +27835,7 @@ }, "description": { "type": "string", - "description": "事件描述（Markdown）。" + "description": "事件描述（Markdown）。为空时不返回。" }, "status": { "type": "string", @@ -27521,14 +27848,14 @@ "ongoing", "completed" ], - "description": "事件当前状态。故障事件支持 `investigating`/`identified`/`monitoring`/`resolved`；维护事件支持 `scheduled`/`ongoing`/`completed`。" + "description": "事件当前状态。故障事件支持 `investigating`/`identified`/`monitoring`/`resolved`；维护事件支持 `scheduled`/`ongoing`/`completed`。为空时不返回（已存储事件必有值）。" }, "affected_components": { "type": "array", "items": { "$ref": "#/components/schemas/AffectedStatusPageComponentItem" }, - "description": "当前受此事件影响的组件及其状态。" + "description": "当前受此事件影响的组件及其状态。无受影响组件时不返回。" }, "responder_ids": { "type": "array", @@ -27536,43 +27863,43 @@ "type": "integer", "format": "int64" }, - "description": "事件负责成员 ID 列表。" + "description": "事件负责成员 ID 列表。未指派负责成员时不返回。" }, "linked_change_ids": { "type": "array", "items": { "type": "string" }, - "description": "关联的事件 ID 列表（相关故障、发布等）。" + "description": "关联的事件 ID 列表（相关故障、发布等）。为空时不返回。" }, "start_at_seconds": { "type": "integer", "format": "int64", - "description": "事件开始时间（Unix 秒）。" + "description": "事件开始时间（Unix 秒），取自第一条时间线更新。为 0 时不返回。" }, "close_at_seconds": { "type": "integer", "format": "int64", - "description": "计划结束时间（Unix 秒）。回溯事件和维护事件会设置此字段。" + "description": "事件结束时间（Unix 秒）。维护事件为计划结束时间；已关闭事件为进入终态（`resolved`/`completed`）的时间。未设置时不返回。" }, "is_retrospective": { "type": "boolean", - "description": "是否为回溯（历史）事件。" + "description": "是否为回溯（历史）事件。为 false 时不返回。" }, "updates": { "type": "array", "items": { "$ref": "#/components/schemas/StatusPageChangeUpdateItem" }, - "description": "事件的时间线更新列表，按时间排序。" + "description": "事件的时间线更新列表，按时间排序。事件无时间线更新时不返回。" }, "notify_subscribers": { "type": "boolean", - "description": "创建本事件时是否通知订阅者。" + "description": "创建本事件时是否通知订阅者。为 false 时不返回。" }, "auto_update_by_schedule": { "type": "boolean", - "description": "仅维护事件：是否根据计划窗口自动推进状态。" + "description": "仅维护事件：是否按计划窗口自动推进状态。为 false 时不返回。" } } }, @@ -27637,14 +27964,14 @@ }, "description": { "type": "string", - "description": "更新说明（Markdown）。" + "description": "更新说明（Markdown）。为空时不返回。" }, "component_changes": { "type": "array", "items": { "$ref": "#/components/schemas/StatusPageComponentChangeItem" }, - "description": "本次更新应用的组件状态变更。" + "description": "本次更新应用的组件状态变更。本次更新无组件状态变更时不返回。" } } }, @@ -27662,7 +27989,7 @@ }, "component_name": { "type": "string", - "description": "组件显示名称。读取时由后端填充，写入时忽略。" + "description": "组件显示名称。读取时由后端填充，写入时忽略。为空时不返回。" }, "status": { "type": "string", @@ -27686,11 +28013,11 @@ "properties": { "component_id": { "type": "string", - "description": "组件 ID。" + "description": "组件 ID。为空时不返回。" }, "section_id": { "type": "string", - "description": "所属区域 ID。" + "description": "所属区域 ID。组件位于顶层（不属于任何分组）时不返回。" }, "name": { "type": "string", @@ -27698,25 +28025,25 @@ }, "description": { "type": "string", - "description": "组件描述。" + "description": "组件描述。为空时不返回。" }, "available_since_seconds": { "type": "integer", "format": "int64", - "description": "组件首次可用时间（Unix 秒）。" + "description": "组件可用起始时间（Unix 时间戳，秒）。为 0 时不返回。" }, "order_id": { "type": "integer", "format": "int64", - "description": "在所属区域内的显示顺序。" + "description": "在所属区域内的显示顺序。为 0 时不返回。" }, "hide_uptime": { "type": "boolean", - "description": "为 true 时在摘要响应中隐藏可用率数据。" + "description": "为 true 时在摘要响应中隐藏可用率数据。为 false 时不返回。" }, "hide_all": { "type": "boolean", - "description": "为 true 时从摘要接口中完全隐藏该组件。" + "description": "为 true 时从摘要接口中完全隐藏该组件。为 false 时不返回。" } } }, @@ -27765,13 +28092,12 @@ "status": { "type": "string", "enum": [ - "pending", "running", "completed", "failed", "cancelled" ], - "description": "任务当前状态。\n| 值 | 含义 |\n|---|---|\n| `pending` | 已创建，等待执行。 |\n| `running` | 执行中。 |\n| `completed` | 已全部完成。 |\n| `failed` | 执行失败，`error` 字段含失败原因。 |\n| `cancelled` | 已被取消。 |" + "description": "任务当前状态。\n| 值 | 含义 |\n|---|---|\n| `running` | 执行中。 |\n| `completed` | 已全部完成。 |\n| `failed` | 执行失败，`error` 字段含失败原因。 |\n| `cancelled` | 已被取消。 |" }, "progress": { "$ref": "#/components/schemas/StatusPageMigrationProgress", @@ -27779,17 +28105,17 @@ }, "error": { "type": "string", - "description": "`status` 为 `failed` 时的终态错误信息。" + "description": "`status` 为 `failed` 时的终态错误信息。任务未失败时不返回该字段。" }, "created_at": { "type": "integer", "format": "int64", - "description": "任务创建时间（Unix 秒）。" + "description": "任务创建时间（Unix 时间戳，秒）。" }, "updated_at": { "type": "integer", "format": "int64", - "description": "任务最近一次状态更新时间（Unix 秒）。" + "description": "任务最近一次状态更新时间（Unix 时间戳，秒）。" } } }, @@ -27849,7 +28175,7 @@ "items": { "type": "string" }, - "description": "任务执行过程中记录的非致命警告。" + "description": "任务执行过程中记录的非致命警告。无告警时不返回该字段。" } } }, @@ -27934,7 +28260,7 @@ "minLength": 1, "maxLength": 39, "description": "模板名称，同一账户内唯一，长度 1–39 个字符。", - "example": "生产环境默认模板" + "example": "Prod incident default" }, "description": { "type": "string", @@ -28024,9 +28350,10 @@ "template_name": { "type": "string", "description": "从请求中回显的模板名称。", - "example": "生产环境默认模板" + "example": "Prod incident default" } - } + }, + "description": "创建模板响应。" }, "TemplateIDRequest": { "type": "object", @@ -28037,10 +28364,11 @@ "template_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", - "description": "要操作的模板 ID。传入 `000000000000000000000001` 可访问系统预置模板。", + "description": "目标模板 ID。传入 `6321aad26c12104586a88916` 可访问内置预设模板。", "example": "6605a1b2c3d4e5f6a7b8c9d0" } - } + }, + "description": "携带模板 ID 的请求体。" }, "TemplateItem": { "type": "object", @@ -28070,7 +28398,8 @@ "creator_id", "updated_by", "created_at", - "updated_at" + "updated_at", + "incident_card_hidden_fields" ], "properties": { "account_id": { @@ -28158,7 +28487,8 @@ "description": "Zoom 机器人消息模板源。" }, "incident_card_hidden_fields": { - "$ref": "#/components/schemas/IncidentCardHiddenFields" + "$ref": "#/components/schemas/IncidentCardHiddenFields", + "description": "按 IM 应用类型配置的故障卡片隐藏字段，未配置时为空对象。" }, "status": { "type": "string", @@ -28267,7 +28597,7 @@ "total": { "type": "integer", "format": "int64", - "description": "符合过滤条件的模板总数。", + "description": "符合筛选条件的模板总数（跨页统计，包含内置预设模板）。", "example": 47 }, "has_next_page": { @@ -28446,7 +28776,9 @@ "repeat": { "type": "array", "items": { - "type": "integer" + "type": "integer", + "minimum": 0, + "maximum": 6 }, "description": "窗口每周生效的日期，空表示每天。" }, @@ -28514,7 +28846,8 @@ "description": "规则描述。" }, "filters": { - "$ref": "#/components/schemas/FilterGroup" + "$ref": "#/components/schemas/FilterGroup", + "description": "告警事件匹配条件（OR-of-AND 结构）；命中的事件被完全丢弃。为空时规则不匹配任何事件。" }, "status": { "type": "string", @@ -28543,6 +28876,11 @@ "type": "integer", "format": "int64", "description": "最近更新时间，Unix 时间戳（秒）。" + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "删除时间，Unix 秒时间戳。仅在规则被软删除时返回；已删除的规则不会出现在列表响应中。" } } }, @@ -28608,7 +28946,7 @@ "trigger", "update" ], - "description": "自动恢复计时方式：`trigger` 从故障触发时开始计时，`update` 每次告警更新都重新计时。" + "description": "自动恢复计时模式：`trigger` 在故障触发时启动计时，`update` 在每次告警更新时重新计时。仅在请求同时携带 `auto_resolve_timeout` 时生效。" }, "is_private": { "type": [ @@ -28645,6 +28983,10 @@ "null" ], "description": "允许外部上报人向该协作空间上报故障。" + }, + "event_group": { + "$ref": "#/components/schemas/EventGroup", + "description": "告警事件合并配置。仅在传入时更新。" } } }, @@ -28690,7 +29032,7 @@ }, "filters": { "$ref": "#/components/schemas/FilterGroup", - "description": "命中条件的告警将被屏蔽，不产生任何通知。" + "description": "告警事件匹配条件（OR-of-AND 结构）；命中的事件被完全丢弃。为空时规则不匹配任何事件。" } } }, @@ -28758,7 +29100,7 @@ }, "filters": { "$ref": "#/components/schemas/FilterGroup", - "description": "本策略适用的告警匹配条件，留空表示对空间内全部告警生效。" + "description": "故障级匹配条件（OR-of-AND 结构）：策略匹配的是告警聚合而成的故障，而不是告警本身。不传或为空时对空间内所有故障生效。" } } }, @@ -28851,19 +29193,19 @@ "items": { "type": "string" }, - "description": "用于配对源告警与目标告警的 label 键列表。" + "description": "源（抑制方）告警与目标（被抑制）告警之间必须取值相等的字段键，例如 `data_source_id` 或 `labels.cluster`。" }, "source_filters": { "$ref": "#/components/schemas/FilterGroup", - "description": "源告警的匹配条件，与 `equals` 共同决定抑制哪些目标告警。" + "description": "源告警需要满足的条件，针对已存的活跃告警求值。支持的键：`status`、`incident_status`、`alert_status`、`severity`、`incident_severity`、`alert_severity`、`title`、`description` 或任意 `labels.`。为空时策略不生效。" }, "target_filters": { "$ref": "#/components/schemas/FilterGroup", - "description": "目标（被抑制）告警的匹配条件。" + "description": "目标（被抑制）告警事件需要满足的条件；为空表示所有事件都是抑制目标。" }, "is_directly_discard": { "type": "boolean", - "description": "为 true 时被抑制的目标告警直接丢弃，而非合并。" + "description": "为 true 时，命中的告警事件被完全丢弃；为 false 时，告警仍会被记录，但标记为被本策略静默。" } } }, @@ -28914,7 +29256,7 @@ }, "is_directly_discard": { "type": "boolean", - "description": "为 true 时静默的告警直接丢弃，而非抑制为故障。" + "description": "为 true 时，命中的告警事件被完全丢弃；为 false 时，告警仍会被记录，但标记为被本策略静默。" }, "is_auto_delete": { "type": "boolean", @@ -28933,12 +29275,12 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "change_id": { "type": "integer", "format": "int64", - "description": "目标事件 ID，可通过 `POST /status-page/change/list` 获取。" + "description": "目标事件 ID，可通过 `GET /status-page/change/list` 获取。" }, "title": { "type": [ @@ -28967,7 +29309,7 @@ }, "UpdateStatusPageChangeTimelineRequest": { "type": "object", - "description": "更新状态页事件已有时间线条目所需的参数。", + "description": "更新状态页事件已有时间线条目所需的参数。`at_seconds` 与 `description` 至少提供一个；未提供的字段保持原值。", "required": [ "page_id", "change_id", @@ -28977,16 +29319,16 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "change_id": { "type": "integer", "format": "int64", - "description": "所属事件 ID，可通过 `POST /status-page/change/list` 获取。" + "description": "所属事件 ID，可通过 `GET /status-page/change/list` 获取。" }, "update_id": { "type": "string", - "description": "目标时间线更新 ID，可通过 `POST /status-page/change/info` 获取。" + "description": "目标时间线更新 ID，可通过 `GET /status-page/change/info` 获取。" }, "at_seconds": { "type": "integer", @@ -29032,7 +29374,7 @@ "version": { "type": "integer", "format": "int64", - "description": "用于乐观并发控制的当前版本号,传入最近一次读取时返回的值。" + "description": "预留给乐观并发控制使用；当前服务端忽略该字段——每次 upsert 时服务端会自动递增 `version`。" } } }, @@ -29118,7 +29460,11 @@ }, "status": { "type": "string", - "description": "战情室状态。" + "description": "作战室记录状态：`enabled` 生效中，`deleted` 已解散。", + "enum": [ + "enabled", + "deleted" + ] }, "created_at": { "type": "integer", @@ -29133,7 +29479,7 @@ }, "WebhookHistoryDetail": { "type": "object", - "description": "Webhook 推送的完整详情。相较 `WebhookHistoryItem`，额外附带查询时解析出的引用元信息。", + "description": "单条 Webhook 投递记录的完整详情，在 `WebhookHistoryItem` 基础上增加查询时解析的关联对象信息。无匹配记录时，`data` 为空对象。", "required": [ "integration_id", "event_id", @@ -29158,11 +29504,15 @@ }, "webhook_type": { "type": "string", - "description": "来源对象类型：`incident` 或 `alert`。" + "description": "来源对象类型：`incident`（故障）或 `alert`（告警）。", + "enum": [ + "incident", + "alert" + ] }, "event_type": { "type": "string", - "description": "事件类型。" + "description": "事件类型代码。`i_*` 为故障事件（如 `i_new` 故障创建），`a_*` 为告警事件（如 `a_new` 告警触发）。" }, "channel_id": { "type": "integer", @@ -29219,7 +29569,7 @@ }, "event_time": { "type": "string", - "description": "事件时间的格式化时间串。" + "description": "事件时间，格式 `YYYY-MM-DD HH:MM:SS.ffffff`。" }, "ref_title": { "type": "string", @@ -29258,11 +29608,15 @@ }, "webhook_type": { "type": "string", - "description": "来源对象类型：`incident` 或 `alert`。" + "description": "来源对象类型：`incident`（故障）或 `alert`（告警）。", + "enum": [ + "incident", + "alert" + ] }, "event_type": { "type": "string", - "description": "事件类型（如 `created`、`acknowledged`、`closed`）。" + "description": "事件类型代码。`i_*` 为故障事件（如 `i_new` 故障创建），`a_*` 为告警事件（如 `a_new` 告警触发）。" }, "channel_id": { "type": "integer", @@ -29319,7 +29673,7 @@ }, "event_time": { "type": "string", - "description": "事件时间的格式化时间串。" + "description": "事件时间，格式 `YYYY-MM-DD HH:MM:SS.ffffff`。" } } }, @@ -29404,7 +29758,12 @@ }, "status": { "type": "string", - "description": "字段状态，如 `enabled`、`deleted`。" + "enum": [ + "enabled", + "disabled", + "deleted" + ], + "description": "字段状态：`enabled`（生效）、`disabled`（仅内部逻辑可设置，API 无法设置）或 `deleted`（已软删除）。`/field/list` 不返回 `deleted`，`/field/info` 可能返回。" }, "creator_id": { "type": "integer", @@ -29443,7 +29802,10 @@ "creator_id", "updated_by", "created_at", - "updated_at" + "updated_at", + "description", + "options", + "default_value" ] }, "FieldInfoRequest": { @@ -29468,7 +29830,7 @@ "created_at", "updated_at" ], - "description": "排序键，未传时使用后端默认顺序。" + "description": "排序键，省略时默认为 `created_at`。" }, "asc": { "type": "boolean", @@ -29484,7 +29846,7 @@ }, "query": { "type": "string", - "description": "对 `field_name` 与 `display_name` 进行正则过滤；非法正则会回退为字面量子串匹配。" + "description": "正则过滤，仅匹配 `field_name`。非法正则会自动转义为字面量子串匹配。" } } }, @@ -29536,7 +29898,7 @@ "single_select", "text" ], - "description": "字段类型，创建后不可更改：`text` 文本、`single_select` 单选、`multi_select` 多选、`checkbox` 复选。" + "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": { "type": "string", @@ -29601,7 +29963,7 @@ "items": { "type": "string" }, - "description": "替换后的候选项，规则同创建接口。" + "description": "替换后的选项列表，规则与创建时相同。注意：更新接口总是用提交的值覆盖 `display_name`、`description`、`options` 和 `default_value`，因此 `single_select`/`multi_select` 字段每次更新都必须传非空 `options`。" }, "default_value": { "description": "替换后的默认值，类型须与字段当前 `field_type` 匹配。", @@ -29730,7 +30092,7 @@ "deleted_at": { "type": "integer", "format": "int64", - "description": "变更事件删除时的 Unix 时间戳（秒）。" + "description": "变更事件的删除时间，Unix 时间戳（秒）。未删除时不返回该字段。" } } }, @@ -29757,7 +30119,11 @@ }, "channel_status": { "type": "string", - "description": "协作通道状态。" + "description": "协作空间状态：`enabled`（启用）或 `disabled`（禁用）。", + "enum": [ + "enabled", + "disabled" + ] }, "integration_id": { "type": "integer", @@ -29782,7 +30148,14 @@ }, "change_status": { "type": "string", - "description": "变更当前的生命周期状态。" + "description": "变更的当前生命周期状态。\n| 取值 | 含义 |\n|---|---|\n| `Planned` | 已计划，未开始。 |\n| `Ready` | 就绪，待执行。 |\n| `Processing` | 执行中。 |\n| `Canceled` | 已取消。 |\n| `Done` | 已完成。 |", + "enum": [ + "Planned", + "Ready", + "Processing", + "Canceled", + "Done" + ] }, "start_time": { "type": "integer", @@ -29825,12 +30198,14 @@ "start_time": { "type": "integer", "format": "int64", - "description": "查询窗口起始的 Unix 时间戳（秒）。" + "description": "查询窗口起点，Unix 时间戳（秒）。可选——`start_time` 和 `end_time` 都不传或为 0 时，默认查询最近一小时。必须小于 `end_time`，跨度不超过 31 天。当变更的 [start_time, last_time] 区间与查询窗口重叠时命中。", + "minimum": 0 }, "end_time": { "type": "integer", "format": "int64", - "description": "查询窗口结束的 Unix 时间戳（秒）。" + "description": "查询窗口终点，Unix 时间戳（秒）。默认值与约束见 `start_time`。", + "minimum": 0 }, "p": { "type": "integer", @@ -29862,11 +30237,12 @@ "description": "", "format": "int64" }, - "description": "按上报集成 ID 过滤。" + "description": "按上报集成 ID 过滤。提供时至少 1 个。", + "minItems": 1 }, "orderby": { "type": "string", - "description": "结果排序字段。", + "description": "排序字段：`start_time` 或 `last_time`，默认 `start_time`。", "enum": [ "start_time", "last_time" @@ -29874,7 +30250,7 @@ }, "asc": { "type": "boolean", - "description": "为 true 时升序排序。" + "description": "为 true 时升序排序，默认降序。" }, "include_events": { "type": "boolean", @@ -29882,7 +30258,39 @@ }, "query": { "type": "string", - "description": "对变更字段进行全文或正则搜索。" + "description": "对变更标题、change_key、描述做大小写不敏感的子串或正则匹配。非法正则按字面量匹配。" + }, + "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": 1, + "deprecated": true, + "description": "已废弃：请使用 `integration_ids`。按单个集成 ID 过滤。" + }, + "integration_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "deprecated": true, + "description": "已废弃：请使用 `integration_ids`。按单个集成 ID 过滤。" } } }, @@ -29952,7 +30360,11 @@ "type": "string", "description": "人员当前状态。" } - } + }, + "required": [ + "account_id", + "person_id" + ] }, "GetWarRoomDefaultObserversRequest": { "type": "object", @@ -29994,7 +30406,6 @@ "type": "array", "items": { "type": "integer", - "description": "", "format": "int64" }, "description": "要加入作战室的人员 ID 列表。" @@ -30015,11 +30426,12 @@ }, "type": { "type": "string", - "description": "决定渲染引擎的模板通道类型。" + "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`。" }, "incident_id": { "type": "string", - "description": "用于渲染模板的故障 ID，省略时使用模拟数据。MongoDB ObjectID 十六进制字符串。" + "description": "用于渲染模板的故障 ID，省略时使用模拟数据。MongoDB ObjectID 十六进制字符串。", + "pattern": "^[0-9a-fA-F]{24}$" }, "incident_card_hidden_fields": { "$ref": "#/components/schemas/IncidentCardHiddenFields", @@ -30029,7 +30441,8 @@ "required": [ "content", "type" - ] + ], + "description": "模板预览请求。" }, "PreviewTemplateResponse": { "type": "object", @@ -30053,7 +30466,13 @@ }, "description": "已应用隐藏规则后，为受支持 IM 预览返回的固定故障卡片字段。" } - } + }, + "required": [ + "success", + "content", + "message" + ], + "description": "模板预览结果。" }, "WarRoomDataSourceItem": { "type": "object", @@ -30084,15 +30503,19 @@ }, "status": { "type": "string", - "description": "集成当前状态。" + "description": "集成状态：`enabled` 启用、`disabled` 禁用。已删除的集成不会返回。", + "enum": [ + "enabled", + "disabled" + ] }, "category": { "type": "string", - "description": "集成插件的类别。" + "description": "插件类别；本接口返回的 IM 集成固定为 `im`。" }, "plugin_type": { "type": "string", - "description": "集成插件的类型标识。" + "description": "IM 集成插件类型标识，如 `feishu_app`、`dingtalk_app`、`wecom_app`、`slack_app`、`teams_app`。" }, "plugin_type_name": { "type": "string", @@ -30142,11 +30565,11 @@ "last_time": { "type": "integer", "format": "int64", - "description": "集成最近活动的 Unix 时间戳（秒）。" + "description": "该数据源最近活动时间的 Unix 秒级时间戳。固定为 `0`，本接口不填充该字段。" }, "exclusive_data_source_id": { "type": "integer", - "description": "与该集成关联的专属集成 ID。", + "description": "历史遗留的独占集成关联 ID，已废弃。", "format": "int64" }, "integration_id": { @@ -30154,26 +30577,54 @@ "description": "集成 ID，data_source_id 的别名。", "format": "int64" } - } - }, - "ListWarRoomEnabledResponse": { - "type": "object", - "properties": { - "items": { - "type": "array", + }, + "required": [ + "data_source_id", + "account_id", + "team_id", + "plugin_id", + "name", + "status", + "category", + "plugin_type", + "plugin_type_name", + "description", + "integration_key", + "ref_id", + "settings", + "no_editable", + "creator_id", + "updated_by", + "created_at", + "updated_at", + "last_time", + "exclusive_data_source_id", + "integration_id" + ], + "description": "IM 集成（数据源）条目。" + }, + "ListWarRoomEnabledResponse": { + "type": "object", + "properties": { + "items": { + "type": "array", "items": { "$ref": "#/components/schemas/WarRoomDataSourceItem" }, "description": "已开启作战室功能的 IM 集成。" } - } + }, + "required": [ + "items" + ], + "description": "已开启作战室功能的 IM 集成列表响应。" }, "StatusPageSectionItem": { "type": "object", "properties": { "section_id": { "type": "string", - "description": "分组 ID。" + "description": "分组 ID。为空时不返回。" }, "name": { "type": "string", @@ -30185,7 +30636,7 @@ }, "order_id": { "type": "integer", - "description": "分组的展示顺序。", + "description": "分组的展示顺序。为 0 时不返回。", "format": "int64" }, "hide_uptime": { @@ -30196,7 +30647,13 @@ "type": "boolean", "description": "是否在汇总接口中隐藏该分组及其组件。" } - } + }, + "required": [ + "name", + "description", + "hide_uptime", + "hide_all" + ] }, "StatusPageSubscriptionItem": { "type": "object", @@ -30209,7 +30666,11 @@ "type": "boolean", "description": "是否开启 IM 订阅。" } - } + }, + "required": [ + "email", + "im" + ] }, "StatusPageItem": { "type": "object", @@ -30237,35 +30698,35 @@ }, "custom_domain": { "type": "string", - "description": "指向状态页的自定义域名。" + "description": "指向状态页的自定义域名。未设置时不返回。" }, "logo": { "type": "string", - "description": "状态页 Logo 图片。" + "description": "状态页 Logo 图片。未设置时不返回。" }, "dark_logo": { "type": "string", - "description": "状态页暗色模式 Logo 图片。" + "description": "状态页暗色模式 Logo 图片。未设置时不返回。" }, "logo_url": { "type": "string", - "description": "点击 Logo 时跳转的 URL。" + "description": "点击 Logo 时跳转的 URL。未设置时不返回。" }, "favicon": { "type": "string", - "description": "状态页的网站图标。" + "description": "状态页的网站图标。未设置时不返回。" }, "page_header": { "type": "string", - "description": "状态页头部内容。" + "description": "状态页头部内容。未设置时不返回。" }, "page_footer": { "type": "string", - "description": "状态页底部内容。" + "description": "状态页底部内容。未设置时不返回。" }, "date_view": { "type": "string", - "description": "时间线的展示方式。`calendar` 以日历视图展示事件日期；`list` 以列表视图展示。", + "description": "时间线的展示方式。`calendar` 以日历视图展示事件日期；`list` 以列表视图展示。未设置时不返回。", "enum": [ "calendar", "list" @@ -30273,7 +30734,7 @@ }, "display_uptime_mode": { "type": "string", - "description": "可用率的展示方式。`chart_and_percentage` 同时展示可用率图表与百分比数值；`chart` 仅展示图表；`none` 不展示可用率。", + "description": "可用率的展示方式。`chart_and_percentage` 同时展示可用率图表与百分比数值；`chart` 仅展示图表；`none` 不展示可用率。未设置时不返回。", "enum": [ "chart_and_percentage", "chart", @@ -30288,11 +30749,11 @@ "type": "string" } }, - "description": "状态页上展示的自定义导航链接。" + "description": "状态页上展示的自定义导航链接。未设置时不返回。" }, "contact_info": { "type": "string", - "description": "联系方式，mailto 或网站 URL。" + "description": "联系方式，mailto 或网站 URL。未设置时不返回。" }, "components": { "type": "array", @@ -30309,13 +30770,23 @@ "description": "对组件进行分组的分组列表。" }, "subscription": { - "$ref": "#/components/schemas/StatusPageSubscriptionItem" + "$ref": "#/components/schemas/StatusPageSubscriptionItem", + "description": "订阅渠道开关。" }, "template_preference": { "type": "string", - "description": "偏好的变更事件模板类型。" + "description": "偏好的事件模板类型：`pre_defined` 或 `message`。从未设置时不返回。" } - } + }, + "required": [ + "page_id", + "name", + "url_name", + "type", + "components", + "sections", + "subscription" + ] }, "ListStatusPageResponse": { "type": "object", @@ -30327,7 +30798,10 @@ }, "description": "账户拥有的状态页。" } - } + }, + "required": [ + "items" + ] }, "DeletePostMortemTemplateRequest": { "type": "object", @@ -30503,7 +30977,13 @@ }, "incidents_highest_severity": { "type": "string", - "description": "关联故障中的最高严重级别。" + "description": "关联故障中的最高严重级别：`Critical`、`Warning`、`Info` 或 `Ok`。", + "enum": [ + "Critical", + "Warning", + "Info", + "Ok" + ] }, "incidents_earliest_start_seconds": { "type": "integer", @@ -30641,7 +31121,7 @@ }, "TryLinkPersonResponse": { "type": "object", - "description": "本次尝试关联成功的人员。", + "description": "本次调用新关联的人员。如果没有成员可关联，响应中的 `new_linked_person_ids` 可能为空数组，或整个 `data` 字段被省略。", "required": [ "new_linked_person_ids" ], @@ -30702,14 +31182,15 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "component_ids": { "type": "array", "items": { "type": "string" }, - "description": "要删除的组件 ID 列表，可通过 `POST /status-page/info` 获取。" + "description": "要删除的组件 ID 列表，可通过 `GET /status-page/info` 获取。", + "minItems": 1 } } }, @@ -30724,14 +31205,15 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "section_ids": { "type": "array", "items": { "type": "string" }, - "description": "要删除的区域 ID 列表，可通过 `POST /status-page/info` 获取。" + "description": "要删除的区域 ID 列表，可通过 `GET /status-page/info` 获取。", + "minItems": 1 } } }, @@ -30747,7 +31229,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "type": { "type": "string", @@ -30759,7 +31241,7 @@ }, "template_id": { "type": "string", - "description": "要删除的模板 ID，可通过 `POST /status-page/template/list` 获取。" + "description": "要删除的模板 ID，可通过 `GET /status-page/template/list` 获取。" } } }, @@ -30774,7 +31256,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "components": { "type": "array", @@ -30813,9 +31295,15 @@ "hide_all": { "type": "boolean", "description": "为 true 时，在汇总接口中完全隐藏该组件。" + }, + "available_since_seconds": { + "type": "integer", + "format": "int64", + "description": "组件可用起始时间（Unix 秒）。创建时缺省取当前时间；更新时覆盖原值。" } } - } + }, + "minItems": 1 } } }, @@ -30846,7 +31334,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "sections": { "type": "array", @@ -30883,7 +31371,8 @@ "description": "为 true 时，在汇总接口中完全隐藏该区域。" } } - } + }, + "minItems": 1 } } }, @@ -30915,7 +31404,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "type": { "type": "string", @@ -30926,48 +31415,15 @@ "description": "模板分类。`pre_defined` 为预定义事件模板；`message` 为通知消息模板。" }, "template": { - "type": "object", - "description": "模板内容。", - "required": [ - "title", - "event_type", - "status" - ], - "properties": { - "template_id": { - "type": "string", - "description": "模板 ID。省略则创建；提供则更新。" - }, - "title": { - "type": "string", - "description": "模板标题。" - }, - "event_type": { - "type": "string", - "enum": [ - "incident", - "maintenance" - ], - "description": "本模板适用的事件类型：`incident` 故障，`maintenance` 计划维护。" - }, - "status": { - "type": "string", - "enum": [ - "investigating", - "identified", - "monitoring", - "resolved", - "scheduled", - "ongoing", - "completed" - ], - "description": "本模板对应的事件状态。故障用 `investigating`/`identified`/`monitoring`/`resolved`，维护用 `scheduled`/`ongoing`/`completed`。" + "oneOf": [ + { + "$ref": "#/components/schemas/StatusPagePreDefinedTemplate" }, - "description": { - "type": "string", - "description": "模板正文（Markdown）。" + { + "$ref": "#/components/schemas/StatusPageMessageTemplate" } - } + ], + "description": "模板内容。结构取决于 `type`：`pre_defined` 为预定义事件模板，`message` 为消息模板。" } } }, @@ -31091,7 +31547,7 @@ }, "UpdateStatusPageRequest": { "type": "object", - "description": "更新已有状态页所需的参数。除 `page_id` 外均为可选字段；省略某字段表示保持其原值。", + "description": "更新已有状态页所需的参数。除 `page_id` 外均为可选字段；省略某字段或传 null 表示保持其原值。", "required": [ "page_id" ], @@ -31099,62 +31555,99 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "name": { - "type": "string", - "description": "状态页展示名称。留空表示保持原值。", + "type": [ + "string", + "null" + ], + "description": "状态页展示名称。省略或传 null 表示保持原值。", "maxLength": 255 }, "url_name": { - "type": "string", - "description": "URL 安全的状态页路径，在账户和状态页类型内唯一。留空表示保持原值。", + "type": [ + "string", + "null" + ], + "description": "URL 安全的状态页路径，在账户和状态页类型内唯一。省略或传 null 表示保持原值。", "maxLength": 255 }, "custom_domain": { - "type": "string", - "description": "公开状态页使用的自定义域名。留空表示保持原值。", + "type": [ + "string", + "null" + ], + "description": "公开状态页使用的自定义域名。省略或传 null 表示保持原值。", "maxLength": 255 }, "page_title": { - "type": "string", - "description": "状态页浏览器标题。留空表示保持原值。" + "type": [ + "string", + "null" + ], + "description": "状态页浏览器标题。省略或传 null 表示保持原值。" }, "logo": { - "type": "string", - "description": "状态页 Logo 图片。留空表示保持原值。" + "type": [ + "string", + "null" + ], + "description": "状态页 Logo 图片。省略或传 null 表示保持原值。" }, "dark_logo": { - "type": "string", - "description": "状态页暗色模式 Logo 图片。留空表示保持原值。" + "type": [ + "string", + "null" + ], + "description": "状态页暗色模式 Logo 图片。省略或传 null 表示保持原值。" }, "logo_url": { - "type": "string", - "description": "点击 Logo 时跳转的 URL。留空表示保持原值。" + "type": [ + "string", + "null" + ], + "description": "点击 Logo 时跳转的 URL。省略或传 null 表示保持原值。", + "maxLength": 255 }, "favicon": { - "type": "string", - "description": "状态页的网站图标。留空表示保持原值。" + "type": [ + "string", + "null" + ], + "description": "状态页的网站图标。省略或传 null 表示保持原值。" }, "page_header": { - "type": "string", - "description": "状态页页头内容。留空表示保持原值。" + "type": [ + "string", + "null" + ], + "description": "状态页页头内容。省略或传 null 表示保持原值。" }, "page_footer": { - "type": "string", - "description": "状态页页脚内容。留空表示保持原值。" + "type": [ + "string", + "null" + ], + "description": "状态页页脚内容。省略或传 null 表示保持原值。" }, "date_view": { - "type": "string", - "description": "事件日期展示方式。留空表示保持原值。`calendar` 为日历视图；`list` 为列表视图。", + "type": [ + "string", + "null" + ], + "description": "事件日期展示方式。省略或传 null 表示保持原值。`calendar` 为日历视图；`list` 为列表视图。", "enum": [ "calendar", "list" ] }, "display_uptime_mode": { - "type": "string", - "description": "可用率展示方式。留空表示保持原值。`chart_and_percentage` 同时展示图表与百分比；`chart` 仅展示图表；`none` 不展示。", + "type": [ + "string", + "null" + ], + "description": "可用率展示方式。省略或传 null 表示保持原值。`chart_and_percentage` 同时展示图表与百分比；`chart` 仅展示图表；`none` 不展示。", "enum": [ "chart_and_percentage", "chart", @@ -31163,7 +31656,7 @@ }, "custom_links": { "type": "array", - "description": "状态页展示的自定义导航链接。留空表示保持原值。", + "description": "状态页展示的自定义导航链接。省略或传空数组表示保持当前链接。", "items": { "type": "object", "additionalProperties": { @@ -31172,16 +31665,22 @@ } }, "contact_info": { - "type": "string", - "description": "联系信息，例如 mailto 或网站 URL。留空表示保持原值。" + "type": [ + "string", + "null" + ], + "description": "联系信息，例如 mailto 或网站 URL。省略或传 null 表示保持原值。" }, "subscription": { "$ref": "#/components/schemas/StatusPageSubscriptionItem", - "description": "订阅渠道开关。" + "description": "订阅渠道开关。省略或传 null 表示保持原值。" }, "template_preference": { - "type": "string", - "description": "偏好的变更事件模板类型。留空表示保持原值。" + "type": [ + "string", + "null" + ], + "description": "偏好的事件模板类型：`pre_defined` 或 `message`。省略或传 null 表示保持原值。" } } }, @@ -31195,7 +31694,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" } } }, @@ -31296,7 +31795,7 @@ }, "name": { "type": "string", - "description": "引用该字段的自定义表单显示名称。" + "description": "引用该字段的自定义表单类型名称（如 `解决故障` 表示解决故障表单）。" }, "href": { "type": "string", @@ -31555,7 +32054,18 @@ "format": "int64", "description": "最后更新时间，Unix 秒级时间戳。" } - } + }, + "required": [ + "comment_type_id", + "account_id", + "name", + "color", + "position", + "creator_id", + "updated_by", + "created_at", + "updated_at" + ] }, "ListIncidentCommentTypesRequest": { "type": "object", @@ -31577,7 +32087,7 @@ }, "CreateIncidentCommentTypeRequest": { "type": "object", - "description": "创建评论类型的参数。", + "description": "创建评论类型的参数。每个账户最多 10 个评论类型。", "required": [ "name", "color" @@ -31607,7 +32117,11 @@ "item": { "$ref": "#/components/schemas/IncidentCommentTypeItem" } - } + }, + "required": [ + "comment_type_id", + "item" + ] }, "UpdateIncidentCommentTypeRequest": { "type": "object", @@ -31897,7 +32411,7 @@ "limit": { "type": "integer", "format": "int64", - "minimum": 1, + "minimum": 0, "maximum": 200, "default": 50, "description": "每页条数，最多 200，默认 50。" @@ -32451,6 +32965,264 @@ } }, "title": "i_wi_deleted" + }, + "FeedDetailAlertMerge": { + "type": "object", + "title": "a_merge", + "description": "`a_merge` 的详情数据：告警被合并到故障。", + "properties": { + "comment": { + "type": "string", + "description": "合并时记录的评论。为空时不返回。" + }, + "target_incident": { + "$ref": "#/components/schemas/IncidentShort", + "description": "告警合并到的目标故障。未记录时不返回。" + }, + "source_alerts": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AlertShort" + }, + "description": "被合并进目标故障的源告警。为空时不返回。" + }, + "owner_id": { + "type": "integer", + "format": "int64", + "description": "目标故障被设置的新负责人成员 ID。未变更时不返回。" + }, + "title": { + "type": "string", + "description": "目标故障被设置的新标题。未变更时不返回。" + } + } + }, + "AlertShort": { + "type": "object", + "description": "告警简要引用。", + "properties": { + "alert_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "告警 ID（ObjectID 十六进制字符串）。" + }, + "title": { + "type": "string", + "description": "告警标题，读取时解析填充。为空时不返回。" + } + } + }, + "EventGroup": { + "type": "object", + "description": "告警事件合并配置。启用后，同一告警的重复事件会在时间窗口内并入已有告警，而不是新建告警。", + "properties": { + "is_enabled": { + "type": "boolean", + "description": "为 true 时，重复事件并入已有告警；为 false 时，每个事件都单独生成告警。默认为 true。" + }, + "time_window": { + "type": "integer", + "minimum": 1, + "description": "合并窗口，单位分钟，范围 1-1440（24 小时）；开通扩展额度的账号最大可设 10080（7 天）。默认 1440。" + } + } + }, + "StatusPageInfoResponse": { + "type": "object", + "description": "`GET /status-page/info` 返回的状态页详情：完整页面配置及特性开关。", + "allOf": [ + { + "$ref": "#/components/schemas/StatusPageItem" + }, + { + "type": "object", + "properties": { + "managed_domain_feature_enabled": { + "type": "boolean", + "description": "该页面是否启用托管自定义域名特性。公开页面为 `true`，内部页面恒为 `false`。" + } + }, + "required": [ + "managed_domain_feature_enabled" + ] + } + ] + }, + "StatusPagePreDefinedTemplate": { + "type": "object", + "description": "预定义事件模板：可复用的事件草稿（标题、类型、状态、描述）。在 `POST /status-page/template/upsert` 中，省略 `template_id` 表示创建，提供则表示更新；更新时仅应用非空字段。", + "properties": { + "template_id": { + "type": "string", + "description": "模板 ID。省略表示创建新模板；提供表示更新已有模板。" + }, + "title": { + "type": "string", + "description": "模板标题。" + }, + "type": { + "type": "string", + "enum": [ + "incident", + "maintenance" + ], + "description": "模板适用的事件类型：`incident` 故障，`maintenance` 计划维护。" + }, + "status": { + "type": "string", + "enum": [ + "investigating", + "identified", + "monitoring", + "resolved", + "scheduled", + "ongoing", + "completed" + ], + "description": "模板对应的事件状态。故障事件支持 `investigating`/`identified`/`monitoring`/`resolved`；维护事件支持 `scheduled`/`ongoing`/`completed`。" + }, + "description": { + "type": "string", + "description": "模板正文（Markdown）。" + } + } + }, + "StatusPageMessageTemplate": { + "type": "object", + "description": "消息模板：某一事件类型下、按状态划分的通知文案。在 `POST /status-page/template/upsert` 中，省略 `template_id` 表示创建，提供则表示更新；更新时仅应用非空字段。", + "properties": { + "template_id": { + "type": "string", + "description": "模板 ID。省略表示创建新模板；提供表示更新已有模板。" + }, + "title": { + "type": "string", + "description": "模板标题。" + }, + "type": { + "type": "string", + "enum": [ + "incident", + "maintenance" + ], + "description": "模板适用的事件类型：`incident` 故障，`maintenance` 计划维护。" + }, + "messages": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "按事件状态划分的通知文案（Markdown）。键为与模板 `type` 匹配的事件状态（如故障事件的 `investigating`、`resolved`），值为事件进入该状态时使用的文本。" + } + } + }, + "ListStatusPageTemplatesResponse": { + "type": "object", + "description": "事件模板列表。条目结构取决于请求的 `type`：`pre_defined` 为预定义事件模板，`message` 为消息模板。", + "required": [ + "items" + ], + "properties": { + "items": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/StatusPagePreDefinedTemplate" + }, + { + "$ref": "#/components/schemas/StatusPageMessageTemplate" + } + ] + }, + "description": "所请求类别的模板列表。" + } + } + }, + "FeedDetailAlertUpdate": { + "type": "object", + "title": "a_update", + "description": "`a_update` 的详情数据：更新后的严重程度/状态。", + "properties": { + "severity": { + "$ref": "#/components/schemas/FeedSeverity" + }, + "status": { + "$ref": "#/components/schemas/FeedSeverity" + } + } + }, + "FeedDetailAlertMuteBySilence": { + "type": "object", + "title": "a_m_silence", + "description": "`a_m_silence` 的详情数据：告警被静默规则收敛。", + "properties": { + "rule_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "收敛该告警的静默规则 ID。为空时不返回。" + }, + "rule_name": { + "type": "string", + "description": "静默规则名称，读取时解析填充。为空时不返回。" + } + } + }, + "FeedDetailAlertMuteByInhibit": { + "type": "object", + "title": "a_m_inhibit", + "description": "`a_m_inhibit` 的详情数据：告警因源告警被抑制规则收敛。", + "properties": { + "rule_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "收敛该告警的抑制规则 ID。为空时不返回。" + }, + "rule_name": { + "type": "string", + "description": "抑制规则名称，读取时解析填充。为空时不返回。" + }, + "source_alert_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "触发抑制的源告警 ID。为空时不返回。" + }, + "source_alert_title": { + "type": "string", + "description": "源告警标题，读取时解析填充。为空时不返回。" + } + } + }, + "FeedDetailAlertMuteByFlapping": { + "type": "object", + "title": "a_m_flapping", + "description": "`a_m_flapping` 的详情数据（历史）：告警被抖动检测收敛。", + "properties": { + "max_changes": { + "type": "integer", + "description": "触发抖动检测的状态变化次数阈值。为 0 时不返回。" + }, + "in_secs": { + "type": "integer", + "description": "统计状态变化的时间窗口（秒）。为 0 时不返回。" + }, + "mute_secs": { + "type": "integer", + "description": "静默时长（秒）。为 0 时不返回。" + } + } + }, + "FeedDetailAlertAck": { + "type": "object", + "title": "a_ack", + "description": "`a_ack` 的详情数据（历史），无字段。", + "properties": {} + }, + "FeedDetailAlertUnack": { + "type": "object", + "title": "a_unack", + "description": "`a_unack` 的详情数据（历史），无字段。", + "properties": {} } } } diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json index 9e4a04d1..139030e2 100644 --- a/api-reference/openapi.en.json +++ b/api-reference/openapi.en.json @@ -219,6 +219,7 @@ "incident_id": "69da451ef77b1b51f40e83ee", "account_id": 2451002751131, "channel_id": 2551105804131, + "team_id": 2477033058131, "integration_id": 2490562293131, "integration_ids": [ 2490562293131 @@ -469,6 +470,7 @@ "incident_id": "69da451ef77b1b51f40e83ee", "account_id": 2451002751131, "channel_id": 2551105804131, + "team_id": 2477033058131, "integration_id": 2490562293131, "integration_ids": [ 2490562293131 @@ -620,6 +622,7 @@ "incident_id": "69da451ef77b1b51f40e83ee", "account_id": 2451002751131, "channel_id": 2551105804131, + "team_id": 2477033058131, "integration_id": 2490562293131, "integration_ids": [ 2490562293131 @@ -3217,7 +3220,7 @@ "post": { "operationId": "channelDelete", "summary": "Delete channel", - "description": "Delete a channel and all associated configuration.", + "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.", "tags": [ "On-call/Channels" ], @@ -3287,7 +3290,7 @@ "post": { "operationId": "channelEnable", "summary": "Enable channel", - "description": "Enable a disabled channel to resume incident routing.", + "description": "Enable a channel to resume incident routing. Only a `disabled` channel can be enabled.", "tags": [ "On-call/Channels" ], @@ -3357,7 +3360,7 @@ "post": { "operationId": "channelDisable", "summary": "Disable channel", - "description": "Disable a channel to stop incident routing without deleting it.", + "description": "Disable a channel to stop incident routing without deleting it; a disabled channel discards incoming events. Only an `enabled` channel can be disabled.", "tags": [ "On-call/Channels" ], @@ -3708,7 +3711,7 @@ "post": { "operationId": "channelSilenceRuleDelete", "summary": "Delete silence rule", - "description": "Delete a silence rule.", + "description": "Delete a silence rule. Only a `disabled` rule can be deleted.", "tags": [ "On-call/Channels" ], @@ -3779,7 +3782,7 @@ "post": { "operationId": "channelSilenceRuleEnable", "summary": "Enable silence rule", - "description": "Enable a disabled silence rule.", + "description": "Enable a disabled silence rule. Only a `disabled` rule can be enabled.", "tags": [ "On-call/Channels" ], @@ -3850,7 +3853,7 @@ "post": { "operationId": "channelSilenceRuleDisable", "summary": "Disable silence rule", - "description": "Disable a silence rule without deleting it.", + "description": "Disable a silence rule without deleting it. Only an `enabled` rule can be disabled.", "tags": [ "On-call/Channels" ], @@ -4209,7 +4212,7 @@ "post": { "operationId": "channelInhibitRuleDelete", "summary": "Delete inhibit rule", - "description": "Delete an inhibit rule.", + "description": "Delete an inhibit rule. Only a `disabled` rule can be deleted.", "tags": [ "On-call/Channels" ], @@ -4280,7 +4283,7 @@ "post": { "operationId": "channelInhibitRuleEnable", "summary": "Enable inhibit rule", - "description": "Enable a disabled inhibit rule.", + "description": "Enable a disabled inhibit rule. Only a `disabled` rule can be enabled.", "tags": [ "On-call/Channels" ], @@ -4351,7 +4354,7 @@ "post": { "operationId": "channelInhibitRuleDisable", "summary": "Disable inhibit rule", - "description": "Disable an inhibit rule without deleting it.", + "description": "Disable an inhibit rule without deleting it. Only an `enabled` rule can be disabled.", "tags": [ "On-call/Channels" ], @@ -4687,7 +4690,7 @@ "post": { "operationId": "channelUnsubscribeRuleDelete", "summary": "Delete drop rule", - "description": "Delete a drop rule.", + "description": "Delete a drop rule. Only a `disabled` rule can be deleted.", "tags": [ "On-call/Channels" ], @@ -4758,7 +4761,7 @@ "post": { "operationId": "channelUnsubscribeRuleEnable", "summary": "Enable drop rule", - "description": "Enable a disabled drop rule.", + "description": "Enable a disabled drop rule. Only a `disabled` rule can be enabled.", "tags": [ "On-call/Channels" ], @@ -4829,7 +4832,7 @@ "post": { "operationId": "channelUnsubscribeRuleDisable", "summary": "Disable drop rule", - "description": "Disable a drop rule without deleting it.", + "description": "Disable a drop rule without deleting it. Only an `enabled` rule can be disabled.", "tags": [ "On-call/Channels" ], @@ -5291,7 +5294,7 @@ "post": { "operationId": "channelEscalateRuleDelete", "summary": "Delete escalation rule", - "description": "Delete an escalation rule.", + "description": "Delete an escalation rule. Only a `disabled` rule can be deleted.", "tags": [ "On-call/Channels" ], @@ -5362,7 +5365,7 @@ "post": { "operationId": "channelEscalateRuleEnable", "summary": "Enable escalation rule", - "description": "Enable a disabled escalation rule.", + "description": "Enable a disabled escalation rule. Only a `disabled` rule can be enabled.", "tags": [ "On-call/Channels" ], @@ -5433,7 +5436,7 @@ "post": { "operationId": "channelEscalateRuleDisable", "summary": "Disable escalation rule", - "description": "Disable an escalation rule without deleting it.", + "description": "Disable an escalation rule without deleting it. Only an `enabled` rule can be disabled.", "tags": [ "On-call/Channels" ], @@ -5857,7 +5860,6 @@ "data": { "total": 1, "has_next_page": false, - "search_after_ctx": "", "items": [ { "alert_id": "663a1b2c3d4e5f6789abcdef", @@ -5999,7 +6001,7 @@ "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.", + "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.", "tags": [ "On-call/Alerts" ], @@ -6033,7 +6035,7 @@ "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { - "total": 1, + "total": 0, "has_next_page": false, "items": [ { @@ -6173,7 +6175,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. `alert_comment`, `alert_merge`).", + "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" @@ -6206,7 +6208,7 @@ "items": [ { "ref_id": "663a1b2c3d4e5f6789abcdef", - "type": "alert_comment", + "type": "a_comm", "detail": { "comment": "Investigating now." }, @@ -6572,7 +6574,7 @@ }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": {} + "data": null } } } @@ -6765,7 +6767,7 @@ "duration": 132, "status": "success", "status_code": 200, - "event_time": "2026-04-12T13:31:11.357472+08:00" + "event_time": "2026-04-12 13:31:11.357472" } ], "search_after_ctx": "eyJldmVudF90aW1lIjoiMjAyNi0wNC0xMlQxMzoxNToyNi4zODI1NDcrMDg6MDAiLCJldmVudF9pZCI6IjIwMjYwNDEybUdzeFAzZHJwRmZzNFpDUWQycFNEcCJ9", @@ -6860,7 +6862,7 @@ "status_code": 200, "response_headers": "{\"Content-Type\":\"application/json\"}", "response_body": "{\"ok\":true}", - "event_time": "2026-04-12T13:31:11.357472+08:00", + "event_time": "2026-04-12 13:31:11.357472", "ref_title": "High CPU Usage on host-01", "channel_name": "Production Alerts" } @@ -9553,7 +9555,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 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` (regex with named group `result`) or `g_json` (GJson path).\n- For `kind: composition`: `template` uses Go text/template syntax referencing `labels.*` keys.\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 | **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" @@ -9622,7 +9624,7 @@ "kind": "composition", "settings": { "result_label": "full_env", - "template": "{{.labels.region}}-{{.labels.environment}}", + "template": "{{.Labels.region}}-{{.Labels.environment}}", "override": false } } @@ -9819,7 +9821,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- 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-z][a-z0-9_]{0,39}$` (lowercase).\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 | **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" @@ -10415,16 +10417,48 @@ "requestBody": { "required": true, "content": { - "application/json": { + "multipart/form-data": { "schema": { - "$ref": "#/components/schemas/MappingDataUploadRequest" - }, - "example": { - "schema_id": "665f1a2b3c4d5e6f7a8b9c01" + "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" + ] } } } - } + }, + "parameters": [ + { + "name": "schema_id", + "in": "query", + "required": true, + "schema": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$" + }, + "description": "ID of the target mapping schema (ObjectID hex).", + "example": "665f1a2b3c4d5e6f7a8b9c01" + }, + { + "name": "do_not_truncate_first", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "TRUE" + ] + }, + "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/download": { @@ -10444,28 +10478,15 @@ }, "responses": { "200": { - "description": "Success", + "description": "Success. CSV attachment stream, not a JSON envelope.", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/CsvFileResponse" - } - } - } - ] + "type": "string", + "format": "binary", + "description": "CSV file stream (`Content-Type: application/octet-stream`, `Content-Disposition: attachment; filename=.csv`). The header row lists the schema's source_labels followed by result_labels in order; each subsequent row is one mapping document." }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": "host,owner,team,service\nserver01,alice,sre,api\n" - } + "example": "host,owner,team\nserver01,alice,sre\nserver02,bob,backend\n" } } }, @@ -10543,7 +10564,7 @@ "description": "Query CMDB for host metadata", "url": "https://cmdb.example.com/api/lookup", "headers": { - "X-Token": "***" + "Authorization": "Bearer eyJhbGciOiJIUzI1NiJ9.example-token" }, "timeout": 2, "retry_count": 1, @@ -11220,7 +11241,7 @@ "post": { "operationId": "insightIncidentExport", "summary": "Export insight incidents", - "description": "Export the filtered incident analytics list as a CSV file. CSV headers and formatted values use the request locale, falling back to the member locale and then the account locale. The response is a CSV stream delivered with `Content-Disposition: attachment` — it is not a JSON envelope.", + "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.", "tags": [ "On-call/Analytics" ], @@ -11235,26 +11256,13 @@ "200": { "description": "Success", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/EmptyResponse" - } - } - } - ] + "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`." }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": {} - } + "example": "incident_id,title,severity,created_at\n6a86b5d6f72de50ae1ce2ffb,CPU usage above 90%,Critical,2026-01-01 10:00:00 +0800 CST\n" } } }, @@ -11407,7 +11415,7 @@ "post": { "operationId": "insightChannelExport", "summary": "Export channel insight", - "description": "Export channel insight metrics as a CSV file. CSV headers and formatted values use the request locale, falling back to the member locale and then the account locale. The response is a CSV stream delivered with `Content-Disposition: attachment` — it is not a JSON envelope.", + "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.", "tags": [ "On-call/Analytics" ], @@ -11422,26 +11430,13 @@ "200": { "description": "Success", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/EmptyResponse" - } - } - } - ] + "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`." }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": {} - } + "example": "channel_id,channel_name,total_incident_cnt,total_incidents_closed\n4321322010131,Production Alerts,12,10\n" } } }, @@ -11589,7 +11584,7 @@ "post": { "operationId": "insightTeamExport", "summary": "Export team insight", - "description": "Export team insight metrics as a CSV file. CSV headers and formatted values use the request locale, falling back to the member locale and then the account locale. The response is a CSV stream delivered with `Content-Disposition: attachment` — it is not a JSON envelope.", + "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.", "tags": [ "On-call/Analytics" ], @@ -11604,26 +11599,13 @@ "200": { "description": "Success", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/EmptyResponse" - } - } - } - ] + "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`." }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": {} - } + "example": "team_id,team_name,total_incident_cnt,total_incidents_closed\n4295771902131,SRE Team,12,10\n" } } }, @@ -11762,7 +11744,7 @@ "post": { "operationId": "insightResponderExport", "summary": "Export responder insight", - "description": "Export responder insight metrics as a CSV file. CSV headers and formatted values use the request locale, falling back to the member locale and then the account locale. The response is a CSV stream delivered with `Content-Disposition: attachment` — it is not a JSON envelope.", + "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.", "tags": [ "On-call/Analytics" ], @@ -11777,26 +11759,13 @@ "200": { "description": "Success", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/EmptyResponse" - } - } - } - ] + "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`." }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": {} - } + "example": "responder_id,responder_name,total_incident_cnt,total_incidents_acknowledged\n3790925372131,alice,5,4\n" } } }, @@ -11967,12 +11936,12 @@ "get": { "operationId": "statusPageChangeList", "summary": "List status page events", - "description": "List status page events with only publicly visible affected components.", + "description": "List status page events for console management. Unlike the public display endpoints, the response includes 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- Hidden affected components are omitted. Events remain in the result when none are visible, with an empty `affected_components` array.", + "content": "## Restrictions\n\n| Aspect | Value |\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", "metadata": { "sidebarTitle": "List status page events" @@ -12089,7 +12058,7 @@ "type": "integer", "format": "int64" }, - "description": "Filter events started at or after this unix timestamp (seconds)." + "description": "Lower bound of the event activity window: only events still open at, or closed at or after, this Unix timestamp (seconds) are returned." }, { "name": "end_at_seconds", @@ -12099,7 +12068,7 @@ "type": "integer", "format": "int64" }, - "description": "Filter events started at or before this unix timestamp (seconds)." + "description": "Upper bound of the event activity window: only events started at or before this Unix timestamp (seconds) are returned." }, { "name": "type", @@ -12130,7 +12099,7 @@ "completed" ] }, - "description": "Event status filter. Required. Must be a status valid for the given `type` (e.g. `investigating`/`identified`/`monitoring`/`resolved` for incidents; `scheduled`/`ongoing`/`completed` for maintenances)." + "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`)." } ] } @@ -12843,7 +12812,7 @@ "post": { "operationId": "statusPageSubscriberImport", "summary": "Import subscribers", - "description": "Bulk import subscribers for a status page.", + "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.", "tags": [ "On-call/Status pages" ], @@ -12942,28 +12911,13 @@ }, "responses": { "200": { - "description": "Success", + "description": "Success. CSV attachment, not a JSON envelope.", "content": { - "application/json": { + "text/csv": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/StatusPageSubscriberExportResponse" - } - } - } - ] + "$ref": "#/components/schemas/StatusPageSubscriberExportResponse" }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": "Method,Recipient,Components,Subscribe All,Locale\nemail,alice@example.com,,true,zh-CN\nemail,bob@example.com,,true,en-US" - } + "example": "Method,Recipient,Components,Subscribe All,Locale\nemail,alice@example.com,,Yes,zh-CN\nemail,bob@example.com,\"Core Services › API\",No,en-US" } } }, @@ -13345,7 +13299,9 @@ "ds_type": "prometheus", "enabled": true, "triggered": true, - "created_at": 1710000000 + "created_at": 1710000000, + "active_alert_count": 2, + "runtime_state": "normal" } ] } @@ -13426,7 +13382,7 @@ "prometheus*" ], "enabled": true, - "cron_pattern": "* * * * *", + "cron_pattern": "0 * * * * *", "channel_ids": [ 20001 ] @@ -13539,7 +13495,7 @@ "prometheus*" ], "enabled": true, - "cron_pattern": "* * * * *", + "cron_pattern": "0 * * * * *", "channel_ids": [ 20001 ], @@ -13641,7 +13597,7 @@ "prometheus*" ], "enabled": true, - "cron_pattern": "* * * * *", + "cron_pattern": "0 * * * * *", "rule_configs": { "queries": [ { @@ -13961,7 +13917,7 @@ "prometheus*" ], "enabled": true, - "cron_pattern": "* * * * *", + "cron_pattern": "0 * * * * *", "rule_configs": { "queries": [ { @@ -14022,7 +13978,7 @@ "prometheus*" ], "enabled": true, - "cron_pattern": "* * * * *" + "cron_pattern": "0 * * * * *" } ] } @@ -14138,19 +14094,19 @@ } } }, - "/monit/rule/status": { + "/monit/rule/audits": { "post": { - "operationId": "monit-rule-write-status", - "summary": "Get rule trigger status under folder", - "description": "Return the rule trigger summary for all rules under a folder node and its descendants.", + "operationId": "monit-rule-read-audits", + "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 | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- Set `folder_id` to `0` to get summary across all folders.\n- If the folder contains too many rules, computation is skipped for self-protection.", - "href": "/en/api-reference/monitors/alert-rules/monit-rule-write-status", + "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": "Get rule trigger status under folder" + "sidebarTitle": "List rule change history" } }, "responses": { @@ -14167,7 +14123,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/RuleStatusResponse" + "$ref": "#/components/schemas/RuleAuditListResponse" } } } @@ -14177,10 +14133,13 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": [ { - "folder_id": 100, - "folder_name": "Production", - "rule_total": 10, - "triggered_rule_count": 2 + "id": 9001, + "account_id": 10023, + "alert_rule_id": 50001, + "action": "update", + "creator_id": 80011, + "creator_name": "Alice", + "created_at": 1712000000 } ] } @@ -14205,29 +14164,29 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RuleFolderIDRequest" + "$ref": "#/components/schemas/RuleIDRequest" }, "example": { - "folder_id": 100 + "id": 50001 } } } } } }, - "/monit/rule/audits": { + "/monit/rule/audit/detail": { "post": { - "operationId": "monit-rule-read-audits", - "summary": "List rule change history", - "description": "Return the change history (audit records) for an alert rule.", + "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).", "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", + "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": "List rule change history" + "sidebarTitle": "Get rule audit snapshot" } }, "responses": { @@ -14244,7 +14203,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/RuleAuditListResponse" + "$ref": "#/components/schemas/AlertRuleAudit" } } } @@ -14252,17 +14211,16 @@ }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": [ - { - "id": 9001, - "account_id": 10023, - "alert_rule_id": 50001, - "action": "update", - "creator_id": 80011, - "creator_name": "Alice", - "created_at": 1712000000 - } - ] + "data": { + "id": 9001, + "account_id": 10023, + "alert_rule_id": 50001, + "action": "update", + "content": "{\"id\":50001,\"name\":\"CPU High\"}", + "creator_id": 80011, + "creator_name": "Alice", + "created_at": 1712000000 + } } } } @@ -14285,29 +14243,29 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RuleIDRequest" + "$ref": "#/components/schemas/AuditRecordIDRequest" }, "example": { - "id": 50001 + "id": 9001 } } } } } }, - "/monit/rule/audit/detail": { + "/monit/rule/dstypes": { "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).", + "operationId": "monit-rule-read-dstypes", + "summary": "List available datasource types", + "description": "Return the list of datasource types (`DSType` records) that the current account can use when authoring alert rules — combines global types and account-scoped types.", "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", + "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-dstypes", "metadata": { - "sidebarTitle": "Get rule audit snapshot" + "sidebarTitle": "List available datasource types" } }, "responses": { @@ -14324,7 +14282,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/AlertRuleAudit" + "$ref": "#/components/schemas/RuleDsTypesResponse" } } } @@ -14332,16 +14290,15 @@ }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": { - "id": 9001, - "account_id": 10023, - "alert_rule_id": 50001, - "action": "update", - "content": "{\"id\":50001,\"name\":\"CPU High\"}", - "creator_id": 80011, - "creator_name": "Alice", - "created_at": 1712000000 - } + "data": [ + { + "id": 1, + "name": "Prometheus", + "ident": "prometheus", + "account_id": 0, + "weight": 100 + } + ] } } } @@ -14364,29 +14321,27 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AuditRecordIDRequest" + "$ref": "#/components/schemas/RuleEmptyRequest" }, - "example": { - "id": 9001 - } + "example": {} } } } } }, - "/monit/rule/dstypes": { + "/monit/rule/counter/total": { "post": { - "operationId": "monit-rule-read-dstypes", - "summary": "List available datasource types", - "description": "Return the list of datasource types (`DSType` records) that the current account can use when authoring alert rules — combines global types and account-scoped types.", + "operationId": "monit-rule-read-counter-total", + "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 | **Alerting Rules Read** (`monit`) |", - "href": "/en/api-reference/monitors/alert-rules/monit-rule-read-dstypes", + "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": "List available datasource types" + "sidebarTitle": "Get rule counter time series" } }, "responses": { @@ -14403,7 +14358,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/RuleDsTypesResponse" + "$ref": "#/components/schemas/RuleCounterTotalResponse" } } } @@ -14414,85 +14369,9 @@ "data": [ { "id": 1, - "name": "Prometheus", - "ident": "prometheus", - "account_id": 0, - "weight": 100 - } - ] - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/Unauthorized" - }, - "429": { - "$ref": "#/components/responses/TooManyRequests" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RuleEmptyRequest" - }, - "example": {} - } - } - } - } - }, - "/monit/rule/counter/total": { - "post": { - "operationId": "monit-rule-read-counter-total", - "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 | **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" - } - }, - "responses": { - "200": { - "description": "Success", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/RuleCounterTotalResponse" - } - } - } - ] - }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": [ - { - "id": 1, - "account_id": 10023, - "num": 50, - "clock": 1712000000 + "account_id": 10023, + "num": 50, + "clock": 1712000000 } ] } @@ -14788,7 +14667,8 @@ "note": "Production Prometheus", "address": "http://prometheus.example.com:9090", "edge_cluster_name": "default", - "updated_at": 1712000000 + "updated_at": 1712000000, + "payload": null } ] } @@ -14832,7 +14712,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## Credential fields\n\nThe `info` / `create` / `update` responses include the `payload` configuration exactly as stored — `password`, `basic_auth_password`, `api_key`, `service_token`, `access_key_secret`, `tls_key`, `tls_key_pwd` and similar fields are returned as-is, not masked. Treat these responses as sensitive: avoid logging them or forwarding them to third parties.", + "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## Credential fields\n\nThe `info` / `create` / `update` responses include the `payload` configuration exactly as stored — `password`, `basic_auth_password`, `api_key`, `service_token`, `access_key_secret`, `tls_key`, `tls_key_pwd` and similar fields are returned as-is, not masked. The one exception is `payload.tencent_cls.secret_key`, which is always masked to an empty string (an `${env:...}` reference is returned verbatim). Treat these responses as sensitive: avoid logging them or forwarding them to third parties.", "href": "/en/api-reference/monitors/data-sources/monit-datasource-read-info", "metadata": { "sidebarTitle": "Get datasource detail" @@ -14920,7 +14800,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 Manage** (`monit`) |\n\n## Usage\n\n- `type_ident` must be one of: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `victorialogs`.\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. Don't put secrets in request fields.\n\n## Credential fields\n\nThe `info` / `create` / `update` responses include the `payload` configuration exactly as stored — `password`, `basic_auth_password`, `api_key`, `service_token`, `access_key_secret`, `tls_key`, `tls_key_pwd` and similar fields are returned as-is, not masked. Treat these responses as sensitive: avoid logging them or forwarding them to third parties.", + "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`.\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. Don't put secrets in request fields.\n\n## Credential fields\n\nThe `info` / `create` / `update` responses include the `payload` configuration exactly as stored — `password`, `basic_auth_password`, `api_key`, `service_token`, `access_key_secret`, `tls_key`, `tls_key_pwd` and similar fields are returned as-is, not masked. The one exception is `payload.tencent_cls.secret_key`, which is always masked to an empty string (an `${env:...}` reference is returned verbatim). Treat these responses as sensitive: avoid logging them or forwarding them to third parties.", "href": "/en/api-reference/monitors/data-sources/monit-datasource-write-create", "metadata": { "sidebarTitle": "Create datasource" @@ -15006,7 +14886,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 Manage** (`monit`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Don't put secrets in request fields.\n\n## Credential fields\n\nThe `info` / `create` / `update` responses include the `payload` configuration exactly as stored — `password`, `basic_auth_password`, `api_key`, `service_token`, `access_key_secret`, `tls_key`, `tls_key_pwd` and similar fields are returned as-is, not masked. Treat these responses as sensitive: avoid logging them or forwarding them to third parties.", + "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.\n\n## Credential fields\n\nThe `info` / `create` / `update` responses include the `payload` configuration exactly as stored — `password`, `basic_auth_password`, `api_key`, `service_token`, `access_key_secret`, `tls_key`, `tls_key_pwd` and similar fields are returned as-is, not masked. The one exception is `payload.tencent_cls.secret_key`, which is always masked to an empty string (an `${env:...}` reference is returned verbatim). Treat these responses as sensitive: avoid logging them or forwarding them to third parties.", "href": "/en/api-reference/monitors/data-sources/monit-datasource-write-update", "metadata": { "sidebarTitle": "Update datasource" @@ -15088,7 +14968,7 @@ "post": { "operationId": "monit-datasource-write-delete", "summary": "Delete datasource", - "description": "Delete a data source by ID. Alert rules referencing this datasource must be updated or deleted first.", + "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.", "tags": [ "Monitors/Data sources" ], @@ -15191,10 +15071,30 @@ }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": [ - "project-a", - "project-b" - ] + "data": { + "projects": [ + { + "projectName": "project-a", + "description": "Production logs", + "status": "Normal", + "owner": "", + "region": "cn-shanghai", + "createTime": "1710000000", + "lastModifyTime": "1712000000" + }, + { + "projectName": "project-b", + "description": "Staging logs", + "status": "Normal", + "owner": "", + "region": "cn-shanghai", + "createTime": "1710000000", + "lastModifyTime": "1712000000" + } + ], + "count": 2, + "total": 2 + } } } } @@ -17373,12 +17273,12 @@ "post": { "operationId": "memberInfo", "summary": "Get current member info", - "description": "Return the current session member's full profile.", + "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.", "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 |", + "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" @@ -17688,6 +17588,10 @@ { "member_id": 5068740052131, "member_name": "Charlie" + }, + { + "member_id": 5068740052132, + "member_name": "Dave" } ] } @@ -17744,7 +17648,7 @@ "post": { "operationId": "memberGrantRole", "summary": "Grant role to member", - "description": "Add a role assignment to a 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.", "tags": [ "Platform/Members" ], @@ -17817,7 +17721,7 @@ "post": { "operationId": "memberRevokeRole", "summary": "Revoke role from member", - "description": "Remove a role assignment from a 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.", "tags": [ "Platform/Members" ], @@ -17890,7 +17794,7 @@ "post": { "operationId": "memberUpdateRole", "summary": "Update member roles", - "description": "Replace all role assignments for a member at once.", + "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).", "tags": [ "Platform/Members" ], @@ -18230,7 +18134,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- Up to 100 team 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 deduplicated; IDs that match no team are ignored.", "href": "/en/api-reference/platform/teams/team-read-infos", "metadata": { "sidebarTitle": "Batch get teams" @@ -18417,7 +18321,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 invite members who don't yet have accounts.\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 | **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" @@ -18820,7 +18724,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- Only custom roles can be enabled/disabled. Built-in roles always remain enabled.\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 | **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" @@ -18893,7 +18797,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 held this role lose its permissions immediately.\n- Only custom roles can be disabled.\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 | **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" @@ -18961,12 +18865,12 @@ "post": { "operationId": "role-write-delete", "summary": "Delete a role", - "description": "Permanently delete a custom role and revoke it from all members.", + "description": "Delete a custom role. While members still hold the role, the call fails with `ReferenceExist` unless `is_force` is true.", "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 cannot be deleted.\n- All members who held this role lose its permissions immediately.\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 | **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" @@ -19020,7 +18924,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RoleIDRequest" + "$ref": "#/components/schemas/RoleDeleteRequest" }, "example": { "role_id": 150 @@ -19077,7 +18981,8 @@ "class": "On-call", "scope": "on-call", "status": "enabled", - "is_granted": true + "is_granted": true, + "source": "system" } ] } @@ -19120,12 +19025,12 @@ "post": { "operationId": "role-read-list-permission-factor", "summary": "List permission factors", - "description": "Return all permission factors (API, button, menu, URL, visit) optionally filtered by type.", + "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.", "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- 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 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" @@ -19156,7 +19061,8 @@ "data": [ { "factor_name": "template:read:info", - "factor_type": "api" + "factor_type": "api", + "source": "system" } ] } @@ -19202,7 +19108,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- Up to 100 member IDs per request.\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 | **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" @@ -19355,7 +19261,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- Default page size is 20 rows; maximum is 99.", + "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" @@ -19399,7 +19305,10 @@ "body": "{\"template_name\":\"Prod default\"}", "params": [], "is_dangerous": false, - "is_write": true + "is_write": true, + "principal_kind": "member", + "credential_type": "", + "credential_id": 0 } ] } @@ -19533,7 +19442,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- Only fields whose status is not `deleted` are returned; a deleted or unknown `field_id` yields a 400 error.\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 | **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" @@ -19623,7 +19532,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` and `display_name`; 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 | **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" @@ -20100,92 +20009,6 @@ } } }, - "/monit/query/rows": { - "post": { - "operationId": "monit-read-query-rows", - "summary": "Query data source rows", - "description": "Deprecated. Run a synchronous ad-hoc query and return the historical flattened rows shape. Existing consumers should migrate to `/monit/query/data`, which preserves frames, records, and samples without forcing every result into legacy rows.", - "deprecated": true, - "tags": [ - "Monitors/Diagnostics" - ], - "x-mint": { - "content": "## Deprecated\n\nUse [`POST /monit/query/data`](/en/api-reference/monitors/diagnostics/monit-read-query-data) for all new integrations. This endpoint remains available only during the migration of existing UI and AI SRE consumers.\n\n## 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\n## Usage\n\n- The request is forwarded to `monit-edge` over WebSocket; the data source named by `ds_type` + `ds_name` must already exist under the calling account.\n- `account_id` in the body is optional. When supplied it must equal the authenticated account; mismatched values are rejected.\n- Validation failures use the standard error envelope. When `monit-edge` rejects a query, its `{\"error\": {\"code\": ..., \"message\": ...}}` body is preserved and the HTTP status matches the edge error code; an invalid or absent code becomes HTTP 500. Check both the status and the error body.\n- monit-edge enforces a row cap; large result sets come back as `error.message = \"too many rows\"`. Narrow the time range or aggregate at the source.\n- `args` is a polymorphic `string→string` map that is forwarded verbatim. Semantics depend on `ds_type` (SLS requires `sls.project` + `sls.logstore`; Loki / VictoriaLogs raw mode requires a time range via `*.start`/`*.end` or `*.timespan.value`/`*.timespan.unit`; Prometheus and SQL sources ignore it). See the monit-webapi query-api docs for the per-source key list.", - "href": "/en/api-reference/monitors/diagnostics/monit-read-query-rows", - "metadata": { - "sidebarTitle": "Query data source rows" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/QueryRowsRequest" - }, - "example": { - "account_id": 10001, - "ds_type": "prometheus", - "ds_name": "prod-prom", - "expr": "up", - "delay_seconds": 30 - } - } - } - }, - "responses": { - "200": { - "description": "Success", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/QueryRowsResponse" - } - } - } - ] - }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": [ - { - "fields": { - "__name__": "up", - "instance": "10.0.0.1:9100", - "job": "node" - }, - "values": { - "__value__": 1 - } - } - ] - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/Unauthorized" - }, - "429": { - "$ref": "#/components/responses/TooManyRequests" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - } - } - }, "/monit/query/diagnose": { "post": { "operationId": "monit-read-query-diagnose", @@ -20195,7 +20018,7 @@ "Monitors/Diagnostics" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **600 requests/minute**; **10 requests/second** per account |\n| Permissions | Any valid `app_key` (read-only; not gated by a specific permission class) |\n\n## Usage\n\n- This is a diagnostic / RCA endpoint, not a raw data query — pair it with `/monit/query/rows` when you need detailed rows.\n- Only three `ds_type` and `operation` pairs are supported: `loki` / `victorialogs` → `log_patterns`, and `prometheus` → `metric_trends`. Every other datasource is rejected, even when `operation` is explicit.\n- `methods` selects the analyses to run; when omitted, `log_patterns` defaults to `pattern_snapshot + pattern_compare(previous_window)` and `metric_trends` defaults to `single_window_shape + window_compare(previous_window)`.\n- `time_range` is in Unix seconds; missing or invalid values default to the last 15 minutes; a window wider than 6 hours is rejected.\n- The request is forwarded over WebSocket to `monit-edge`. Long-running: the request may take up to ~30 s on the edge side plus webapi overhead. Set client timeouts to **at least 35 s**.\n- `options.*` are upper-bounded by edge (`max_logs_scanned` ≤ 50 000, `max_patterns` ≤ 50, `examples_per_pattern` ≤ 3, `step_seconds` ∈ [15, 300], `max_series` ≤ 200, `topk` ≤ 50, `timeout_seconds` ≤ 30).\n- Two error layers as with `/monit/query/rows`: edge-level execution errors come back as HTTP 200 with an `error` object in the body — check both layers.\n- Log examples are basic-redacted before being returned; expect `warnings: [\"examples redacted\"]`. Do not treat them as raw logs.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **600 requests/minute**; **10 requests/second** per account |\n| Permissions | Any valid `app_key` (read-only; not gated by a specific permission class) |\n\n## Usage\n\n- This is a diagnostic / RCA endpoint, not a raw data query — pair it with `/monit/query/data` when you need the underlying data.\n- Only three `ds_type` and `operation` pairs are supported: `loki` / `victorialogs` → `log_patterns`, and `prometheus` → `metric_trends`. Every other datasource is rejected, even when `operation` is explicit.\n- `methods` selects the analyses to run; when omitted, `log_patterns` defaults to `pattern_snapshot + pattern_compare(previous_window)` and `metric_trends` defaults to `single_window_shape + window_compare(previous_window)`.\n- `time_range` is in Unix seconds; missing or invalid values default to the last 15 minutes; a window wider than 6 hours is rejected.\n- The request is forwarded over WebSocket to `monit-edge`. Long-running: the request may take up to ~30 s on the edge side plus webapi overhead. Set client timeouts to **at least 35 s**.\n- `options.*` are upper-bounded by edge (`max_logs_scanned` ≤ 50 000, `max_patterns` ≤ 50, `examples_per_pattern` ≤ 3, `step_seconds` ∈ [15, 300], `max_series` ≤ 200, `topk` ≤ 50, `timeout_seconds` ≤ 30).\n- The success body is a raw `{\"data\": ...}` object WITHOUT the usual `request_id` wrapper field (raw passthrough from the edge).\n- Two error layers: request-level failures return a non-200 status with the standard `error` envelope, while edge-level execution errors come back as HTTP 200 with an `error` object in the body — check both.\n- Log examples are basic-redacted before being returned; expect `warnings: [\"examples redacted\"]`. Do not treat them as raw logs.", "href": "/en/api-reference/monitors/diagnostics/monit-read-query-diagnose", "metadata": { "sidebarTitle": "Diagnose data source" @@ -20245,22 +20068,17 @@ "content": { "application/json": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/DiagnoseResponse" - } - } + "type": "object", + "required": [ + "data" + ], + "properties": { + "data": { + "$ref": "#/components/schemas/DiagnoseResponse" } - ] + } }, "example": { - "request_id": "01JZPD1PCDTN5F4YVBD2GS6S9A", "data": { "schema_version": "2", "operation": "log_patterns", @@ -20733,7 +20551,7 @@ "account_id": 10001, "channel_id": 5001, "channel_name": "Production", - "channel_status": "active", + "channel_status": "enabled", "integration_id": 362, "integration_name": "GitHub Deploy", "title": "Deploy api-server v2.3.1", @@ -21100,7 +20918,7 @@ "updated_by": 20001, "created_at": 1716962400, "updated_at": 1716962700, - "last_time": 1716963000, + "last_time": 0, "exclusive_data_source_id": 0, "integration_id": 362 } @@ -21283,7 +21101,7 @@ ] }, "example": { - "error_code": 0, + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "account_id": 1001, "account_name": "acme", @@ -21343,7 +21161,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- If no member can be linked, the response contains an empty `new_linked_person_ids` array.", + "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" @@ -22275,85 +22093,6 @@ ] } }, - "/monit/preview/sync": { - "post": { - "operationId": "monit-preview-sync", - "summary": "Preview datasource query", - "description": "Execute a synchronous datasource query and return the raw result. Used to preview alert rule expressions before saving.", - "tags": [ - "Monitors/Monitor utilities" - ], - "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- `ds_type` must match the datasource type (e.g. `prometheus`, `loki`).\n- `ds_name` is the display name of the datasource as configured in the account.\n- `delay_seconds` shifts the query window backward by the specified number of seconds, useful for accommodating data ingestion latency.\n- The response body is the raw JSON returned by the datasource — its schema varies by datasource type.", - "href": "/en/api-reference/monitors/monitor-utilities/monit-preview-sync", - "metadata": { - "sidebarTitle": "Preview datasource query" - } - }, - "responses": { - "200": { - "description": "Success", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/PreviewSyncResponse" - } - } - } - ] - }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": { - "status": "success", - "data": { - "resultType": "vector", - "result": [] - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/Unauthorized" - }, - "429": { - "$ref": "#/components/responses/TooManyRequests" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PreviewSyncRequest" - }, - "example": { - "ds_type": "prometheus", - "ds_name": "Prometheus Prod", - "expr": "rate(http_requests_total[5m])", - "delay_seconds": 0 - } - } - } - } - } - }, "/status-page/info": { "get": { "operationId": "statusPageInfo", @@ -22383,7 +22122,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/StatusPageItem" + "$ref": "#/components/schemas/StatusPageInfoResponse" } } } @@ -22433,7 +22172,8 @@ "email": true, "im": false }, - "template_preference": "message" + "template_preference": "message", + "managed_domain_feature_enabled": true } } } @@ -22458,9 +22198,10 @@ "in": "query", "required": true, "schema": { - "type": "string" + "type": "integer", + "format": "int64" }, - "description": "Status page ID" + "description": "Status page ID." } ] } @@ -23064,9 +22805,9 @@ "type": "pre_defined", "template": { "title": "Service Disruption", - "event_type": "incident", "status": "investigating", - "description": "We are investigating a service disruption affecting some users." + "description": "We are investigating a service disruption affecting some users.", + "type": "incident" } } } @@ -23175,7 +22916,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/EmptyResponse" + "$ref": "#/components/schemas/ListStatusPageTemplatesResponse" } } } @@ -23252,7 +22993,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- `environment_kind` accepts only empty (automatic) or `byoc`; `cloud` is rejected. `byoc` requires `environment_id`, and the 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 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", "metadata": { "sidebarTitle": "Create A2A agent" @@ -23317,8 +23058,9 @@ "auth_type": "bearer", "streaming": true, "team_id": 0, - "environment_kind": "byoc", - "environment_id": "env_8s7Hn2kLpQ3xYbVc4Wd2m" + "environments": [ + "env_8s7Hn2kLpQ3xYbVc4Wd2m" + ] } } } @@ -23609,8 +23351,9 @@ "account_id": 10023, "team_id": 0, "can_edit": true, - "environment_kind": "", - "environment_id": "", + "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", @@ -23710,8 +23453,9 @@ "account_id": 10023, "team_id": 0, "can_edit": true, - "environment_kind": "", - "environment_id": "", + "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", @@ -23861,7 +23605,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` is immutable after creation.\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 | 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", "metadata": { "sidebarTitle": "Create Automation rule" @@ -24114,7 +23858,6 @@ "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, @@ -24227,7 +23970,6 @@ "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, @@ -24390,7 +24132,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` cannot be changed from its current value.\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 | 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", "metadata": { "sidebarTitle": "Update Automation rule" @@ -24544,6 +24286,8 @@ "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", @@ -24704,7 +24448,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 the account (case-insensitive); violations return InvalidParameter.\n- `environment_kind` accepts only `byoc` (with `environment_id`) or empty for automatic selection — `cloud` cannot be bound directly to an MCP server.\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 | **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", "metadata": { "sidebarTitle": "Create MCP server" @@ -24737,8 +24481,7 @@ "account_id": 10023, "team_id": 0, "can_edit": true, - "environment_kind": "", - "environment_id": "", + "environments": [], "server_name": "prometheus", "description": "Query Prometheus metrics and alerts.", "transport": "streamable-http", @@ -24746,17 +24489,6 @@ "status": "enabled", "connect_timeout": 10, "call_timeout": 60, - "tool_count": 2, - "tools": [ - { - "name": "query", - "description": "Run a PromQL instant query." - }, - { - "name": "query_range", - "description": "Run a PromQL range query." - } - ], "auth_mode": "shared", "created_by": 80011, "created_at": 1716960000000, @@ -25042,7 +24774,7 @@ "post": { "operationId": "mcp-read-server-get", "summary": "Get MCP server detail", - "description": "Get one MCP server and run a live probe of its tool list.", + "description": "Get one MCP server as a pure database read — no live probe is performed.", "tags": [ "AI SRE/MCP servers" ], @@ -25052,7 +24784,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 detail call live-probes tools; on failure `list_error` is set and the request still succeeds.\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 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", "metadata": { "sidebarTitle": "Get MCP server detail" @@ -25085,8 +24817,7 @@ "account_id": 10023, "team_id": 0, "can_edit": true, - "environment_kind": "", - "environment_id": "", + "environments": [], "server_name": "prometheus", "description": "Query Prometheus metrics and alerts.", "transport": "streamable-http", @@ -25094,17 +24825,6 @@ "status": "enabled", "connect_timeout": 10, "call_timeout": 60, - "tool_count": 2, - "tools": [ - { - "name": "query", - "description": "Run a PromQL instant query." - }, - { - "name": "query_range", - "description": "Run a PromQL range query." - } - ], "auth_mode": "shared", "created_by": 80011, "created_at": 1716960000000, @@ -25156,7 +24876,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 live tool list is not included; fetch a single server to probe its tools.\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- 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", "metadata": { "sidebarTitle": "List MCP servers" @@ -25192,8 +24912,7 @@ "account_id": 10023, "team_id": 0, "can_edit": true, - "environment_kind": "", - "environment_id": "", + "environments": [], "server_name": "prometheus", "description": "Query Prometheus metrics and alerts.", "transport": "streamable-http", @@ -25201,17 +24920,6 @@ "status": "enabled", "connect_timeout": 10, "call_timeout": 60, - "tool_count": 2, - "tools": [ - { - "name": "query", - "description": "Run a PromQL instant query." - }, - { - "name": "query_range", - "description": "Run a PromQL range query." - } - ], "auth_mode": "shared", "created_by": 80011, "created_at": 1716960000000, @@ -25267,7 +24975,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- `environment_kind`/`environment_id` are independent partial-update fields: omit both to leave the runner binding unchanged; set either to change it, subject to the same `byoc`-or-empty constraint as create.\n- Changing `team_id` requires reassignment permission on the destination team; if the runner binding is left unchanged, it 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 | **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", "metadata": { "sidebarTitle": "Update MCP server" @@ -25300,8 +25008,7 @@ "account_id": 10023, "team_id": 0, "can_edit": true, - "environment_kind": "", - "environment_id": "", + "environments": [], "server_name": "prometheus", "description": "Query Prometheus metrics, alerts, and rules.", "transport": "streamable-http", @@ -25309,17 +25016,6 @@ "status": "enabled", "connect_timeout": 10, "call_timeout": 60, - "tool_count": 2, - "tools": [ - { - "name": "query", - "description": "Run a PromQL instant query." - }, - { - "name": "query_range", - "description": "Run a PromQL range query." - } - ], "auth_mode": "shared", "created_by": 80011, "created_at": 1716960000000, @@ -26386,8 +26082,7 @@ "updated_at": 1717046400000, "can_edit": true, "update_available": false, - "is_modified": false, - "created": true + "is_modified": false } } } @@ -27429,7 +27124,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/EmptyResponse" + "$ref": "#/components/schemas/WorkItemMutationResult" } } } @@ -31204,7 +30899,8 @@ "properties": { "total": { "type": "integer", - "description": "Number of people holding an active license." + "description": "Number of people holding an active license.", + "format": "int64" }, "items": { "type": "array", @@ -31789,10 +31485,9 @@ "enum": [ "Critical", "Warning", - "Info", - "Ok" + "Info" ], - "description": "Severity of this event." + "description": "Severity of this event: `Critical`, `Warning`, or `Info`. An event never carries `Ok` as severity — `Ok` appears only as `event_status`." }, "event_status": { "type": "string", @@ -31802,7 +31497,7 @@ "Info", "Ok" ], - "description": "Status of this event." + "description": "Status carried by this event: `Critical`/`Warning`/`Info` for a firing event, `Ok` for a recovery event." }, "event_time": { "type": "integer", @@ -31836,7 +31531,7 @@ "deleted_at": { "type": "integer", "format": "int64", - "description": "Soft-delete timestamp (seconds). Zero if not deleted." + "description": "Soft-delete time, Unix epoch seconds. Omitted when the event is not deleted." } } }, @@ -32049,6 +31744,7 @@ "incident_id", "account_id", "channel_id", + "team_id", "integration_id", "integration_ids", "integration_types", @@ -32111,6 +31807,11 @@ "format": "int64", "description": "Channel ID. 0 for standalone incidents." }, + "team_id": { + "type": "integer", + "format": "int64", + "description": "ID of the team that owns the incident's channel. 0 when the channel has no team." + }, "integration_id": { "type": "integer", "format": "int64", @@ -32749,6 +32450,10 @@ "failed_reason": { "type": "string", "description": "Failure reason if delivery did not succeed." + }, + "sms_content": { + "type": "string", + "description": "SMS text delivered to the recipient; present on SMS deliveries." } } }, @@ -32841,6 +32546,17 @@ "progress": { "type": "string", "description": "Progress note entered at acknowledgement." + }, + "comment": { + "type": "string", + "description": "Form summary recorded as a timeline comment. Omitted when no acknowledgement form summary was submitted." + }, + "images": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Image" + }, + "description": "Images from the acknowledgement form, recorded on the timeline entry only. Omitted when none were submitted." } }, "title": "i_ack" @@ -32900,6 +32616,17 @@ "escalation" ], "description": "Source that triggered the resolve.\n| Value | Meaning |\n|---|---|\n| `voice` | Phone-call (voice DTMF) action. |\n| `console` | Console (Web UI) action. |\n| `card` | IM notification card button (DingTalk/Feishu/Slack/Teams). |\n| `wcard` | WeCom notification card button. |\n| `event` | Event-driven: auto-close when all related alerts recover to Ok, or a close synced from an external ITSM system. |\n| `autorslv` | Auto-resolve: closed by the system after no new alerts within the channel's auto-resolve timeout. |\n| `autorefresh` | Card auto-refresh (reserved; never appears on resolve feeds). |\n| `escalation` | Escalation flow (reserved; never appears on resolve feeds). |" + }, + "comment": { + "type": "string", + "description": "Form summary recorded as a timeline comment on resolution. Omitted when no resolve form summary was submitted." + }, + "images": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Image" + }, + "description": "Images from the resolve form, recorded on the timeline entry only. Omitted when none were submitted." } }, "title": "i_rslv" @@ -33274,7 +33001,7 @@ "$ref": "#/components/schemas/IncidentFeedType" }, "detail": { - "description": "Type-specific payload. The concrete shape is determined by `type`.", + "description": "Type-specific payload. The concrete shape is determined by `type`; `null` when the entry has no structured detail.", "oneOf": [ { "$ref": "#/components/schemas/FeedDetailIncidentNew" @@ -33374,6 +33101,9 @@ }, { "$ref": "#/components/schemas/FeedDetailWorkItemDeleted" + }, + { + "$ref": "#/components/schemas/FeedDetailAlertMerge" } ], "discriminator": { @@ -33411,7 +33141,8 @@ "i_wi_completed": "#/components/schemas/FeedDetailWorkItemCompleted", "i_wi_converted": "#/components/schemas/FeedDetailWorkItemConverted", "i_wi_bound": "#/components/schemas/FeedDetailWorkItemBound", - "i_wi_deleted": "#/components/schemas/FeedDetailWorkItemDeleted" + "i_wi_deleted": "#/components/schemas/FeedDetailWorkItemDeleted", + "a_merge": "#/components/schemas/FeedDetailAlertMerge" } } }, @@ -33650,7 +33381,10 @@ "description": "Optional resolution note applied to every resolved incident." }, "description": { - "type": "string", + "type": [ + "string", + "null" + ], "maxLength": 6144, "description": "New incident description, up to 6,144 characters. When set, it replaces the current description before the incident closes." }, @@ -33710,14 +33444,15 @@ "pattern": "^[0-9a-fA-F]{24}$" }, "maxItems": 100, - "description": "Incident IDs to snooze. At most 100 per call." + "description": "Incident IDs to snooze. At most 100 per call.", + "minItems": 1 }, "minutes": { "type": "integer", "format": "int64", "exclusiveMinimum": 0, - "maximum": 1440, - "description": "Duration in minutes. Must be greater than 0 and at most 1440 (24h)." + "maximum": 43200, + "description": "Duration in minutes. Must be greater than 0 and at most 43,200 (30 days)." } } }, @@ -33776,7 +33511,7 @@ "owner_id": { "type": "integer", "format": "int64", - "description": "Optional new owner member ID for the target incident." + "description": "Accepted for compatibility but currently ignored by the server; the merge does not change the target incident owner." }, "remove_source_incidents": { "type": "boolean", @@ -33797,7 +33532,8 @@ "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, - "description": "Incident IDs whose automatic merge should be disabled." + "description": "Incident IDs whose automatic merge should be disabled.", + "minItems": 1 } } }, @@ -33868,7 +33604,8 @@ "pattern": "^[0-9a-fA-F]{24}$" }, "maxItems": 100, - "description": "Incident IDs to remove. At most 100 per call. The caller must have access to every channel the incidents belong to." + "description": "Incident IDs to remove. At most 100 per call. The caller must have access to every channel the incidents belong to.", + "minItems": 1 } } }, @@ -33876,7 +33613,8 @@ "type": "object", "description": "Parameters for adding a comment to one or more incidents.", "required": [ - "incident_ids" + "incident_ids", + "comment" ], "properties": { "incident_ids": { @@ -34137,7 +33875,11 @@ }, "status": { "type": "string", - "description": "War room status." + "description": "War room record status: `enabled` active, `deleted` disbanded.", + "enum": [ + "enabled", + "deleted" + ] }, "created_at": { "type": "integer", @@ -34196,7 +33938,7 @@ "drafting", "published" ], - "description": "Post-mortem status filter; the server defaults to `published` when omitted. `drafting` returns only drafts; `published` returns only published post-mortems." + "description": "Optional status filter: `drafting` returns only drafts, `published` returns only published post-mortems. When omitted, post-mortems in all statuses are returned." }, "team_ids": { "type": "array", @@ -34690,21 +34432,21 @@ "items": { "type": "string" }, - "description": "Channels for Critical events (e.g. `voice`, `sms`, `email`, `feishu`)." + "description": "Notify channels used for Critical severity. Personal channels: `sms`, `voice`, `email`, `push`; IM group-chat channels: `feishu_app:`, `dingtalk_app:`, `wecom_app:`, `slack_app:`, `teams_app:`." }, "warning": { "type": "array", "items": { "type": "string" }, - "description": "Channels for Warning events." + "description": "Notify channels used for Warning severity. Values as for `critical`." }, "info": { "type": "array", "items": { "type": "string" }, - "description": "Channels for Info events." + "description": "Notify channels used for Info severity. Values as for `critical`." } } }, @@ -34720,7 +34462,7 @@ "properties": { "type": { "type": "string", - "description": "Webhook type (e.g. `feishu`, `dingtalk_app`, `wecom_app`, `slack`, `teams`, `custom`)." + "description": "Webhook type, one of `feishu`, `feishu_app`, `dingtalk`, `dingtalk_app`, `wecom`, `slack`, `slack_app`, `teams_app`, `telegram`, `zoom`." }, "settings": { "type": "object", @@ -34766,7 +34508,30 @@ "maxItems": 100, "description": "Per-filter grouping overrides.", "items": { - "type": "object" + "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.`." + } + } } }, "all_equals_required": { @@ -34883,6 +34648,10 @@ "is_external_report_enabled": { "type": "boolean", "description": "Allow external reporters to file incidents into this channel." + }, + "event_group": { + "$ref": "#/components/schemas/EventGroup", + "description": "Alert event merge configuration. Omit to use the default (merge enabled, 1440-minute window)." } } }, @@ -35006,21 +34775,21 @@ "items": { "type": "string" }, - "description": "Channels for Critical events (e.g. `voice`, `sms`, `email`, `feishu`)." + "description": "Notify channels used for Critical severity. Personal channels: `sms`, `voice`, `email`, `push`; IM group-chat channels: `feishu_app:`, `dingtalk_app:`, `wecom_app:`, `slack_app:`, `teams_app:`." }, "warning": { "type": "array", "items": { "type": "string" }, - "description": "Channels for Warning events." + "description": "Notify channels used for Warning severity. Values as for `critical`." }, "info": { "type": "array", "items": { "type": "string" }, - "description": "Channels for Info events." + "description": "Notify channels used for Info severity. Values as for `critical`." } } }, @@ -35036,7 +34805,7 @@ "properties": { "type": { "type": "string", - "description": "Webhook type (e.g. `feishu`, `dingtalk_app`, `wecom_app`, `slack`, `teams`, `custom`)." + "description": "Webhook type, one of `feishu`, `feishu_app`, `dingtalk`, `dingtalk_app`, `wecom`, `slack`, `slack_app`, `teams_app`, `telegram`, `zoom`." }, "settings": { "type": "object", @@ -35096,7 +34865,7 @@ }, "filters": { "type": "array", - "description": "Or-of-and filter tree. Each outer element is an AND group; within each group, all conditions must match.", + "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": { @@ -35162,11 +34931,11 @@ "items": { "type": "string" }, - "description": "Label keys used to pair source and target alerts." + "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`." }, "source_filters": { "type": "array", - "description": "Or-of-and filter tree. Each outer element is an AND group; within each group, all conditions must match.", + "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.`. Empty makes the rule inert.", "items": { "type": "array", "items": { @@ -35202,7 +34971,7 @@ }, "target_filters": { "type": "array", - "description": "Or-of-and filter tree. Each outer element is an AND group; within each group, all conditions must match.", + "description": "Conditions the incoming target alert event must match to be suppressed; empty means every event is a target.", "items": { "type": "array", "items": { @@ -35238,7 +35007,7 @@ }, "is_directly_discard": { "type": "boolean", - "description": "When true, suppressed target alerts are dropped instead of merged." + "description": "When true, matching alert events are discarded entirely; when false, alerts are still recorded but marked as muted by this rule." } } }, @@ -35268,7 +35037,8 @@ }, "from_incident_id": { "type": "string", - "description": "Source incident ID when the silence was created from an incident." + "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}$" }, "time_filters": { "type": "array", @@ -35314,18 +35084,20 @@ "start_time": { "type": "integer", "format": "int64", - "description": "Window start (unix seconds). Must be less than `end_time`." + "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 seconds)." + "description": "Window end, Unix timestamp in seconds. Must be greater than 0.", + "exclusiveMinimum": 0 } } }, "filters": { "type": "array", - "description": "Or-of-and filter tree. Each outer element is an AND group; within each group, all conditions must match.", + "description": "Alert event match conditions (OR-of-AND). Required and must contain at least one condition.", "items": { "type": "array", "items": { @@ -35361,7 +35133,7 @@ }, "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 muted by this rule." }, "is_auto_delete": { "type": "boolean", @@ -35395,7 +35167,7 @@ }, "filters": { "type": "array", - "description": "Or-of-and filter tree. Each outer element is an AND group; within each group, all conditions must match.", + "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": { @@ -35446,7 +35218,9 @@ "repeat": { "type": "array", "items": { - "type": "integer" + "type": "integer", + "minimum": 0, + "maximum": 6 }, "description": "Days of the week this window repeats on. Empty means every day." }, @@ -35471,13 +35245,13 @@ "start_time": { "type": "integer", "format": "int64", - "description": "Window start (unix seconds). Must be > 0 and less than `end_time`.", + "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 seconds). Must be > 0.", + "description": "Window end, Unix timestamp in seconds. Must be greater than 0.", "exclusiveMinimum": 0 } } @@ -35537,21 +35311,21 @@ "items": { "type": "string" }, - "description": "Channels for Critical events (e.g. `voice`, `sms`, `email`, `feishu`)." + "description": "Notify channels used for Critical severity. Personal channels: `sms`, `voice`, `email`, `push`; IM group-chat channels: `feishu_app:`, `dingtalk_app:`, `wecom_app:`, `slack_app:`, `teams_app:`." }, "warning": { "type": "array", "items": { "type": "string" }, - "description": "Channels for Warning events." + "description": "Notify channels used for Warning severity. Values as for `critical`." }, "info": { "type": "array", "items": { "type": "string" }, - "description": "Channels for Info events." + "description": "Notify channels used for Info severity. Values as for `critical`." } } }, @@ -35567,7 +35341,7 @@ "properties": { "type": { "type": "string", - "description": "Webhook type (e.g. `feishu`, `dingtalk_app`, `wecom_app`, `slack`, `teams`, `custom`)." + "description": "Webhook type, one of `feishu`, `feishu_app`, `dingtalk`, `dingtalk_app`, `wecom`, `slack`, `slack_app`, `teams_app`, `telegram`, `zoom`." }, "settings": { "type": "object", @@ -35645,7 +35419,30 @@ "maxItems": 100, "description": "Per-filter grouping overrides.", "items": { - "type": "object" + "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.`." + } + } } }, "all_equals_required": { @@ -35803,17 +35600,17 @@ "deleted_at": { "type": "integer", "format": "int64", - "description": "Deletion timestamp (unix seconds). Non-zero only for soft-deleted channels." + "description": "Deletion time, Unix timestamp in seconds. Non-zero only for soft-deleted channels." }, "created_at": { "type": "integer", "format": "int64", - "description": "Creation timestamp (unix seconds)." + "description": "Creation time, Unix timestamp in seconds." }, "updated_at": { "type": "integer", "format": "int64", - "description": "Last update timestamp (unix seconds)." + "description": "Last update time, Unix timestamp in seconds." }, "auto_resolve_timeout": { "type": "integer", @@ -35841,26 +35638,34 @@ "description": "When true, automatic incident closing is disabled." }, "group": { - "$ref": "#/components/schemas/Group" + "$ref": "#/components/schemas/Group", + "description": "Alert grouping configuration." }, "flapping": { - "$ref": "#/components/schemas/Flapping" + "$ref": "#/components/schemas/Flapping", + "description": "Flapping detection configuration." }, "progress_to_incident_cnts": { - "$ref": "#/components/schemas/IncProgressCnts" + "$ref": "#/components/schemas/IncProgressCnts", + "description": "Incident counts by progress over the last 30 days." }, "is_starred": { "type": "boolean", - "description": "Whether the current user has starred this channel." + "description": "Whether the current user has starred this channel. Present only in `POST /channel/list` responses." }, "active_incident_highest_severity": { "type": "string", - "description": "Highest severity among active incidents in the channel." + "enum": [ + "Critical", + "Warning", + "Info" + ], + "description": "Highest severity among the channel's active (triggered or processing) incidents: `Critical`, `Warning` or `Info`. Omitted when there are no active incidents." }, "last_incident_at": { "type": "integer", "format": "int64", - "description": "Timestamp of the most recent incident (unix seconds)." + "description": "Time of the most recent incident, Unix timestamp in seconds." }, "is_external_report_enabled": { "type": "boolean", @@ -35868,7 +35673,11 @@ }, "external_report_token": { "type": "string", - "description": "Token granted to external reporters when external reporting is enabled." + "description": "Token granted to external reporters. Omitted unless external reporting is enabled on the channel." + }, + "event_group": { + "$ref": "#/components/schemas/EventGroup", + "description": "Alert event merge configuration." } } }, @@ -35892,9 +35701,10 @@ "type": "string", "enum": [ "enabled", - "disabled" + "disabled", + "deleted" ], - "description": "Channel status." + "description": "Channel status: `enabled` processes events normally; `disabled` discards incoming events; `deleted` is soft-deleted." } } }, @@ -35959,15 +35769,17 @@ "description": "Recurring time windows during which the rule applies." }, "filters": { - "$ref": "#/components/schemas/FilterGroup" + "$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." }, "status": { "type": "string", "enum": [ "enabled", - "disabled" + "disabled", + "deleted" ], - "description": "Rule 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)." }, "template_id": { "type": "string", @@ -35987,17 +35799,17 @@ "deleted_at": { "type": "integer", "format": "int64", - "description": "Deletion timestamp (unix seconds). Emitted only for soft-deleted rules." + "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 timestamp (unix seconds)." + "description": "Creation time, Unix timestamp in seconds." }, "updated_at": { "type": "integer", "format": "int64", - "description": "Last update timestamp (unix seconds)." + "description": "Last update time, Unix timestamp in seconds." }, "channel_name": { "type": "string", @@ -36045,20 +35857,22 @@ "from_incident_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", - "description": "Source incident ID when the silence was created from an incident." + "description": "Incident the rule is attached to. Always present; the zero ObjectID `000000000000000000000000` means the rule was not created from an incident." }, "time_filters": { "type": "array", "items": { "$ref": "#/components/schemas/TimeFilter" }, - "description": "Recurring time windows." + "description": "Recurring silence windows. Empty when the rule uses a one-off `time_filter`." }, "time_filter": { - "$ref": "#/components/schemas/OnceTimeFilter" + "$ref": "#/components/schemas/OnceTimeFilter", + "description": "One-off silence window. Present with zero values when the rule uses recurring `time_filters` instead." }, "filters": { - "$ref": "#/components/schemas/FilterGroup" + "$ref": "#/components/schemas/FilterGroup", + "description": "Alert event match conditions; matching events are silenced within the time window." }, "is_directly_discard": { "type": "boolean", @@ -36094,11 +35908,16 @@ }, "is_effective": { "type": "boolean", - "description": "Whether the rule is currently in effect." + "description": "Whether the rule's time window covers the current moment, evaluated at response time." }, "is_auto_delete": { "type": "boolean", "description": "When true, the silence rule is automatically deleted after its time window expires. Defaults to false." + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "Deletion time, Unix timestamp in seconds. Omitted unless the rule is soft-deleted; deleted rules are excluded from list responses." } } }, @@ -36139,21 +35958,23 @@ "description": "Rule description." }, "source_filters": { - "$ref": "#/components/schemas/FilterGroup" + "$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.`. Empty makes the rule inert." }, "target_filters": { - "$ref": "#/components/schemas/FilterGroup" + "$ref": "#/components/schemas/FilterGroup", + "description": "Conditions the incoming target alert event must match to be suppressed; empty means every event is a target." }, "equals": { "type": "array", "items": { "type": "string" }, - "description": "Label keys used to pair source and target alerts." + "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`." }, "is_directly_discard": { "type": "boolean", - "description": "When true, the inhibited target alert is discarded outright; when false, the alert is still created but muted — no incident is triggered and no notification is sent." + "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", @@ -36182,6 +36003,11 @@ "type": "integer", "format": "int64", "description": "Last update time, Unix timestamp in seconds." + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "Deletion time, Unix timestamp in seconds. Omitted unless the rule is soft-deleted; deleted rules are excluded from list responses." } } }, @@ -36220,7 +36046,8 @@ "description": "Rule description." }, "filters": { - "$ref": "#/components/schemas/FilterGroup" + "$ref": "#/components/schemas/FilterGroup", + "description": "Alert event match conditions (OR-of-AND); matching events are discarded entirely. Empty means the rule matches nothing." }, "status": { "type": "string", @@ -36249,6 +36076,11 @@ "type": "integer", "format": "int64", "description": "Last update time, Unix timestamp in seconds." + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "Deletion time, Unix timestamp in seconds. Omitted unless the rule is soft-deleted; deleted rules are excluded from list responses." } } }, @@ -36289,11 +36121,11 @@ "channel_name", "last_incident_at" ], - "description": "Field used to order results." + "description": "Field used to order results. Defaults to `created_at`." }, "asc": { "type": "boolean", - "description": "When true, sort ascending." + "description": "When true, sort ascending; defaults to false (descending)." }, "is_my_managed": { "type": "boolean", @@ -36305,7 +36137,7 @@ }, "is_brief": { "type": "boolean", - "description": "When true, return only brief fields (`channel_id`, `channel_name`, `description`, `status`)." + "description": "When true, return only `channel_id`, `channel_name`, `description` and `status`, and return all matches without pagination." }, "is_my_team": { "type": "boolean", @@ -36321,7 +36153,7 @@ }, "query": { "type": "string", - "description": "Free-text query against channel name/description." + "description": "Case-insensitive regular expression matched against channel name and description; invalid regex syntax falls back to a literal match." }, "channel_ids": { "type": "array", @@ -36416,7 +36248,7 @@ "trigger", "update" ], - "description": "Auto-resolve timing mode: `trigger` starts the timer when the incident triggers, `update` restarts it on every alert 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." }, "is_private": { "type": [ @@ -36453,6 +36285,10 @@ "null" ], "description": "Allow external reporters to file incidents into this channel." + }, + "event_group": { + "$ref": "#/components/schemas/EventGroup", + "description": "Alert event merge configuration. Updated only when present." } } }, @@ -36539,7 +36375,7 @@ }, "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 muted by this rule." }, "is_auto_delete": { "type": "boolean", @@ -36602,19 +36438,19 @@ "items": { "type": "string" }, - "description": "Label keys used to pair source and target alerts." + "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`." }, "source_filters": { "$ref": "#/components/schemas/FilterGroup", - "description": "Match conditions for source alerts; together with `equals`, determines which target alerts are suppressed." + "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.`. Empty makes the rule inert." }, "target_filters": { "$ref": "#/components/schemas/FilterGroup", - "description": "Match conditions for target (suppressed) alerts." + "description": "Conditions the incoming target alert event must match to be suppressed; empty means every event is a target." }, "is_directly_discard": { "type": "boolean", - "description": "When true, suppressed target alerts are dropped instead of merged." + "description": "When true, matching alert events are discarded entirely; when false, alerts are still recorded but marked as muted by this rule." } } }, @@ -36650,7 +36486,7 @@ }, "filters": { "$ref": "#/components/schemas/FilterGroup", - "description": "Matching alerts are dropped and generate no notification." + "description": "Alert event match conditions (OR-of-AND); matching events are discarded entirely. When empty, the rule matches nothing." } } }, @@ -36718,7 +36554,7 @@ }, "filters": { "$ref": "#/components/schemas/FilterGroup", - "description": "Match conditions for alerts this rule applies to; omit to apply it to all alerts in the channel." + "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." } } }, @@ -36897,9 +36733,7 @@ "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", - "channel_ids", - "fallthrough" + "if" ], "properties": { "if": { @@ -36910,12 +36744,15 @@ } }, "channel_ids": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "type": "integer", "format": "int64" }, - "description": "Target channel IDs. Required when `routing_mode` is `standard` (or empty)." + "description": "Target channel IDs. Required when `routing_mode` is `standard` (or empty); returned as `null` for `name_mapping`." }, "fallthrough": { "type": "boolean", @@ -37048,7 +36885,8 @@ "integration_id": { "type": "integer", "format": "int64", - "description": "Integration ID. Must be greater than 0." + "description": "Integration ID. Must be greater than 0.", + "exclusiveMinimum": 0 } } }, @@ -37065,7 +36903,8 @@ "type": "integer", "format": "int64" }, - "description": "Integration IDs to fetch routing rules for." + "description": "Integration IDs to fetch routing rules for.", + "minItems": 1 } } }, @@ -37118,7 +36957,7 @@ "version": { "type": "integer", "format": "int64", - "description": "Expected current version for optimistic concurrency control. Pass the value returned by the latest read." + "description": "Reserved for optimistic concurrency control; currently ignored — the server increments `version` automatically on every upsert." } } }, @@ -37138,20 +36977,32 @@ "end_time": { "type": "integer", "format": "int64", - "description": "End of the search window, Unix epoch seconds. Max span 31 days." + "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." }, "p": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "Page number, starting at 1. Used when `search_after_ctx` is not provided." + "description": "Page number, starting at 1. Used when `search_after_ctx` is not provided; `p * limit` must stay within 10,000 records.", + "minimum": 0 }, "limit": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "Page size. Max 100, default 20." + "description": "Page size. Max 100, default 20.", + "minimum": 0, + "maximum": 100 }, "search_after_ctx": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "Opaque cursor from the previous response for the next page." }, "is_active": { @@ -37159,7 +37010,7 @@ "boolean", "null" ], - "description": "Filter by active (`true`) or resolved (`false`) status." + "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." }, "ever_muted": { "type": [ @@ -37193,7 +37044,7 @@ "items": { "type": "string" }, - "description": "Filter to specific alert IDs (ObjectID hex strings)." + "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", @@ -37202,17 +37053,9 @@ }, "description": "Filter by alert deduplication keys." }, - "orderby": { - "type": "string", - "enum": [ - "created_at", - "updated_at" - ], - "description": "Sort field." - }, "asc": { "type": "boolean", - "description": "Sort ascending when `true`. Default descending." + "description": "Sort ascending by `start_time` when `true`; default is descending." }, "by_updated_at": { "type": "boolean", @@ -37236,7 +37079,7 @@ "data_source_id": { "type": "integer", "format": "int64", - "description": "Deprecated. Use `integration_id` instead. Deprecated: use `integration_id` instead.", + "description": "Deprecated: use `integration_id` instead.", "deprecated": true }, "channel_id": { @@ -37266,10 +37109,9 @@ "enum": [ "Critical", "Warning", - "Info", - "Ok" + "Info" ], - "description": "Current severity." + "description": "Current severity — the highest severity ever seen on this alert: `Critical`, `Warning`, or `Info`." }, "alert_status": { "type": "string", @@ -37279,7 +37121,7 @@ "Info", "Ok" ], - "description": "Current status." + "description": "Current status: `Critical`/`Warning`/`Info` while firing, `Ok` once recovered." }, "alert_key": { "type": "string", @@ -37339,15 +37181,19 @@ }, "channel_status": { "type": "string", - "description": "Status of the channel (e.g. `enabled`, `disabled`)." + "description": "Status of the channel: `enabled` or `disabled`.", + "enum": [ + "enabled", + "disabled" + ] }, "responder_name": { "type": "string", - "description": "Display name of the current responder (from the associated incident)." + "description": "Responder display name. Always empty in this response — responder tracking lives on the associated incident." }, "responder_email": { "type": "string", - "description": "Email of the current responder (from the associated incident)." + "description": "Responder email. Always empty in this response — responder tracking lives on the associated incident." }, "event_cnt": { "type": "integer", @@ -37363,7 +37209,7 @@ "items": { "$ref": "#/components/schemas/AlertEventItem" }, - "description": "Recent raw events attached to this alert. Populated only by some endpoints." + "description": "Raw events of this alert. Omitted here; populated only by `POST /incident/alert/list`." }, "images": { "type": "array", @@ -37374,15 +37220,23 @@ }, "data_source_name": { "type": "string", - "description": "Deprecated. Use `integration_name` instead." + "description": "Deprecated: use `integration_name` instead.", + "deprecated": true }, "data_source_type": { "type": "string", - "description": "Deprecated. Use `integration_type` instead." + "description": "Deprecated: use `integration_type` instead. Omitted when empty.", + "deprecated": true }, "data_source_ref_id": { "type": "string", - "description": "Deprecated. Use `integration_ref_id` instead." + "description": "Deprecated: use `integration_ref_id` instead.", + "deprecated": true + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "Soft-delete time, Unix epoch seconds. Omitted when the alert is not deleted." } } }, @@ -37414,7 +37268,7 @@ "total": { "type": "integer", "format": "int64", - "description": "Total matching alerts." + "description": "Total matching alerts, capped at 1000." }, "has_next_page": { "type": "boolean", @@ -37422,7 +37276,7 @@ }, "search_after_ctx": { "type": "string", - "description": "Cursor for the next page." + "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." }, "items": { "type": "array", @@ -37441,7 +37295,8 @@ "properties": { "alert_id": { "type": "string", - "description": "Alert ID (ObjectID hex string)." + "description": "Alert ID (ObjectID hex string).", + "pattern": "^[0-9a-fA-F]{24}$" } } }, @@ -37456,7 +37311,8 @@ "items": { "type": "string" }, - "description": "List of alert IDs (ObjectID hex strings)." + "description": "Alert IDs (ObjectID hex strings) to fetch.", + "minItems": 1 } } }, @@ -37477,7 +37333,10 @@ "description": "When true, return events oldest-first. Defaults to newest-first." }, "limit": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", "minimum": 0, "maximum": 100, @@ -37485,14 +37344,20 @@ "description": "Page size. Defaults to 20 and cannot exceed 100." }, "p": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", "minimum": 0, "default": 1, "description": "Page number starting at 1. Used when `search_after_ctx` is omitted." }, "search_after_ctx": { - "type": "string", + "type": [ + "string", + "null" + ], "pattern": "^[0-9a-fA-F]{24}$", "description": "Cursor returned by the previous page. When supplied, cursor pagination is used instead of page-number pagination." } @@ -37516,7 +37381,7 @@ "total": { "type": "integer", "format": "int64", - "description": "Total matching event count." + "description": "Total matching event count, capped at 1000." }, "has_next_page": { "type": "boolean", @@ -37524,7 +37389,7 @@ }, "search_after_ctx": { "type": "string", - "description": "Cursor to pass as `search_after_ctx` for the next page." + "description": "Cursor to pass as `search_after_ctx` for the next page. Omitted when the page is empty; in cursor mode also omitted when there is no next page." } } }, @@ -37536,18 +37401,22 @@ "properties": { "alert_id": { "type": "string", - "description": "Alert ID; obtain it from `POST /alert/list`." + "description": "Alert ID (ObjectID hex string); obtain it from `POST /alert/list`.", + "pattern": "^[0-9a-fA-F]{24}$" }, "p": { "type": "integer", "format": "int64", "description": "Page number, starting at 1.", - "default": 1 + "default": 1, + "minimum": 1 }, "limit": { "type": "integer", "format": "int64", - "description": "Page size, max 100, default 20." + "description": "Page size, max 100, default 20.", + "minimum": 1, + "maximum": 100 }, "asc": { "type": "boolean", @@ -37558,20 +37427,23 @@ "items": { "type": "string" }, - "description": "Filter by feed type codes (e.g. `a_new`, `a_close`, `a_ack`)." + "description": "Filter by feed type codes — see the `type` field of the response items for the full list (e.g. `a_new`, `a_comm`, `a_merge`)." } } }, "AlertFeedType": { "type": "string", - "description": "Alert activity feed entry type. Each value identifies one alert lifecycle event; the matching `detail` payload shape is determined by this field.\n\n| Type | Meaning |\n|---|---|\n| `a_new` | Alert triggered. |\n| `a_update` | Alert updated by an incoming event (e.g. severity or status change). |\n| `a_merge` | Alert merged. |\n| `a_comm` | Comment added on the alert. |\n| `a_m_silence` | Alert muted by a silence rule. |\n| `a_m_inhibit` | Alert muted by an inhibit rule. |\n| `a_close` | Alert closed (historical data only; no longer produced). |", + "description": "Alert activity feed entry type. Each value identifies one alert lifecycle event; the matching `detail` payload shape is determined by this field.\n\n| Type | Meaning |\n|---|---|\n| `a_new` | Alert triggered by an incoming event. |\n| `a_update` | Alert severity or status changed on an incoming event. |\n| `a_comm` | Comment added on the alert. |\n| `a_merge` | Alert merged into an incident. |\n| `a_m_silence` | Alert muted by a silence rule. |\n| `a_m_inhibit` | Alert muted by an inhibit rule. |\n| `a_m_flapping` | Alert muted by flapping detection (historical data only; no longer produced). |\n| `a_ack` | Alert acknowledged (historical data only; alert-level acknowledgement has been removed). |\n| `a_unack` | Alert acknowledgement revoked (historical data only). |\n| `a_close` | Alert closed (historical data only; no longer produced). |", "enum": [ "a_new", "a_update", - "a_merge", "a_comm", + "a_merge", "a_m_silence", "a_m_inhibit", + "a_m_flapping", + "a_ack", + "a_unack", "a_close" ] }, @@ -37628,14 +37500,35 @@ "$ref": "#/components/schemas/AlertFeedType" }, "detail": { - "description": "Type-specific payload. The concrete shape is determined by `type`.", + "description": "Type-specific payload; the concrete shape is determined by `type`. May be `null` for entries stored without detail.", "oneOf": [ { "$ref": "#/components/schemas/FeedDetailAlertTrigger" }, + { + "$ref": "#/components/schemas/FeedDetailAlertUpdate" + }, { "$ref": "#/components/schemas/FeedDetailAlertComment" }, + { + "$ref": "#/components/schemas/FeedDetailAlertMerge" + }, + { + "$ref": "#/components/schemas/FeedDetailAlertMuteBySilence" + }, + { + "$ref": "#/components/schemas/FeedDetailAlertMuteByInhibit" + }, + { + "$ref": "#/components/schemas/FeedDetailAlertMuteByFlapping" + }, + { + "$ref": "#/components/schemas/FeedDetailAlertAck" + }, + { + "$ref": "#/components/schemas/FeedDetailAlertUnack" + }, { "$ref": "#/components/schemas/FeedDetailAlertClose" } @@ -37644,7 +37537,14 @@ "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" } } @@ -37668,6 +37568,11 @@ "type": "integer", "format": "int64", "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." } } }, @@ -37699,19 +37604,23 @@ "items": { "type": "string" }, - "description": "Alert IDs to merge; obtain them from `POST /alert/list`." + "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 }, "incident_id": { "type": "string", - "description": "Target incident ID; obtain it from `POST /incident/list`." + "description": "Target incident ID (ObjectID hex string); obtain it from `POST /incident/list`.", + "pattern": "^[0-9a-fA-F]{24}$" }, "comment": { "type": "string", - "description": "Optional comment on the merge action." + "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." + "description": "Optional new title for the target incident. At most 512 characters.", + "maxLength": 512 }, "owner_id": { "type": "integer", @@ -37729,7 +37638,8 @@ "integration_id": { "type": "integer", "format": "int64", - "description": "Integration ID." + "description": "Integration ID. Must be greater than 0.", + "exclusiveMinimum": 0 } } }, @@ -37749,11 +37659,14 @@ "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", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/FilterCondition" }, - "description": "Optional AND-filter list — the rule applies only when every condition matches. Omit to apply the rule to all alerts." + "description": "AND-filter list — the rule applies only when every condition matches. `null` or omitted means the rule applies to all events." }, "settings": { "type": "object", @@ -37776,7 +37689,10 @@ } ] } - } + }, + "required": [ + "kind" + ] }, "AlertPipelineItem": { "type": "object", @@ -37796,7 +37712,10 @@ }, "status": { "type": "string", - "description": "Pipeline status. Possible values: `enabled`, `disabled`." + "description": "Pipeline status. Always `enabled` in these responses — deleted pipelines are filtered out.", + "enum": [ + "enabled" + ] }, "creator_id": { "type": "integer", @@ -37817,6 +37736,11 @@ "type": "integer", "format": "int64", "description": "Last update timestamp, Unix epoch seconds." + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "Soft-delete time, Unix epoch seconds. Omitted when not deleted." } } }, @@ -37832,7 +37756,8 @@ "type": "integer", "format": "int64" }, - "description": "Integration IDs." + "description": "Integration IDs. At least one entry is required.", + "minItems": 1 } } }, @@ -37865,8 +37790,9 @@ "items": { "$ref": "#/components/schemas/AlertPipeline" }, - "description": "Rules to apply. Max 50.", - "maxItems": 50 + "description": "Rules to apply, evaluated in array order. Between 1 and 50 entries.", + "maxItems": 50, + "minItems": 1 } } }, @@ -37875,27 +37801,46 @@ "description": "Filter and pagination criteria for the global raw event list.", "properties": { "start_time": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "Start of search window, Unix epoch seconds." + "description": "Start of the search window, Unix epoch seconds. Must be greater than 0 when provided.", + "exclusiveMinimum": 0 }, "end_time": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "End of search window, Unix epoch seconds." + "description": "End of the search window, Unix epoch seconds. Must be greater than `start_time` when provided." }, "p": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "Page number, starting at 1. Used when `search_after_ctx` is not provided." + "description": "Page number, starting at 1. Used when `search_after_ctx` is not provided.", + "minimum": 0 }, "limit": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "Page size, max 100, default 20." + "description": "Page size, max 100, default 20.", + "minimum": 0, + "maximum": 100 }, "search_after_ctx": { - "type": "string", + "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": { @@ -37919,11 +37864,12 @@ "type": "integer", "format": "int64" }, - "description": "Filter by channel IDs. Max 100." + "description": "Filter by channel IDs. At most 100 entries.", + "maxItems": 100 }, "severities": { "type": "string", - "description": "Comma-separated severity filter, e.g. `Critical,Warning`." + "description": "Comma-separated severity filter, e.g. `Critical,Warning`. Accepted values: `Critical`, `Warning`, `Info`, `Ok`." }, "orderby": { "type": "string", @@ -37952,7 +37898,7 @@ }, "search_after_ctx": { "type": "string", - "description": "Cursor for the next page — the ObjectID of the last event on this page; pass it back as `search_after_ctx`. Omitted when there are no more results or the result is empty." + "description": "Cursor for the next page — the ObjectID of the last event 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", @@ -38126,7 +38072,8 @@ }, "total": { "type": "integer", - "description": "Total number of matching records." + "description": "Total number of matching records.", + "format": "int64" }, "search_after_ctx": { "type": "string", @@ -38161,11 +38108,15 @@ }, "webhook_type": { "type": "string", - "description": "Source object kind. `incident` or `alert`." + "description": "Source object kind: `incident` or `alert`.", + "enum": [ + "incident", + "alert" + ] }, "event_type": { "type": "string", - "description": "Event type (e.g. `created`, `acknowledged`, `closed`)." + "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)." }, "channel_id": { "type": "integer", @@ -38222,7 +38173,7 @@ }, "event_time": { "type": "string", - "description": "Event time as a formatted timestamp string." + "description": "Event time formatted as `YYYY-MM-DD HH:MM:SS.ffffff`." } } }, @@ -38248,7 +38199,7 @@ }, "WebhookHistoryDetail": { "type": "object", - "description": "Full detail for a webhook delivery attempt. Extends `WebhookHistoryItem` with human-friendly reference metadata resolved at query time.", + "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", @@ -38273,11 +38224,15 @@ }, "webhook_type": { "type": "string", - "description": "Source object kind. `incident` or `alert`." + "description": "Source object kind: `incident` or `alert`.", + "enum": [ + "incident", + "alert" + ] }, "event_type": { "type": "string", - "description": "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)." }, "channel_id": { "type": "integer", @@ -38334,7 +38289,7 @@ }, "event_time": { "type": "string", - "description": "Event time as a formatted timestamp string." + "description": "Event time formatted as `YYYY-MM-DD HH:MM:SS.ffffff`." }, "ref_title": { "type": "string", @@ -38353,19 +38308,23 @@ }, "ScheduleSelfRequest": { "type": "object", - "description": "Query parameters for listing the current user's schedules. Both start and end are Unix timestamps (seconds). If omitted they default to 0. The window must not exceed 30 days.", + "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.", "properties": { "start": { "type": "integer", "format": "int64", - "description": "Window start (Unix seconds, 10 digits)." + "description": "Window start (Unix seconds, 10 digits). Required." }, "end": { "type": "integer", "format": "int64", - "description": "Window end (Unix seconds, 10 digits). Must be within 30 days of start." + "description": "Window end (Unix seconds, 10 digits). Required. Must be within 45 days of start." } - } + }, + "required": [ + "start", + "end" + ] }, "ScheduleIDResponse": { "type": "object", @@ -38452,7 +38411,8 @@ "role_id": { "type": "integer", "format": "int64", - "description": "Oncall role ID." + "description": "Oncall role ID.", + "minimum": 0 }, "person_ids": { "type": "array", @@ -38460,7 +38420,8 @@ "type": "integer", "format": "int64" }, - "description": "Person IDs in this slot." + "description": "Person IDs in this slot.", + "minItems": 1 } } }, @@ -38476,8 +38437,11 @@ ], "properties": { "group_name": { - "type": "string", - "description": "Group display name." + "type": [ + "string", + "null" + ], + "description": "Group display name. Null when only the legacy name is set." }, "name": { "type": "string", @@ -38504,7 +38468,7 @@ }, "ScheduleRestrictPeriod": { "type": "object", - "description": "Restrict window inside a rotation cycle.", + "description": "Restrict window inside a rotation cycle. restrict_start and restrict_end are second offsets and cannot be equal unless both are 0.", "required": [ "restrict_start", "restrict_end" @@ -38527,11 +38491,16 @@ "description": "Day-of-week mask for a rotation layer.", "properties": { "repeat": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { - "type": "integer" + "type": "integer", + "minimum": 0, + "maximum": 6 }, - "description": "Weekday numbers (0 = Sunday) included in the rotation." + "description": "Weekday numbers (0 = Sunday) included in the rotation. Conflicts with restrict_mode = 2 (week)." } } }, @@ -38596,11 +38565,14 @@ "description": "Layer weight for ordering." }, "groups": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleGroup" }, - "description": "Oncall groups participating in the rotation." + "description": "Oncall groups participating in the rotation. Null when not set." }, "rotation_duration": { "type": "integer", @@ -38610,7 +38582,7 @@ "handoff_time": { "type": "integer", "format": "int64", - "description": "Rotation handoff time, as a Unix timestamp in seconds." + "description": "Rotation handoff time as a weekly offset in seconds (weekday x 86400 + seconds since midnight), not an absolute Unix timestamp." }, "enable_time": { "type": "integer", @@ -38642,11 +38614,14 @@ "description": "Legacy end offset inside the restriction window (seconds)." }, "restrict_periods": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleRestrictPeriod" }, - "description": "Restriction windows inside each rotation cycle." + "description": "Restriction windows inside each rotation cycle. Null when not set." }, "day_mask": { "$ref": "#/components/schemas/ScheduleDayMask", @@ -38673,17 +38648,23 @@ "description": "Last updater person ID." }, "layer_name": { - "type": "string", - "description": "User-facing layer name." + "type": [ + "string", + "null" + ], + "description": "User-facing layer name. Null when not set." }, "fair_rotation": { "type": "boolean", "description": "Whether fair rotation is enabled." }, "layer_start": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "Layer start timestamp (Unix seconds)." + "description": "Layer effective start (Unix seconds). Null when not set." }, "layer_end": { "type": [ @@ -38706,7 +38687,8 @@ "rotation_value": { "type": "integer", "format": "int64", - "description": "Rotation quantity (number of rotation_unit per cycle)." + "description": "Rotation quantity (number of rotation_unit per cycle).", + "minimum": 0 }, "mask_continuous_enabled": { "type": "boolean", @@ -38769,7 +38751,8 @@ "description": "IM provider type (for example feishu_app, dingtalk_app, wecom_app, teams_app, slack_app)." }, "settings": { - "$ref": "#/components/schemas/ScheduleImNotifySettings" + "$ref": "#/components/schemas/ScheduleImNotifySettings", + "description": "Webhook channel settings." } } }, @@ -38783,11 +38766,14 @@ "properties": { "cycle": { "type": "string", - "description": "Notification cycle." + "description": "Notification cycle; only `day` is supported.", + "enum": [ + "day" + ] }, "start": { "type": "string", - "description": "Notification start time within the cycle." + "description": "Time of day to send, format `HH:MM` (24-hour)." } } }, @@ -38830,10 +38816,12 @@ "description": "Advance notification lead time in seconds. `0` notifies exactly at shift start; omitting disables advance notification." }, "fixed_time": { - "$ref": "#/components/schemas/ScheduleFixedTimeNotifyInfo" + "$ref": "#/components/schemas/ScheduleFixedTimeNotifyInfo", + "description": "Fixed-time notification config; null when not configured." }, "by": { - "$ref": "#/components/schemas/ScheduleNotifyBy" + "$ref": "#/components/schemas/ScheduleNotifyBy", + "description": "Recipient notification preference; null when not configured." }, "im": { "type": "object", @@ -38843,11 +38831,14 @@ "description": "Legacy IM-type to token map." }, "webhooks": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleImNotify" }, - "description": "IM webhook notification channels." + "description": "IM webhook notification channels; null when not configured." } } }, @@ -38872,7 +38863,8 @@ "description": "Shift end timestamp (Unix seconds)." }, "group": { - "$ref": "#/components/schemas/ScheduleGroup" + "$ref": "#/components/schemas/ScheduleGroup", + "description": "Oncall group covering the shift; null marks a coverage gap." }, "index": { "type": "integer", @@ -38903,11 +38895,14 @@ "description": "Layer mode: 0 = common rotation, 1 = override." }, "schedules": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleCalculatedSchedule" }, - "description": "Computed shifts." + "description": "Computed shifts; null when the layer produces none." } } }, @@ -38934,7 +38929,8 @@ "description": "Shift end timestamp (Unix seconds)." }, "group": { - "$ref": "#/components/schemas/ScheduleGroup" + "$ref": "#/components/schemas/ScheduleGroup", + "description": "Oncall group on duty for the shift." }, "update_at": { "type": "integer", @@ -39034,22 +39030,28 @@ "description": "Last updater person ID." }, "layers": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleLayer" }, - "description": "Rotation layers defined on the schedule." + "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", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleCalculatedLayer" }, - "description": "Computed layers for the requested window." + "description": "Computed per-layer schedules for the requested window. Null when not computed." }, "final_schedule": { "$ref": "#/components/schemas/ScheduleCalculatedLayer", @@ -39058,20 +39060,24 @@ "start": { "type": "integer", "format": "int64", - "description": "Window start (Unix seconds)." + "description": "Window start (Unix seconds). Omitted when 0 (no window requested)." }, "end": { "type": "integer", "format": "int64", - "description": "Window end (Unix seconds)." + "description": "Window end (Unix seconds). Omitted when 0 (no window requested)." }, "notify": { - "$ref": "#/components/schemas/ScheduleNotify" + "$ref": "#/components/schemas/ScheduleNotify", + "description": "Notification configuration. Null when the schedule has none." }, "schedule_id": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "Schedule ID." + "description": "Schedule ID. Null when returned from `/schedule/preview`." }, "schedule_name": { "type": [ @@ -39096,11 +39102,14 @@ "description": "Schedule description. null when returned from /schedule/preview." }, "layer_schedules": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleCalculatedLayer" }, - "description": "Alias of schedule_layers returned for compatibility." + "description": "Alias of schedule_layers returned for compatibility. Null when not computed." }, "status": { "type": [ @@ -39121,7 +39130,7 @@ }, "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. For update, set schedule_id. For preview, start and end are required.", + "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.", "properties": { "schedule_id": { "type": [ @@ -39183,6 +39192,13 @@ "type": "integer", "format": "int64", "description": "Preview window end (Unix seconds, 10 digits). Required for /schedule/preview. Max 45 days after start." + }, + "disabled": { + "type": [ + "integer", + "null" + ], + "description": "0 = enabled, 1 = disabled. Defaults to enabled when omitted." } } }, @@ -39192,7 +39208,7 @@ "properties": { "query": { "type": "string", - "description": "Search keyword matched against schedule names." + "description": "Search keyword matched against schedule name or description." }, "p": { "type": "integer", @@ -39242,11 +39258,14 @@ ], "properties": { "items": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleItem" }, - "description": "Schedules on this page." + "description": "Schedules on this page; null when no schedule matches." }, "total": { "type": "integer", @@ -39263,11 +39282,14 @@ ], "properties": { "items": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleItem" }, - "description": "Schedules assigned to the current user (or matching the requested IDs)." + "description": "Schedules assigned to the current user (or matching the requested IDs); null when none." } } }, @@ -39301,7 +39323,7 @@ }, "team_id": { "type": "integer", - "format": "int64", + "format": "uint64", "description": "Owning team ID. 0 means no team." }, "workdays": { @@ -39380,7 +39402,7 @@ "integer", "null" ], - "format": "int64", + "format": "uint64", "description": "New owning team ID; obtain it from `POST /team/list`." }, "workdays": { @@ -39474,14 +39496,14 @@ "minimum": 0, "maximum": 6 }, - "description": "Workday numbers (0 = Sunday, 6 = Saturday)." + "description": "Workday numbers (0 = Sunday, 6 = Saturday). Omitted when empty." }, "extra_cal_ids": { "type": "array", "items": { "type": "string" }, - "description": "Inherited public-holiday calendar IDs." + "description": "Inherited public-holiday calendar IDs. Omitted when empty." }, "created_at": { "type": "integer", @@ -39548,7 +39570,8 @@ }, "total": { "type": "integer", - "description": "Total number of calendars returned." + "description": "Total number of calendars returned.", + "format": "int64" } } }, @@ -39592,10 +39615,7 @@ "description": "Event end date in YYYY-MM-DD (exclusive)." }, "is_off": { - "type": [ - "boolean", - "null" - ], + "type": "boolean", "description": "Whether the event marks a non-working day. true = day off, false = working day override." } } @@ -39753,7 +39773,8 @@ }, "total": { "type": "integer", - "description": "Total number of events returned." + "description": "Total number of events returned.", + "format": "int64" } } }, @@ -39785,7 +39806,8 @@ "creator_id", "updated_by", "created_at", - "updated_at" + "updated_at", + "incident_card_hidden_fields" ], "properties": { "account_id": { @@ -39873,7 +39895,8 @@ "description": "Zoom bot message template source." }, "incident_card_hidden_fields": { - "$ref": "#/components/schemas/IncidentCardHiddenFields" + "$ref": "#/components/schemas/IncidentCardHiddenFields", + "description": "Incident card fields hidden per IM app type; an empty object when none are configured." }, "status": { "type": "string", @@ -39920,10 +39943,11 @@ "template_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", - "description": "Target template ID. Pass `000000000000000000000001` to address the built-in preset.", + "description": "Target template ID. Pass `6321aad26c12104586a88916` to address the built-in preset.", "example": "6605a1b2c3d4e5f6a7b8c9d0" } - } + }, + "description": "Request body carrying a template ID." }, "TemplateListRequest": { "type": "object", @@ -39996,7 +40020,7 @@ "total": { "type": "integer", "format": "int64", - "description": "Total number of templates matching the filter, across all pages.", + "description": "Total number of templates matching the filter, across all pages (including the built-in preset template).", "example": 47 }, "has_next_page": { @@ -40123,7 +40147,8 @@ "description": "Template name echoed from the request.", "example": "Prod incident default" } - } + }, + "description": "Create template response." }, "TemplateUpdateRequest": { "type": "object", @@ -40272,10 +40297,6 @@ } } }, - "CsvFileResponse": { - "type": "string", - "description": "CSV file content returned as an attachment download." - }, "EnrichmentInfoRequest": { "type": "object", "required": [ @@ -40302,7 +40323,8 @@ "type": "integer", "format": "int64" }, - "description": "List of integration IDs to query." + "description": "List of integration IDs to query. Must contain at least one ID.", + "minItems": 1 } } }, @@ -40343,14 +40365,17 @@ "mapping", "drop" ], - "description": "Rule type. `extraction` extracts a label via regex or GJson. `composition` builds a label from a template. `mapping` looks up values from a schema or API. `drop` removes labels." + "description": "Rule type.\n| Value | Meaning |\n|---|---|\n| `extraction` | Extract a value from the alert's `title`, `description`, or a `labels.*` key via regex or GJson, and write it to a label. |\n| `composition` | Render a Go `text/template` against the event and write the result to a label. |\n| `mapping` | Look up labels from a mapping schema or an external mapping API. |\n| `drop` | Remove the listed labels from the alert. |" }, "if": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/EnrichFilter" }, - "description": "Optional AND-filter list. The rule is skipped if the condition does not match." + "description": "Optional AND-filter list; the rule is skipped unless every filter matches. `null` when the rule has no condition. Filter keys come from the alert/change event vocabulary (e.g. `title`, `labels.severity`)." }, "settings": { "description": "Rule-kind–specific settings. The shape depends on `kind`.", @@ -40394,11 +40419,12 @@ }, "result_label": { "type": "string", - "description": "Destination label key to write the extracted value into. Must match `^[a-z][a-z0-9_]{0,62}$`." + "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": { "type": "string", - "description": "RE2 regular expression. Use a named capture group `(?P...)` to extract a sub-match; without a named group the full match is used. Mutually exclusive with `g_json`." + "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`." }, "g_json": { "type": "string", @@ -40420,12 +40446,14 @@ "properties": { "result_label": { "type": "string", - "description": "Destination label key to write the composed value into. Must match `^[a-z][a-z0-9_]{0,62}$`." + "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_]*$" }, "template": { "type": "string", "maxLength": 500, - "description": "Go `text/template` string. Alert fields are available as `{{.title}}`, `{{.description}}`, and `{{.labels.key}}`. Example: `{{.labels.region}}-{{.labels.env}}`." + "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", @@ -40443,9 +40471,10 @@ "result_labels": { "type": "array", "items": { - "type": "string" + "type": "string", + "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, - "description": "Label keys to populate from the mapping lookup result." + "description": "Label keys to populate from the mapping lookup result. Each must match `^[a-zA-Z_][a-zA-Z0-9_]*$`." }, "mapping_type": { "type": "string", @@ -40497,7 +40526,8 @@ "properties": { "key": { "type": "string", - "description": "Alert label key." + "description": "Event key to match on (e.g. `labels.severity`, `title`). Must be non-empty.", + "minLength": 1 }, "oper": { "type": "string", @@ -40512,7 +40542,8 @@ "items": { "type": "string" }, - "description": "Values to match against." + "description": "Values to match against. Must contain at least one value.", + "minItems": 1 } } }, @@ -40534,7 +40565,11 @@ }, "status": { "type": "string", - "description": "Rule set status." + "enum": [ + "enabled", + "deleted" + ], + "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", @@ -40555,6 +40590,11 @@ "type": "integer", "format": "int64", "description": "Last update timestamp, Unix seconds." + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "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": [ @@ -40620,18 +40660,22 @@ "source_labels": { "type": "array", "items": { - "type": "string" + "type": "string", + "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "maxItems": 3, - "description": "Lookup key label names (1–3). Must not overlap with `result_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`.", + "uniqueItems": true }, "result_labels": { "type": "array", "items": { - "type": "string" + "type": "string", + "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "maxItems": 10, - "description": "Output label names (1–10). Must not overlap with `source_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`.", + "uniqueItems": true } } }, @@ -40720,7 +40764,11 @@ }, "status": { "type": "string", - "description": "Schema status." + "enum": [ + "enabled", + "deleted" + ], + "description": "Schema status: `enabled` or `deleted` (soft-deleted). The list endpoint excludes `deleted` items; the info endpoint may return them." }, "team_id": { "type": "integer", @@ -40740,12 +40788,17 @@ "created_at": { "type": "integer", "format": "int64", - "description": "Creation timestamp, Unix seconds." + "description": "Creation time, Unix seconds. Omitted when 0 (legacy records)." }, "updated_at": { "type": "integer", "format": "int64", - "description": "Last update timestamp, Unix seconds." + "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": [ @@ -40795,7 +40848,7 @@ "additionalProperties": { "type": "string" }, - "description": "Exact-match filter on source label values. All source labels must be provided if any are specified." + "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": { "type": "string", @@ -40803,25 +40856,37 @@ "created_at", "updated_at" ], - "description": "Sort field." + "description": "Sort field. Defaults to `updated_at`." }, "asc": { "type": "boolean", "description": "Sort ascending when `true`." }, "p": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "Page number (1-based). Used for offset-based pagination." + "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 }, "limit": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "Page size (1–100, default 20)." + "description": "Page size (0–100); defaults to 20 when omitted, `null`, or 0.", + "minimum": 0, + "maximum": 100 }, "search_after_ctx": { - "type": "string", - "description": "Opaque cursor token for cursor-based pagination." + "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." } } }, @@ -40831,24 +40896,24 @@ "properties": { "key": { "type": "string", - "description": "Composite key derived from source label values." + "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 for this row." + "description": "All label key-value pairs of this row. Omitted when empty." }, "created_at": { "type": "integer", "format": "int64", - "description": "Creation timestamp, Unix seconds." + "description": "Creation time, Unix seconds. Omitted when 0." }, "updated_at": { "type": "integer", "format": "int64", - "description": "Last update timestamp, Unix seconds." + "description": "Last update time, Unix seconds. Omitted when 0." } } }, @@ -40873,7 +40938,7 @@ }, "search_after_ctx": { "type": "string", - "description": "Cursor token for the next page." + "description": "Cursor token (ObjectID hex of this page's last row) for fetching the next page. Omitted when there is no next page." } }, "required": [ @@ -40902,7 +40967,7 @@ } }, "maxItems": 1000, - "description": "Rows to insert or update. Each row must include all source and result labels." + "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." } } }, @@ -40942,21 +41007,6 @@ } } }, - "MappingDataUploadRequest": { - "type": "object", - "description": "Multipart form-data upload request. `schema_id` is passed as a query parameter; `file` is the CSV file field.", - "properties": { - "schema_id": { - "type": "string", - "description": "Mapping schema ID (passed as a query parameter); obtain it from `POST /enrichment/mapping/schema/list`." - }, - "file": { - "type": "string", - "format": "binary", - "description": "CSV file to upload." - } - } - }, "MappingAPIIDRequest": { "type": "object", "required": [ @@ -40983,7 +41033,7 @@ }, "description": { "type": "string", - "description": "Optional description." + "description": "Optional description. Values longer than 500 characters are silently truncated." }, "url": { "type": "string", @@ -41000,15 +41050,19 @@ "additionalProperties": { "type": "string" }, - "description": "Custom HTTP request headers." + "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." }, "timeout": { "type": "integer", - "description": "Request timeout in seconds (1–3). Default 2." + "description": "Request timeout in seconds (1–3). Default 2.", + "minimum": 1, + "maximum": 3 }, "retry_count": { "type": "integer", - "description": "Number of retries on failure (0–1). Default 0." + "description": "Number of retries on failure (0–1). Default 0.", + "minimum": 0, + "maximum": 1 }, "team_id": { "type": "integer", @@ -41080,21 +41134,25 @@ "additionalProperties": { "type": "string" }, - "description": "New headers map (replaces existing)." + "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." }, "timeout": { "type": [ "integer", "null" ], - "description": "New timeout in seconds." + "description": "New timeout in seconds.", + "minimum": 1, + "maximum": 3 }, "retry_count": { "type": [ "integer", "null" ], - "description": "New retry count." + "description": "New retry count.", + "minimum": 0, + "maximum": 1 }, "team_id": { "type": [ @@ -41127,11 +41185,14 @@ "description": "Endpoint URL." }, "headers": { - "type": "object", + "type": [ + "object", + "null" + ], "additionalProperties": { "type": "string" }, - "description": "Custom request headers." + "description": "Custom request headers. `null` when none are configured." }, "timeout": { "type": "integer", @@ -41147,7 +41208,11 @@ }, "status": { "type": "string", - "description": "API status." + "enum": [ + "enabled", + "deleted" + ], + "description": "API status: `enabled` or `deleted` (soft-deleted). The list endpoint excludes `deleted` items; the info endpoint may return them." }, "team_id": { "type": "integer", @@ -41167,12 +41232,17 @@ "created_at": { "type": "integer", "format": "int64", - "description": "Creation timestamp, Unix seconds." + "description": "Creation time, Unix seconds. Omitted when 0 (legacy records)." }, "updated_at": { "type": "integer", "format": "int64", - "description": "Last update timestamp, Unix seconds." + "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": [ @@ -41221,7 +41291,8 @@ "start_time": { "type": "integer", "format": "int64", - "description": "Start time, Unix seconds. Must be greater than 0." + "description": "Start time, Unix seconds. Must be greater than 0.", + "exclusiveMinimum": 0 }, "end_time": { "type": "integer", @@ -41234,7 +41305,8 @@ "type": "integer", "format": "int64" }, - "description": "Filter by team IDs. At most 100 entries." + "description": "Filter by team IDs. At most 100 entries.", + "maxItems": 100 }, "channel_ids": { "type": "array", @@ -41242,7 +41314,8 @@ "type": "integer", "format": "int64" }, - "description": "Filter by channel IDs. At most 100 entries." + "description": "Filter by channel IDs. At most 100 entries.", + "maxItems": 100 }, "responder_ids": { "type": "array", @@ -41250,7 +41323,8 @@ "type": "integer", "format": "int64" }, - "description": "Filter by responder person IDs. At most 100 entries." + "description": "Filter by responder person IDs. At most 100 entries.", + "maxItems": 100 }, "severities": { "type": "array", @@ -41263,7 +41337,8 @@ "Ok" ] }, - "description": "Filter by severity. At most 3 entries." + "description": "Filter by severity. At most 3 entries.", + "maxItems": 3 }, "incident_ids": { "type": "array", @@ -41271,11 +41346,12 @@ "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, - "description": "Filter by incident IDs (MongoDB ObjectIDs). At most 100 entries." + "description": "Filter by incident IDs (MongoDB ObjectIDs). At most 100 entries.", + "maxItems": 100 }, "query": { "type": "string", - "description": "Full-text query applied to incident title and description." + "description": "Substring match on the incident title (SQL `LIKE %query%`)." }, "labels": { "type": "object", @@ -41294,11 +41370,11 @@ "enum": [ "created_at" ], - "description": "Sort field of the underlying incident set. Currently only `created_at` (incident creation time) is supported." + "description": "Sort field of the incident list; only `created_at` (incident creation time) is supported. Used by `/insight/incident/list` only." }, "asc": { "type": "boolean", - "description": "Sort ascending when `true`, descending otherwise." + "description": "Sort ascending when `true`, descending otherwise. Only used by `/insight/incident/list`." }, "is_my_team": { "type": "boolean", @@ -41306,65 +41382,39 @@ }, "time_zone": { "type": "string", - "description": "IANA time zone name used to interpret the time range (e.g. `Asia/Shanghai`). Defaults to the account 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`." }, "seconds_to_close_from": { "type": "integer", "format": "int64", - "description": "Lower bound (inclusive) on time-to-close, in seconds." + "description": "Lower bound (inclusive) on time-to-close, in seconds.", + "minimum": 0 }, "seconds_to_close_to": { "type": "integer", "format": "int64", - "description": "Upper bound (exclusive) on time-to-close, in seconds. Must be greater than `seconds_to_close_from` when both are set." + "description": "Upper bound (exclusive) on time-to-close, in seconds. Must be greater than `seconds_to_close_from` when both are set.", + "minimum": 0 }, "seconds_to_ack_from": { "type": "integer", "format": "int64", - "description": "Lower bound (inclusive) on time-to-acknowledge, in seconds." + "description": "Lower bound (inclusive) on time-to-acknowledge, in seconds.", + "minimum": 0 }, "seconds_to_ack_to": { "type": "integer", "format": "int64", - "description": "Upper bound (exclusive) on time-to-acknowledge, in seconds. Must be greater than `seconds_to_ack_from` when both are set." + "description": "Upper bound (exclusive) on time-to-acknowledge, in seconds. Must be greater than `seconds_to_ack_from` when both are set.", + "minimum": 0 }, "export_fields": { "type": "array", "items": { - "type": "string", - "enum": [ - "incident_id", - "title", - "severity", - "progress", - "channel_id", - "channel_name", - "team_id", - "team_name", - "created_at", - "seconds_to_ack", - "seconds_to_close", - "closed_by", - "engaged_seconds", - "hours", - "notifications", - "interruptions", - "acknowledgements", - "assignments", - "reassignments", - "escalations", - "manual_escalations", - "timeout_escalations", - "assigned_to", - "responders", - "description", - "labels", - "fields", - "creator_id", - "creator_name" - ] + "type": "string" }, - "description": "Subset of CSV column keys to include in the export. At most 50 entries. Only used by the export endpoints." + "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 }, "description_html_to_text": { "type": "boolean", @@ -41412,21 +41462,30 @@ "description": "Paged incident list request. Extends InsightFilter with pagination.", "properties": { "p": { - "type": "integer", - "minimum": 1, + "type": [ + "integer", + "null" + ], + "minimum": 0, "default": 1, - "description": "Page number, starting at 1. Defaults to 1." + "description": "Page number, starting at 1. Used when `search_after_ctx` is not provided; `p * limit` must stay within 10,000 records." }, "limit": { - "type": "integer", - "minimum": 1, + "type": [ + "integer", + "null" + ], + "minimum": 0, "maximum": 100, "default": 20, - "description": "Page size, between 1 and 100. Defaults to 20." + "description": "Page size, max 100, default 20." }, "search_after_ctx": { - "type": "string", - "description": "Cursor token returned by a previous page. Pass it back to fetch the next page." + "type": [ + "string", + "null" + ], + "description": "Cursor token returned by a previous page (the incident ID of its last row). Pass it back to fetch the next page." } } } @@ -41456,7 +41515,10 @@ }, "k": { "type": "integer", - "description": "Number of top entries to return, between 1 and 100." + "description": "Number of top entries to return, between 1 and 100. Defaults to 20.", + "minimum": 1, + "maximum": 100, + "default": 20 }, "orderby": { "type": "string", @@ -41464,7 +41526,7 @@ "total_alert_cnt", "total_alert_event_cnt" ], - "description": "Sort field. `total_alert_cnt` sorts by alert count; `total_alert_event_cnt` sorts by raw alert event count." + "description": "Sort field. `total_alert_cnt` sorts by alert count; `total_alert_event_cnt` sorts by raw alert event count (default)." }, "asc": { "type": "boolean", @@ -41485,12 +41547,12 @@ "sleep", "off" ], - "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`)." + "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." }, "ts": { "type": "integer", "format": "int64", - "description": "Aggregation bucket start time, Unix seconds. Present when `aggregate_unit` is used." + "description": "Start of the aggregation bucket, Unix epoch seconds. Equals `start_time` when no `aggregate_unit` is given." }, "channel_id": { "type": "integer", @@ -41608,22 +41670,22 @@ "mean_seconds_to_ack": { "type": "number", "format": "double", - "description": "Mean time to first acknowledgement in seconds." + "description": "Mean time to first acknowledgement in seconds; 0 when no incident in the bucket was acknowledged." }, "mean_seconds_to_close": { "type": "number", "format": "double", - "description": "Mean time to close in seconds." + "description": "Mean time to close in seconds; 0 when no incident in the bucket was closed." }, "noise_reduction_pct": { "type": "number", "format": "double", - "description": "Noise reduction ratio (%): `100 − incidents ÷ alert events × 100`; 0 when no alert-event comparison data exists." + "description": "Noise reduction ratio (%): 100 − incidents ÷ alert events × 100, rounded to two decimals; 0 when there is no alert-event data or alert events do not exceed incidents." }, "acknowledgement_pct": { "type": "number", "format": "double", - "description": "Acknowledgement rate (%): acknowledged incidents ÷ total incidents × 100, rounded to two decimals; 100 when there are no incidents." + "description": "Acknowledgement rate (%): acknowledged incidents ÷ total incidents × 100, rounded to two decimals and capped at 100; 0 when the bucket has no incidents." }, "total_alert_cnt": { "type": "integer", @@ -41701,12 +41763,12 @@ "mean_seconds_to_ack": { "type": "number", "format": "double", - "description": "This responder's mean time to acknowledgement in seconds." + "description": "This responder's mean time to acknowledgement in seconds; 0 when the responder acknowledged nothing." }, "acknowledgement_pct": { "type": "number", "format": "double", - "description": "This responder's acknowledgement rate (%): acknowledged incidents ÷ involved incidents × 100, rounded to two decimals." + "description": "This responder's acknowledgement rate (%): acknowledged incidents ÷ involved incidents × 100, rounded to two decimals and capped at 100; 0 when the responder has no incidents." } } } @@ -41773,7 +41835,12 @@ }, "progress": { "type": "string", - "description": "Incident progress state — one of `Triggered`, `Processing`, `Closed`." + "description": "Incident progress state — one of `Triggered`, `Processing`, `Closed`.", + "enum": [ + "Triggered", + "Processing", + "Closed" + ] }, "severity": { "type": "string", @@ -41817,11 +41884,11 @@ "owner_id": { "type": "integer", "format": "int64", - "description": "Member ID of the incident owner." + "description": "Member ID of the incident owner. Omitted when 0 (no owner)." }, "owner_name": { "type": "string", - "description": "Display name of the incident owner." + "description": "Display name of the incident owner. Omitted when empty." }, "creator_id": { "type": "integer", @@ -41835,11 +41902,11 @@ "closer_id": { "type": "integer", "format": "int64", - "description": "Member ID of the person who closed the incident." + "description": "Member ID of the person who closed the incident. Omitted when 0 (not closed manually)." }, "closer_name": { "type": "string", - "description": "Display name of the person who closed the incident." + "description": "Display name of the person who closed the incident. Omitted when empty." }, "seconds_to_ack": { "type": "integer", @@ -41868,11 +41935,11 @@ "snoozed_before": { "type": "integer", "format": "int64", - "description": "Unix timestamp in seconds until which the incident is snoozed." + "description": "Unix timestamp in seconds until which the incident is snoozed. Omitted when the incident is not snoozed." }, "ever_muted": { "type": "boolean", - "description": "Whether the incident was ever muted by flapping-based noise reduction." + "description": "Whether the incident was ever muted by noise reduction. Omitted when false." }, "frequency": { "type": "string", @@ -41880,7 +41947,7 @@ "frequent", "rare" ], - "description": "Frequency classification: `frequent` or `rare`." + "description": "Frequency classification: `frequent` or `rare`. Omitted when not classified." }, "responders": { "type": "array", @@ -41919,8 +41986,11 @@ } }, "assigned_to": { - "type": "object", - "description": "Current assignment target for the incident.", + "type": [ + "object", + "null" + ], + "description": "Current assignment target for the incident; `null` when the incident has no assignment record.", "properties": { "person_ids": { "type": "array", @@ -41969,12 +42039,12 @@ "additionalProperties": { "type": "string" }, - "description": "Incident labels as key-value pairs. Omitted when empty." + "description": "Incident labels as key-value pairs. Always omitted in this response (reserved for export)." }, "fields": { "type": "object", "additionalProperties": true, - "description": "Custom fields of the incident. Omitted when empty." + "description": "Custom fields of the incident. Always omitted in this response (reserved for export)." }, "notifications": { "type": "integer", @@ -42032,7 +42102,7 @@ }, "search_after_ctx": { "type": "string", - "description": "Cursor token to fetch the next page. Pass it back in the next request's `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." }, "items": { "type": "array", @@ -42052,7 +42122,12 @@ }, "hours": { "type": "string", - "description": "Hour bucket when `split_hours` is enabled." + "description": "Hour bucket when `split_hours` is enabled: `work`, `sleep`, or `off`. Omitted when `split_hours` is false.", + "enum": [ + "work", + "sleep", + "off" + ] }, "total_alert_cnt": { "type": "integer", @@ -42095,7 +42170,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Parent status page ID." + "description": "Parent status page ID. Omitted when 0 (never for stored events)." }, "type": { "type": "string", @@ -42111,7 +42186,7 @@ }, "description": { "type": "string", - "description": "Event description (Markdown)." + "description": "Event description (Markdown). Omitted when empty." }, "status": { "type": "string", @@ -42124,14 +42199,14 @@ "ongoing", "completed" ], - "description": "Current event status. Incident statuses: `investigating`/`identified`/`monitoring`/`resolved`. Maintenance statuses: `scheduled`/`ongoing`/`completed`." + "description": "Current event status. Incident statuses: `investigating`/`identified`/`monitoring`/`resolved`. Maintenance statuses: `scheduled`/`ongoing`/`completed`. Omitted when empty (never for stored events)." }, "affected_components": { "type": "array", "items": { "$ref": "#/components/schemas/AffectedStatusPageComponentItem" }, - "description": "Components currently affected by this event, with their resulting status." + "description": "Components currently affected by this event, with their resulting status. Omitted when no components are affected." }, "responder_ids": { "type": "array", @@ -42139,43 +42214,43 @@ "type": "integer", "format": "int64" }, - "description": "Member IDs responsible for this event." + "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.)." + "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." + "description": "Event start time in Unix seconds, derived from the first timeline update. Omitted when 0." }, "close_at_seconds": { "type": "integer", "format": "int64", - "description": "Scheduled close time in unix seconds. Set for retrospective and maintenance events." + "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." + "description": "Whether this event is a retrospective (historical) one. Omitted when false." }, "updates": { "type": "array", "items": { "$ref": "#/components/schemas/StatusPageChangeUpdateItem" }, - "description": "Timeline updates attached to this event, ordered by time." + "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." + "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." + "description": "Maintenance only: whether the status advances automatically based on the scheduled window. Omitted when false." } } }, @@ -42189,11 +42264,11 @@ "properties": { "component_id": { "type": "string", - "description": "Component ID." + "description": "Component ID. Omitted when empty." }, "section_id": { "type": "string", - "description": "Parent section ID." + "description": "Parent section ID. Omitted when the component sits at the top level." }, "name": { "type": "string", @@ -42201,25 +42276,25 @@ }, "description": { "type": "string", - "description": "Component description." + "description": "Component description. Omitted when empty." }, "available_since_seconds": { "type": "integer", "format": "int64", - "description": "Timestamp when the component was first available, in unix seconds." + "description": "Time the component became available, as a Unix timestamp in seconds. Omitted when 0." }, "order_id": { "type": "integer", "format": "int64", - "description": "Display order within its section." + "description": "Display order within its section. Omitted when 0." }, "hide_uptime": { "type": "boolean", - "description": "When true, uptime data is hidden from summary responses." + "description": "When true, uptime data is hidden from summary responses. Omitted when false." }, "hide_all": { "type": "boolean", - "description": "When true, the component is hidden entirely from summary endpoints." + "description": "When true, the component is hidden entirely from summary endpoints. Omitted when false." }, "status": { "type": "string", @@ -42249,7 +42324,7 @@ "at_seconds": { "type": "integer", "format": "int64", - "description": "Update timestamp in unix seconds." + "description": "Update timestamp in Unix seconds." }, "status": { "type": "string", @@ -42266,14 +42341,14 @@ }, "description": { "type": "string", - "description": "Update description (Markdown)." + "description": "Update description (Markdown). Omitted when empty." }, "component_changes": { "type": "array", "items": { "$ref": "#/components/schemas/StatusPageComponentChangeItem" }, - "description": "Component status transitions applied by this update." + "description": "Component status transitions applied by this update. Omitted when the update changes no component statuses." } } }, @@ -42291,7 +42366,7 @@ }, "component_name": { "type": "string", - "description": "Component display name. Populated by the backend on read; ignored on write." + "description": "Component display name. Populated by the backend on read; ignored on write. Omitted when empty." }, "status": { "type": "string", @@ -42352,12 +42427,12 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "change_id": { "type": "integer", "format": "int64", - "description": "Target change ID; obtain it from `POST /status-page/change/list`." + "description": "Target change ID; obtain it from `GET /status-page/change/list`." }, "title": { "type": [ @@ -42395,12 +42470,12 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "change_id": { "type": "integer", "format": "int64", - "description": "Target change ID; obtain it from `POST /status-page/change/list`." + "description": "Target change ID; obtain it from `GET /status-page/change/list`." } } }, @@ -42419,7 +42494,7 @@ }, "UpdateStatusPageChangeTimelineRequest": { "type": "object", - "description": "Parameters for updating an existing timeline entry on a status page event.", + "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", @@ -42429,21 +42504,21 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "change_id": { "type": "integer", "format": "int64", - "description": "Owning change ID; obtain it from `POST /status-page/change/list`." + "description": "Owning change ID; obtain it from `GET /status-page/change/list`." }, "update_id": { "type": "string", - "description": "Target timeline update ID; obtain it from `POST /status-page/change/info`." + "description": "Target timeline update ID; obtain it from `GET /status-page/change/info`." }, "at_seconds": { "type": "integer", "format": "int64", - "description": "New update timestamp in unix seconds." + "description": "New update timestamp in Unix seconds." }, "description": { "type": "string", @@ -42463,16 +42538,16 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "change_id": { "type": "integer", "format": "int64", - "description": "Owning change ID; obtain it from `POST /status-page/change/list`." + "description": "Owning change ID; obtain it from `GET /status-page/change/list`." }, "update_id": { "type": "string", - "description": "Timeline update ID to delete; obtain it from `POST /status-page/change/info`." + "description": "Timeline update ID to delete; obtain it from `GET /status-page/change/info`." } } }, @@ -42538,7 +42613,7 @@ }, "locale": { "type": "string", - "description": "Preferred locale for notifications." + "description": "Preferred locale for notifications. Omitted when empty." } } }, @@ -42551,11 +42626,11 @@ "properties": { "component_id": { "type": "string", - "description": "Component ID." + "description": "Component ID. Omitted when empty." }, "section_id": { "type": "string", - "description": "Parent section ID." + "description": "Parent section ID. Omitted when the component sits at the top level." }, "name": { "type": "string", @@ -42563,25 +42638,25 @@ }, "description": { "type": "string", - "description": "Component description." + "description": "Component description. Omitted when empty." }, "available_since_seconds": { "type": "integer", "format": "int64", - "description": "Timestamp when the component was first available, in unix seconds." + "description": "Time the component became available, as a Unix timestamp in seconds. Omitted when 0." }, "order_id": { "type": "integer", "format": "int64", - "description": "Display order within its section." + "description": "Display order within its section. Omitted when 0." }, "hide_uptime": { "type": "boolean", - "description": "When true, uptime data is hidden from summary responses." + "description": "When true, uptime data is hidden from summary responses. Omitted when false." }, "hide_all": { "type": "boolean", - "description": "When true, the component is hidden entirely from summary endpoints." + "description": "When true, the component is hidden entirely from summary endpoints. Omitted when false." } } }, @@ -42596,7 +42671,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Target status page ID; obtain it from `POST /status-page/list`." + "description": "Target status page ID; obtain it from `GET /status-page/list`." }, "method": { "type": "string", @@ -42662,7 +42737,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "component_ids": { "type": "array", @@ -42699,7 +42774,8 @@ "string", "null" ], - "description": "Target URL name for the migrated status page. When omitted, the source page's URL name is reused." + "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 } } }, @@ -42785,13 +42861,12 @@ "status": { "type": "string", "enum": [ - "pending", "running", "completed", "failed", "cancelled" ], - "description": "Current job status.\n| Value | Meaning |\n|---|---|\n| `pending` | Created, waiting to run. |\n| `running` | In progress. |\n| `completed` | Finished successfully. |\n| `failed` | Failed; the `error` field holds the reason. |\n| `cancelled` | Canceled by request. |" + "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. |" }, "progress": { "$ref": "#/components/schemas/StatusPageMigrationProgress", @@ -42799,17 +42874,17 @@ }, "error": { "type": "string", - "description": "Terminal error message when `status` is `failed`." + "description": "Terminal error message when `status` is `failed`. Omitted when the job has not failed." }, "created_at": { "type": "integer", "format": "int64", - "description": "Job creation time, unix seconds." + "description": "Job creation time as a Unix timestamp in seconds." }, "updated_at": { "type": "integer", "format": "int64", - "description": "Last status update time, unix seconds." + "description": "Last status update time as a Unix timestamp in seconds." } } }, @@ -42869,7 +42944,7 @@ "items": { "type": "string" }, - "description": "Non-fatal warnings recorded during the job." + "description": "Non-fatal warnings recorded during the job. Omitted when empty." } } }, @@ -42882,7 +42957,7 @@ "properties": { "job_id": { "type": "string", - "description": "Migration job ID, returned when the migration job is created; check progress via `POST /status-page/migration/status`." + "description": "Migration job ID, returned when the migration job is created; check progress via `GET /status-page/migration/status`." } } }, @@ -42893,6 +42968,7 @@ "page_id", "type", "title", + "description", "status", "updates" ], @@ -42900,7 +42976,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "type": { "type": "string", @@ -42917,7 +42993,7 @@ }, "description": { "type": "string", - "description": "Event description (Markdown). Required by the validator." + "description": "Event description (Markdown). Must not be empty." }, "status": { "type": "string", @@ -42935,7 +43011,7 @@ "start_at_seconds": { "type": "integer", "format": "int64", - "description": "Event start time in unix seconds. Defaults to now when omitted." + "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`." }, "responders": { "type": "array", @@ -42943,7 +43019,7 @@ "type": "integer", "format": "int64" }, - "description": "Member IDs responsible for the change; obtain member IDs from `POST /member/list`." + "description": "Member IDs responsible for the event." }, "linked_changes": { "type": "array", @@ -42955,7 +43031,7 @@ "close_at_seconds": { "type": "integer", "format": "int64", - "description": "Scheduled close time for retrospective events. Must be greater than `start_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." }, "updates": { "type": "array", @@ -42970,10 +43046,13 @@ "at_seconds": { "type": "integer", "format": "int64", - "description": "Update timestamp in unix seconds." + "description": "Update timestamp in Unix seconds. When omitted or 0 on the first update, defaults to the current time." }, "status": { - "type": "string", + "type": [ + "string", + "null" + ], "enum": [ "investigating", "identified", @@ -42983,10 +43062,13 @@ "ongoing", "completed" ], - "description": "Change status after this update. May be omitted 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": "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", + "type": [ + "string", + "null" + ], "description": "Update description (Markdown)." }, "component_changes": { @@ -43000,7 +43082,7 @@ "properties": { "component_id": { "type": "string", - "description": "Component ID; obtain it from `POST /status-page/info`." + "description": "Component ID; obtain it from `GET /status-page/info`." }, "status": { "type": "string", @@ -43019,7 +43101,8 @@ } } }, - "description": "Timeline updates. Immediate events normally pass one update; retrospective events must pass all historical 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.", + "minItems": 1 }, "notify_subscribers": { "type": "boolean", @@ -43041,23 +43124,24 @@ "required": [ "page_id", "change_id", - "status" + "status", + "description" ], "properties": { "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "change_id": { "type": "integer", "format": "int64", - "description": "Target change ID; obtain it from `POST /status-page/change/list`." + "description": "Target change ID; obtain it from `GET /status-page/change/list`." }, "at_seconds": { "type": "integer", "format": "int64", - "description": "Update timestamp in unix seconds. Defaults to now when omitted." + "description": "Update timestamp in Unix seconds. Defaults to the current time when omitted or 0." }, "status": { "type": "string", @@ -43070,11 +43154,11 @@ "ongoing", "completed" ], - "description": "Change status after this update; must match 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| `scheduled` | Scheduled (maintenance). |\n| `ongoing` | In progress (maintenance). |" + "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": { "type": "string", - "description": "Update description (Markdown). Required." + "description": "Update description (Markdown). Must not be empty." }, "component_changes": { "type": "array", @@ -43087,7 +43171,7 @@ "properties": { "component_id": { "type": "string", - "description": "Component ID; obtain it from `POST /status-page/info`." + "description": "Component ID; obtain it from `GET /status-page/info`." }, "status": { "type": "string", @@ -43113,7 +43197,21 @@ "folder_id": { "type": "integer", "format": "uint64", - "description": "Folder ID. 0 to list all accessible rules." + "description": "Folder ID. Must be an existing folder; `0` is rejected with a `folder_not_found` error." + }, + "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." + }, + "query": { + "type": "string", + "description": "Rule name fuzzy filter; only effective when `include_descendants` is `true`." + }, + "limit": { + "type": "integer", + "default": 50, + "maximum": 100, + "description": "Max number of rules returned; only effective when `include_descendants` is `true`. Defaults to 50, capped at 100." } } }, @@ -43136,7 +43234,10 @@ "updater_name", "created_at", "updated_at", - "triggered" + "triggered", + "labels", + "timezone", + "active_alert_count" ], "properties": { "id": { @@ -43179,7 +43280,7 @@ }, "cron_pattern": { "type": "string", - "description": "5-field cron schedule, e.g. `* * * * *`. Must not start with `CRON_TZ=` or `TZ=`; use the `timezone` field instead." + "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." }, "timezone": { "type": "string", @@ -43221,6 +43322,25 @@ "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": { + "type": "string", + "enum": [ + "disabled", + "offline", + "abnormal", + "stale", + "no_datasource", + "config_pending", + "waiting", + "normal" + ], + "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. |" } } }, @@ -43344,6 +43464,20 @@ "condition": { "type": "string", "description": "Recovery condition expression; required when `mode` is `threshold` or `ql`, and must be empty for `invert`." + }, + "value_fields": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Numeric result fields the recovery `condition` references as `$A.`; same semantics as the query's `value_fields`. Omitted when empty." + }, + "args": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Datasource-specific extra parameters for the recovery query, using the same `.` key convention as query `args`. Omitted when empty." } }, "description": "Recovery evaluation configuration for threshold checks." @@ -43454,7 +43588,10 @@ } } } - } + }, + "required": [ + "queries" + ] }, "AlertRule": { "type": "object", @@ -43495,7 +43632,7 @@ "items": { "type": "string" }, - "description": "Data source name patterns (supports wildcards)." + "description": "Data source name patterns (supports wildcards). At least one of `ds_list` / `ds_ids` must be non-empty; the two are merged to decide which datasources the rule monitors." }, "ds_ids": { "type": "array", @@ -43635,7 +43772,14 @@ "format": "int64", "description": "Last update time as a Unix timestamp in seconds. Generated by the server; do not provide." } - } + }, + "required": [ + "folder_id", + "name", + "ds_type", + "cron_pattern", + "rule_configs" + ] }, "AlertRuleInfoResponse": { "allOf": [ @@ -43714,16 +43858,6 @@ "description": "Empty response on success.", "additionalProperties": false }, - "RuleFolderIDRequest": { - "type": "object", - "properties": { - "folder_id": { - "type": "integer", - "format": "uint64", - "description": "Folder ID to summarize. Obtainable via `POST /monit/folder/list`. Trigger statistics are returned grouped by direct child folder." - } - } - }, "RuleFieldsUpdateRequest": { "type": "object", "required": [ @@ -43845,6 +43979,14 @@ "type": "integer", "format": "int64", "description": "Maximum number of repeated notifications. 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." + }, + "annotations_patch": { + "$ref": "#/components/schemas/StringMapPatch", + "description": "Partial annotation update. Effective only when `fields` includes `annotations`; takes precedence over `annotations` when both are sent." } } }, @@ -43950,7 +44092,11 @@ }, "action": { "type": "string", - "description": "Action performed, e.g. `create`, `update`." + "description": "Action performed: `create` = rule created; `update` = rule updated (covers full updates, field-batch updates, imports and moves).", + "enum": [ + "create", + "update" + ] }, "content": { "type": "string", @@ -44238,7 +44384,7 @@ "properties": { "type": { "type": "string", - "description": "Filter by datasource type identifier. Omit to return all types. Allowed values: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `victorialogs`." + "description": "Filter by datasource type identifier. Omit to return all types. Allowed values: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`." } } }, @@ -44272,6 +44418,10 @@ }, "victorialogs": { "$ref": "#/components/schemas/DSVictoriaLogsConfig" + }, + "tencent_cls": { + "$ref": "#/components/schemas/DSTencentCLSConfig", + "description": "Tencent CLS credentials. Required when `type_ident` is `tencent_cls`." } } }, @@ -44782,7 +44932,8 @@ "note", "address", "edge_cluster_name", - "updated_at" + "updated_at", + "payload" ], "properties": { "id": { @@ -44797,7 +44948,7 @@ }, "type_ident": { "type": "string", - "description": "Datasource type identifier. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `victorialogs`." + "description": "Datasource type identifier. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`." }, "name": { "type": "string", @@ -44816,7 +44967,15 @@ "description": "Connection address. For Prometheus/Loki/VictoriaLogs: HTTP URL. For MySQL/Oracle/Postgres/ClickHouse: `host:port`. For SLS: endpoint without http/https prefix." }, "payload": { - "$ref": "#/components/schemas/DSPayload" + "anyOf": [ + { + "$ref": "#/components/schemas/DSPayload" + }, + { + "type": "null" + } + ], + "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." }, "edge_cluster_name": { "type": "string", @@ -44846,7 +45005,7 @@ }, "type_ident": { "type": "string", - "description": "Datasource type identifier. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `victorialogs`." + "description": "Datasource type identifier. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`." }, "name": { "type": "string", @@ -44858,7 +45017,7 @@ }, "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. Not required for Elasticsearch cloud deployment." + "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)." }, "payload": { "$ref": "#/components/schemas/DSPayload", @@ -44867,12 +45026,16 @@ "edge_cluster_name": { "type": "string", "description": "Monitors edge cluster name responsible for evaluating rules using this datasource." + }, + "enabled": { + "type": "boolean", + "description": "Whether the datasource is enabled for rule evaluation. When omitted on create, the datasource is created disabled (`false`)." } } }, "DataSourceListResponse": { "type": "array", - "description": "List of datasources. Sensitive credential fields are omitted.", + "description": "List of datasources. The `payload` column is not read by this endpoint, so `payload` is `null` in every item.", "items": { "$ref": "#/components/schemas/DataSourceItem" } @@ -44912,13 +45075,35 @@ "type": "integer", "description": "Page size. Defaults to 200 server-side when 0." } - } + }, + "required": [ + "id" + ] }, "SLSProjectsResponse": { - "type": "array", - "description": "List of SLS project names.", - "items": { - "type": "string" + "type": "object", + "description": "A page of Aliyun SLS projects.", + "required": [ + "projects", + "count", + "total" + ], + "properties": { + "projects": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SLSProject" + }, + "description": "Projects in the current page." + }, + "count": { + "type": "integer", + "description": "Number of projects in this page." + }, + "total": { + "type": "integer", + "description": "Total number of projects matching `query`, independent of pagination." + } } }, "SLSLogstoresRequest": { @@ -44942,7 +45127,10 @@ "type": "integer", "description": "Page size. Defaults to 200 server-side when 0." } - } + }, + "required": [ + "id" + ] }, "SLSLogstoresResponse": { "type": "array", @@ -44975,7 +45163,7 @@ 1, 2 ], - "description": "Sharing scope. `0` = private (creator only), `1` = account-shared, `2` = public. Defaults to `0` if omitted." + "description": "Sharing scope. `0` = private (visible to the creator and the account owner), `1` = account-shared, `2` = public. Defaults to `0` if omitted." }, "payload": { "type": "string", @@ -45018,7 +45206,7 @@ 1, 2 ], - "description": "Sharing scope. `0` = private (creator only), `1` = account-shared, `2` = public." + "description": "Sharing scope. `0` = private (visible to the creator and the account owner), `1` = account-shared, `2` = public." }, "payload": { "type": "string", @@ -45095,7 +45283,7 @@ 1, 2 ], - "description": "New sharing scope. `0` = private, `1` = account-shared, `2` = public." + "description": "New sharing scope. `0` = private (visible to the creator and the account owner), `1` = account-shared, `2` = public." }, "payload": { "type": "string", @@ -45109,11 +45297,14 @@ "properties": { "p": { "type": "integer", - "description": "Page number (1-based). Default: 1." + "description": "Page number (1-based). Default: 1.", + "minimum": 1 }, "limit": { "type": "integer", - "description": "Page size. Range: 1–100. Default: 20." + "description": "Page size. Range: 1–100. Default: 20.", + "minimum": 1, + "maximum": 100 }, "orderby": { "type": "string", @@ -45121,7 +45312,7 @@ "created_at", "updated_at" ], - "description": "Sort field; defaults to `updated_at` when omitted." + "description": "Sort field: `created_at` (creation time) or `updated_at` (last update time); defaults to `updated_at` when omitted." }, "asc": { "type": "boolean", @@ -45147,10 +45338,7 @@ "description": "Alert settings for the application.", "properties": { "enabled": { - "type": [ - "boolean", - "null" - ], + "type": "boolean", "description": "Whether alerting is enabled." }, "channel_ids": { @@ -45159,12 +45347,25 @@ "type": "integer", "format": "int64" }, - "description": "Channel IDs to send alerts to." + "description": "Channel IDs to send alerts to. Used only when `delivery_mode` is `oncall`." }, "integration_id": { "type": "integer", "format": "int64", - "description": "Associated on-call integration ID (read-only, auto-assigned)." + "description": "Associated on-call integration ID (read-only, auto-assigned on save when `delivery_mode` is `oncall`)." + }, + "delivery_mode": { + "type": "string", + "enum": [ + "oncall", + "webhook" + ], + "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)." + }, + "webhook_url": { + "type": "string", + "format": "uri", + "description": "URL that receives alert events when `delivery_mode` is `webhook`; required in that mode, ignored otherwise. Omitted when empty." } } }, @@ -45213,7 +45414,7 @@ "all" ] }, - "description": "RUM event types where this external system link is shown." + "description": "RUM event types where this external system link is shown; at least one is required.\n\n| Value | Meaning |\n|---|---|\n| `crash` | Crash events (errors flagged `is_crash`) |\n| `error` | Error events |\n| `view` | Page/screen view events |\n| `action` | User action events |\n| `resource` | Resource load events |\n| `session` | Session events |\n| `all` | All event types |" }, "enabled": { "type": "boolean", @@ -45295,7 +45496,7 @@ "harmony", "electron" ], - "description": "Application type. Platform identifier, one of `browser` (web), `ios`, `android`, `react-native`, `flutter`, `kotlin-multiplatform`, `roku`, `unity`. Note: the create API also accepts `miniprogram`, `harmony`, and `electron`, and applications of those types appear in responses too (see Enum gaps)." + "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 |" }, "client_token": { "type": "string", @@ -45319,13 +45520,16 @@ "description": "If `true`, geographic location is not inferred from IP." }, "alerting": { - "$ref": "#/components/schemas/RumApplicationAlerting" + "$ref": "#/components/schemas/RumApplicationAlerting", + "description": "Alerting configuration of the application." }, "tracing": { - "$ref": "#/components/schemas/RumApplicationTracing" + "$ref": "#/components/schemas/RumApplicationTracing", + "description": "APM tracing integration configuration." }, "links": { - "$ref": "#/components/schemas/RumApplicationLinks" + "$ref": "#/components/schemas/RumApplicationLinks", + "description": "External-link integration configuration." }, "status": { "type": "string", @@ -45404,7 +45608,8 @@ "items": { "type": "string" }, - "description": "Up to 200 application IDs. Get IDs via `POST /rum/application/list`." + "description": "Up to 200 application IDs. Get IDs via `POST /rum/application/list`.", + "maxItems": 200 } } }, @@ -45432,7 +45637,9 @@ "properties": { "application_name": { "type": "string", - "description": "Application name. 1–40 characters." + "description": "Application name. 1–40 characters.", + "minLength": 1, + "maxLength": 40 }, "type": { "type": "string", @@ -45449,12 +45656,13 @@ "harmony", "electron" ], - "description": "Application type. Platform identifier, one of `browser` (web), `ios`, `android`, `react-native`, `flutter`, `kotlin-multiplatform`, `roku`, `unity`, `miniprogram` (WeChat mini program), `harmony` (HarmonyOS), `electron`." + "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 |" }, "team_id": { "type": "integer", "format": "int64", - "description": "Owning team ID. Get team IDs via `POST /team/list`." + "description": "Owning team ID. Get team IDs via `POST /team/list`.", + "exclusiveMinimum": 0 }, "is_private": { "type": "boolean", @@ -45512,11 +45720,19 @@ "description": "Application ID to update. Get application IDs via `POST /rum/application/list`." }, "application_name": { - "type": "string", - "description": "New application name, 1–40 characters. Omit to leave unchanged." + "type": [ + "string", + "null" + ], + "description": "New application name, 1–40 characters. Omit to leave unchanged.", + "minLength": 1, + "maxLength": 40 }, "type": { - "type": "string", + "type": [ + "string", + "null" + ], "enum": [ "browser", "ios", @@ -45530,12 +45746,16 @@ "harmony", "electron" ], - "description": "Application type. Omit to leave unchanged. Platform identifier, one of `browser` (web), `ios`, `android`, `react-native`, `flutter`, `kotlin-multiplatform`, `roku`, `unity`, `miniprogram` (WeChat mini program), `harmony` (HarmonyOS), `electron`." + "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 |" }, "team_id": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "Owning team ID. Get team IDs via `POST /team/list`. Omit to leave unchanged." + "description": "Owning team ID. Get team IDs via `POST /team/list`. Omit to leave unchanged.", + "exclusiveMinimum": 0 }, "is_private": { "type": [ @@ -45588,7 +45808,7 @@ "end_time": { "type": "integer", "format": "int64", - "description": "End of time range, millisecond timestamp. Maximum range: 183 days." + "description": "End of the time range, Unix epoch milliseconds. Must be greater than `start_time`; maximum range: 183 days." }, "application_ids": { "type": "array", @@ -45616,7 +45836,7 @@ "resolved" ] }, - "description": "Filter by status; only the enum values are accepted — any other value is rejected with a parameter error." + "description": "Filter by triage status; any other value is rejected with a parameter error.\n\n| Value | Meaning |\n|---|---|\n| `for_review` | Pending triage |\n| `reviewed` | Reviewed |\n| `ignored` | Ignored |\n| `resolved` | Resolved |" }, "suspected_causes": { "type": "array", @@ -45631,7 +45851,7 @@ "unknown" ] }, - "description": "Filter by suspected cause; see the enum for valid values." + "description": "Filter by suspected cause category.\n\n| Value | Meaning |\n|---|---|\n| `api.failed_request` | API request failure (e.g. HTTP 4xx/5xx responses) |\n| `network.error` | Network connectivity error (offline, aborted requests, etc.) |\n| `code.exception` | Code exception (Syntax/Reference/Range and similar runtime errors) |\n| `code.invalid_object_access` | Invalid object access (e.g. reading a property of `undefined`/`null`) |\n| `code.invalid_argument` | Invalid argument passed to a function |\n| `unknown` | Cause could not be determined |" }, "team_ids": { "type": "array", @@ -45643,11 +45863,14 @@ }, "p": { "type": "integer", - "description": "Page number (1-based). Ignored by the export — the first 100 matching rows are always read." + "description": "Page number (1-based). Ignored by the export — the first 100 matching rows are always read.", + "minimum": 1 }, "limit": { "type": "integer", - "description": "Page size (1–100). Ignored by the export — the row cap is fixed at 100." + "description": "Page size (1–100). Ignored by the export — the row cap is fixed at 100.", + "minimum": 1, + "maximum": 100 }, "orderby": { "type": "string", @@ -45658,7 +45881,7 @@ "error_count", "severity" ], - "description": "Sort field; defaults to `updated_at` when omitted." + "description": "Sort field; defaults to `updated_at` when omitted.\n\n| Value | Meaning |\n|---|---|\n| `created_at` | Issue creation time |\n| `updated_at` | Last update time |\n| `session_count` | Affected session count |\n| `error_count` | Error occurrence count |\n| `severity` | Severity rank (`Critical` > `Warning` > `Info`) |" }, "asc": { "type": "boolean", @@ -45697,7 +45920,7 @@ "resolved_at" ] }, - "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." + "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`) |" }, "console_origin": { "type": "string", @@ -45742,7 +45965,7 @@ "ignored", "resolved" ], - "description": "Triage status of the issue: `for_review`, `reviewed`, `ignored`, or `resolved`; soft-deleted (`deleted`) issues are never returned." + "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 |" }, "error_count": { "type": "integer", @@ -45761,7 +45984,7 @@ "age": { "type": "integer", "format": "int64", - "description": "Time span between the first and most recent occurrence, in seconds. Note: the struct comment at `model/issue/issue.go:40` says millisecond, but the value is computed and consumed (severity rules) in seconds — the comment is stale." + "description": "Time span between the first and most recent occurrence, in seconds." }, "resolved_at": { "type": "integer", @@ -45869,7 +46092,7 @@ "regressed_at": { "type": "integer", "format": "int64", - "description": "Timestamp when the regression was detected." + "description": "Time the regression was detected, Unix timestamp in milliseconds." }, "regressed_at_version": { "type": "string", @@ -45891,7 +46114,12 @@ }, "severity": { "type": "string", - "description": "Issue severity level." + "description": "Issue severity: `Critical`, `Warning`, or `Info`. Empty string on legacy issues created before severity existed.", + "enum": [ + "Critical", + "Warning", + "Info" + ] } } }, @@ -45911,7 +46139,7 @@ "end_time": { "type": "integer", "format": "int64", - "description": "End of time range, millisecond timestamp. Maximum range: 183 days." + "description": "End of the time range, Unix epoch milliseconds. Must be greater than `start_time`; maximum range: 183 days." }, "application_ids": { "type": "array", @@ -45939,7 +46167,7 @@ "resolved" ] }, - "description": "Filter by status; only the enum values are accepted — any other value is rejected with a parameter error." + "description": "Filter by triage status; any other value is rejected with a parameter error.\n\n| Value | Meaning |\n|---|---|\n| `for_review` | Pending triage |\n| `reviewed` | Reviewed |\n| `ignored` | Ignored |\n| `resolved` | Resolved |" }, "suspected_causes": { "type": "array", @@ -45954,7 +46182,7 @@ "unknown" ] }, - "description": "Filter by suspected cause; see the enum for valid values." + "description": "Filter by suspected cause category.\n\n| Value | Meaning |\n|---|---|\n| `api.failed_request` | API request failure (e.g. HTTP 4xx/5xx responses) |\n| `network.error` | Network connectivity error (offline, aborted requests, etc.) |\n| `code.exception` | Code exception (Syntax/Reference/Range and similar runtime errors) |\n| `code.invalid_object_access` | Invalid object access (e.g. reading a property of `undefined`/`null`) |\n| `code.invalid_argument` | Invalid argument passed to a function |\n| `unknown` | Cause could not be determined |" }, "team_ids": { "type": "array", @@ -45966,11 +46194,14 @@ }, "p": { "type": "integer", - "description": "Page number (1-based). Default: 1." + "description": "Page number (1-based). Default: 1.", + "minimum": 1 }, "limit": { "type": "integer", - "description": "Page size. Range: 1–100. Default: 20." + "description": "Page size. Range: 1–100. Default: 20.", + "minimum": 1, + "maximum": 100 }, "orderby": { "type": "string", @@ -45981,7 +46212,7 @@ "error_count", "severity" ], - "description": "Sort field; defaults to `updated_at` when omitted." + "description": "Sort field; defaults to `updated_at` when omitted.\n\n| Value | Meaning |\n|---|---|\n| `created_at` | Issue creation time |\n| `updated_at` | Last update time |\n| `session_count` | Affected session count |\n| `error_count` | Error occurrence count |\n| `severity` | Severity rank (`Critical` > `Warning` > `Info`) |" }, "asc": { "type": "boolean", @@ -46048,7 +46279,7 @@ "ignored", "resolved" ], - "description": "New status. Setting `resolved` records the resolution time and operator; switching away from `resolved` clears them. One of `for_review` (pending triage), `reviewed`, `ignored`, `resolved`." + "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 |" }, "suspected_cause": { "type": "string", @@ -46084,11 +46315,16 @@ }, "type": { "type": "string", - "description": "Platform type. Defaults to `browser` when omitted. One of `browser` (JavaScript sourcemaps), `android` (ProGuard/R8 mappings or NDK native symbols, distinguishable via `kind`), `ios` (dSYM symbol files).", + "description": "Platform whose symbol store to list. Defaults to `browser` when omitted; any other value returns an empty list.\n\n| Value | Store listed |\n|---|---|\n| `browser` | JavaScript sourcemaps (shared store; excludes HarmonyOS ArkTS and React Native rows) |\n| `android` | ProGuard/R8 mapping files; with `kind=native`, Android NDK .so symbols |\n| `ios` | iOS dSYM symbol files |\n| `miniprogram` | WeChat mini program sourcemaps |\n| `react-native` | React Native JS sourcemaps |\n| `harmony` | HarmonyOS ArkTS sourcemaps; with `kind=native`, HarmonyOS .so symbols |\n| `flutter` | Flutter Dart AOT symbols |\n| `electron` | Electron Breakpad symbols |", "enum": [ "browser", "android", - "ios" + "ios", + "miniprogram", + "react-native", + "harmony", + "flutter", + "electron" ] }, "services": { @@ -46096,26 +46332,39 @@ "items": { "type": "string" }, - "description": "Filter by service names. Up to 100 values." + "description": "Filter by service names. Up to 100 values.", + "maxItems": 100 }, "versions": { "type": "array", "items": { "type": "string" }, - "description": "Filter by version strings. Up to 100 values." + "description": "Filter by version strings. Up to 100 values.", + "maxItems": 100 }, "query": { "type": "string", - "description": "Substring match on the minified URL (browser) or build ID (android). Max 200 characters." + "description": "Free-text substring match. Matches `minified_url` for the JS stores (browser/react-native/harmony/miniprogram), `build_id` for android/flutter/electron and harmony with `kind=native`, or `uuid` for ios (case-insensitive, hyphens ignored).", + "maxLength": 200 }, "build_id": { "type": "string", - "description": "Android only. Filter by Gradle plugin build identifier. Max 200 characters." + "description": "Android only. Filter by Gradle plugin build identifier. Max 200 characters.", + "maxLength": 200 }, "uuid": { "type": "string", - "description": "iOS only. Filter by dSYM bundle UUID. Max 200 characters." + "description": "iOS only. Filter by dSYM bundle UUID. Max 200 characters.", + "maxLength": 200 + }, + "kind": { + "type": "string", + "enum": [ + "mapping", + "native" + ], + "description": "Symbol type filter, Android and HarmonyOS only (ignored for other platforms): `mapping` (default) lists ProGuard/R8 mappings or ArkTS sourcemaps, `native` lists native .so symbols." }, "p": { "type": "integer", @@ -46156,11 +46405,13 @@ }, "type": { "type": "string", - "description": "Platform type: `browser`, `android`, or `ios`.", + "description": "Platform store this record belongs to. JavaScript rows always report `browser` (including HarmonyOS ArkTS and React Native uploads); native-symbol rows always report `android` (including HarmonyOS native and Electron uploads).\n\n| Value | Store |\n|---|---|\n| `browser` | JavaScript sourcemap store |\n| `android` | Android mapping store, or the shared native symbol store |\n| `ios` | iOS dSYM store |\n| `miniprogram` | WeChat mini program sourcemap store |\n| `flutter` | Flutter Dart AOT symbol store |", "enum": [ "browser", "android", - "ios" + "ios", + "miniprogram", + "flutter" ] }, "service": { @@ -46196,23 +46447,31 @@ }, "metadata": { "type": "object", - "description": "Free-form key-value metadata attached to the sourcemap. Shape depends on the upload client; common keys include `git_repository_url` and `git_commit_sha` (though those are also promoted to top-level fields).", + "description": "Platform-specific metadata: `minified_url` (browser/react-native/harmony/miniprogram); `build_id`, `variant`, `version_code` (android mappings), plus `arch`, `lib_name`, `code_id` (android/harmony/electron native symbols); `uuid` (ios); `build_id`, `platform`, `arch`, `flavor`, `code_id`, `debug_id` (flutter); `subpackage`, `minified_url` (miniprogram). Omitted when empty.", "additionalProperties": true + }, + "minified_url": { + "type": "string", + "description": "Deprecated. URL of the minified file; present only on JavaScript and miniprogram records. New integrations should read `metadata.minified_url`." + }, + "minified_path": { + "type": "string", + "description": "Deprecated. Storage path of the minified file; present only on JavaScript records." + }, + "sourcemap_path": { + "type": "string", + "description": "Deprecated. Storage path of the sourcemap file; present only on JavaScript and miniprogram records." } } }, "SourcemapListResponse": { "type": "object", "description": "Paginated list of sourcemap records.", - "required": [ - "total", - "items" - ], "properties": { "total": { "type": "integer", "format": "int64", - "description": "Total number of matching records.", + "description": "Total number of matching records. Omitted when 0.", "example": 3 }, "items": { @@ -46220,7 +46479,7 @@ "items": { "$ref": "#/components/schemas/SourcemapItem" }, - "description": "Sourcemap records of the current page (including iOS dSYM and miniprogram symbol files)." + "description": "Sourcemap records of the current page. Omitted when empty." } } }, @@ -46265,11 +46524,11 @@ }, "account_locale": { "type": "string", - "description": "Account-level locale preference (e.g. zh-CN or en-US)" + "description": "Account-level locale preference (e.g. zh-CN or en-US). Omitted when the account has none set." }, "account_time_zone": { "type": "string", - "description": "Account-level time zone (e.g. Asia/Shanghai)" + "description": "Account-level time zone (e.g. Asia/Shanghai). Omitted when the account has none set." }, "domain": { "type": "string", @@ -46310,26 +46569,48 @@ }, "locale": { "type": "string", - "description": "Locale preference" + "description": "Member's locale preference. Omitted when the member has none set." }, "time_zone": { "type": "string", - "description": "Time zone" + "description": "Member's IANA time zone. Omitted when the member has none set." }, "is_external": { "type": "boolean", "description": "Whether provisioned via SSO" }, - "status": { + "created_at": { + "type": "integer", + "format": "int64", + "description": "Member creation time, Unix timestamp in seconds." + }, + "mp_plat": { "type": "string", - "enum": [ - "enabled", - "pending", - "deleted" - ], - "description": "Member status. `enabled` — active member; `pending` — invited but not yet accepted; `deleted` — removed from the organization." + "description": "Cloud marketplace platform the account was provisioned from. Omitted when the account did not come from a marketplace." + }, + "mp_account_id": { + "type": "string", + "description": "Account identifier on the marketplace platform. Omitted together with `mp_plat`." } - } + }, + "required": [ + "account_id", + "account_name", + "account_avatar", + "account_email", + "account_role_ids", + "domain", + "member_id", + "member_name", + "phone", + "phone_verified", + "email", + "email_verified", + "country_code", + "avatar", + "is_external", + "created_at" + ] }, "MemberListRequest": { "type": "object", @@ -46419,11 +46700,11 @@ }, "locale": { "type": "string", - "description": "Locale" + "description": "Member's locale preference (e.g. `zh-CN`). Omitted when empty — the list endpoint does not populate it." }, "time_zone": { "type": "string", - "description": "Time zone" + "description": "Member's IANA time zone (e.g. `Asia/Shanghai`). Omitted when empty — the list endpoint does not populate it." }, "phone_verified": { "type": "boolean", @@ -46497,7 +46778,13 @@ }, "description": "Member items" } - } + }, + "required": [ + "p", + "limit", + "total", + "items" + ] }, "MemberDeleteRequest": { "type": "object", @@ -46533,25 +46820,52 @@ "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", "default": false } - } + }, + "anyOf": [ + { + "required": [ + "member_id" + ] + }, + { + "required": [ + "member_name" + ] + }, + { + "required": [ + "email" + ] + }, + { + "required": [ + "phone" + ] + }, + { + "required": [ + "ref_id" + ] + } + ] }, "InviteMemberItem": { "type": "object", - "description": "Member to invite", + "description": "A member to invite. Identify the invitee by `email` alone, or by `member_name` + `phone` together.", "properties": { "member_name": { "type": "string", "minLength": 2, "maxLength": 39, - "description": "Display name" + "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" + "description": "Email address. Required when `phone` is not provided." }, "phone": { "type": "string", - "description": "Phone number" + "description": "Phone number. Required when `email` is not provided." }, "country_code": { "type": "string", @@ -46560,7 +46874,8 @@ "role_ids": { "type": "array", "items": { - "type": "integer" + "type": "integer", + "format": "uint64" }, "description": "Role IDs to assign" }, @@ -46594,7 +46909,8 @@ "items": { "$ref": "#/components/schemas/InviteMemberItem" }, - "description": "Members to invite (max 20)" + "description": "Members to invite in one call (at least 1). Each entry needs either an `email`, or `member_name` + `phone` together.", + "minItems": 1 }, "from": { "type": "string", @@ -46680,8 +46996,7 @@ "type": "object", "description": "Update member roles request", "required": [ - "member_id", - "role_ids" + "member_id" ], "properties": { "member_id": { @@ -46773,34 +47088,55 @@ "description": "Member profile fields to write. Omitted fields remain unchanged.", "properties": { "member_name": { - "type": "string", + "type": [ + "string", + "null" + ], "minLength": 2, "maxLength": 39, "description": "New display name." }, "password": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "New login password in the encrypted format accepted by the backend." }, "phone": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "New phone number. Include country_code when the number is not in E.164 format." }, "country_code": { - "type": "string", + "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." }, "email": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "New email address." }, "avatar": { - "type": "string", + "type": [ + "string", + "null" + ], "maxLength": 499, "description": "New avatar URL." }, "locale": { - "type": "string", + "type": [ + "string", + "null" + ], "enum": [ "zh-CN", "en-US" @@ -46808,11 +47144,17 @@ "description": "New locale preference. One of: `zh-CN` (Simplified Chinese), `en-US` (English); other values are rejected with a 400." }, "time_zone": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "New IANA time zone name, such as Asia/Shanghai." }, "ref_id": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "New external reference ID." } } @@ -46856,35 +47198,31 @@ }, "person_name": { "type": "string", - "description": "Display name" + "description": "Display name. Omitted when empty." }, "avatar": { "type": "string", - "description": "Avatar URL" + "description": "Avatar URL. Omitted when empty." }, "locale": { "type": "string", - "description": "Locale" + "description": "Locale. Omitted when empty." }, "time_zone": { "type": "string", - "description": "Time zone" + "description": "Time zone. Omitted when empty." }, "email": { "type": "string", - "description": "Email address" - }, - "country_code": { - "type": "string", - "description": "ISO 3166-1 alpha-2 region code of the contact phone (e.g. \"CN\", \"US\", \"HK\")." + "description": "Email address. Omitted when empty." }, "phone": { "type": "string", - "description": "Phone number" + "description": "Phone number. Omitted when empty — this endpoint never populates it." }, "phone_verified": { "type": "boolean", - "description": "Phone verified" + "description": "Whether the phone is verified. Always false in this endpoint's response." }, "email_verified": { "type": "boolean", @@ -46892,7 +47230,11 @@ }, "as": { "type": "string", - "description": "Login role (account/member)" + "description": "Principal kind: `account` — the account owner principal; `member` — an organization member.", + "enum": [ + "account", + "member" + ] }, "status": { "type": "string", @@ -46901,7 +47243,7 @@ "pending", "deleted" ], - "description": "Person status. `enabled` — active; `pending` — invited but not yet accepted; `deleted` — removed." + "description": "Person status. `enabled` — active; `pending` — invited but not yet accepted; `deleted` — removed. Omitted when empty." } } }, @@ -46916,7 +47258,10 @@ }, "description": "Person profiles" } - } + }, + "required": [ + "items" + ] }, "TeamItem": { "type": "object", @@ -46959,9 +47304,9 @@ "type": "string", "enum": [ "enabled", - "disabled" + "deleted" ], - "description": "Team 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)." }, "updated_by_name": { "type": "string", @@ -46979,7 +47324,7 @@ }, "creator_name": { "type": "string", - "description": "Display name of the creator." + "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", @@ -47022,7 +47367,24 @@ "type": "string", "description": "External reference ID. When provided, takes precedence over `team_name` and `team_id`." } - } + }, + "anyOf": [ + { + "required": [ + "team_id" + ] + }, + { + "required": [ + "team_name" + ] + }, + { + "required": [ + "ref_id" + ] + } + ] }, "TeamInfosRequest": { "type": "object", @@ -47037,7 +47399,7 @@ "type": "integer", "format": "uint64" }, - "description": "List of team IDs to look up. Max 100." + "description": "List of team IDs to look up." } } }, @@ -47062,7 +47424,12 @@ }, "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" + ] }, "TeamInfosResponse": { "type": "object", @@ -47117,7 +47484,7 @@ }, "query": { "type": "string", - "description": "Substring match on team name." + "description": "Substring match on team name or description." } } }, @@ -47196,7 +47563,7 @@ "items": { "type": "string" }, - "description": "Add existing members to the team by phone number. Numbers that don't match an existing member are silently ignored; non-E.164 numbers are parsed with `countryCode`." + "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." }, "countryCode": { "type": "string", @@ -47208,7 +47575,7 @@ }, "reset_if_name_exist": { "type": "boolean", - "description": "If true and a team with the same name already exists, reset its membership to the provided person_ids." + "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." } } }, @@ -47248,7 +47615,24 @@ "type": "string", "description": "External reference ID. Only used when neither `team_id` nor `team_name` is provided." } - } + }, + "anyOf": [ + { + "required": [ + "team_id" + ] + }, + { + "required": [ + "team_name" + ] + }, + { + "required": [ + "ref_id" + ] + } + ] }, "PlatformEmptyObject": { "type": "object", @@ -47355,6 +47739,10 @@ "asc": { "type": "boolean", "description": "Ascending sort order. Default: false (descending)." + }, + "no_global": { + "type": "boolean", + "description": "When true, exclude the built-in global roles (Admin, Responder, Viewer) and return only custom roles. Default: false." } } }, @@ -47459,7 +47847,9 @@ "description", "class", "scope", - "status" + "status", + "source", + "is_granted" ], "properties": { "id": { @@ -47489,19 +47879,45 @@ }, "scope": { "type": "string", - "description": "Permission scope (e.g., 'on-call', 'organization')." + "description": "Functional scope the permission applies to.\n\n| value | meaning |\n| --- | --- |\n| `account` | Account settings and API keys |\n| `organization` | Members, teams, roles, audit |\n| `on-call` | On-call incident management |\n| `monit` | Monitoring |\n| `rum` | Real user monitoring |\n| `ai-sre` | AI SRE features |\n| `custom_menu` | Account-defined custom menu pages (on-premises only) |", + "enum": [ + "account", + "organization", + "on-call", + "monit", + "rum", + "ai-sre", + "custom_menu" + ] }, "status": { "type": "string", "enum": [ "enabled", - "disabled" + "deleted" ], - "description": "Permission status." + "description": "Permission status. `enabled` — active; `deleted` — removed (deleted permissions are filtered out and never returned)." }, "is_granted": { "type": "boolean", - "description": "Present when with_all is true. Indicates whether this permission is granted to the requested roles." + "description": "Whether this permission is granted to the roles given in `role_ids`. Always present in this endpoint's response; `false` entries only appear when `with_all` is true." + }, + "account_id": { + "type": "integer", + "format": "uint64", + "description": "Owning account ID. Omitted when 0, i.e. for system-level permissions." + }, + "source": { + "type": "string", + "enum": [ + "system", + "account" + ], + "description": "Origin of the permission. `system` — seeded built-in permission; `account` — dynamic permission created for this account (e.g. custom menus)." + }, + "source_ref": { + "type": "string", + "description": "Primary key of the source object (e.g. the custom menu ID) for account-scoped permissions. Omitted when empty." } } }, @@ -47563,6 +47979,18 @@ "url" ], "description": "Factor type. `api`: backend API factor — `factor_name` is the API name (e.g. `skill:write:upload`), enforced at the gateway; `button`: UI action factor, used by the role-config page to render action toggles; `visit`: page-visit factor (custom menu pages use this type); `menu`: menu-visibility factor (legacy, no current seed data); `url`: page route-path factor (legacy, no current seed data)." + }, + "source": { + "type": "string", + "enum": [ + "system", + "account" + ], + "description": "Origin of the factor. `system` — seeded built-in factor; `account` — dynamic factor created for this account (e.g. custom menus)." + }, + "source_ref": { + "type": "string", + "description": "Primary key of the source object (e.g. the custom menu ID) for account-scoped factors. Omitted when empty." } } }, @@ -47587,7 +48015,7 @@ "type": "integer", "format": "uint64" }, - "description": "Member IDs to grant/revoke the role. Max 100." + "description": "Member IDs to grant/revoke the role." }, "role_id": { "type": "integer", @@ -47607,18 +48035,20 @@ "start_time": { "type": "integer", "format": "int64", - "description": "Start of the search window, Unix epoch seconds.", - "example": 1712620800 + "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. Must be after `start_time`. Maximum span 90 days.", - "example": 1712707200 + "description": "End of the search window, Unix epoch seconds. Inclusive. Must be after `start_time`; maximum span 90 days.", + "example": 1712707200, + "minimum": 1 }, "limit": { "type": "integer", - "description": "Page size. Minimum 0, maximum 99.", + "description": "Page size, 0–99. Omit or set to 0 for no page-size cap — all matching rows in the window are returned.", "minimum": 0, "maximum": 99, "example": 20 @@ -47674,7 +48104,10 @@ "body", "params", "is_dangerous", - "is_write" + "is_write", + "principal_kind", + "credential_type", + "credential_id" ], "properties": { "created_at": { @@ -47690,11 +48123,11 @@ "member_id": { "type": "integer", "format": "uint64", - "description": "ID of the member who performed the action." + "description": "ID of the member who performed the action. 0 when the action was performed by the account principal itself." }, "member_name": { "type": "string", - "description": "Display name of the member." + "description": "Display name of the member. Empty when `member_id` is 0." }, "request_id": { "type": "string", @@ -47710,11 +48143,11 @@ }, "operation_name": { "type": "string", - "description": "Human-readable operation label in the account's locale." + "description": "Human-readable Chinese label of the operation (e.g. `创建模板`)." }, "body": { "type": "string", - "description": "JSON-encoded request body (may be truncated at 10 KB)." + "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", @@ -47740,6 +48173,23 @@ "is_write": { "type": "boolean", "description": "True for mutating operations; false for read-only ones." + }, + "principal_kind": { + "type": "string", + "enum": [ + "member", + "service" + ], + "description": "Kind of the caller. `member` — an interactive member session; `service` — an app key credential." + }, + "credential_type": { + "type": "string", + "description": "Credential type used for the call. `app_key` when authenticated with an app key; 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." } } }, @@ -47766,7 +48216,7 @@ "items": { "$ref": "#/components/schemas/AuditLog" }, - "description": "Audit log entries for this page." + "description": "Audit log entries for this page, newest first. Omitted when the page is empty." } } }, @@ -47892,7 +48342,12 @@ }, "status": { "type": "string", - "description": "Field status (e.g. `enabled`, `deleted`)." + "enum": [ + "enabled", + "disabled", + "deleted" + ], + "description": "Field status: `enabled` (active), `disabled` (set only via internal helpers, not via the API), or `deleted` (soft-deleted). `/field/list` excludes `deleted`; `/field/info` may return it." }, "creator_id": { "type": "integer", @@ -47931,7 +48386,10 @@ "creator_id", "updated_by", "created_at", - "updated_at" + "updated_at", + "description", + "options", + "default_value" ] }, "FieldInfoRequest": { @@ -47956,7 +48414,7 @@ "created_at", "updated_at" ], - "description": "Sort key. Defaults to backend ordering when omitted." + "description": "Sort key. Defaults to `created_at` when omitted." }, "asc": { "type": "boolean", @@ -47972,7 +48430,7 @@ }, "query": { "type": "string", - "description": "Regex filter against `field_name` and `display_name`. Invalid regex is auto-escaped to literal substring match." + "description": "Regex filter matched against `field_name` only. An invalid regex is auto-escaped to a literal substring match." } } }, @@ -48024,7 +48482,7 @@ "single_select", "text" ], - "description": "Field type, immutable after creation: `text`, `single_select`, `multi_select` or `checkbox`." + "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", @@ -48089,7 +48547,7 @@ "items": { "type": "string" }, - "description": "Replacement options list. Must obey the same per-type rules as create." + "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`.", @@ -48145,7 +48603,7 @@ } }, "QueryDataRequest": { - "description": "Request for the stable structured query endpoint. It uses the same query fields as the deprecated rows endpoint.", + "description": "Request for the stable structured query endpoint. It accepts the same query fields as the retired rows endpoint.", "allOf": [ { "$ref": "#/components/schemas/QueryRowsRequest" @@ -48415,33 +48873,6 @@ } } }, - "QueryRowsResponse": { - "type": "array", - "description": "Result rows. Different data sources populate `fields` vs `values` differently — metric sources (Prometheus, *-stats) put numbers into `values`; detail sources (SQL, SLS, raw logs) put data into `fields` and may return `values: null`.", - "items": { - "$ref": "#/components/schemas/QueryRow" - } - }, - "QueryRow": { - "type": "object", - "properties": { - "fields": { - "type": "object", - "description": "String-valued fields (labels, log fields, SQL columns).", - "additionalProperties": { - "type": "string" - } - }, - "values": { - "type": "object", - "nullable": true, - "description": "Numeric fields. For metric queries the canonical key is `__value__`. May be `null` for detail-oriented sources.", - "additionalProperties": { - "type": "number" - } - } - } - }, "DiagnoseRequest": { "type": "object", "required": [ @@ -48879,6 +49310,14 @@ "type": "integer", "format": "int64", "description": "Last route-projection upsert time, Unix seconds. Treat as 'most recently observed', not a live-online indicator." + }, + "host_id": { + "type": "string", + "description": "ID of the host agent reporting this target. Omitted when the target is not associated with a host." + }, + "servicemap": { + "$ref": "#/components/schemas/TargetInventoryServiceMapCapability", + "description": "ServiceMap capability and latest status of the target's host. Omitted when the reporting agent has no ServiceMap capability." } } }, @@ -48893,6 +49332,10 @@ "type": "string", "description": "Opaque cursor for the next page. Absent / empty means this is the last page.", "x-flashduty-preserve-absence": true + }, + "servicemap_coverage": { + "$ref": "#/components/schemas/TargetInventoryServiceMapCoverage", + "description": "ServiceMap status-fetch coverage for this page. Omitted when no item on the page carries ServiceMap data." } } }, @@ -48940,7 +49383,11 @@ }, "channel_status": { "type": "string", - "description": "Status of the collaboration channel." + "description": "Status of the collaboration channel: `enabled` or `disabled`.", + "enum": [ + "enabled", + "disabled" + ] }, "integration_id": { "type": "integer", @@ -48965,7 +49412,14 @@ }, "change_status": { "type": "string", - "description": "Current lifecycle status of the change." + "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. |", + "enum": [ + "Planned", + "Ready", + "Processing", + "Canceled", + "Done" + ] }, "start_time": { "type": "integer", @@ -49076,7 +49530,7 @@ "deleted_at": { "type": "integer", "format": "int64", - "description": "Unix timestamp in seconds when the change event was deleted." + "description": "Unix timestamp in seconds when the change event was deleted. Omitted when not deleted." } } }, @@ -49137,7 +49591,11 @@ "type": "string", "description": "Current status of the person." } - } + }, + "required": [ + "account_id", + "person_id" + ] }, "GetWarRoomDefaultObserversRequest": { "type": "object", @@ -49173,7 +49631,13 @@ }, "description": "Fixed incident-card fields returned for supported IM previews after the requested hiding rules are applied." } - } + }, + "required": [ + "success", + "content", + "message" + ], + "description": "Template preview result." }, "ResponseEnvelope": { "type": "object", @@ -49201,12 +49665,14 @@ "start_time": { "type": "integer", "format": "int64", - "description": "Unix timestamp in seconds for the start of the query window." + "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.", + "minimum": 0 }, "end_time": { "type": "integer", "format": "int64", - "description": "Unix timestamp in seconds for the end of the query window." + "description": "End of the query window, Unix epoch seconds. See `start_time` for defaults and constraints.", + "minimum": 0 }, "p": { "type": "integer", @@ -49238,11 +49704,12 @@ "description": "", "format": "int64" }, - "description": "Filter by reporting integration IDs." + "description": "Filter by reporting integration IDs. At least 1 entry when provided.", + "minItems": 1 }, "orderby": { "type": "string", - "description": "Field to sort the result by.", + "description": "Sort field: `start_time` or `last_time`. Defaults to `start_time`.", "enum": [ "start_time", "last_time" @@ -49250,7 +49717,7 @@ }, "asc": { "type": "boolean", - "description": "Sort in ascending order when true." + "description": "Sort in ascending order when true; default is descending." }, "include_events": { "type": "boolean", @@ -49258,7 +49725,39 @@ }, "query": { "type": "string", - "description": "Free-text or regular-expression search over change fields." + "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." + }, + "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": 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." } } }, @@ -49272,7 +49771,11 @@ }, "description": "IM integrations with the war-room feature enabled." } - } + }, + "required": [ + "items" + ], + "description": "War-room-enabled IM integration list response." }, "WarRoomDataSourceItem": { "type": "object", @@ -49303,15 +49806,19 @@ }, "status": { "type": "string", - "description": "Current status of the integration." + "description": "Integration status: `enabled` or `disabled`. Deleted integrations are never returned.", + "enum": [ + "enabled", + "disabled" + ] }, "category": { "type": "string", - "description": "Category of the integration plugin." + "description": "Plugin category; `im` for the IM integrations returned here." }, "plugin_type": { "type": "string", - "description": "Type identifier of the integration plugin." + "description": "Plugin type identifier of the IM integration, for example `feishu_app`, `dingtalk_app`, `wecom_app`, `slack_app`, or `teams_app`." }, "plugin_type_name": { "type": "string", @@ -49361,11 +49868,11 @@ "last_time": { "type": "integer", "format": "int64", - "description": "Unix timestamp in seconds of the most recent activity on the integration." + "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": "Exclusive integration ID associated with this integration.", + "description": "Legacy exclusive-integration linkage; deprecated.", "format": "int64" }, "integration_id": { @@ -49373,7 +49880,31 @@ "description": "Integration ID, alias of data_source_id.", "format": "int64" } - } + }, + "required": [ + "data_source_id", + "account_id", + "team_id", + "plugin_id", + "name", + "status", + "category", + "plugin_type", + "plugin_type_name", + "description", + "integration_key", + "ref_id", + "settings", + "no_editable", + "creator_id", + "updated_by", + "created_at", + "updated_at", + "last_time", + "exclusive_data_source_id", + "integration_id" + ], + "description": "An IM integration (data source) entry." }, "AddWarRoomMemberRequest": { "type": "object", @@ -49391,7 +49922,6 @@ "type": "array", "items": { "type": "integer", - "description": "", "format": "int64" }, "description": "Person IDs to add to the war room." @@ -49408,7 +49938,8 @@ "properties": { "account_id": { "type": "integer", - "description": "Account identifier." + "description": "Account identifier.", + "format": "uint64" }, "account_name": { "type": "string", @@ -49456,7 +49987,7 @@ }, "restrictions": { "type": "object", - "description": "Account access restrictions (present only when configured).", + "description": "Account access restrictions. Omitted when none are configured.", "properties": { "ips": { "type": "array", @@ -49480,13 +50011,26 @@ }, "mp_plat": { "type": "string", - "description": "Cloud marketplace platform the account was provisioned from (present only for marketplace accounts)." + "description": "Cloud marketplace platform the account was provisioned from. Omitted when the account did not come from a marketplace." }, "mp_account_id": { "type": "string", - "description": "Account identifier on the cloud marketplace platform (present only for marketplace accounts)." + "description": "Account identifier on the marketplace platform. Omitted together with `mp_plat`." } - } + }, + "required": [ + "account_id", + "account_name", + "domain", + "extra_domains", + "phone", + "country_code", + "email", + "avatar", + "locale", + "time_zone", + "created_at" + ] }, "PreviewTemplateRequest": { "type": "object", @@ -49497,11 +50041,12 @@ }, "type": { "type": "string", - "description": "Template channel type that selects the rendering engine." + "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`." }, "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 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}$" }, "incident_card_hidden_fields": { "$ref": "#/components/schemas/IncidentCardHiddenFields", @@ -49511,7 +50056,8 @@ "required": [ "content", "type" - ] + ], + "description": "Template preview request." }, "ListStatusPageResponse": { "type": "object", @@ -49523,7 +50069,10 @@ }, "description": "Status pages owned by the account." } - } + }, + "required": [ + "items" + ] }, "StatusPageItem": { "type": "object", @@ -49551,35 +50100,35 @@ }, "custom_domain": { "type": "string", - "description": "Custom domain pointing to the status page." + "description": "Custom domain pointing to the status page. Omitted when not set." }, "logo": { "type": "string", - "description": "Logo image of the status page." + "description": "Logo image of the status page. Omitted when not set." }, "dark_logo": { "type": "string", - "description": "Dark-mode logo image of the status page." + "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." + "description": "URL opened when the logo is clicked. Omitted when not set." }, "favicon": { "type": "string", - "description": "Favicon of the status page." + "description": "Favicon of the status page. Omitted when not set." }, "page_header": { "type": "string", - "description": "Header content of the status page." + "description": "Header content of the status page. Omitted when not set." }, "page_footer": { "type": "string", - "description": "Footer content of the status page." + "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.", + "description": "How the timeline displays change dates. `calendar` uses a calendar view; `list` uses a list view. Omitted when not set.", "enum": [ "calendar", "list" @@ -49587,7 +50136,7 @@ }, "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.", + "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", @@ -49602,11 +50151,11 @@ "type": "string" } }, - "description": "Custom navigation links shown on the status page." + "description": "Custom navigation links shown on the status page. Omitted when not set." }, "contact_info": { "type": "string", - "description": "Get-in-touch contact, a mailto or website URL." + "description": "Get-in-touch contact, a mailto or website URL. Omitted when not set." }, "components": { "type": "array", @@ -49623,13 +50172,23 @@ "description": "Sections grouping the components." }, "subscription": { - "$ref": "#/components/schemas/StatusPageSubscriptionItem" + "$ref": "#/components/schemas/StatusPageSubscriptionItem", + "description": "Subscription channel toggles." }, "template_preference": { "type": "string", - "description": "Preferred change-event template type." + "description": "Preferred event template type: `pre_defined` or `message`. Omitted when never set." } - } + }, + "required": [ + "page_id", + "name", + "url_name", + "type", + "components", + "sections", + "subscription" + ] }, "StatusPageSubscriptionItem": { "type": "object", @@ -49642,14 +50201,18 @@ "type": "boolean", "description": "Whether IM subscription is enabled." } - } + }, + "required": [ + "email", + "im" + ] }, "StatusPageSectionItem": { "type": "object", "properties": { "section_id": { "type": "string", - "description": "Section ID." + "description": "Section ID. Omitted when empty." }, "name": { "type": "string", @@ -49661,7 +50224,7 @@ }, "order_id": { "type": "integer", - "description": "Display order of the section.", + "description": "Display order of the section. Omitted when 0.", "format": "int64" }, "hide_uptime": { @@ -49672,7 +50235,13 @@ "type": "boolean", "description": "Whether the section and its components are hidden from summary endpoints." } - } + }, + "required": [ + "name", + "description", + "hide_uptime", + "hide_all" + ] }, "DeletePostMortemTemplateRequest": { "type": "object", @@ -49833,44 +50402,6 @@ } } }, - "PreviewSyncRequest": { - "type": "object", - "required": [ - "ds_type", - "ds_name", - "expr" - ], - "description": "Parameters for a synchronous datasource query preview.", - "properties": { - "ds_type": { - "type": "string", - "description": "Datasource type, e.g. `prometheus`, `loki`, `elasticsearch`." - }, - "ds_name": { - "type": "string", - "description": "Datasource display name as configured in the account." - }, - "expr": { - "type": "string", - "description": "Query expression. Format depends on `ds_type` (PromQL for Prometheus, LogQL for Loki, etc.)." - }, - "delay_seconds": { - "type": "integer", - "description": "Shift the query window backward by this many seconds to compensate for data ingestion latency." - }, - "args": { - "type": "object", - "additionalProperties": { - "type": "string" - }, - "description": "Additional datasource-type-specific query arguments (string keys and values), e.g. `sls.project` and `sls.logstore` for SLS, `es.type` for Elasticsearch, `loki.type` and `loki.limit` for Loki." - } - } - }, - "PreviewSyncResponse": { - "type": "object", - "description": "Raw JSON response from the datasource. Schema varies by datasource type." - }, "ResetPostMortemBasicsRequest": { "type": "object", "description": "Basic incident facts to write back to a post-mortem report.", @@ -49886,7 +50417,13 @@ }, "incidents_highest_severity": { "type": "string", - "description": "Highest severity among linked incidents." + "description": "Highest severity among linked incidents: `Critical`, `Warning`, `Info`, or `Ok`.", + "enum": [ + "Critical", + "Warning", + "Info", + "Ok" + ] }, "incidents_earliest_start_seconds": { "type": "integer", @@ -50066,7 +50603,7 @@ }, "TryLinkPersonResponse": { "type": "object", - "description": "People linked by this attempt.", + "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.", "required": [ "new_linked_person_ids" ], @@ -50127,14 +50664,15 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "component_ids": { "type": "array", "items": { "type": "string" }, - "description": "Component IDs to delete; obtain them from `POST /status-page/info`." + "description": "Component IDs to delete; obtain them from `GET /status-page/info`.", + "minItems": 1 } } }, @@ -50149,14 +50687,15 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "section_ids": { "type": "array", "items": { "type": "string" }, - "description": "Section IDs to delete; obtain them from `POST /status-page/info`." + "description": "Section IDs to delete; obtain them from `GET /status-page/info`.", + "minItems": 1 } } }, @@ -50172,7 +50711,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "type": { "type": "string", @@ -50184,7 +50723,7 @@ }, "template_id": { "type": "string", - "description": "ID of the template to delete; obtain it from `POST /status-page/template/list`." + "description": "ID of the template to delete; obtain it from `GET /status-page/template/list`." } } }, @@ -50199,7 +50738,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "components": { "type": "array", @@ -50238,9 +50777,15 @@ "hide_all": { "type": "boolean", "description": "When true, the component is hidden entirely from summary endpoints." + }, + "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." } } - } + }, + "minItems": 1 } } }, @@ -50271,7 +50816,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "sections": { "type": "array", @@ -50308,7 +50853,8 @@ "description": "When true, the entire section is hidden from summary endpoints." } } - } + }, + "minItems": 1 } } }, @@ -50340,7 +50886,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "type": { "type": "string", @@ -50351,48 +50897,15 @@ "description": "Template category. `pre_defined` for predefined event templates; `message` for notification message templates." }, "template": { - "type": "object", - "description": "Template content.", - "required": [ - "title", - "event_type", - "status" - ], - "properties": { - "template_id": { - "type": "string", - "description": "Template ID. Omit to create; supply to update." - }, - "title": { - "type": "string", - "description": "Template title." - }, - "event_type": { - "type": "string", - "enum": [ - "incident", - "maintenance" - ], - "description": "Change type this template applies to: `incident` unplanned incident, `maintenance` planned maintenance." - }, - "status": { - "type": "string", - "enum": [ - "investigating", - "identified", - "monitoring", - "resolved", - "scheduled", - "ongoing", - "completed" - ], - "description": "Change status this template maps to. Incidents use `investigating`/`identified`/`monitoring`/`resolved`; maintenances use `scheduled`/`ongoing`/`completed`." + "oneOf": [ + { + "$ref": "#/components/schemas/StatusPagePreDefinedTemplate" }, - "description": { - "type": "string", - "description": "Template body text (Markdown)." + { + "$ref": "#/components/schemas/StatusPageMessageTemplate" } - } + ], + "description": "Template content. Shape depends on `type`: a predefined event template for `pre_defined`, a message template for `message`." } } }, @@ -50428,29 +50941,6 @@ } } }, - "RumDataAggregateFunction": { - "type": "object", - "description": "Aggregate function metadata used by the sampling engine.", - "required": [ - "type", - "column_name", - "column_index" - ], - "properties": { - "type": { - "type": "string", - "description": "Aggregate function type." - }, - "column_name": { - "type": "string", - "description": "Column name used by the aggregate." - }, - "column_index": { - "type": "integer", - "description": "Column index used by the aggregate." - } - } - }, "RumDataFieldMeta": { "type": "object", "description": "Metadata for one returned column.", @@ -50537,10 +51027,12 @@ "description": "Result for one query. Failed subqueries populate `error`; successful ones populate `data`.", "properties": { "error": { - "$ref": "#/components/schemas/DutyError" + "$ref": "#/components/schemas/DutyError", + "description": "Subquery failure details. Omitted when the query succeeded." }, "data": { - "$ref": "#/components/schemas/RumDataQueryResult" + "$ref": "#/components/schemas/RumDataQueryResult", + "description": "Query result. Omitted when the query failed." } } }, @@ -50593,7 +51085,7 @@ "properties": { "search_after_ctx": { "type": "string", - "description": "Opaque cursor for continuing paginated table queries." + "description": "Opaque cursor for continuing paginated table queries. Omitted when the query is not a cursor-paginated table query or no further pages exist." }, "fields": { "type": "array", @@ -50613,16 +51105,17 @@ "interval": { "type": "integer", "format": "int64", - "description": "Effective time bucket interval in seconds for time-series queries." + "description": "Effective time bucket interval in seconds. Omitted for `table`-format queries." }, "sampling": { - "$ref": "#/components/schemas/RumDataSamplingDecision" + "$ref": "#/components/schemas/RumDataSamplingDecision", + "description": "Sampling metadata. Omitted when the query did not use sampling." } } }, "RumDataSamplingDecision": { "type": "object", - "description": "Sampling metadata when the query engine uses sampled data.", + "description": "Sampling metadata returned when the query engine used sampled data.", "required": [ "enabled", "scale_factor" @@ -50630,25 +51123,11 @@ "properties": { "enabled": { "type": "boolean", - "description": "Whether sampling was applied." + "description": "Whether sampling was applied. Always `true` here — the `sampling` object is omitted entirely when sampling was not used." }, "scale_factor": { "type": "number", "description": "Multiplier used to scale sampled counts back to estimated full counts." - }, - "selected_tablets": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Storage tablets selected for the sampled query." - }, - "aggregate_funcs": { - "type": "array", - "items": { - "$ref": "#/components/schemas/RumDataAggregateFunction" - }, - "description": "Aggregate functions affected by sampling." } } }, @@ -50684,6 +51163,30 @@ "facet_value": { "description": "When set, filter events where `facet_key` equals this value before counting. Accepts string, number, or boolean." }, + "type": { + "type": "string", + "enum": [ + "browser", + "web", + "javascript", + "android", + "ios", + "miniprogram", + "harmony", + "flutter", + "electron", + "react-native" + ], + "description": "Symbol-store platform, used only when `scope` is `sourcemap`. Defaults to `browser` when omitted; `web` and `javascript` are accepted aliases of `browser`.\n\n| Value | Store queried |\n|---|---|\n| `browser` / `web` / `javascript` | JavaScript sourcemaps (excluding HarmonyOS ArkTS and React Native rows) |\n| `android` | Android ProGuard/R8 mappings; with `kind=native`, Android NDK .so symbols |\n| `ios` | iOS dSYM symbols |\n| `miniprogram` | WeChat mini program sourcemaps |\n| `harmony` | HarmonyOS ArkTS sourcemaps; with `kind=native`, HarmonyOS .so symbols |\n| `flutter` | Flutter Dart AOT symbols |\n| `electron` | Electron Breakpad symbols |\n| `react-native` | React Native JS sourcemaps |" + }, + "kind": { + "type": "string", + "enum": [ + "mapping", + "native" + ], + "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." + }, "start_time": { "type": "integer", "format": "int64", @@ -50847,9 +51350,20 @@ "scopes": { "type": "array", "items": { - "type": "string" + "type": "string", + "enum": [ + "session", + "view", + "action", + "error", + "resource", + "long_task", + "vital", + "issue", + "sourcemap" + ] }, - "description": "Filter by RUM data scopes. Valid values: `session`, `view`, `action`, `error`, `resource`, `long_task`, `vital`, `issue`, `sourcemap`." + "description": "Filter by RUM data scopes; unknown values are rejected with a parameter error. Omit to list fields of all scopes.\n\n| Value | Meaning |\n|---|---|\n| `session` | User sessions |\n| `view` | Page views |\n| `action` | User actions |\n| `error` | Error events |\n| `resource` | Resource loads |\n| `long_task` | Long tasks |\n| `vital` | Performance vitals (Web Vitals, etc.) |\n| `issue` | Aggregated error-tracking issues |\n| `sourcemap` | Sourcemap / symbol files |" }, "is_facet": { "type": [ @@ -50965,14 +51479,15 @@ "items": { "$ref": "#/components/schemas/SourcemapCodeSnippet" }, - "description": "Source-code snippets around this frame." + "description": "Source-code snippets around this frame. Omitted when no snippet was extracted (for example the source content was unavailable or `near` was not requested)." }, "original_frame": { - "$ref": "#/components/schemas/SourcemapStackFrame" + "$ref": "#/components/schemas/SourcemapStackFrame", + "description": "The original minified/obfuscated frame before enrichment. Omitted when the processor did not retain one." }, "third_party": { "type": "boolean", - "description": "Whether the frame is from third-party or system libraries." + "description": "Whether the frame is from third-party or system libraries (Android and native symbolication only). Omitted when `false`." } } } @@ -50995,9 +51510,18 @@ "miniprogram", "harmony", "flutter", - "electron" + "electron", + "react-native" ], - "description": "Source platform. Defaults to `browser` when omitted. One of `browser` (JS stacks, sourcemap-based), `android` (mapping/NDK symbolication), `ios` (dSYM symbolication), `miniprogram` (WeChat mini program, sourcemap-based), `harmony` (HarmonyOS, sourcemap/native symbolication), `flutter` (Flutter stack symbolication), `electron` (Electron, sourcemap-based)." + "description": "Source platform whose symbol store is used. Defaults to `browser` when omitted.\n\n| Value | Symbolication |\n|---|---|\n| `browser` | JavaScript stacks via sourcemaps |\n| `android` | Java/Kotlin stacks via ProGuard/R8 mappings; native stacks via NDK symbols (send `source_type=ndk` with `arch`) |\n| `ios` | iOS crash stacks via dSYM (send `binary_images`) |\n| `miniprogram` | WeChat mini program stacks via sourcemaps |\n| `harmony` | HarmonyOS stacks via ArkTS sourcemaps or native symbols |\n| `flutter` | Flutter/Dart stacks via Dart AOT symbols |\n| `electron` | Electron JavaScript stacks via sourcemaps; minidump native frames via Breakpad symbols (derived from `source_type`) |\n| `react-native` | React Native JS stacks via sourcemaps; narrow the lookup with `platform` |" + }, + "platform": { + "type": "string", + "enum": [ + "ios", + "android" + ], + "description": "Narrows a `react-native` enrich to the app's native platform: `ios` for the iOS native layer, `android` for the Android native layer (the console derives it from the event's OS). Ignored for other `type` values." }, "service": { "type": "string", @@ -51215,7 +51739,7 @@ }, "UpdateStatusPageRequest": { "type": "object", - "description": "Parameters for updating an existing status page. All fields except `page_id` are optional; omit a field to keep its existing value.", + "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" ], @@ -51223,53 +51747,87 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." }, "name": { - "type": "string", - "description": "Display name of the status page. Omit to keep the existing value.", + "type": [ + "string", + "null" + ], + "description": "Display name of the status page. Omit or pass null to keep the existing value.", "maxLength": 255 }, "url_name": { - "type": "string", - "description": "URL-safe slug, unique per account and page type. Omit to keep the existing value.", + "type": [ + "string", + "null" + ], + "description": "URL-safe slug, unique per account and page type. Omit or pass null to keep the existing value.", "maxLength": 255 }, "custom_domain": { - "type": "string", - "description": "Custom domain for a public status page. Omit to keep the existing value.", + "type": [ + "string", + "null" + ], + "description": "Custom domain for a public status page. Omit or pass null to keep the existing value.", "maxLength": 255 }, "page_title": { - "type": "string", - "description": "Browser title shown for the status page. Omit to keep the existing value." + "type": [ + "string", + "null" + ], + "description": "Browser title shown for the status page. Omit or pass null to keep the existing value." }, "logo": { - "type": "string", - "description": "Logo image of the status page. Omit to keep the existing value." + "type": [ + "string", + "null" + ], + "description": "Logo image of the status page. Omit or pass null to keep the existing value." }, "dark_logo": { - "type": "string", - "description": "Dark-mode logo image of the status page. Omit to keep the existing value." + "type": [ + "string", + "null" + ], + "description": "Dark-mode logo image of the status page. Omit or pass null to keep the existing value." }, "logo_url": { - "type": "string", - "description": "URL opened when the logo is clicked. Omit to keep the existing value." + "type": [ + "string", + "null" + ], + "description": "URL opened when the logo is clicked. Omit or pass null to keep the existing value.", + "maxLength": 255 }, "favicon": { - "type": "string", - "description": "Favicon of the status page. Omit to keep the existing value." + "type": [ + "string", + "null" + ], + "description": "Favicon of the status page. Omit or pass null to keep the existing value." }, "page_header": { - "type": "string", - "description": "Header content shown on the status page. Omit to keep the existing value." + "type": [ + "string", + "null" + ], + "description": "Header content shown on the status page. Omit or pass null to keep the existing value." }, "page_footer": { - "type": "string", - "description": "Footer content shown on the status page. Omit to keep the existing value." + "type": [ + "string", + "null" + ], + "description": "Footer content shown on the status page. Omit or pass null to keep the existing value." }, "date_view": { - "type": "string", + "type": [ + "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.", "enum": [ "calendar", @@ -51277,7 +51835,10 @@ ] }, "display_uptime_mode": { - "type": "string", + "type": [ + "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.", "enum": [ "chart_and_percentage", @@ -51287,7 +51848,7 @@ }, "custom_links": { "type": "array", - "description": "Custom navigation links shown on the status page. Omit to keep the existing value.", + "description": "Custom navigation links shown on the status page. Omit or pass an empty array to keep the current links.", "items": { "type": "object", "additionalProperties": { @@ -51296,16 +51857,22 @@ } }, "contact_info": { - "type": "string", - "description": "Get-in-touch contact, such as a mailto or website URL. Omit to keep the existing value." + "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." + "description": "Subscription channel toggles. Omit or pass null to keep the existing value." }, "template_preference": { - "type": "string", - "description": "Preferred change-event template type. Omit to keep the existing value." + "type": [ + "string", + "null" + ], + "description": "Preferred event template type: `pre_defined` or `message`. Omit or pass null to keep the existing value." } } }, @@ -51319,7 +51886,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "Status page ID; obtain it from `POST /status-page/list`." + "description": "Status page ID; obtain it from `GET /status-page/list`." } } }, @@ -51334,8 +51901,8 @@ }, "instructions": { "type": "string", - "description": "Natural-language instructions for the remote agent. Required — a deprecated `description` field is still accepted for legacy clients and, if both are sent, must exactly match `instructions`.", - "maxLength": 2000 + "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 }, "card_url": { "type": "string", @@ -51343,14 +51910,19 @@ }, "auth_type": { "type": "string", - "description": "Authentication type for reaching the remote agent: `none`, `api_key`, or `bearer`." + "description": "Authentication type for reaching the remote agent: `none` (default when omitted), `api_key`, or `bearer`.", + "enum": [ + "none", + "api_key", + "bearer" + ] }, "auth_config": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "Authentication config key-values, e.g. the API key or bearer token. Values for sensitive keys (`api_key`, `token`, `client_secret`) are masked back in responses." + "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." }, "streaming": { "type": "boolean", @@ -51361,17 +51933,12 @@ "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" }, - "environment_kind": { - "type": "string", - "enum": [ - "", - "byoc" - ], - "description": "Execution environment binding. Omit or send empty for automatic routing; `byoc` pins the agent to a specific runner given by `environment_id`. `cloud` is not accepted — configured A2A agents need a persistent runner, not a disposable cloud sandbox." - }, - "environment_id": { - "type": "string", - "description": "BYOC runner ID. Required when `environment_kind=byoc`; the runner must belong to the account or a team the caller belongs to." + "environments": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Execution environments this agent is callable from: `cloud` and/or BYOC runner environment IDs. Omitted or empty means all environments." }, "auth_mode": { "type": "string", @@ -51448,17 +52015,12 @@ "type": "boolean", "description": "Whether the caller may edit this agent." }, - "environment_kind": { - "type": "string", - "enum": [ - "", - "byoc" - ], - "description": "Execution environment binding. Empty selects automatic routing; `byoc` pins the agent to a specific runner named by `environment_id`." - }, - "environment_id": { - "type": "string", - "description": "BYOC runner ID. Set only when `environment_kind=byoc`; empty otherwise." + "environments": { + "type": "array", + "items": { + "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": { "type": "string", @@ -51467,7 +52029,7 @@ "instructions": { "type": "string", "description": "Natural-language instructions for the remote agent (formerly named `description`).", - "maxLength": 2000 + "maxLength": 51200 }, "card_url": { "type": "string", @@ -51475,14 +52037,20 @@ }, "auth_type": { "type": "string", - "description": "Authentication type for reaching the remote agent: `none`, `api_key`, or `bearer`." + "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`.", + "enum": [ + "", + "none", + "api_key", + "bearer" + ] }, "auth_config": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "Authentication config; sensitive values (`api_key`, `token`, `client_secret`) are masked." + "description": "Authentication config key-values. Values under credential-looking keys (name containing KEY, SECRET, TOKEN, PASSWORD, etc.) are masked. Omitted when empty." }, "streaming": { "type": "boolean", @@ -51498,14 +52066,14 @@ }, "agent_card_name": { "type": "string", - "description": "Agent name resolved from the remote card." + "description": "Agent name resolved from the remote card. Omitted until the card has been fetched." }, "agent_card_skills": { "type": "array", "items": { "type": "string" }, - "description": "Skills advertised by the remote card." + "description": "Skills advertised by the remote card. Omitted until the card has been fetched." }, "card_resolve_timeout": { "type": "integer", @@ -51561,8 +52129,6 @@ "account_id", "team_id", "can_edit", - "environment_kind", - "environment_id", "agent_name", "instructions", "card_url", @@ -51573,7 +52139,8 @@ "task_timeout", "created_by", "created_at", - "updated_at" + "updated_at", + "environments" ] }, "A2AAgentListRequest": { @@ -51665,8 +52232,8 @@ "string", "null" ], - "description": "New instructions. Omit to leave unchanged. A deprecated `description` field is also accepted; if both are sent they must match.", - "maxLength": 2000 + "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 }, "card_url": { "type": [ @@ -51680,14 +52247,19 @@ "string", "null" ], - "description": "New auth type. Omit to leave unchanged." + "description": "New auth type: `none`, `api_key`, or `bearer`. Omit to leave unchanged.", + "enum": [ + "none", + "api_key", + "bearer" + ] }, "auth_config": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "Replace the auth config. Omit to leave unchanged. Sending back the masked value (or an empty string) for a sensitive key keeps the stored secret instead of overwriting it." + "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": [ @@ -51704,19 +52276,15 @@ "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" }, - "environment_kind": { + "environments": { "type": [ - "string", - "null" - ], - "description": "New execution environment binding: empty for automatic, `byoc` for a specific runner. `cloud` is rejected. Omit to leave unchanged." - }, - "environment_id": { - "type": [ - "string", + "array", "null" ], - "description": "New BYOC runner ID. Required alongside `environment_kind=byoc`. Omit to leave unchanged." + "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." }, "auth_mode": { "type": [ @@ -51772,7 +52340,7 @@ "type": "integer", "format": "int64", "minimum": 0, - "description": "Scope team ID. 0 or omitted means a personal rule; >0 means a team in the account. Immutable after creation." + "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)." }, "enabled": { "type": "boolean", @@ -51926,7 +52494,7 @@ }, "schedule_trigger_id": { "type": "string", - "description": "Schedule trigger ID." + "description": "Schedule trigger ID. Omitted if the rule has no schedule trigger." }, "schedule_trigger_enabled": { "type": "boolean", @@ -51934,11 +52502,11 @@ }, "http_post_trigger_id": { "type": "string", - "description": "HTTP POST trigger ID." + "description": "HTTP POST trigger ID. Omitted when the rule has no HTTP POST trigger." }, "http_post_trigger_url": { "type": "string", - "description": "HTTP POST trigger path." + "description": "HTTP POST trigger path. Omitted when the rule has no HTTP POST trigger." }, "http_post_trigger_enabled": { "type": "boolean", @@ -51946,7 +52514,7 @@ }, "oncall_incident_trigger_id": { "type": "string", - "description": "On-call incident trigger ID." + "description": "On-call incident trigger ID. Omitted when the rule has no On-call incident trigger." }, "oncall_incident_trigger_enabled": { "type": "boolean", @@ -51959,7 +52527,7 @@ "format": "int64", "minimum": 1 }, - "description": "On-call integration IDs to watch. Creating or enabling this trigger requires at least one valid ID." + "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." }, "oncall_incident_severities": { "type": "array", @@ -51971,7 +52539,7 @@ "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. 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." }, "http_post_token": { "type": "string", @@ -52031,7 +52599,6 @@ "limit": { "type": "integer", "default": 20, - "maximum": 100, "description": "Page size." }, "scope": { @@ -52116,7 +52683,7 @@ ], "format": "int64", "minimum": 0, - "description": "Only the current value is accepted; personal/team scope is immutable after creation." + "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." }, "enabled": { "type": [ @@ -52224,9 +52791,20 @@ "type": "string", "description": "Run ID." }, + "session_id": { + "type": "string", + "description": "Session created for this run, extracted from `result_json`. Omitted when the run has not (yet) started a session." + }, + "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." + }, "kind": { "type": "string", - "description": "Run kind." + "description": "Run kind; runs listed for a rule are always `automation_rule`.", + "enum": [ + "automation_rule" + ] }, "account_id": { "type": "integer", @@ -52262,9 +52840,10 @@ "partial", "failed", "skipped", - "abandoned" + "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) |" + "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`) |" }, "attempts": { "type": "integer", @@ -52287,17 +52866,27 @@ }, "error_code": { "type": "string", - "description": "Error code." + "description": "Error code; empty when the run did not fail." }, "error_message": { "type": "string", - "description": "Error message." + "description": "Error message; empty when the run did not fail." }, "stats_json": { - "description": "Run stats JSON." + "type": [ + "object", + "null" + ], + "additionalProperties": true, + "description": "Raw run statistics JSON; null when empty." }, "result_json": { - "description": "Run result JSON." + "type": [ + "object", + "null" + ], + "additionalProperties": true, + "description": "Raw run result JSON (carries the run's `session_id` once started); null when empty." }, "created_at": { "type": "integer", @@ -52323,7 +52912,11 @@ "completed_at", "duration_ms", "created_at", - "updated_at" + "updated_at", + "error_code", + "error_message", + "stats_json", + "result_json" ] }, "AutomationRunListRequest": { @@ -52341,7 +52934,6 @@ "limit": { "type": "integer", "default": 20, - "maximum": 100, "description": "Page size." }, "status": { @@ -52354,9 +52946,10 @@ "partial", "failed", "skipped", - "abandoned" + "abandoned", + "blocked" ], - "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); omit for no filter." + "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": { "type": "string", @@ -52372,12 +52965,14 @@ "started_after_ms": { "type": "integer", "format": "int64", - "description": "Start-time lower bound, Unix milliseconds." + "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." + "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": [ @@ -52439,7 +53034,7 @@ }, "enabled": { "type": "boolean", - "description": "Whether the template is enabled." + "description": "Whether a rule created from this template starts out enabled (prefill value)." }, "prompt": { "type": "string", @@ -52634,7 +53229,7 @@ "properties": { "server_name": { "type": "string", - "description": "MCP server name, unique within the account.", + "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.", "minLength": 1, "maxLength": 255 }, @@ -52716,16 +53311,12 @@ "description": "Team scope: 0 = account-wide; >0 = team.", "format": "int64" }, - "environment_kind": { - "type": "string", - "description": "Pin the server to a specific BYOC runner (`environment_id` required). Omit or send empty for automatic selection; `cloud` is not supported for MCP servers. The only accepted value: `byoc` (a self-hosted BYOC runner in the account; the MCP server process runs on the customer's own infrastructure).", - "enum": [ - "byoc" - ] - }, - "environment_id": { - "type": "string", - "description": "Runner ID; required when environment_kind is byoc." + "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", @@ -52794,21 +53385,16 @@ "type": "boolean", "description": "Whether the caller may edit this server." }, - "environment_kind": { - "type": "string", - "description": "Runtime environment kind: empty for automatic selection, or `byoc` when pinned to a specific runner. `cloud` cannot be bound to an MCP server.", - "enum": [ - "", - "byoc" - ] - }, - "environment_id": { - "type": "string", - "description": "Runner ID when environment_kind is byoc; empty otherwise." + "environments": { + "type": "array", + "items": { + "type": "string" + }, + "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)." }, "server_name": { "type": "string", - "description": "MCP server name, unique within the account." + "description": "MCP server name, unique within its scope (account-wide or one team), case-insensitive." }, "description": { "type": "string", @@ -52816,7 +53402,7 @@ }, "ai_description": { "type": "string", - "description": "LLM-generated description, preferred over `description` when present." + "description": "LLM-generated description, preferred over `description` when present. Omitted when not yet generated." }, "transport": { "type": "string", @@ -52878,26 +53464,11 @@ }, "allow_insecure_oauth_http": { "type": "boolean", - "description": "Allow this server's OAuth token exchange over plaintext HTTP; testing use only." + "description": "Allow this server's OAuth token exchange over plaintext HTTP; testing use only. Omitted when false." }, "allow_insecure_tls_skip_verify": { "type": "boolean", - "description": "Skip TLS certificate verification when connecting to this server; testing use only." - }, - "tools": { - "type": "array", - "items": { - "$ref": "#/components/schemas/MCPToolInfo" - }, - "description": "Live tool list; populated by the get/test endpoints." - }, - "tool_count": { - "type": "integer", - "description": "Number of tools in the live list." - }, - "list_error": { - "type": "string", - "description": "Error message when the live tool list failed." + "description": "Skip TLS certificate verification when connecting to this server; testing use only. Omitted when false." }, "auth_mode": { "type": "string", @@ -52941,8 +53512,6 @@ "account_id", "team_id", "can_edit", - "environment_kind", - "environment_id", "server_name", "description", "transport", @@ -52951,7 +53520,8 @@ "call_timeout", "created_by", "created_at", - "updated_at" + "updated_at", + "environments" ] }, "MCPServerListRequest": { @@ -53079,7 +53649,7 @@ "additionalProperties": { "type": "string" }, - "description": "Environment variables (`stdio` transport); replaces the whole map, but masked secret values sent back as-is keep their stored values; omit to leave unchanged." + "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." }, "url": { "type": "string", @@ -53090,7 +53660,7 @@ "additionalProperties": { "type": "string" }, - "description": "HTTP headers (sse / streamable-http)." + "description": "HTTP headers (`sse` / `streamable-http` transport); replaces the whole map, with the same masked/empty-value preservation as `env`; omit to leave unchanged." }, "connect_timeout": { "type": "integer", @@ -53120,19 +53690,15 @@ "description": "Reassign team scope: 0 = account-wide; >0 = team. Omit to leave unchanged.", "format": "int64" }, - "environment_kind": { + "environments": { "type": [ - "string", - "null" - ], - "description": "Reassign the runner binding: `byoc` (with environment_id) or empty string to reset to automatic selection. Omit (null) to leave the current binding unchanged." - }, - "environment_id": { - "type": [ - "string", + "array", "null" ], - "description": "Runner ID paired with environment_kind=byoc. Omit (null) to leave the current binding unchanged." + "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." }, "allow_insecure_oauth_http": { "type": [ @@ -53153,29 +53719,6 @@ "server_id" ] }, - "MCPToolInfo": { - "type": "object", - "description": "Metadata for one tool exposed by an MCP server.", - "properties": { - "name": { - "type": "string", - "description": "Tool name." - }, - "description": { - "type": "string", - "description": "Tool description." - }, - "input_schema": { - "type": "object", - "additionalProperties": true, - "description": "JSON Schema describing the tool's input parameters." - } - }, - "required": [ - "name", - "description" - ] - }, "ManualRunRuleResult": { "type": "object", "description": "Result of manually running an Automation rule outside its schedule.", @@ -53511,7 +54054,7 @@ "pinned_at": { "type": "integer", "format": "int64", - "description": "Caller's per-user pin timestamp in milliseconds; 0 means not pinned." + "description": "Caller's per-user pin time as a Unix timestamp in milliseconds; 0 means not pinned." }, "last_event_at": { "type": "integer", @@ -53618,7 +54161,7 @@ }, "asc": { "type": "boolean", - "description": "Ascending order when true, descending when false; also applies when `orderby` is omitted (sorted by `updated_at`)." + "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", @@ -53778,7 +54321,7 @@ }, "skill_name": { "type": "string", - "description": "Skill name, unique within the account." + "description": "Skill name, unique within its scope (account-wide or within one team)." }, "description": { "type": "string", @@ -53818,6 +54361,13 @@ }, "description": "Required tools (builtin or `mcp:server/tool`)." }, + "venues": { + "type": "array", + "items": { + "type": "string" + }, + "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." + }, "s3_key": { "type": "string", "description": "Object-storage key of the skill zip." @@ -54044,7 +54594,8 @@ "ts": { "type": "integer", "format": "int64", - "description": "Unix timestamp in milliseconds of the session start time. Optional; disambiguates when a session ID has been reused across different time windows." + "description": "Unix timestamp in milliseconds of the session start time. Optional; disambiguates when a session ID has been reused across different time windows.", + "exclusiveMinimum": 0 } } }, @@ -54082,16 +54633,18 @@ "type": "string", "enum": [ "browser", - "android", "ios", - "miniprogram", + "android", "react-native", "flutter", "kotlin-multiplatform", "roku", - "unity" + "unity", + "miniprogram", + "harmony", + "electron" ], - "description": "SDK platform that recorded the session. Platform identifier, one of `browser`, `android`, `ios`, `miniprogram`, `react-native`, `flutter`, `kotlin-multiplatform`, `roku`, `unity`." + "description": "SDK platform that recorded the session. 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 |" }, "start": { "type": "integer", @@ -54112,16 +54665,18 @@ "type": "string", "enum": [ "browser", - "android", "ios", - "miniprogram", + "android", "react-native", "flutter", "kotlin-multiplatform", "roku", - "unity" + "unity", + "miniprogram", + "harmony", + "electron" ], - "description": "SDK platform that recorded the view. Platform identifier, one of `browser`, `android`, `ios`, `miniprogram`, `react-native`, `flutter`, `kotlin-multiplatform`, `roku`, `unity`." + "description": "SDK platform that recorded the view. 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 |" }, "view_id": { "type": "string", @@ -54141,11 +54696,11 @@ }, "container_source": { "type": "string", - "description": "SDK platform of the container app, when this view is embedded (e.g. a WebView inside a native app)." + "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." }, "container_view_id": { "type": "string", - "description": "View ID of the containing view, when this view is embedded." + "description": "View ID of the containing view, when this view is embedded. Omitted when the view is not embedded." }, "server_time_delta": { "type": "integer", @@ -54193,13 +54748,16 @@ "description": "Replay metadata for a session: the application, device, session bounds, and every recorded view.", "properties": { "application": { - "$ref": "#/components/schemas/RumReplayApplication" + "$ref": "#/components/schemas/RumReplayApplication", + "description": "Application the session belongs to." }, "device": { - "$ref": "#/components/schemas/RumReplayDevice" + "$ref": "#/components/schemas/RumReplayDevice", + "description": "Device that recorded the session." }, "session": { - "$ref": "#/components/schemas/RumReplaySession" + "$ref": "#/components/schemas/RumReplaySession", + "description": "Session bounds and state." }, "views": { "type": "array", @@ -54239,7 +54797,8 @@ "ts": { "type": "integer", "format": "int64", - "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), seeks to the most recent full-snapshot segment at or before this time instead of starting from the beginning.", + "exclusiveMinimum": 0 }, "url_mode": { "type": "boolean", @@ -54368,7 +54927,7 @@ }, "name": { "type": "string", - "description": "Display name of the referencing custom form." + "description": "Human label of the referencing custom form's type (a Chinese label, e.g. `解决故障` for the resolve form)." }, "href": { "type": "string", @@ -55292,7 +55851,18 @@ "format": "int64", "description": "Last update time as a Unix timestamp in seconds." } - } + }, + "required": [ + "comment_type_id", + "account_id", + "name", + "color", + "position", + "creator_id", + "updated_by", + "created_at", + "updated_at" + ] }, "ListIncidentCommentTypesRequest": { "type": "object", @@ -55314,7 +55884,7 @@ }, "CreateIncidentCommentTypeRequest": { "type": "object", - "description": "Parameters for creating a comment type.", + "description": "Parameters for creating a comment type. At most 10 comment types per account.", "required": [ "name", "color" @@ -55344,7 +55914,11 @@ "item": { "$ref": "#/components/schemas/IncidentCommentTypeItem" } - } + }, + "required": [ + "comment_type_id", + "item" + ] }, "UpdateIncidentCommentTypeRequest": { "type": "object", @@ -55634,7 +56208,7 @@ "limit": { "type": "integer", "format": "int64", - "minimum": 1, + "minimum": 0, "maximum": 200, "default": 50, "description": "Page size, at most 200. Defaults to 50." @@ -57874,7 +58448,7 @@ "properties": { "id": { "type": "integer", - "format": "uint64", + "format": "int64", "description": "Internal row ID." }, "account_id": { @@ -58642,7 +59216,7 @@ }, "id": { "type": "integer", - "format": "uint64", + "format": "int64", "description": "Internal auto-increment row ID. Not stable across a history revert — reverting reinserts rows with new IDs." }, "deleted_at": { @@ -58953,7 +59527,7 @@ }, "team_name": { "type": "string", - "description": "Display name of the owning team (team scope only); empty for account scope." + "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", @@ -59114,7 +59688,7 @@ }, "query": { "type": "string", - "description": "Case-insensitive substring filter over pack ID, scope, and team name.", + "description": "Case-insensitive substring filter over pack ID, scope, scope ID/account ID, and team name.", "maxLength": 128 }, "team_ids": { @@ -59172,8 +59746,7 @@ "description": "Destination scope; omit for a no-op that returns the current pack.", "enum": [ "account", - "team", - null + "team" ] }, "scope_id": { @@ -59225,11 +59798,11 @@ }, "p": { "type": "integer", - "description": "Page number, 1-based." + "description": "Page number, 1-based. Accepted but currently ignored — the response always contains the full file list." }, "limit": { "type": "integer", - "description": "Page size." + "description": "Page size. Accepted but currently ignored — the response always contains the full file list." } } }, @@ -59264,7 +59837,7 @@ }, "content_b64": { "type": "string", - "description": "Base64-encoded file content; must decode to valid UTF-8 text." + "description": "Base64-encoded file content; must decode to valid UTF-8 text (binary is rejected). Per-file limit 1 MiB." }, "content_type": { "type": "string", @@ -59408,6 +59981,503 @@ "description": "Non-blocking warnings after deletion; `code=still_referenced_by` means the (force-)deleted file is still @ref-referenced by other files in the pack (`refs` lists the referrers). Absent when there are no warnings (omitempty)." } } + }, + "FeedDetailAlertMerge": { + "type": "object", + "title": "a_merge", + "description": "Detail payload for `a_merge`: an alert merged into an incident.", + "properties": { + "comment": { + "type": "string", + "description": "Comment recorded with the merge. Omitted when empty." + }, + "target_incident": { + "$ref": "#/components/schemas/IncidentShort", + "description": "Incident the alerts were merged into. Omitted when not recorded." + }, + "source_alerts": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AlertShort" + }, + "description": "Source alerts merged into the target incident. Omitted when empty." + }, + "owner_id": { + "type": "integer", + "format": "int64", + "description": "New owner member ID set on the target incident. Omitted when unchanged." + }, + "title": { + "type": "string", + "description": "New title set on the target incident. Omitted when unchanged." + } + } + }, + "AlertShort": { + "type": "object", + "description": "Brief alert reference.", + "properties": { + "alert_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "Alert ID (ObjectID hex string)." + }, + "title": { + "type": "string", + "description": "Alert title, resolved at read time. Omitted when empty." + } + } + }, + "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": { + "type": "boolean", + "description": "When true, repeated events merge into the existing alert; when false, every event creates a separate alert. Defaults to true." + }, + "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." + } + } + }, + "StatusPageInfoResponse": { + "type": "object", + "description": "Status page detail returned by `GET /status-page/info`: the full page configuration plus feature flags.", + "allOf": [ + { + "$ref": "#/components/schemas/StatusPageItem" + }, + { + "type": "object", + "properties": { + "managed_domain_feature_enabled": { + "type": "boolean", + "description": "Whether the managed custom-domain feature is enabled for this page. `true` for public pages, always `false` for internal pages." + } + }, + "required": [ + "managed_domain_feature_enabled" + ] + } + ] + }, + "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": { + "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." + }, + "status": { + "type": "string", + "enum": [ + "investigating", + "identified", + "monitoring", + "resolved", + "scheduled", + "ongoing", + "completed" + ], + "description": "Change status the template maps to. Incidents use `investigating`/`identified`/`monitoring`/`resolved`; maintenances use `scheduled`/`ongoing`/`completed`." + }, + "description": { + "type": "string", + "description": "Template body text (Markdown)." + } + } + }, + "StatusPageMessageTemplate": { + "type": "object", + "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.", + "properties": { + "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." + }, + "messages": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Notification text (Markdown) per event status. Keys are change statuses valid for the template's `type` (for example `investigating` or `resolved` for incidents); the value is the text used when the event reaches that status." + } + } + }, + "ListStatusPageTemplatesResponse": { + "type": "object", + "description": "Event template list. Item shape depends on the requested `type`: predefined event templates for `pre_defined`, message templates for `message`.", + "required": [ + "items" + ], + "properties": { + "items": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/StatusPagePreDefinedTemplate" + }, + { + "$ref": "#/components/schemas/StatusPageMessageTemplate" + } + ] + }, + "description": "Templates of the requested category." + } + } + }, + "FeedDetailAlertUpdate": { + "type": "object", + "title": "a_update", + "description": "Detail payload for `a_update`: severity/status after the update.", + "properties": { + "severity": { + "$ref": "#/components/schemas/FeedSeverity" + }, + "status": { + "$ref": "#/components/schemas/FeedSeverity" + } + } + }, + "FeedDetailAlertMuteBySilence": { + "type": "object", + "title": "a_m_silence", + "description": "Detail payload for `a_m_silence`: the alert was muted by a silence rule.", + "properties": { + "rule_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "Silence rule ID that muted the alert. Omitted when empty." + }, + "rule_name": { + "type": "string", + "description": "Silence rule name, resolved at read time. Omitted when empty." + } + } + }, + "FeedDetailAlertMuteByInhibit": { + "type": "object", + "title": "a_m_inhibit", + "description": "Detail payload for `a_m_inhibit`: the alert was inhibited by an inhibit rule because of a source alert.", + "properties": { + "rule_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "Inhibit rule ID that muted the alert. Omitted when empty." + }, + "rule_name": { + "type": "string", + "description": "Inhibit rule name, resolved at read time. Omitted when empty." + }, + "source_alert_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "ID of the source alert that triggered the inhibition. Omitted when empty." + }, + "source_alert_title": { + "type": "string", + "description": "Title of the source alert, resolved at read time. Omitted when empty." + } + } + }, + "FeedDetailAlertMuteByFlapping": { + "type": "object", + "title": "a_m_flapping", + "description": "Detail payload for `a_m_flapping` (historical): the alert was muted by flapping detection.", + "properties": { + "max_changes": { + "type": "integer", + "description": "State-change count threshold that triggered flapping detection. Omitted when zero." + }, + "in_secs": { + "type": "integer", + "description": "Window in seconds over which the state changes were counted. Omitted when zero." + }, + "mute_secs": { + "type": "integer", + "description": "Mute duration in seconds. Omitted when zero." + } + } + }, + "FeedDetailAlertAck": { + "type": "object", + "title": "a_ack", + "description": "Detail payload for `a_ack` (historical). No fields.", + "properties": {} + }, + "FeedDetailAlertUnack": { + "type": "object", + "title": "a_unack", + "description": "Detail payload for `a_unack` (historical). No fields.", + "properties": {} + }, + "DSTencentCLSConfig": { + "type": "object", + "description": "Tencent CLS (Cloud Log Service) credential configuration.", + "required": [ + "secret_id" + ], + "properties": { + "secret_id": { + "type": "string", + "description": "Tencent Cloud API SecretId. Always required (create and update). Supports `${env:VAR}` references resolved on the edge." + }, + "secret_key": { + "type": "string", + "description": "Tencent Cloud API SecretKey. Required on create; on update, omit to keep the stored key. Supports `${env:VAR}` references. Never returned by read APIs: responses carry an empty string unless the stored value is an `${env:...}` reference." + } + } + }, + "SLSProject": { + "type": "object", + "description": "An Aliyun SLS project.", + "required": [ + "projectName", + "description", + "status", + "owner", + "region", + "createTime", + "lastModifyTime" + ], + "properties": { + "projectName": { + "type": "string", + "description": "Project name." + }, + "description": { + "type": "string", + "description": "Project description." + }, + "status": { + "type": "string", + "description": "Project status, e.g. `Normal`." + }, + "owner": { + "type": "string", + "description": "Owner Aliyun account ID; empty when not returned by SLS." + }, + "region": { + "type": "string", + "description": "Region ID, e.g. `cn-shanghai`." + }, + "createTime": { + "type": "string", + "description": "Creation time, Unix seconds rendered as a string, e.g. `\"1524539357\"`." + }, + "lastModifyTime": { + "type": "string", + "description": "Last modification time, Unix seconds rendered as a string." + }, + "dataRedundancyType": { + "type": "string", + "enum": [ + "LRS", + "ZRS" + ], + "description": "Data redundancy type: `LRS` = locally redundant storage, `ZRS` = zone-redundant storage. Omitted when not set." + }, + "location": { + "type": "string", + "description": "Storage location, e.g. `cn-beijing-b`. Omitted when not set." + } + } + }, + "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.", + "properties": { + "set": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Keys to insert or replace." + }, + "delete": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Keys to remove." + } + } + }, + "TargetInventoryServiceMapCapability": { + "type": "object", + "description": "ServiceMap capability and live status of a target's host.", + "required": [ + "enabled", + "status", + "snapshot_ready", + "authoritative", + "graph_available", + "node_count", + "edge_count" + ], + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether ServiceMap collection is enabled on the agent." + }, + "status": { + "type": "string", + "enum": [ + "active", + "degraded", + "stale", + "initializing", + "disabled", + "unsupported", + "no_data" + ], + "description": "ServiceMap collection status of the host.\n\n| Value | Meaning |\n|---|---|\n| `active` | Collection healthy: a fresh snapshot exists with no degradation. |\n| `degraded` | Collecting but quality is impaired: health reports are newer than the snapshot, the snapshot is truncated/degraded, or collection is failing. |\n| `stale` | A snapshot exists but is outdated (no update within 2x the report interval). |\n| `initializing` | The agent reported the capability but the first snapshot is not ready yet. |\n| `disabled` | Topology collection is disabled on this host. |\n| `unsupported` | The agent or kernel does not support collection. |\n| `no_data` | No snapshot or health data received yet. |" + }, + "capability_status": { + "type": "string", + "description": "Agent-reported capability status, e.g. `running`, `disabled`, `starting`, `failed`, `unsupported`. Omitted when the agent has not reported one." + }, + "capture_mode": { + "type": "string", + "description": "Capture mode, e.g. `ebpf` or `polling`. Omitted when unknown." + }, + "report_interval_ms": { + "type": "integer", + "format": "int64", + "description": "Configured reporting interval in milliseconds. Omitted when unknown." + }, + "snapshot_ready": { + "type": "boolean", + "description": "True if the agent has produced at least one full snapshot." + }, + "authoritative": { + "type": "boolean", + "description": "True if the current status derives from an authoritative graph snapshot." + }, + "graph_available": { + "type": "boolean", + "description": "True if a current graph can be fetched for this host right now." + }, + "freshness_status": { + "type": "string", + "enum": [ + "fresh", + "stale", + "unknown" + ], + "description": "Freshness classification of the host's graph. `fresh` = the latest snapshot was received within 2x the report interval; `stale` = no new snapshot within that window; `unknown` = not yet classified. Omitted when unknown." + }, + "max_age_ms": { + "type": "integer", + "format": "int64", + "description": "Maximum snapshot age in milliseconds tolerated before it counts as stale. Omitted when not applicable." + }, + "observed_at_ms": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp in milliseconds when the agent last observed graph generation. Omitted when unknown." + }, + "received_at_ms": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp in milliseconds when the server last received a snapshot. Omitted when unknown." + }, + "node_count": { + "type": "integer", + "description": "Number of nodes in the host's current graph." + }, + "edge_count": { + "type": "integer", + "description": "Number of edges in the host's current graph." + }, + "reason_codes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Machine-readable codes explaining the current capability status. Omitted when empty." + }, + "error_code": { + "type": "string", + "description": "Set to `status_unavailable` when the live status could not be read; other fields then fall back to inventory-derived values. Omitted otherwise." + } + } + }, + "TargetInventoryServiceMapCoverage": { + "type": "object", + "description": "ServiceMap status-fetch coverage for a targets page.", + "required": [ + "requested", + "succeeded", + "failed", + "partial" + ], + "properties": { + "requested": { + "type": "integer", + "description": "Items on this page that carry ServiceMap data." + }, + "succeeded": { + "type": "integer", + "description": "Items whose live ServiceMap status was read successfully." + }, + "failed": { + "type": "integer", + "description": "Items whose live ServiceMap status read failed (`servicemap.error_code` set)." + }, + "partial": { + "type": "boolean", + "description": "True when at least one item's status read failed." + } + } + }, + "RoleDeleteRequest": { + "type": "object", + "required": [ + "role_id" + ], + "description": "Request to delete a role.", + "properties": { + "role_id": { + "type": "integer", + "format": "uint64", + "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 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." + } + } } } } diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json index 3b107d0b..263d657d 100644 --- a/api-reference/openapi.zh.json +++ b/api-reference/openapi.zh.json @@ -219,6 +219,7 @@ "incident_id": "69da451ef77b1b51f40e83ee", "account_id": 2451002751131, "channel_id": 2551105804131, + "team_id": 2477033058131, "integration_id": 2490562293131, "integration_ids": [ 2490562293131 @@ -469,6 +470,7 @@ "incident_id": "69da451ef77b1b51f40e83ee", "account_id": 2451002751131, "channel_id": 2551105804131, + "team_id": 2477033058131, "integration_id": 2490562293131, "integration_ids": [ 2490562293131 @@ -620,6 +622,7 @@ "incident_id": "69da451ef77b1b51f40e83ee", "account_id": 2451002751131, "channel_id": 2551105804131, + "team_id": 2477033058131, "integration_id": 2490562293131, "integration_ids": [ 2490562293131 @@ -799,7 +802,7 @@ { "event_id": "69da451df77b1b51f40e83df", "alert_id": "69da451df77b1b51f40e83de", - "title": "CPU 使用率 > 90%", + "title": "CPU usage > 90%", "event_severity": "Critical", "event_status": "Critical", "event_time": 1712650000, @@ -3205,8 +3208,8 @@ }, "example": { "channel_id": 1001, - "channel_name": "生产告警（v2）", - "description": "更新后的描述" + "channel_name": "Production Alerts (v2)", + "description": "Updated description" } } } @@ -3217,7 +3220,7 @@ "post": { "operationId": "channelDelete", "summary": "删除协作空间", - "description": "删除协作空间及其所有关联配置。", + "description": "删除协作空间。仅 `disabled` 状态的协作空间可删除，其下的分派、静默、排除和抑制策略会一并删除。当仍有集成路由引用该空间时调用失败。", "tags": [ "On-call/协作空间" ], @@ -3287,7 +3290,7 @@ "post": { "operationId": "channelEnable", "summary": "启用协作空间", - "description": "启用已禁用的协作空间以恢复故障路由。", + "description": "启用协作空间以恢复故障路由。仅 `disabled` 状态的协作空间可启用。", "tags": [ "On-call/协作空间" ], @@ -3357,7 +3360,7 @@ "post": { "operationId": "channelDisable", "summary": "禁用协作空间", - "description": "禁用协作空间以停止故障路由，而不删除该空间。", + "description": "禁用协作空间以停止故障路由（不删除）；禁用后新事件会被直接丢弃。仅 `enabled` 状态的协作空间可禁用。", "tags": [ "On-call/协作空间" ], @@ -3708,7 +3711,7 @@ "post": { "operationId": "channelSilenceRuleDelete", "summary": "删除静默策略", - "description": "删除指定的静默策略。", + "description": "删除静默策略。仅 `disabled` 状态的策略可删除。", "tags": [ "On-call/协作空间" ], @@ -3779,7 +3782,7 @@ "post": { "operationId": "channelSilenceRuleEnable", "summary": "启用静默策略", - "description": "启用已禁用的静默策略。", + "description": "启用已禁用的静默策略。仅 `disabled` 状态的策略可启用。", "tags": [ "On-call/协作空间" ], @@ -3850,7 +3853,7 @@ "post": { "operationId": "channelSilenceRuleDisable", "summary": "禁用静默策略", - "description": "禁用静默策略而不删除。", + "description": "禁用静默策略而不删除。仅 `enabled` 状态的策略可禁用。", "tags": [ "On-call/协作空间" ], @@ -4209,7 +4212,7 @@ "post": { "operationId": "channelInhibitRuleDelete", "summary": "删除抑制策略", - "description": "删除指定的抑制策略。", + "description": "删除抑制策略。仅 `disabled` 状态的策略可删除。", "tags": [ "On-call/协作空间" ], @@ -4280,7 +4283,7 @@ "post": { "operationId": "channelInhibitRuleEnable", "summary": "启用抑制策略", - "description": "启用已禁用的抑制策略。", + "description": "启用已禁用的抑制策略。仅 `disabled` 状态的策略可启用。", "tags": [ "On-call/协作空间" ], @@ -4351,7 +4354,7 @@ "post": { "operationId": "channelInhibitRuleDisable", "summary": "禁用抑制策略", - "description": "禁用抑制策略而不删除。", + "description": "禁用抑制策略而不删除。仅 `enabled` 状态的策略可禁用。", "tags": [ "On-call/协作空间" ], @@ -4687,7 +4690,7 @@ "post": { "operationId": "channelUnsubscribeRuleDelete", "summary": "删除排除规则", - "description": "删除指定的排除规则。", + "description": "删除排除规则。仅 `disabled` 状态的规则可删除。", "tags": [ "On-call/协作空间" ], @@ -4758,7 +4761,7 @@ "post": { "operationId": "channelUnsubscribeRuleEnable", "summary": "启用排除规则", - "description": "启用已禁用的排除规则。", + "description": "启用已禁用的排除规则。仅 `disabled` 状态的规则可启用。", "tags": [ "On-call/协作空间" ], @@ -4829,7 +4832,7 @@ "post": { "operationId": "channelUnsubscribeRuleDisable", "summary": "禁用排除规则", - "description": "禁用排除规则而不删除。", + "description": "禁用排除规则而不删除。仅 `enabled` 状态的规则可禁用。", "tags": [ "On-call/协作空间" ], @@ -5291,7 +5294,7 @@ "post": { "operationId": "channelEscalateRuleDelete", "summary": "删除分派策略", - "description": "删除指定的分派策略。", + "description": "删除分派策略。仅 `disabled` 状态的策略可删除。", "tags": [ "On-call/协作空间" ], @@ -5362,7 +5365,7 @@ "post": { "operationId": "channelEscalateRuleEnable", "summary": "启用分派策略", - "description": "启用已禁用的分派策略。", + "description": "启用已禁用的分派策略。仅 `disabled` 状态的策略可启用。", "tags": [ "On-call/协作空间" ], @@ -5433,7 +5436,7 @@ "post": { "operationId": "channelEscalateRuleDisable", "summary": "禁用分派策略", - "description": "禁用分派策略而不删除。", + "description": "禁用分派策略而不删除。仅 `enabled` 状态的策略可禁用。", "tags": [ "On-call/协作空间" ], @@ -5857,14 +5860,13 @@ "data": { "total": 1, "has_next_page": false, - "search_after_ctx": "", "items": [ { "alert_id": "663a1b2c3d4e5f6789abcdef", "integration_id": 10001, "channel_id": 20001, "account_id": 10023, - "title": "CPU 使用率 > 90%", + "title": "CPU usage > 90%", "alert_severity": "Critical", "alert_status": "Critical", "start_time": 1712650000, @@ -5878,7 +5880,7 @@ "updated_at": 1712655000, "integration_name": "Prometheus", "integration_type": "prometheus", - "channel_name": "生产", + "channel_name": "Production", "event_cnt": 3 } ] @@ -5957,7 +5959,7 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "alert_id": "663a1b2c3d4e5f6789abcdef", - "title": "CPU 使用率 > 90%", + "title": "CPU usage > 90%", "alert_severity": "Critical", "alert_status": "Critical", "start_time": 1712650000, @@ -5999,7 +6001,7 @@ "post": { "operationId": "alert-read-list-by-ids", "summary": "批量查询告警", - "description": "通过多个告警 ID 一次性返回多条告警详情。", + "description": "通过多个告警 ID 一次性返回多条告警详情。 注意：本接口不分页——`total`、`has_next_page` 恒为 `0`/`false`，`search_after_ctx` 不会返回。", "tags": [ "On-call/告警管理" ], @@ -6033,12 +6035,12 @@ "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { - "total": 1, + "total": 0, "has_next_page": false, "items": [ { "alert_id": "663a1b2c3d4e5f6789abcdef", - "title": "CPU 使用率 > 90%" + "title": "CPU usage > 90%" } ] } @@ -6121,7 +6123,7 @@ { "event_id": "663a1b2c3d4e5f6789abc001", "alert_id": "663a1b2c3d4e5f6789abcdef", - "title": "CPU 使用率 > 90%", + "title": "CPU usage > 90%", "event_severity": "Critical", "event_status": "Critical", "event_time": 1712650000, @@ -6173,7 +6175,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` 过滤特定动态类型（如 `alert_comment`、`alert_merge`）。", + "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": "查询告警动态" @@ -6206,9 +6208,9 @@ "items": [ { "ref_id": "663a1b2c3d4e5f6789abcdef", - "type": "alert_comment", + "type": "a_comm", "detail": { - "comment": "正在排查中。" + "comment": "Investigating now." }, "creator_id": 80011, "created_at": 1712651000 @@ -6572,7 +6574,7 @@ }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": {} + "data": null } } } @@ -6673,7 +6675,7 @@ { "event_id": "663a1b2c3d4e5f6789abc001", "alert_id": "663a1b2c3d4e5f6789abcdef", - "title": "CPU 使用率 > 90%", + "title": "CPU usage > 90%", "event_severity": "Critical", "event_time": 1712650000 } @@ -6765,7 +6767,7 @@ "duration": 132, "status": "success", "status_code": 200, - "event_time": "2026-04-12T13:31:11.357472+08:00" + "event_time": "2026-04-12 13:31:11.357472" } ], "search_after_ctx": "eyJldmVudF90aW1lIjoiMjAyNi0wNC0xMlQxMzoxNToyNi4zODI1NDcrMDg6MDAiLCJldmVudF9pZCI6IjIwMjYwNDEybUdzeFAzZHJwRmZzNFpDUWQycFNEcCJ9", @@ -6860,7 +6862,7 @@ "status_code": 200, "response_headers": "{\"Content-Type\":\"application/json\"}", "response_body": "{\"ok\":true}", - "event_time": "2026-04-12T13:31:11.357472+08:00", + "event_time": "2026-04-12 13:31:11.357472", "ref_title": "High CPU Usage on host-01", "channel_name": "Production Alerts" } @@ -8985,7 +8987,7 @@ "account_id": 10023, "team_id": 0, "template_id": "6605a1b2c3d4e5f6a7b8c9d0", - "template_name": "生产环境默认模板", + "template_name": "Prod incident default", "description": "Default template for production incidents.", "email": "Incident {{ .IncidentName }} on {{ .Severity }}", "sms": "[Flashduty] {{ .IncidentName }} — {{ .Severity }}", @@ -9084,7 +9086,7 @@ "account_id": 10023, "team_id": 0, "template_id": "6605a1b2c3d4e5f6a7b8c9d0", - "template_name": "生产环境默认模板", + "template_name": "Prod incident default", "description": "Default template for production incidents.", "email": "Incident {{ .IncidentName }} on {{ .Severity }}", "sms": "[Flashduty] {{ .IncidentName }} — {{ .Severity }}", @@ -9183,7 +9185,7 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "template_id": "6605a1b2c3d4e5f6a7b8c9d0", - "template_name": "生产环境默认模板" + "template_name": "Prod incident default" } } } @@ -9211,8 +9213,8 @@ }, "example": { "team_id": 0, - "template_name": "生产环境默认模板", - "description": "生产环境故障的默认模板。", + "template_name": "Prod incident default", + "description": "Default template for production incidents.", "email": "Incident {{ .IncidentName }} on {{ .Severity }}", "sms": "[Flashduty] {{ .IncidentName }} — {{ .Severity }}" } @@ -9288,8 +9290,8 @@ }, "example": { "template_id": "6605a1b2c3d4e5f6a7b8c9d0", - "template_name": "生产环境默认模板", - "description": "已更新的描述。", + "template_name": "Prod incident default", + "description": "Updated description.", "email": "Incident {{ .IncidentName }} on {{ .Severity }}", "sms": "[Flashduty] {{ .IncidentName }} — {{ .Severity }}" } @@ -9553,7 +9555,7 @@ "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`（正则，须包含命名分组 `result`）和 `g_json`（GJson 路径）二选一。\n- `kind: composition`：`template` 使用 Go text/template 语法，可引用 `labels.*` 键。\n- `kind: mapping`：`mapping_type` 为 `schema`（默认）或 `api`；分别提供 `schema_id` 或 `api_id`。\n- `kind: drop`：`drop_labels` 列出要删除的标签键名。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", + "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": "创建或替换富化规则" @@ -9617,6 +9619,14 @@ "pattern": "(?Pprod|staging|dev)", "override": true } + }, + { + "kind": "composition", + "settings": { + "result_label": "full_env", + "template": "{{.Labels.region}}-{{.Labels.environment}}", + "override": false + } } ] } @@ -9667,8 +9677,8 @@ "items": [ { "schema_id": "665f1a2b3c4d5e6f7a8b9c01", - "schema_name": "CMDB 查询", - "description": "用 CMDB 数据富化告警", + "schema_name": "CMDB Lookup", + "description": "Enrich alerts with CMDB data", "source_labels": [ "host" ], @@ -9754,8 +9764,8 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "schema_id": "665f1a2b3c4d5e6f7a8b9c01", - "schema_name": "CMDB 查询", - "description": "用 CMDB 数据富化告警", + "schema_name": "CMDB Lookup", + "description": "Enrich alerts with CMDB data", "source_labels": [ "host" ], @@ -9811,7 +9821,7 @@ "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-z][a-z0-9_]{0,39}$`（小写）。\n- `source_labels` 与 `result_labels` 不得重叠。\n- 账户最多可创建 20 个映射规则。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", + "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": "创建映射规则" @@ -9841,7 +9851,7 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "schema_id": "665f1a2b3c4d5e6f7a8b9c01", - "schema_name": "CMDB 查询" + "schema_name": "CMDB Lookup" } } } @@ -9868,8 +9878,8 @@ "$ref": "#/components/schemas/MappingSchemaCreateRequest" }, "example": { - "schema_name": "CMDB 查询", - "description": "用 CMDB 数据富化告警", + "schema_name": "CMDB Lookup", + "description": "Enrich alerts with CMDB data", "source_labels": [ "host" ], @@ -9948,8 +9958,8 @@ }, "example": { "schema_id": "665f1a2b3c4d5e6f7a8b9c01", - "schema_name": "CMDB 查询 v2", - "description": "更新后的描述" + "schema_name": "CMDB Lookup v2", + "description": "Updated description" } } } @@ -10195,7 +10205,7 @@ { "host": "server02", "owner": "bob", - "team": "平台", + "team": "platform", "service": "gateway" } ] @@ -10407,16 +10417,48 @@ "requestBody": { "required": true, "content": { - "application/json": { + "multipart/form-data": { "schema": { - "$ref": "#/components/schemas/MappingDataUploadRequest" - }, - "example": { - "schema_id": "665f1a2b3c4d5e6f7a8b9c01" + "type": "object", + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "CSV 文件，最大 100 MB。表头必须包含 schema 的全部 source/result label 名称。" + } + }, + "required": [ + "file" + ] } } } - } + }, + "parameters": [ + { + "name": "schema_id", + "in": "query", + "required": true, + "schema": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$" + }, + "description": "目标映射 schema 的 ID（ObjectID hex）。", + "example": "665f1a2b3c4d5e6f7a8b9c01" + }, + { + "name": "do_not_truncate_first", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "TRUE" + ] + }, + "description": "传 `TRUE`（大小写不敏感）时追加导入；不传且 schema 已有数据时，服务端先清空再导入。" + } + ] } }, "/enrichment/mapping/data/download": { @@ -10436,28 +10478,15 @@ }, "responses": { "200": { - "description": "成功", + "description": "成功。返回 CSV 附件流，不是 JSON envelope。", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/CsvFileResponse" - } - } - } - ] + "type": "string", + "format": "binary", + "description": "CSV 文件流（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename=.csv`）。首行为表头，按 schema 的 source_labels + result_labels 顺序排列；之后每行一条映射数据。" }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": "host,owner,team,service\nserver01,alice,sre,api\n" - } + "example": "host,owner,team\nserver01,alice,sre\nserver02,bob,backend\n" } } }, @@ -10532,10 +10561,10 @@ { "api_id": "665f1a2b3c4d5e6f7a8b9c02", "api_name": "CMDB API", - "description": "查询 CMDB 主机元数据", + "description": "Query CMDB for host metadata", "url": "https://cmdb.example.com/api/lookup", "headers": { - "X-Token": "***" + "Authorization": "Bearer eyJhbGciOiJIUzI1NiJ9.example-token" }, "timeout": 2, "retry_count": 1, @@ -10726,7 +10755,7 @@ }, "example": { "api_name": "CMDB API", - "description": "查询 CMDB 主机元数据", + "description": "Query CMDB for host metadata", "url": "https://cmdb.example.com/api/lookup", "headers": { "X-Token": "mytoken" @@ -11121,12 +11150,12 @@ "items": [ { "incident_id": "6a86b5d6f72de50ae1ce2ffb", - "title": "prod-web-01 CPU 使用率超过 90%", - "description": "CPU 使用率连续 5 分钟超过阈值", + "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_name": "SRE Team", "channel_id": 3047621227131, - "channel_name": "生产环境告警", + "channel_name": "Production Alerts", "progress": "Closed", "severity": "Critical", "created_at": 1787213270, @@ -11135,9 +11164,9 @@ "alert_event_cnt": 5, "closed_by": "manually", "creator_id": 2477273692131, - "creator_name": "张三", + "creator_name": "alice", "closer_id": 2477273692131, - "closer_name": "张三", + "closer_name": "alice", "seconds_to_ack": 14, "seconds_to_close": 1830, "engaged_seconds": 1816, @@ -11147,8 +11176,8 @@ "person_id": 2477273692131, "assigned_at": 1787213270, "acknowledged_at": 1787213284, - "person_name": "张三", - "email": "zhangsan@example.com" + "person_name": "alice", + "email": "alice@example.com" } ], "assigned_to": { @@ -11157,7 +11186,7 @@ "type": "assign", "assigned_at": 1787213270, "id": "b8tyUoRvCv4wsPndFRpmNL", - "escalate_rule_name": "值班策略" + "escalate_rule_name": "On-call Policy" }, "notifications": 2, "interruptions": 1, @@ -11212,7 +11241,7 @@ "post": { "operationId": "insightIncidentExport", "summary": "导出洞察故障", - "description": "将故障分析列表以 CSV 文件形式导出。CSV 列名和格式化值优先使用请求语言，其次使用成员语言和账户语言。响应为 CSV 字节流（`Content-Disposition: attachment`），不是 JSON 响应包。", + "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` 时导出全部列。", "tags": [ "On-call/分析看板" ], @@ -11225,28 +11254,15 @@ }, "responses": { "200": { - "description": "成功", + "description": "Success", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/EmptyResponse" - } - } - } - ] + "type": "string", + "format": "binary", + "description": "CSV 字节流（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename=incident_export_yyyyMMdd_HHmmss.csv`）。首行为本地化列名。列默认为完整故障字段集，或由 `export_fields` 指定。" }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": {} - } + "example": "incident_id,title,severity,created_at\n6a86b5d6f72de50ae1ce2ffb,CPU usage above 90%,Critical,2026-01-01 10:00:00 +0800 CST\n" } } }, @@ -11399,7 +11415,7 @@ "post": { "operationId": "insightChannelExport", "summary": "导出协作空间洞察", - "description": "将协作空间洞察指标以 CSV 文件形式导出。CSV 列名和格式化值优先使用请求语言，其次使用成员语言和账户语言。响应为 CSV 字节流（`Content-Disposition: attachment`），不是 JSON 响应包。", + "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 也可传入，但导出为空列。", "tags": [ "On-call/分析看板" ], @@ -11412,28 +11428,15 @@ }, "responses": { "200": { - "description": "成功", + "description": "Success", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/EmptyResponse" - } - } - } - ] + "type": "string", + "format": "binary", + "description": "CSV 字节流（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename=channel_export_yyyyMMdd_HHmmss.csv`）。首行为本地化列名。列默认为完整字段集，或由 `export_fields` 指定。" }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": {} - } + "example": "channel_id,channel_name,total_incident_cnt,total_incidents_closed\n4321322010131,Production Alerts,12,10\n" } } }, @@ -11581,7 +11584,7 @@ "post": { "operationId": "insightTeamExport", "summary": "导出团队洞察", - "description": "将团队洞察指标以 CSV 文件形式导出。CSV 列名和格式化值优先使用请求语言，其次使用成员语言和账户语言。响应为 CSV 字节流（`Content-Disposition: attachment`），不是 JSON 响应包。", + "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 也可传入，但导出为空列。", "tags": [ "On-call/分析看板" ], @@ -11594,28 +11597,15 @@ }, "responses": { "200": { - "description": "成功", + "description": "Success", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/EmptyResponse" - } - } - } - ] + "type": "string", + "format": "binary", + "description": "CSV 字节流（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename=team_export_yyyyMMdd_HHmmss.csv`）。首行为本地化列名。列默认为完整字段集，或由 `export_fields` 指定。" }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": {} - } + "example": "team_id,team_name,total_incident_cnt,total_incidents_closed\n4295771902131,SRE Team,12,10\n" } } }, @@ -11754,7 +11744,7 @@ "post": { "operationId": "insightResponderExport", "summary": "导出处理人员洞察", - "description": "将处理人员洞察指标以 CSV 文件形式导出。CSV 列名和格式化值优先使用请求语言，其次使用成员语言和账户语言。响应为 CSV 字节流（`Content-Disposition: attachment`），不是 JSON 响应包。", + "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 也可传入，但导出为空列。", "tags": [ "On-call/分析看板" ], @@ -11767,28 +11757,15 @@ }, "responses": { "200": { - "description": "成功", + "description": "Success", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/EmptyResponse" - } - } - } - ] + "type": "string", + "format": "binary", + "description": "CSV 字节流（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename=responder_export_yyyyMMdd_HHmmss.csv`）。首行为本地化列名。列默认为完整字段集，或由 `export_fields` 指定。" }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": {} - } + "example": "responder_id,responder_name,total_incident_cnt,total_incidents_acknowledged\n3790925372131,alice,5,4\n" } } }, @@ -11959,12 +11936,12 @@ "get": { "operationId": "statusPageChangeList", "summary": "查询状态页事件列表", - "description": "查询状态页事件列表；响应仅包含对外可见的受影响组件。", + "description": "查询状态页事件列表（管理端）。与公开展示接口不同，响应包含隐藏组件在内的完整数据。", "tags": [ "On-call/状态页" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 响应会过滤隐藏的受影响组件。若事件没有任何可见组件，事件仍会保留，但 `affected_components` 为空数组。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |", "href": "/zh/api-reference/on-call/status-pages/status-page-change-list", "metadata": { "sidebarTitle": "查询状态页事件列表" @@ -12081,7 +12058,7 @@ "type": "integer", "format": "int64" }, - "description": "Filter events started at or after this unix timestamp (seconds)." + "description": "Lower bound of the event activity window: only events still open at, or closed at or after, this Unix timestamp (seconds) are returned." }, { "name": "end_at_seconds", @@ -12091,7 +12068,7 @@ "type": "integer", "format": "int64" }, - "description": "Filter events started at or before this unix timestamp (seconds)." + "description": "Upper bound of the event activity window: only events started at or before this Unix timestamp (seconds) are returned." }, { "name": "type", @@ -12122,7 +12099,7 @@ "completed" ] }, - "description": "Event status filter. Required. Must be a status valid for the given `type` (e.g. `investigating`/`identified`/`monitoring`/`resolved` for incidents; `scheduled`/`ongoing`/`completed` for maintenances)." + "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`)." } ] } @@ -12835,7 +12812,7 @@ "post": { "operationId": "statusPageSubscriberImport", "summary": "批量导入订阅者", - "description": "批量导入状态页的订阅者。", + "description": "批量导入状态页订阅者。账户需开通订阅者导入白名单，否则将被拒绝（返回权限不足错误）。", "tags": [ "On-call/状态页" ], @@ -12934,28 +12911,13 @@ }, "responses": { "200": { - "description": "成功", + "description": "成功。CSV 附件，非 JSON 信封。", "content": { - "application/json": { + "text/csv": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/StatusPageSubscriberExportResponse" - } - } - } - ] + "$ref": "#/components/schemas/StatusPageSubscriberExportResponse" }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": "Method,Recipient,Components,Subscribe All,Locale\nemail,alice@example.com,,true,zh-CN\nemail,bob@example.com,,true,en-US" - } + "example": "Method,Recipient,Components,Subscribe All,Locale\nemail,alice@example.com,,Yes,zh-CN\nemail,bob@example.com,\"Core Services › API\",No,en-US" } } }, @@ -13333,11 +13295,13 @@ { "id": 50001, "folder_id": 100, - "name": "CPU 过高", + "name": "CPU High", "ds_type": "prometheus", "enabled": true, "triggered": true, - "created_at": 1710000000 + "created_at": 1710000000, + "active_alert_count": 2, + "runtime_state": "normal" } ] } @@ -13412,13 +13376,13 @@ "data": { "id": 50001, "folder_id": 100, - "name": "CPU 过高", + "name": "CPU High", "ds_type": "prometheus", "ds_list": [ "prometheus*" ], "enabled": true, - "cron_pattern": "* * * * *", + "cron_pattern": "0 * * * * *", "channel_ids": [ 20001 ] @@ -13495,7 +13459,7 @@ "data": { "id": 50001, "folder_id": 100, - "name": "CPU 过高", + "name": "CPU High", "ds_type": "prometheus", "created_at": 1712000000 } @@ -13525,13 +13489,13 @@ }, "example": { "folder_id": 100, - "name": "CPU 过高", + "name": "CPU High", "ds_type": "prometheus", "ds_list": [ "prometheus*" ], "enabled": true, - "cron_pattern": "* * * * *", + "cron_pattern": "0 * * * * *", "channel_ids": [ 20001 ], @@ -13627,13 +13591,13 @@ "example": { "id": 50001, "folder_id": 100, - "name": "CPU 过高 v2", + "name": "CPU High v2", "ds_type": "prometheus", "ds_list": [ "prometheus*" ], "enabled": true, - "cron_pattern": "* * * * *", + "cron_pattern": "0 * * * * *", "rule_configs": { "queries": [ { @@ -13830,11 +13794,11 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": [ { - "name": "CPU 过高", + "name": "CPU High", "message": "" }, { - "name": "磁盘告警", + "name": "Disk High", "message": "" } ] @@ -13916,7 +13880,7 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": [ { - "name": "CPU 过高", + "name": "CPU High", "message": "" } ] @@ -13947,13 +13911,13 @@ "example": [ { "folder_id": 100, - "name": "CPU 过高", + "name": "CPU High", "ds_type": "prometheus", "ds_list": [ "prometheus*" ], "enabled": true, - "cron_pattern": "* * * * *", + "cron_pattern": "0 * * * * *", "rule_configs": { "queries": [ { @@ -14008,13 +13972,13 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": [ { - "name": "CPU 过高", + "name": "CPU High", "ds_type": "prometheus", "ds_list": [ "prometheus*" ], "enabled": true, - "cron_pattern": "* * * * *" + "cron_pattern": "0 * * * * *" } ] } @@ -14090,7 +14054,7 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": [ { - "name": "CPU 过高", + "name": "CPU High", "message": "" } ] @@ -14130,19 +14094,19 @@ } } }, - "/monit/rule/status": { + "/monit/rule/audits": { "post": { - "operationId": "monit-rule-write-status", - "summary": "查看文件夹下规则触发状态", - "description": "返回指定文件夹节点及其子孙节点下所有规则的触发情况汇总。", + "operationId": "monit-rule-read-audits", + "summary": "查询规则变更历史", + "description": "返回告警规则的变更历史（审计记录）。", "tags": [ "Monitors/告警规则" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- 将 `folder_id` 设为 `0` 可获取所有文件夹的汇总。\n- 若文件夹包含规则数量过多，为保护系统会跳过计算。", - "href": "/zh/api-reference/monitors/alert-rules/monit-rule-write-status", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则查看**（`monit`） |", + "href": "/zh/api-reference/monitors/alert-rules/monit-rule-read-audits", "metadata": { - "sidebarTitle": "查看文件夹下规则触发状态" + "sidebarTitle": "查询规则变更历史" } }, "responses": { @@ -14159,7 +14123,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/RuleStatusResponse" + "$ref": "#/components/schemas/RuleAuditListResponse" } } } @@ -14169,10 +14133,13 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": [ { - "folder_id": 100, - "folder_name": "生产环境", - "rule_total": 10, - "triggered_rule_count": 2 + "id": 9001, + "account_id": 10023, + "alert_rule_id": 50001, + "action": "update", + "creator_id": 80011, + "creator_name": "Alice", + "created_at": 1712000000 } ] } @@ -14197,29 +14164,29 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RuleFolderIDRequest" + "$ref": "#/components/schemas/RuleIDRequest" }, "example": { - "folder_id": 100 + "id": 50001 } } } } } }, - "/monit/rule/audits": { + "/monit/rule/audit/detail": { "post": { - "operationId": "monit-rule-read-audits", - "summary": "查询规则变更历史", - "description": "返回告警规则的变更历史（审计记录）。", + "operationId": "monit-rule-read-audit-detail", + "summary": "查看规则审计快照", + "description": "返回审计记录（包含 `content` 字段，即该时间点规则配置的 JSON 字符串快照）。", "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", + "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": "查询规则变更历史" + "sidebarTitle": "查看规则审计快照" } }, "responses": { @@ -14236,7 +14203,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/RuleAuditListResponse" + "$ref": "#/components/schemas/AlertRuleAudit" } } } @@ -14244,17 +14211,16 @@ }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": [ - { - "id": 9001, - "account_id": 10023, - "alert_rule_id": 50001, - "action": "update", - "creator_id": 80011, - "creator_name": "Alice", - "created_at": 1712000000 - } - ] + "data": { + "id": 9001, + "account_id": 10023, + "alert_rule_id": 50001, + "action": "update", + "content": "{\"id\":50001,\"name\":\"CPU High\"}", + "creator_id": 80011, + "creator_name": "Alice", + "created_at": 1712000000 + } } } } @@ -14277,29 +14243,29 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RuleIDRequest" + "$ref": "#/components/schemas/AuditRecordIDRequest" }, "example": { - "id": 50001 + "id": 9001 } } } } } }, - "/monit/rule/audit/detail": { + "/monit/rule/dstypes": { "post": { - "operationId": "monit-rule-read-audit-detail", - "summary": "查看规则审计快照", - "description": "返回审计记录（包含 `content` 字段，即该时间点规则配置的 JSON 字符串快照）。", + "operationId": "monit-rule-read-dstypes", + "summary": "查询可用的数据源类型", + "description": "返回当前账户在创建告警规则时可使用的数据源类型（`DSType` 记录）列表，包括全局类型和账户自定义类型。", "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", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则查看**（`monit`） |", + "href": "/zh/api-reference/monitors/alert-rules/monit-rule-read-dstypes", "metadata": { - "sidebarTitle": "查看规则审计快照" + "sidebarTitle": "查询可用的数据源类型" } }, "responses": { @@ -14316,7 +14282,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/AlertRuleAudit" + "$ref": "#/components/schemas/RuleDsTypesResponse" } } } @@ -14324,94 +14290,15 @@ }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": { - "id": 9001, - "account_id": 10023, - "alert_rule_id": 50001, - "action": "update", - "content": "{\"id\":50001,\"name\":\"CPU 过高\"}", - "creator_id": 80011, - "creator_name": "Alice", - "created_at": 1712000000 - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/Unauthorized" - }, - "429": { - "$ref": "#/components/responses/TooManyRequests" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuditRecordIDRequest" - }, - "example": { - "id": 9001 - } - } - } - } - } - }, - "/monit/rule/dstypes": { - "post": { - "operationId": "monit-rule-read-dstypes", - "summary": "查询可用的数据源类型", - "description": "返回当前账户在创建告警规则时可使用的数据源类型（`DSType` 记录）列表，包括全局类型和账户自定义类型。", - "tags": [ - "Monitors/告警规则" - ], - "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则查看**（`monit`） |", - "href": "/zh/api-reference/monitors/alert-rules/monit-rule-read-dstypes", - "metadata": { - "sidebarTitle": "查询可用的数据源类型" - } - }, - "responses": { - "200": { - "description": "成功", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/RuleDsTypesResponse" - } - } - } - ] - }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": [ - { - "id": 1, - "name": "Prometheus", - "ident": "prometheus", - "account_id": 0, - "weight": 100 - } - ] + "data": [ + { + "id": 1, + "name": "Prometheus", + "ident": "prometheus", + "account_id": 0, + "weight": 100 + } + ] } } } @@ -14555,8 +14442,8 @@ "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { - "生产环境": 10, - "预发环境": 3 + "Production": 10, + "Staging": 3 } } } @@ -14626,7 +14513,7 @@ "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { - "生产": 8 + "Production": 8 } } } @@ -14698,7 +14585,7 @@ "data": [ { "folder_id": 100, - "folder_name": "生产环境", + "folder_name": "Production", "rule_total": 10, "triggered_rule_count": 2 } @@ -14775,12 +14662,13 @@ "id": 10, "account_id": 10023, "type_ident": "prometheus", - "name": "生产 Prometheus", + "name": "Prometheus Prod", "enabled": true, - "note": "生产环境 Prometheus", + "note": "Production Prometheus", "address": "http://prometheus.example.com:9090", "edge_cluster_name": "default", - "updated_at": 1712000000 + "updated_at": 1712000000, + "payload": null } ] } @@ -14824,7 +14712,7 @@ "Monitors/告警数据源" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 凭据字段\n\n`info` / `create` / `update` 的响应会按原样返回 `payload` 配置——`password`、`basic_auth_password`、`api_key`、`service_token`、`access_key_secret`、`tls_key`、`tls_key_pwd` 等字段均如实返回，不做脱敏。请将这些响应视为敏感信息：避免记录日志或转发给第三方。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 凭据字段\n\n`info` / `create` / `update` 的响应会按原样返回 `payload` 配置——`password`、`basic_auth_password`、`api_key`、`service_token`、`access_key_secret`、`tls_key`、`tls_key_pwd` 等字段均如实返回，不做脱敏。唯一例外是 `payload.tencent_cls.secret_key`：始终掩码为空字符串（`${env:...}` 引用则原样返回）。请将这些响应视为敏感信息：避免记录日志或转发给第三方。", "href": "/zh/api-reference/monitors/data-sources/monit-datasource-read-info", "metadata": { "sidebarTitle": "查看数据源详情" @@ -14856,9 +14744,9 @@ "id": 10, "account_id": 10023, "type_ident": "prometheus", - "name": "生产 Prometheus", + "name": "Prometheus Prod", "enabled": true, - "note": "生产环境 Prometheus", + "note": "Production Prometheus", "address": "http://prometheus.example.com:9090", "payload": { "prometheus": { @@ -14912,7 +14800,7 @@ "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`、`victorialogs`。\n- `edge_cluster_name` 指定使用该数据源进行规则评估的 Monitors Edge 集群。\n- 对于 `elasticsearch`，`payload.elasticsearch.deployment` 须设为 `cloud` 或 `self-managed`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。\n\n## 凭据字段\n\n`info` / `create` / `update` 的响应会按原样返回 `payload` 配置——`password`、`basic_auth_password`、`api_key`、`service_token`、`access_key_secret`、`tls_key`、`tls_key_pwd` 等字段均如实返回，不做脱敏。请将这些响应视为敏感信息：避免记录日志或转发给第三方。", + "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`。\n- `edge_cluster_name` 指定使用该数据源进行规则评估的 Monitors Edge 集群。\n- 对于 `elasticsearch`，`payload.elasticsearch.deployment` 须设为 `cloud` 或 `self-managed`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。\n\n## 凭据字段\n\n`info` / `create` / `update` 的响应会按原样返回 `payload` 配置——`password`、`basic_auth_password`、`api_key`、`service_token`、`access_key_secret`、`tls_key`、`tls_key_pwd` 等字段均如实返回，不做脱敏。唯一例外是 `payload.tencent_cls.secret_key`：始终掩码为空字符串（`${env:...}` 引用则原样返回）。请将这些响应视为敏感信息：避免记录日志或转发给第三方。", "href": "/zh/api-reference/monitors/data-sources/monit-datasource-write-create", "metadata": { "sidebarTitle": "创建数据源" @@ -14943,7 +14831,7 @@ "data": { "id": 10, "type_ident": "prometheus", - "name": "生产 Prometheus", + "name": "Prometheus Prod", "enabled": true, "edge_cluster_name": "default", "updated_at": 1712000000 @@ -14974,8 +14862,8 @@ }, "example": { "type_ident": "prometheus", - "name": "生产 Prometheus", - "note": "生产环境 Prometheus", + "name": "Prometheus Prod", + "note": "Production Prometheus", "address": "http://prometheus.example.com:9090", "edge_cluster_name": "default", "payload": { @@ -14998,7 +14886,7 @@ "Monitors/告警数据源" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源管理**（`monit`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。\n\n## 凭据字段\n\n`info` / `create` / `update` 的响应会按原样返回 `payload` 配置——`password`、`basic_auth_password`、`api_key`、`service_token`、`access_key_secret`、`tls_key`、`tls_key_pwd` 等字段均如实返回，不做脱敏。请将这些响应视为敏感信息：避免记录日志或转发给第三方。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源管理**（`monit`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。\n\n## 凭据字段\n\n`info` / `create` / `update` 的响应会按原样返回 `payload` 配置——`password`、`basic_auth_password`、`api_key`、`service_token`、`access_key_secret`、`tls_key`、`tls_key_pwd` 等字段均如实返回，不做脱敏。唯一例外是 `payload.tencent_cls.secret_key`：始终掩码为空字符串（`${env:...}` 引用则原样返回）。请将这些响应视为敏感信息：避免记录日志或转发给第三方。", "href": "/zh/api-reference/monitors/data-sources/monit-datasource-write-update", "metadata": { "sidebarTitle": "更新数据源" @@ -15029,7 +14917,7 @@ "data": { "id": 10, "type_ident": "prometheus", - "name": "生产 Prometheus v2", + "name": "Prometheus Prod v2", "enabled": true, "edge_cluster_name": "default", "updated_at": 1712100000 @@ -15061,8 +14949,8 @@ "example": { "id": 10, "type_ident": "prometheus", - "name": "生产 Prometheus v2", - "note": "已更新", + "name": "Prometheus Prod v2", + "note": "Updated", "address": "http://prometheus-v2.example.com:9090", "edge_cluster_name": "default", "payload": { @@ -15080,7 +14968,7 @@ "post": { "operationId": "monit-datasource-write-delete", "summary": "删除数据源", - "description": "通过 ID 删除数据源。引用该数据源的告警规则需提前更新或删除。", + "description": "通过 ID 删除数据源。引用该数据源的告警规则不会被阻塞：该数据源会从规则的监控范围中移除，规则上相关的未恢复告警会自动关闭。", "tags": [ "Monitors/告警数据源" ], @@ -15183,10 +15071,30 @@ }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": [ - "project-a", - "project-b" - ] + "data": { + "projects": [ + { + "projectName": "project-a", + "description": "Production logs", + "status": "Normal", + "owner": "", + "region": "cn-shanghai", + "createTime": "1710000000", + "lastModifyTime": "1712000000" + }, + { + "projectName": "project-b", + "description": "Staging logs", + "status": "Normal", + "owner": "", + "region": "cn-shanghai", + "createTime": "1710000000", + "lastModifyTime": "1712000000" + } + ], + "count": 2, + "total": 2 + } } } } @@ -15339,7 +15247,7 @@ { "id": 1, "type_ident": "prometheus", - "note": "CPU 用量告警", + "note": "CPU usage alerts", "open_flag": 2, "creator_account_id": 10023, "creator_id": 80011, @@ -15420,7 +15328,7 @@ "data": { "id": 1, "type_ident": "prometheus", - "note": "CPU 用量告警", + "note": "CPU usage alerts", "open_flag": 2, "payload": "[{\"prom_ql\":\"...\"}]", "creator_account_id": 10023, @@ -15501,7 +15409,7 @@ "data": { "id": 1, "type_ident": "prometheus", - "note": "CPU 用量告警", + "note": "CPU usage alerts", "open_flag": 1, "created_at": 1712000000, "updated_at": 1712000000 @@ -15532,7 +15440,7 @@ }, "example": { "type_ident": "prometheus", - "note": "CPU 用量告警", + "note": "CPU usage alerts", "open_flag": 1, "payload": "[{\"prom_ql\":\"rate(cpu_usage[5m]) > 0.8\"}]" } @@ -15580,7 +15488,7 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "id": 1, - "note": "更新后的 CPU 告警", + "note": "Updated CPU alerts", "open_flag": 2, "updated_at": 1712100000 } @@ -15610,7 +15518,7 @@ }, "example": { "id": 1, - "note": "更新后的 CPU 告警", + "note": "Updated CPU alerts", "open_flag": 2, "payload": "[{\"prom_ql\":\"rate(cpu_usage[5m]) > 0.9\"}]" } @@ -15923,7 +15831,7 @@ "suspected_cause": { "source": "auto", "value": "code.exception", - "reason": "错误信息 'Script error.' 通常表示 JavaScript 中的未处理异常。", + "reason": "The error message 'Script error.' typically indicates an unhandled exception in JavaScript.", "person_id": 0 }, "versions": [ @@ -16394,7 +16302,7 @@ "suspected_cause": { "source": "auto", "value": "code.exception", - "reason": "错误信息 'Script error.' 通常表示 JavaScript 中的未处理异常。", + "reason": "The error message 'Script error.' typically indicates an unhandled exception in JavaScript.", "person_id": 0 }, "versions": [ @@ -16432,7 +16340,7 @@ "suspected_cause": { "source": "auto", "value": "api.failed_request", - "reason": "错误信息表明 POST /api/access/logout 请求时服务端发生内部错误。", + "reason": "The error indicates an internal server error during a POST request to /api/access/logout.", "person_id": 0 }, "versions": [ @@ -16845,7 +16753,7 @@ "field_key": "error.type", "field_name": "Error type", "group": "Error", - "description": "错误类型。", + "description": "The type of the error.", "value_type": "string", "show_type": "list", "unit_family": "", @@ -17119,7 +17027,7 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "application_id": "qLpu24Dz4CAzWsESPbJYWA", - "application_name": "我的 Web 应用", + "application_name": "My Web App", "client_token": "e090078724855a4ca168c3884880dfbc131" } } @@ -17147,7 +17055,7 @@ "$ref": "#/components/schemas/RumApplicationCreateRequest" }, "example": { - "application_name": "我的 Web 应用", + "application_name": "My Web App", "type": "browser", "team_id": 2477033058131, "is_private": false, @@ -17238,7 +17146,7 @@ }, "example": { "application_id": "WoyQQ3BohkdtPivubEvE8o", - "application_name": "我的 Web 应用 v2", + "application_name": "My Web App v2", "alerting": { "enabled": true, "channel_ids": [ @@ -17365,12 +17273,12 @@ "post": { "operationId": "memberInfo", "summary": "获取当前成员信息", - "description": "返回当前会话成员的完整资料。", + "description": "返回当前凭据所属成员的完整资料。需要成员级凭据——以账户主体身份（如账户级 App Key）调用会被拒绝并返回 400。", "tags": [ "平台/成员管理" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 但凭据必须属于某个成员；以账户主体身份（如账户级 App Key）调用会被拒绝并返回 400 |", "href": "/zh/api-reference/platform/members/member-info", "metadata": { "sidebarTitle": "获取当前成员信息" @@ -17680,6 +17588,10 @@ { "member_id": 5068740052131, "member_name": "Charlie" + }, + { + "member_id": 5068740052132, + "member_name": "Dave" } ] } @@ -17736,7 +17648,7 @@ "post": { "operationId": "memberGrantRole", "summary": "授予成员角色", - "description": "为成员添加角色授权。", + "description": "为成员追加角色授权。不存在的角色 ID 会被静默忽略；若全部无法解析，则调用成功但不产生任何变更。", "tags": [ "平台/成员管理" ], @@ -17809,7 +17721,7 @@ "post": { "operationId": "memberRevokeRole", "summary": "解除成员角色", - "description": "移除成员的角色授权。", + "description": "解除成员的角色授权。不存在的角色 ID 会被静默忽略；若全部无法解析，则调用成功但不产生任何变更。", "tags": [ "平台/成员管理" ], @@ -17882,7 +17794,7 @@ "post": { "operationId": "memberUpdateRole", "summary": "更新成员角色", - "description": "一次性替换成员的全部角色授权。", + "description": "一次性整体替换成员的角色。不存在的角色 ID 会被静默丢弃；`role_ids` 为空时重置为内置 Viewer 角色（ID 8）。", "tags": [ "平台/成员管理" ], @@ -18166,8 +18078,8 @@ "data": { "account_id": 10023, "team_id": 1001, - "team_name": "后端 SRE", - "description": "后端可靠性工程团队", + "team_name": "Backend SRE", + "description": "Backend reliability engineering team", "status": "enabled", "updated_by_name": "alice", "updated_by": 80011, @@ -18222,7 +18134,7 @@ "平台/团队管理" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 每次最多传入 100 个团队 ID。", + "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": "批量查看团队信息" @@ -18254,7 +18166,7 @@ "items": [ { "team_id": 1001, - "team_name": "后端 SRE", + "team_name": "Backend SRE", "person_ids": [ 80011, 80012 @@ -18262,7 +18174,7 @@ }, { "team_id": 1002, - "team_name": "前端", + "team_name": "Frontend", "person_ids": [ 80013 ] @@ -18349,7 +18261,7 @@ { "account_id": 10023, "team_id": 1001, - "team_name": "后端 SRE", + "team_name": "Backend SRE", "status": "enabled", "creator_id": 80011, "created_at": 1710000000, @@ -18409,7 +18321,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| 速率限制 | 每个账户 **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": "变更团队信息" @@ -18439,7 +18351,7 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "team_id": 1001, - "team_name": "后端 SRE" + "team_name": "Backend SRE" } } } @@ -18469,8 +18381,8 @@ "$ref": "#/components/schemas/TeamUpsertRequest" }, "example": { - "team_name": "后端 SRE", - "description": "后端可靠性工程团队", + "team_name": "Backend SRE", + "description": "Backend reliability engineering team", "person_ids": [ 80011, 80012 @@ -18593,8 +18505,8 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "role_id": 2, - "role_name": "账户管理员", - "description": "拥有所有权限的账户管理员。", + "role_name": "Account Admin", + "description": "Account admin with all permissions.", "status": "enabled", "permission_ids": [ 101, @@ -18679,7 +18591,7 @@ "items": [ { "role_id": 2, - "role_name": "账户管理员", + "role_name": "Account Admin", "description": "", "status": "enabled", "permission_ids": [], @@ -18761,7 +18673,7 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "role_id": 150, - "role_name": "值班管理员" + "role_name": "On-call Manager" } } } @@ -18791,8 +18703,8 @@ "$ref": "#/components/schemas/RoleUpsertRequest" }, "example": { - "role_name": "值班管理员", - "description": "管理值班排班和故障处理。", + "role_name": "On-call Manager", + "description": "Manage on-call rotations and incidents.", "permission_ids": [ 501, 502 @@ -18812,7 +18724,7 @@ "平台/角色与权限" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 只有自定义角色可以被启用/禁用，内置角色始终保持启用状态。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", + "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": "启用角色" @@ -18885,7 +18797,7 @@ "平台/角色与权限" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 持有该角色的成员将立即失去其权限。\n- 只有自定义角色可被禁用。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", + "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": "禁用角色" @@ -18953,12 +18865,12 @@ "post": { "operationId": "role-write-delete", "summary": "删除角色", - "description": "永久删除自定义角色并从所有成员处撤销授权。", + "description": "删除一个自定义角色。当仍有成员持有该角色时，除非 `is_force` 为 true，否则调用失败并返回 `ReferenceExist`。", "tags": [ "平台/角色与权限" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 内置角色无法删除。\n- 持有该角色的所有成员将立即失去其权限。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", + "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": "删除角色" @@ -19012,7 +18924,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RoleIDRequest" + "$ref": "#/components/schemas/RoleDeleteRequest" }, "example": { "role_id": 150 @@ -19063,13 +18975,14 @@ "items": [ { "id": 501, - "permission_name": "模板查看", + "permission_name": "Templates Read", "permission_type": "read", - "description": "查看通知模板", + "description": "View notification templates", "class": "On-call", "scope": "on-call", "status": "enabled", - "is_granted": true + "is_granted": true, + "source": "system" } ] } @@ -19112,12 +19025,12 @@ "post": { "operationId": "role-read-list-permission-factor", "summary": "查看权限因子集合", - "description": "返回所有权限因子（API、按钮、菜单、URL、访问），可按类型过滤。", + "description": "返回当前成员拥有的权限因子（API、按钮、菜单、URL、页面访问），可按类型过滤。需要成员级凭据——以账户主体身份（如账户级 App Key）调用会被拒绝并返回 400，因为账户主体天然拥有全部权限。", "tags": [ "平台/角色与权限" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 权限因子是每个权限的细粒度控制项。\n- `factor_types` 可选值：`api`、`button`、`visit`、`menu`、`url`。", + "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": "查看权限因子集合" @@ -19148,7 +19061,8 @@ "data": [ { "factor_name": "template:read:info", - "factor_type": "api" + "factor_type": "api", + "source": "system" } ] } @@ -19194,7 +19108,7 @@ "平台/角色与权限" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 每次最多传入 100 个成员 ID。\n- 已持有该角色的成员会被静默跳过。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", + "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": "授予成员账户权限" @@ -19347,7 +19261,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- 默认每页 20 条，最大 99 条。", + "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": "检索审计日志" @@ -19388,10 +19302,13 @@ "ip": "203.0.113.42", "operation": "template:write:create", "operation_name": "创建模板", - "body": "{\"template_name\":\"生产默认模板\"}", + "body": "{\"template_name\":\"Prod default\"}", "params": [], "is_dangerous": false, - "is_write": true + "is_write": true, + "principal_kind": "member", + "credential_type": "", + "credential_id": 0 } ] } @@ -19525,7 +19442,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。\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` 不存在时返回 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": "查看自定义字段" @@ -19615,7 +19532,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` 与 `display_name`；非法正则会自动转义为字面量子串匹配。", + "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": "查看自定义字段列表" @@ -20092,92 +20009,6 @@ } } }, - "/monit/query/rows": { - "post": { - "operationId": "monit-read-query-rows", - "summary": "查询数据源原始行", - "description": "已弃用。执行同步即席查询并返回历史扁平 rows 结构。现有调用方应迁移到 `/monit/query/data`；新接口会保留 frames、records 和 samples 的自然语义，不再把所有结果强制压成 legacy rows。", - "deprecated": true, - "tags": [ - "Monitors/诊断分析" - ], - "x-mint": { - "content": "## 已弃用\n\n所有新集成请使用 [`POST /monit/query/data`](/zh/api-reference/monitors/diagnostics/monit-read-query-data)。本接口仅在现有前端和 AI SRE 调用方迁移期间保留。\n\n## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | 每账户 **100 次/分钟**、**5 次/秒** |\n| 权限 | 任意有效的 `app_key`（只读，不受特定权限分类限制） |\n\n## 使用说明\n\n- 请求通过 WebSocket 转发至 `monit-edge`；`ds_type` + `ds_name` 指定的数据源必须已存在于调用账户下。\n- 请求体中的 `account_id` 可选。若传入，必须与认证账户一致；不一致将被拒绝。\n- 参数校验失败使用标准错误 envelope。当 `monit-edge` 拒绝查询时，其 `{\"error\": {\"code\": ..., \"message\": ...}}` 响应体会被保留，HTTP 状态码与 Edge 错误码一致；错误码无效或缺失时返回 HTTP 500。请同时检查状态码和错误响应体。\n- monit-edge 强制行数上限；结果过多时返回 `error.message = \"too many rows\"`。请缩小时间范围或在数据源侧聚合。\n- `args` 是透传的多态 `string→string` 映射，语义取决于 `ds_type`（SLS 需要 `sls.project` + `sls.logstore`；Loki/VictoriaLogs 原始模式需要通过 `*.start`/`*.end` 或 `*.timespan.value`/`*.timespan.unit` 指定时间范围；Prometheus 和 SQL 数据源忽略该字段）。各数据源完整参数列表见 monit-webapi query-api 文档。", - "href": "/zh/api-reference/monitors/diagnostics/monit-read-query-rows", - "metadata": { - "sidebarTitle": "查询数据源原始行" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/QueryRowsRequest" - }, - "example": { - "account_id": 10001, - "ds_type": "prometheus", - "ds_name": "prod-prom", - "expr": "up", - "delay_seconds": 30 - } - } - } - }, - "responses": { - "200": { - "description": "成功", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/QueryRowsResponse" - } - } - } - ] - }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": [ - { - "fields": { - "__name__": "up", - "instance": "10.0.0.1:9100", - "job": "node" - }, - "values": { - "__value__": 1 - } - } - ] - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/Unauthorized" - }, - "429": { - "$ref": "#/components/responses/TooManyRequests" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - } - } - }, "/monit/query/diagnose": { "post": { "operationId": "monit-read-query-diagnose", @@ -20187,7 +20018,7 @@ "Monitors/诊断分析" ], "x-mint": { - "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | **600 次/分钟**;**10 次/秒** 每账户 |\n| 权限 | 任意有效的 `app_key`(只读;不受特定权限分类约束) |\n\n## 使用说明\n\n- 这是诊断 / RCA 接口,而非原始数据查询接口——如需查看明细行,请配合 `/monit/query/rows` 使用。\n- 仅支持三种 `ds_type` 与 `operation` 组合：`loki` / `victorialogs` → `log_patterns`，`prometheus` → `metric_trends`。即使显式传入 `operation`，其他数据源也会被拒绝。\n- `methods` 选择要执行的分析方法;省略时,`log_patterns` 默认为 `pattern_snapshot + pattern_compare(previous_window)`,`metric_trends` 默认为 `single_window_shape + window_compare(previous_window)`。\n- `time_range` 单位为 Unix 秒;缺失或无效时默认最近 15 分钟;窗口宽度超过 6 小时将被拒绝。\n- 请求通过 WebSocket 转发至 `monit-edge`。长耗时:边缘侧执行可能耗时约 30 秒,叠加 webapi 开销。客户端超时应至少设置为 **35 秒**。\n- `options.*` 由边缘侧设置上限(`max_logs_scanned` ≤ 50 000,`max_patterns` ≤ 50,`examples_per_pattern` ≤ 3,`step_seconds` ∈ [15, 300],`max_series` ≤ 200,`topk` ≤ 50,`timeout_seconds` ≤ 30)。\n- 与 `/monit/query/rows` 一样存在两层错误:边缘侧执行错误以 HTTP 200 返回,响应体中带 `error` 对象——务必同时检查两层。\n- 日志样例在返回前会经过基础脱敏处理,响应中会带 `warnings: [\"examples redacted\"]`。不可作为原始日志使用。", + "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | **600 次/分钟**;**10 次/秒** 每账户 |\n| 权限 | 任意有效的 `app_key`(只读;不受特定权限分类约束) |\n\n## 使用说明\n\n- 这是诊断 / RCA 接口,而非原始数据查询接口——如需查询底层数据,请配合 `/monit/query/data` 使用。\n- 仅支持三种 `ds_type` 与 `operation` 组合：`loki` / `victorialogs` → `log_patterns`，`prometheus` → `metric_trends`。即使显式传入 `operation`，其他数据源也会被拒绝。\n- `methods` 选择要执行的分析方法;省略时,`log_patterns` 默认为 `pattern_snapshot + pattern_compare(previous_window)`,`metric_trends` 默认为 `single_window_shape + window_compare(previous_window)`。\n- `time_range` 单位为 Unix 秒;缺失或无效时默认最近 15 分钟;窗口宽度超过 6 小时将被拒绝。\n- 请求通过 WebSocket 转发至 `monit-edge`。长耗时:边缘侧执行可能耗时约 30 秒,叠加 webapi 开销。客户端超时应至少设置为 **35 秒**。\n- `options.*` 由边缘侧设置上限(`max_logs_scanned` ≤ 50 000,`max_patterns` ≤ 50,`examples_per_pattern` ≤ 3,`step_seconds` ∈ [15, 300],`max_series` ≤ 200,`topk` ≤ 50,`timeout_seconds` ≤ 30)。\n- 成功响应体为原始 `{\"data\": ...}` 对象,不含通常的 `request_id` 包装字段（edge 侧原样透传）。\n- 存在两层错误:请求级失败返回非 200 状态码与标准 `error` 包装;边缘侧执行错误以 HTTP 200 返回,响应体中带 `error` 对象——务必同时检查两层。\n- 日志样例在返回前会经过基础脱敏处理,响应中会带 `warnings: [\"examples redacted\"]`。不可作为原始日志使用。", "href": "/zh/api-reference/monitors/diagnostics/monit-read-query-diagnose", "metadata": { "sidebarTitle": "数据源诊断" @@ -20237,22 +20068,17 @@ "content": { "application/json": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/DiagnoseResponse" - } - } + "type": "object", + "required": [ + "data" + ], + "properties": { + "data": { + "$ref": "#/components/schemas/DiagnoseResponse" } - ] + } }, "example": { - "request_id": "01JZPD1PCDTN5F4YVBD2GS6S9A", "data": { "schema_version": "2", "operation": "log_patterns", @@ -20725,7 +20551,7 @@ "account_id": 10001, "channel_id": 5001, "channel_name": "Production", - "channel_status": "active", + "channel_status": "enabled", "integration_id": 362, "integration_name": "GitHub Deploy", "title": "Deploy api-server v2.3.1", @@ -21092,7 +20918,7 @@ "updated_by": 20001, "created_at": 1716962400, "updated_at": 1716962700, - "last_time": 1716963000, + "last_time": 0, "exclusive_data_source_id": 0, "integration_id": 362 } @@ -21275,7 +21101,7 @@ ] }, "example": { - "error_code": 0, + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "account_id": 1001, "account_name": "acme", @@ -21335,7 +21161,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` 为空数组。", + "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 人员" @@ -22267,85 +22093,6 @@ ] } }, - "/monit/preview/sync": { - "post": { - "operationId": "monit-preview-sync", - "summary": "同步预览数据源查询", - "description": "同步执行数据源查询并返回原始结果，用于在保存前预览告警规则表达式的效果。", - "tags": [ - "Monitors/通用工具" - ], - "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **60 次/分钟**；**10 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `ds_type` 须与数据源类型匹配，如 `prometheus`、`loki`。\n- `ds_name` 为账户中配置的数据源显示名称。\n- `delay_seconds` 将查询窗口向前偏移指定秒数，用于补偿数据摄入延迟。\n- 响应体为数据源返回的原始 JSON，其结构随数据源类型而异。", - "href": "/zh/api-reference/monitors/monitor-utilities/monit-preview-sync", - "metadata": { - "sidebarTitle": "同步预览数据源查询" - } - }, - "responses": { - "200": { - "description": "成功", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/PreviewSyncResponse" - } - } - } - ] - }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": { - "status": "success", - "data": { - "resultType": "vector", - "result": [] - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/Unauthorized" - }, - "429": { - "$ref": "#/components/responses/TooManyRequests" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PreviewSyncRequest" - }, - "example": { - "ds_type": "prometheus", - "ds_name": "生产 Prometheus", - "expr": "rate(http_requests_total[5m])", - "delay_seconds": 0 - } - } - } - } - } - }, "/status-page/info": { "get": { "operationId": "statusPageInfo", @@ -22375,7 +22122,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/StatusPageItem" + "$ref": "#/components/schemas/StatusPageInfoResponse" } } } @@ -22425,7 +22172,8 @@ "email": true, "im": false }, - "template_preference": "message" + "template_preference": "message", + "managed_domain_feature_enabled": true } } } @@ -22450,9 +22198,10 @@ "in": "query", "required": true, "schema": { - "type": "string" + "type": "integer", + "format": "int64" }, - "description": "Status page ID" + "description": "Status page ID." } ] } @@ -23056,9 +22805,9 @@ "type": "pre_defined", "template": { "title": "Service Disruption", - "event_type": "incident", "status": "investigating", - "description": "We are investigating a service disruption affecting some users." + "description": "We are investigating a service disruption affecting some users.", + "type": "incident" } } } @@ -23167,7 +22916,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/EmptyResponse" + "$ref": "#/components/schemas/ListStatusPageTemplatesResponse" } } } @@ -23244,7 +22993,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- `environment_kind` 仅接受空字符串（自动）或 `byoc`；`cloud` 将被拒绝。`byoc` 需要 `environment_id`，且该 Runner 对调用者可见。\n- 创建到某个团队（`team_id > 0`）需要调用者真实属于该团队；只有账户 owner/admin 可以在账户级（`team_id=0`）创建。\n- 每次调用都会记录到账户审计日志。\n", + "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", "metadata": { "sidebarTitle": "创建 A2A 智能体" @@ -23309,8 +23058,9 @@ "auth_type": "bearer", "streaming": true, "team_id": 0, - "environment_kind": "byoc", - "environment_id": "env_8s7Hn2kLpQ3xYbVc4Wd2m" + "environments": [ + "env_8s7Hn2kLpQ3xYbVc4Wd2m" + ] } } } @@ -23601,8 +23351,9 @@ "account_id": 10023, "team_id": 0, "can_edit": true, - "environment_kind": "", - "environment_id": "", + "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", @@ -23702,8 +23453,9 @@ "account_id": 10023, "team_id": 0, "can_edit": true, - "environment_kind": "", - "environment_id": "", + "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", @@ -23853,7 +23605,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 有效 `app_key`；管理操作要求调用者可管理目标规则 |\n\n## 使用说明\n\n- 可以创建个人规则，也可以创建当前账户下任意团队的规则；`team_id` 创建后不可修改。\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| 权限要求 | 有效 `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", "metadata": { "sidebarTitle": "创建自动化规则" @@ -24106,7 +23858,6 @@ "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, @@ -24219,7 +23970,6 @@ "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, @@ -24382,7 +24132,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 有效 `app_key`；管理操作要求调用者可管理目标规则 |\n\n## 使用说明\n\n- 省略或传 `null` 的字段保持不变；`team_id` 不能修改为与当前值不同的值。\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| 权限要求 | 有效 `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", "metadata": { "sidebarTitle": "更新自动化规则" @@ -24536,6 +24286,8 @@ "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", @@ -24696,7 +24448,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- `environment_kind` 仅支持 `byoc`（需同时提供 `environment_id`）或留空表示自动选择——MCP 服务器不支持直接绑定 `cloud`。\n- `per_user_secret` 认证模式要求 `secret_schema` 为合法 JSON 且包含非空的 `header_name`。\n- 每次调用都会记录到账户审计日志。\n", + "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", "metadata": { "sidebarTitle": "创建 MCP 服务器" @@ -24729,8 +24481,7 @@ "account_id": 10023, "team_id": 0, "can_edit": true, - "environment_kind": "", - "environment_id": "", + "environments": [], "server_name": "prometheus", "description": "Query Prometheus metrics and alerts.", "transport": "streamable-http", @@ -24738,17 +24489,6 @@ "status": "enabled", "connect_timeout": 10, "call_timeout": 60, - "tool_count": 2, - "tools": [ - { - "name": "query", - "description": "Run a PromQL instant query." - }, - { - "name": "query_range", - "description": "Run a PromQL range query." - } - ], "auth_mode": "shared", "created_by": 80011, "created_at": 1716960000000, @@ -25034,7 +24774,7 @@ "post": { "operationId": "mcp-read-server-get", "summary": "查看 MCP 服务器详情", - "description": "查看单个 MCP 服务器并实时探测其工具列表。", + "description": "查看单个 MCP 服务器（纯数据库读取，不实时探测远端服务器）。", "tags": [ "AI SRE/MCP 服务器" ], @@ -25044,7 +24784,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 详情接口会实时探测工具；探测失败时设置 `list_error`，请求本身仍成功。\n", + "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", "metadata": { "sidebarTitle": "查看 MCP 服务器详情" @@ -25077,8 +24817,7 @@ "account_id": 10023, "team_id": 0, "can_edit": true, - "environment_kind": "", - "environment_id": "", + "environments": [], "server_name": "prometheus", "description": "Query Prometheus metrics and alerts.", "transport": "streamable-http", @@ -25086,17 +24825,6 @@ "status": "enabled", "connect_timeout": 10, "call_timeout": 60, - "tool_count": 2, - "tools": [ - { - "name": "query", - "description": "Run a PromQL instant query." - }, - { - "name": "query_range", - "description": "Run a PromQL range query." - } - ], "auth_mode": "shared", "created_by": 80011, "created_at": 1716960000000, @@ -25148,7 +24876,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| 速率限制 | 每个 `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", "metadata": { "sidebarTitle": "查询 MCP 服务器列表" @@ -25184,8 +24912,7 @@ "account_id": 10023, "team_id": 0, "can_edit": true, - "environment_kind": "", - "environment_id": "", + "environments": [], "server_name": "prometheus", "description": "Query Prometheus metrics and alerts.", "transport": "streamable-http", @@ -25193,17 +24920,6 @@ "status": "enabled", "connect_timeout": 10, "call_timeout": 60, - "tool_count": 2, - "tools": [ - { - "name": "query", - "description": "Run a PromQL instant query." - }, - { - "name": "query_range", - "description": "Run a PromQL range query." - } - ], "auth_mode": "shared", "created_by": 80011, "created_at": 1716960000000, @@ -25259,7 +24975,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- `env`/`headers` 中的脱敏密钥会被保留——回传脱敏值不会覆盖已存储的真实密钥。\n- `environment_kind`/`environment_id` 是相互独立的部分更新字段：两者都省略表示运行器绑定不变；设置任一字段即可修改绑定，约束与创建时相同（byoc 或留空）。\n- 变更 `team_id` 需要对目标团队具有重新分配权限；若运行器绑定未随之修改，则该绑定在新团队下仍须对调用者可选，否则更新会被拒绝。\n- 每次调用都会记录到账户审计日志。\n", + "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", "metadata": { "sidebarTitle": "更新 MCP 服务器" @@ -25292,8 +25008,7 @@ "account_id": 10023, "team_id": 0, "can_edit": true, - "environment_kind": "", - "environment_id": "", + "environments": [], "server_name": "prometheus", "description": "Query Prometheus metrics, alerts, and rules.", "transport": "streamable-http", @@ -25301,17 +25016,6 @@ "status": "enabled", "connect_timeout": 10, "call_timeout": 60, - "tool_count": 2, - "tools": [ - { - "name": "query", - "description": "Run a PromQL instant query." - }, - { - "name": "query_range", - "description": "Run a PromQL range query." - } - ], "auth_mode": "shared", "created_by": 80011, "created_at": 1716960000000, @@ -26378,8 +26082,7 @@ "updated_at": 1717046400000, "can_edit": true, "update_available": false, - "is_modified": false, - "created": true + "is_modified": false } } } @@ -27421,7 +27124,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/EmptyResponse" + "$ref": "#/components/schemas/WorkItemMutationResult" } } } @@ -29290,8 +28993,8 @@ "items": [ { "rule_id": "n8mZQ2VbXk4wPRs6DfC9Ay", - "rule_name": "已知浏览器插件噪声错误", - "description": "将已知浏览器插件错误降级为 Info", + "rule_name": "Known noisy browser extension errors", + "description": "Downgrade known extension errors to Info", "filters": [ [ { @@ -29311,8 +29014,8 @@ }, { "rule_id": "TAHUYnQmXKzgMS4TFVUKvz", - "rule_name": "生产环境崩溃升级", - "description": "将生产环境的崩溃错误升级为 Critical 严重级别", + "rule_name": "Critical crash spikes", + "description": "Escalate production crashes to Critical severity", "filters": [ [ { @@ -29410,7 +29113,7 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "rule_id": "TAHUYnQmXKzgMS4TFVUKvz", - "rule_name": "生产环境崩溃升级", + "rule_name": "Critical crash spikes", "priority": 2 } } @@ -29439,8 +29142,8 @@ }, "example": { "application_id": "WoyQQ3BohkdtPivubEvE8o", - "rule_name": "生产环境崩溃升级", - "description": "将生产环境的崩溃错误升级为 Critical 严重级别", + "rule_name": "Critical crash spikes", + "description": "Escalate production crashes to Critical severity", "filters": [ [ { @@ -29531,7 +29234,7 @@ "example": { "application_id": "WoyQQ3BohkdtPivubEvE8o", "rule_id": "TAHUYnQmXKzgMS4TFVUKvz", - "rule_name": "生产环境崩溃升级（已更新）", + "rule_name": "Critical crash spikes (updated)", "severity": "Critical" } } @@ -29871,8 +29574,8 @@ "account_id": 3790925372131, "application_id": "WoyQQ3BohkdtPivubEvE8o", "rule_id": "n8mZQ2VbXk4wPRs6DfC9Ay", - "rule_name": "已知浏览器插件噪声错误", - "description": "将已知浏览器插件错误降级为 Info", + "rule_name": "Known noisy browser extension errors", + "description": "Downgrade known extension errors to Info", "filters": [ [ { @@ -29898,8 +29601,8 @@ "account_id": 3790925372131, "application_id": "WoyQQ3BohkdtPivubEvE8o", "rule_id": "TAHUYnQmXKzgMS4TFVUKvz", - "rule_name": "生产环境崩溃升级", - "description": "将生产环境的崩溃错误升级为 Critical 严重级别", + "rule_name": "Critical crash spikes", + "description": "Escalate production crashes to Critical severity", "filters": [ [ { @@ -29940,8 +29643,8 @@ "account_id": 3790925372131, "application_id": "WoyQQ3BohkdtPivubEvE8o", "rule_id": "n8mZQ2VbXk4wPRs6DfC9Ay", - "rule_name": "已知浏览器插件噪声错误", - "description": "将已知浏览器插件错误降级为 Info", + "rule_name": "Known noisy browser extension errors", + "description": "Downgrade known extension errors to Info", "filters": [ [ { @@ -31196,7 +30899,8 @@ "properties": { "total": { "type": "integer", - "description": "持有有效许可的人员数量。" + "description": "持有有效许可的人员数量。", + "format": "int64" }, "items": { "type": "array", @@ -31781,10 +31485,9 @@ "enum": [ "Critical", "Warning", - "Info", - "Ok" + "Info" ], - "description": "事件严重程度。" + "description": "事件严重级别：`Critical`、`Warning` 或 `Info`。事件级别不会取 `Ok`，`Ok` 只出现在 `event_status` 字段。" }, "event_status": { "type": "string", @@ -31794,7 +31497,7 @@ "Info", "Ok" ], - "description": "事件状态。" + "description": "事件状态：`Critical`/`Warning`/`Info` 表示触发事件，`Ok` 表示恢复事件。" }, "event_time": { "type": "integer", @@ -31828,7 +31531,7 @@ "deleted_at": { "type": "integer", "format": "int64", - "description": "软删除时间戳（秒），未删除时为 0。" + "description": "软删除时间，Unix 时间戳（秒）。未删除时不返回该字段。" } } }, @@ -32041,6 +31744,7 @@ "incident_id", "account_id", "channel_id", + "team_id", "integration_id", "integration_ids", "integration_types", @@ -32103,6 +31807,11 @@ "format": "int64", "description": "协作空间 ID，独立故障为 0。" }, + "team_id": { + "type": "integer", + "format": "int64", + "description": "故障所属协作空间的团队 ID；协作空间无团队时为 0。" + }, "integration_id": { "type": "integer", "format": "int64", @@ -32282,7 +31991,8 @@ "description": "自定义字段取值，按字段名索引。" }, "assigned_to": { - "$ref": "#/components/schemas/AssignedTo" + "$ref": "#/components/schemas/AssignedTo", + "description": "故障当前的指派对象。" }, "reporter_email": { "type": "string", @@ -32740,6 +32450,10 @@ "failed_reason": { "type": "string", "description": "投递失败原因。" + }, + "sms_content": { + "type": "string", + "description": "短信投递时发送的短信内容。" } } }, @@ -32832,6 +32546,17 @@ "progress": { "type": "string", "description": "认领时记录的处理进展。" + }, + "comment": { + "type": "string", + "description": "写入时间线评论的表单摘要。未提交认领表单摘要时省略。" + }, + "images": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Image" + }, + "description": "认领表单提交的图片，仅写入时间线记录。未提交时省略。" } }, "title": "i_ack" @@ -32891,6 +32616,17 @@ "escalation" ], "description": "触发恢复操作的来源。\n| 值 | 含义 |\n|---|---|\n| `voice` | 语音电话按键操作。 |\n| `console` | 控制台（Web UI）操作。 |\n| `card` | IM 通知卡片按钮（钉钉/飞书/Slack/Teams）。 |\n| `wcard` | 企业微信通知卡片按钮。 |\n| `event` | 事件驱动：关联告警全部恢复 Ok 自动关闭，或外部 ITSM 系统同步的关闭。 |\n| `autorslv` | 自动恢复：超过协作空间配置的自动恢复时长无新告警，由系统关闭。 |\n| `autorefresh` | 卡片自动刷新（保留值，恢复动态中不会出现）。 |\n| `escalation` | 升级流程（保留值，恢复动态中不会出现）。 |" + }, + "comment": { + "type": "string", + "description": "写入解决时间线评论的表单摘要。未提交解决表单摘要时省略。" + }, + "images": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Image" + }, + "description": "解决表单提交的图片，仅写入时间线记录。未提交时省略。" } }, "title": "i_rslv" @@ -33265,7 +33001,7 @@ "$ref": "#/components/schemas/IncidentFeedType" }, "detail": { - "description": "类型相关的负载，具体结构由 `type` 决定。", + "description": "由 `type` 决定的具体载荷；条目无结构化详情时为 `null`。", "oneOf": [ { "$ref": "#/components/schemas/FeedDetailIncidentNew" @@ -33365,6 +33101,9 @@ }, { "$ref": "#/components/schemas/FeedDetailWorkItemDeleted" + }, + { + "$ref": "#/components/schemas/FeedDetailAlertMerge" } ], "discriminator": { @@ -33402,7 +33141,8 @@ "i_wi_completed": "#/components/schemas/FeedDetailWorkItemCompleted", "i_wi_converted": "#/components/schemas/FeedDetailWorkItemConverted", "i_wi_bound": "#/components/schemas/FeedDetailWorkItemBound", - "i_wi_deleted": "#/components/schemas/FeedDetailWorkItemDeleted" + "i_wi_deleted": "#/components/schemas/FeedDetailWorkItemDeleted", + "a_merge": "#/components/schemas/FeedDetailAlertMerge" } } }, @@ -33641,7 +33381,10 @@ "description": "可选，应用到所有故障的解决方案说明。" }, "description": { - "type": "string", + "type": [ + "string", + "null" + ], "maxLength": 6144, "description": "新的故障描述，最多 6,144 个字符。提供后会在故障关闭前替换当前描述。" }, @@ -33701,14 +33444,15 @@ "pattern": "^[0-9a-fA-F]{24}$" }, "maxItems": 100, - "description": "待暂停的故障 ID 列表，单次最多 100 条。" + "description": "待暂停的故障 ID 列表，单次最多 100 条。", + "minItems": 1 }, "minutes": { "type": "integer", "format": "int64", "exclusiveMinimum": 0, - "maximum": 1440, - "description": "暂停时长（分钟），必须大于 0 且不超过 1440（24 小时）。" + "maximum": 43200, + "description": "暂停时长（分钟），必须大于 0 且不超过 43,200（30 天）。" } } }, @@ -33767,7 +33511,7 @@ "owner_id": { "type": "integer", "format": "int64", - "description": "可选，为目标故障设置新负责人。" + "description": "仅为兼容保留，服务端当前忽略该字段；合并不会修改目标故障的负责人。" }, "remove_source_incidents": { "type": "boolean", @@ -33788,7 +33532,8 @@ "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, - "description": "需禁用自动合并的故障 ID 列表。" + "description": "需禁用自动合并的故障 ID 列表。", + "minItems": 1 } } }, @@ -33859,7 +33604,8 @@ "pattern": "^[0-9a-fA-F]{24}$" }, "maxItems": 100, - "description": "待删除的故障 ID 列表，单次最多 100 条。调用方必须拥有所有故障所在协作空间的访问权限。" + "description": "待删除的故障 ID 列表，单次最多 100 条。调用方必须拥有所有故障所在协作空间的访问权限。", + "minItems": 1 } } }, @@ -33867,7 +33613,8 @@ "type": "object", "description": "为故障添加评论的参数。", "required": [ - "incident_ids" + "incident_ids", + "comment" ], "properties": { "incident_ids": { @@ -34128,7 +33875,11 @@ }, "status": { "type": "string", - "description": "战情室状态。" + "description": "作战室记录状态：`enabled` 生效中，`deleted` 已解散。", + "enum": [ + "enabled", + "deleted" + ] }, "created_at": { "type": "integer", @@ -34187,7 +33938,7 @@ "drafting", "published" ], - "description": "复盘状态，缺省时服务端默认按 `published` 过滤。`drafting` 仅返回草稿中的复盘；`published` 仅返回已发布的复盘。" + "description": "可选的复盘状态过滤：`drafting` 仅返回草稿，`published` 仅返回已发布。缺省时返回全部状态的复盘。" }, "team_ids": { "type": "array", @@ -34681,21 +34432,21 @@ "items": { "type": "string" }, - "description": "Critical 级别使用的通知渠道(如 `voice`、`sms`、`email`、`feishu`)。" + "description": "Critical 级别使用的通知渠道。个人通知渠道：`sms`、`voice`、`email`、`push`；IM 群聊渠道：`feishu_app:`、`dingtalk_app:`、`wecom_app:`、`slack_app:`、`teams_app:`。" }, "warning": { "type": "array", "items": { "type": "string" }, - "description": "Warning 级别使用的通知渠道。" + "description": "Warning 级别使用的通知渠道。取值同 `critical`。" }, "info": { "type": "array", "items": { "type": "string" }, - "description": "Info 级别使用的通知渠道。" + "description": "Info 级别使用的通知渠道。取值同 `critical`。" } } }, @@ -34711,7 +34462,7 @@ "properties": { "type": { "type": "string", - "description": "Webhook 类型(如 `feishu`、`dingtalk_app`、`wecom_app`、`slack`、`teams`、`custom`)。" + "description": "Webhook 类型，可选值：`feishu`、`feishu_app`、`dingtalk`、`dingtalk_app`、`wecom`、`slack`、`slack_app`、`teams_app`、`telegram`、`zoom`。" }, "settings": { "type": "object", @@ -34757,7 +34508,30 @@ "maxItems": 100, "description": "按过滤条件的聚合策略覆盖。", "items": { - "type": "object" + "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.`。" + } + } } }, "all_equals_required": { @@ -34874,6 +34648,10 @@ "is_external_report_enabled": { "type": "boolean", "description": "允许外部上报人向该协作空间上报故障。" + }, + "event_group": { + "$ref": "#/components/schemas/EventGroup", + "description": "告警事件合并配置。不传时使用默认配置（启用合并，窗口 1440 分钟）。" } } }, @@ -34997,21 +34775,21 @@ "items": { "type": "string" }, - "description": "Critical 级别使用的通知渠道(如 `voice`、`sms`、`email`、`feishu`)。" + "description": "Critical 级别使用的通知渠道。个人通知渠道：`sms`、`voice`、`email`、`push`；IM 群聊渠道：`feishu_app:`、`dingtalk_app:`、`wecom_app:`、`slack_app:`、`teams_app:`。" }, "warning": { "type": "array", "items": { "type": "string" }, - "description": "Warning 级别使用的通知渠道。" + "description": "Warning 级别使用的通知渠道。取值同 `critical`。" }, "info": { "type": "array", "items": { "type": "string" }, - "description": "Info 级别使用的通知渠道。" + "description": "Info 级别使用的通知渠道。取值同 `critical`。" } } }, @@ -35027,7 +34805,7 @@ "properties": { "type": { "type": "string", - "description": "Webhook 类型(如 `feishu`、`dingtalk_app`、`wecom_app`、`slack`、`teams`、`custom`)。" + "description": "Webhook 类型，可选值：`feishu`、`feishu_app`、`dingtalk`、`dingtalk_app`、`wecom`、`slack`、`slack_app`、`teams_app`、`telegram`、`zoom`。" }, "settings": { "type": "object", @@ -35087,7 +34865,7 @@ }, "filters": { "type": "array", - "description": "或-与组合条件树。每个外层元素为一组 AND 条件,组内所有条件需同时满足。", + "description": "故障级匹配条件（OR-of-AND 结构）：策略匹配的是告警聚合而成的故障，而不是告警本身。不传或为空时对空间内所有故障生效。", "items": { "type": "array", "items": { @@ -35153,11 +34931,11 @@ "items": { "type": "string" }, - "description": "用于匹配源告警与目标告警的 label 键列表。" + "description": "源（抑制方）告警与目标（被抑制）告警之间必须取值相等的字段键，例如 `data_source_id` 或 `labels.cluster`。" }, "source_filters": { "type": "array", - "description": "或-与组合条件树。每个外层元素为一组 AND 条件,组内所有条件需同时满足。", + "description": "源告警需要满足的条件，针对已存的活跃告警求值。支持的键：`status`、`incident_status`、`alert_status`、`severity`、`incident_severity`、`alert_severity`、`title`、`description` 或任意 `labels.`。为空时策略不生效。", "items": { "type": "array", "items": { @@ -35193,7 +34971,7 @@ }, "target_filters": { "type": "array", - "description": "或-与组合条件树。每个外层元素为一组 AND 条件,组内所有条件需同时满足。", + "description": "目标（被抑制）告警事件需要满足的条件；为空表示所有事件都是抑制目标。", "items": { "type": "array", "items": { @@ -35229,7 +35007,7 @@ }, "is_directly_discard": { "type": "boolean", - "description": "为 true 时被抑制的目标告警将直接丢弃而非合并。" + "description": "为 true 时，命中的告警事件被完全丢弃；为 false 时，告警仍会被记录，但标记为被本策略静默。" } } }, @@ -35259,7 +35037,8 @@ }, "from_incident_id": { "type": "string", - "description": "当静默策略从故障创建时对应的源故障 ID。" + "description": "策略关联的故障 ID（ObjectID 十六进制）。可选；设置后每个故障最多存在一条启用中的静默策略。", + "pattern": "^[0-9a-fA-F]{24}$" }, "time_filters": { "type": "array", @@ -35305,18 +35084,20 @@ "start_time": { "type": "integer", "format": "int64", - "description": "窗口起始时间戳(Unix 秒),需小于 `end_time`。" + "description": "窗口起始时间，Unix 秒时间戳。必须大于 0 且小于 `end_time`。", + "exclusiveMinimum": 0 }, "end_time": { "type": "integer", "format": "int64", - "description": "窗口结束时间戳(Unix 秒)。" + "description": "窗口结束时间，Unix 秒时间戳。必须大于 0。", + "exclusiveMinimum": 0 } } }, "filters": { "type": "array", - "description": "或-与组合条件树。每个外层元素为一组 AND 条件,组内所有条件需同时满足。", + "description": "告警事件匹配条件（OR-of-AND 结构）。必填且至少包含一个条件。", "items": { "type": "array", "items": { @@ -35352,7 +35133,7 @@ }, "is_directly_discard": { "type": "boolean", - "description": "为 true 时被静默的告警将直接丢弃而非并入故障。" + "description": "为 true 时，命中的告警事件被完全丢弃；为 false 时，告警仍会被记录，但标记为被本策略静默。" }, "is_auto_delete": { "type": "boolean", @@ -35386,7 +35167,7 @@ }, "filters": { "type": "array", - "description": "或-与组合条件树。每个外层元素为一组 AND 条件,组内所有条件需同时满足。", + "description": "告警事件匹配条件（OR-of-AND 结构）；命中的事件被完全丢弃——不产生告警、故障或通知。不传或为空时，规则不匹配任何事件。", "items": { "type": "array", "items": { @@ -35437,7 +35218,9 @@ "repeat": { "type": "array", "items": { - "type": "integer" + "type": "integer", + "minimum": 0, + "maximum": 6 }, "description": "窗口每周生效的日期，空表示每天。" }, @@ -35528,21 +35311,21 @@ "items": { "type": "string" }, - "description": "Critical 级别使用的通知渠道（如 `voice`、`sms`、`email`、`feishu`）。" + "description": "Critical 级别使用的通知渠道。个人通知渠道：`sms`、`voice`、`email`、`push`；IM 群聊渠道：`feishu_app:`、`dingtalk_app:`、`wecom_app:`、`slack_app:`、`teams_app:`。" }, "warning": { "type": "array", "items": { "type": "string" }, - "description": "Warning 级别使用的通知渠道。" + "description": "Warning 级别使用的通知渠道。取值同 `critical`。" }, "info": { "type": "array", "items": { "type": "string" }, - "description": "Info 级别使用的通知渠道。" + "description": "Info 级别使用的通知渠道。取值同 `critical`。" } } }, @@ -35558,7 +35341,7 @@ "properties": { "type": { "type": "string", - "description": "Webhook 类型（如 `feishu`、`dingtalk_app`、`wecom_app`、`slack`、`teams`、`custom`）。" + "description": "Webhook 类型，可选值：`feishu`、`feishu_app`、`dingtalk`、`dingtalk_app`、`wecom`、`slack`、`slack_app`、`teams_app`、`telegram`、`zoom`。" }, "settings": { "type": "object", @@ -35636,7 +35419,30 @@ "maxItems": 100, "description": "按过滤条件的聚合策略覆盖。", "items": { - "type": "object" + "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.`。" + } + } } }, "all_equals_required": { @@ -35832,21 +35638,29 @@ "description": "为 true 时禁用故障自动关闭。" }, "group": { - "$ref": "#/components/schemas/Group" + "$ref": "#/components/schemas/Group", + "description": "告警聚合配置。" }, "flapping": { - "$ref": "#/components/schemas/Flapping" + "$ref": "#/components/schemas/Flapping", + "description": "抖动检测配置。" }, "progress_to_incident_cnts": { - "$ref": "#/components/schemas/IncProgressCnts" + "$ref": "#/components/schemas/IncProgressCnts", + "description": "近 30 天按进度统计的故障数量。" }, "is_starred": { "type": "boolean", - "description": "当前用户是否已收藏该协作空间。" + "description": "当前用户是否已收藏该协作空间。仅在 `POST /channel/list` 响应中返回。" }, "active_incident_highest_severity": { "type": "string", - "description": "协作空间内活跃故障的最高严重程度。" + "enum": [ + "Critical", + "Warning", + "Info" + ], + "description": "协作空间内活跃（已触发或处理中）故障的最高严重程度：`Critical`、`Warning` 或 `Info`。无活跃故障时不返回。" }, "last_incident_at": { "type": "integer", @@ -35859,7 +35673,11 @@ }, "external_report_token": { "type": "string", - "description": "启用外部上报时授予外部上报人的 token。" + "description": "授予外部上报人的 token。仅在协作空间启用外部上报时返回。" + }, + "event_group": { + "$ref": "#/components/schemas/EventGroup", + "description": "告警事件合并配置。" } } }, @@ -35883,9 +35701,10 @@ "type": "string", "enum": [ "enabled", - "disabled" + "disabled", + "deleted" ], - "description": "协作空间状态。" + "description": "协作空间状态：`enabled` 正常处理事件；`disabled` 丢弃新事件；`deleted` 已删除。" } } }, @@ -35950,15 +35769,17 @@ "description": "策略生效的周期性时间窗口。" }, "filters": { - "$ref": "#/components/schemas/FilterGroup" + "$ref": "#/components/schemas/FilterGroup", + "description": "故障级匹配条件（OR-of-AND 结构）：策略匹配的是告警聚合而成的故障，而不是告警本身。不传或为空时对空间内所有故障生效。" }, "status": { "type": "string", "enum": [ "enabled", - "disabled" + "disabled", + "deleted" ], - "description": "策略状态。" + "description": "策略状态：`enabled` 生效中，`disabled` 已暂停，`deleted` 已软删除（仅详情接口可能返回；列表接口不会返回已删除策略）。" }, "template_id": { "type": "string", @@ -35978,17 +35799,17 @@ "deleted_at": { "type": "integer", "format": "int64", - "description": "删除时间（Unix 秒），仅软删除时返回。" + "description": "删除时间，Unix 秒时间戳。仅在策略被软删除时返回；已删除的策略不会出现在列表响应中。" }, "created_at": { "type": "integer", "format": "int64", - "description": "创建时间（Unix 秒）。" + "description": "创建时间，Unix 秒时间戳。" }, "updated_at": { "type": "integer", "format": "int64", - "description": "最近更新时间（Unix 秒）。" + "description": "最近更新时间，Unix 秒时间戳。" }, "channel_name": { "type": "string", @@ -36036,20 +35857,22 @@ "from_incident_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", - "description": "从故障创建静默时的源故障 ID。" + "description": "策略关联的故障 ID。始终返回；零值 ObjectID `000000000000000000000000` 表示该策略并非从故障创建。" }, "time_filters": { "type": "array", "items": { "$ref": "#/components/schemas/TimeFilter" }, - "description": "周期性时间窗口。" + "description": "周期性静默窗口。当策略使用一次性 `time_filter` 时为空。" }, "time_filter": { - "$ref": "#/components/schemas/OnceTimeFilter" + "$ref": "#/components/schemas/OnceTimeFilter", + "description": "一次性静默窗口。当策略使用周期性 `time_filters` 时，该字段以零值返回。" }, "filters": { - "$ref": "#/components/schemas/FilterGroup" + "$ref": "#/components/schemas/FilterGroup", + "description": "告警事件匹配条件；命中的事件在时间窗口内被静默。" }, "is_directly_discard": { "type": "boolean", @@ -36085,11 +35908,16 @@ }, "is_effective": { "type": "boolean", - "description": "当前是否正在生效。" + "description": "策略的时间窗口是否覆盖当前时刻（按响应时刻计算）。" }, "is_auto_delete": { "type": "boolean", "description": "为 true 时，静默规则在时间窗结束后会被自动删除；默认为 false。" + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "删除时间，Unix 秒时间戳。仅在策略被软删除时返回；已删除的策略不会出现在列表响应中。" } } }, @@ -36130,21 +35958,23 @@ "description": "规则描述。" }, "source_filters": { - "$ref": "#/components/schemas/FilterGroup" + "$ref": "#/components/schemas/FilterGroup", + "description": "源告警需要满足的条件，针对已存的活跃告警求值。支持的键：`status`、`incident_status`、`alert_status`、`severity`、`incident_severity`、`alert_severity`、`title`、`description` 或任意 `labels.`。为空时策略不生效。" }, "target_filters": { - "$ref": "#/components/schemas/FilterGroup" + "$ref": "#/components/schemas/FilterGroup", + "description": "目标（被抑制）告警事件需要满足的条件；为空表示所有事件都是抑制目标。" }, "equals": { "type": "array", "items": { "type": "string" }, - "description": "用于配对源告警与目标告警的 label 键列表。" + "description": "源（抑制方）告警与目标（被抑制）告警之间必须取值相等的字段键，例如 `data_source_id` 或 `labels.cluster`。" }, "is_directly_discard": { "type": "boolean", - "description": "为 true 时被抑制的目标告警直接丢弃；为 false 时告警仍会创建但被静音，不触发故障与通知。" + "description": "为 true 时，命中的告警事件被完全丢弃；为 false 时，告警仍会被记录，但标记为被本策略静默。" }, "status": { "type": "string", @@ -36173,6 +36003,11 @@ "type": "integer", "format": "int64", "description": "最近更新时间，Unix 时间戳（秒）。" + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "删除时间，Unix 秒时间戳。仅在策略被软删除时返回；已删除的策略不会出现在列表响应中。" } } }, @@ -36211,7 +36046,8 @@ "description": "规则描述。" }, "filters": { - "$ref": "#/components/schemas/FilterGroup" + "$ref": "#/components/schemas/FilterGroup", + "description": "告警事件匹配条件（OR-of-AND 结构）；命中的事件被完全丢弃。为空时规则不匹配任何事件。" }, "status": { "type": "string", @@ -36240,6 +36076,11 @@ "type": "integer", "format": "int64", "description": "最近更新时间，Unix 时间戳（秒）。" + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "删除时间，Unix 秒时间戳。仅在规则被软删除时返回；已删除的规则不会出现在列表响应中。" } } }, @@ -36280,11 +36121,11 @@ "channel_name", "last_incident_at" ], - "description": "排序字段。" + "description": "排序字段。默认为 `created_at`。" }, "asc": { "type": "boolean", - "description": "为 true 时升序排序。" + "description": "为 true 时升序排列；默认为 false（降序）。" }, "is_my_managed": { "type": "boolean", @@ -36296,7 +36137,7 @@ }, "is_brief": { "type": "boolean", - "description": "为 true 时仅返回简要字段（`channel_id`、`channel_name`、`description`、`status`）。" + "description": "为 true 时仅返回 `channel_id`、`channel_name`、`description` 和 `status` 字段，且不分页，一次返回全部匹配结果。" }, "is_my_team": { "type": "boolean", @@ -36312,7 +36153,7 @@ }, "query": { "type": "string", - "description": "按名称/描述的全文查询串。" + "description": "针对协作空间名称和描述的不区分大小写正则匹配；正则语法非法时按字面量匹配。" }, "channel_ids": { "type": "array", @@ -36407,7 +36248,7 @@ "trigger", "update" ], - "description": "自动恢复计时方式：`trigger` 从故障触发时开始计时，`update` 每次告警更新都重新计时。" + "description": "自动恢复计时模式：`trigger` 在故障触发时启动计时，`update` 在每次告警更新时重新计时。仅在请求同时携带 `auto_resolve_timeout` 时生效。" }, "is_private": { "type": [ @@ -36444,6 +36285,10 @@ "null" ], "description": "允许外部上报人向该协作空间上报故障。" + }, + "event_group": { + "$ref": "#/components/schemas/EventGroup", + "description": "告警事件合并配置。仅在传入时更新。" } } }, @@ -36530,7 +36375,7 @@ }, "is_directly_discard": { "type": "boolean", - "description": "为 true 时静默的告警直接丢弃，而非抑制为故障。" + "description": "为 true 时，命中的告警事件被完全丢弃；为 false 时，告警仍会被记录，但标记为被本策略静默。" }, "is_auto_delete": { "type": "boolean", @@ -36593,19 +36438,19 @@ "items": { "type": "string" }, - "description": "用于配对源告警与目标告警的 label 键列表。" + "description": "源（抑制方）告警与目标（被抑制）告警之间必须取值相等的字段键，例如 `data_source_id` 或 `labels.cluster`。" }, "source_filters": { "$ref": "#/components/schemas/FilterGroup", - "description": "源告警的匹配条件，与 `equals` 共同决定抑制哪些目标告警。" + "description": "源告警需要满足的条件，针对已存的活跃告警求值。支持的键：`status`、`incident_status`、`alert_status`、`severity`、`incident_severity`、`alert_severity`、`title`、`description` 或任意 `labels.`。为空时策略不生效。" }, "target_filters": { "$ref": "#/components/schemas/FilterGroup", - "description": "目标（被抑制）告警的匹配条件。" + "description": "目标（被抑制）告警事件需要满足的条件；为空表示所有事件都是抑制目标。" }, "is_directly_discard": { "type": "boolean", - "description": "为 true 时被抑制的目标告警直接丢弃，而非合并。" + "description": "为 true 时，命中的告警事件被完全丢弃；为 false 时，告警仍会被记录，但标记为被本策略静默。" } } }, @@ -36641,7 +36486,7 @@ }, "filters": { "$ref": "#/components/schemas/FilterGroup", - "description": "命中条件的告警将被屏蔽，不产生任何通知。" + "description": "告警事件匹配条件（OR-of-AND 结构）；命中的事件被完全丢弃。为空时规则不匹配任何事件。" } } }, @@ -36709,7 +36554,7 @@ }, "filters": { "$ref": "#/components/schemas/FilterGroup", - "description": "本策略适用的告警匹配条件，留空表示对空间内全部告警生效。" + "description": "故障级匹配条件（OR-of-AND 结构）：策略匹配的是告警聚合而成的故障，而不是告警本身。不传或为空时对空间内所有故障生效。" } } }, @@ -36888,9 +36733,7 @@ "type": "object", "description": "路由规则中的单个 case 分支。当其全部条件命中后,告警将分发到所配置的协作空间。", "required": [ - "if", - "channel_ids", - "fallthrough" + "if" ], "properties": { "if": { @@ -36901,12 +36744,15 @@ } }, "channel_ids": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "type": "integer", "format": "int64" }, - "description": "目标协作空间 ID。当 `routing_mode` 为 `standard`(或为空)时必填。" + "description": "目标协作空间 ID。当 `routing_mode` 为 `standard`（或为空）时必填；`name_mapping` 模式下返回 `null`。" }, "fallthrough": { "type": "boolean", @@ -37039,7 +36885,8 @@ "integration_id": { "type": "integer", "format": "int64", - "description": "集成 ID,必须大于 0。" + "description": "集成 ID,必须大于 0。", + "exclusiveMinimum": 0 } } }, @@ -37056,7 +36903,8 @@ "type": "integer", "format": "int64" }, - "description": "需要查询路由规则的集成 ID 列表。" + "description": "需要查询路由规则的集成 ID 列表。", + "minItems": 1 } } }, @@ -37109,7 +36957,7 @@ "version": { "type": "integer", "format": "int64", - "description": "用于乐观并发控制的当前版本号,传入最近一次读取时返回的值。" + "description": "预留给乐观并发控制使用；当前服务端忽略该字段——每次 upsert 时服务端会自动递增 `version`。" } } }, @@ -37129,28 +36977,40 @@ "end_time": { "type": "integer", "format": "int64", - "description": "检索窗口结束时间，Unix 时间戳（秒）。最大跨度 31 天。" + "description": "查询窗口终点，Unix 时间戳（秒）。必须大于 `start_time`；跨度不超过 31 天，且需在账户数据保留期内。" }, "p": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "页码，从 1 开始。未提供 `search_after_ctx` 时使用。" + "description": "页码，从 1 开始。仅在未提供 `search_after_ctx` 时生效；`p * limit` 不能超过 10,000 条。", + "minimum": 0 }, "limit": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "每页条数，最大 100，默认 20。" + "description": "每页条数，最大 100，默认 20。", + "minimum": 0, + "maximum": 100 }, "search_after_ctx": { - "type": "string", - "description": "上次响应返回的不透明游标，用于获取下一页。" + "type": [ + "string", + "null" + ], + "description": "上一页响应返回的分页游标，用于获取下一页。" }, "is_active": { "type": [ "boolean", "null" ], - "description": "过滤活跃（true）或已恢复（false）状态告警。" + "description": "按生命周期过滤：`true` 只返回未恢复告警（状态 `Critical`/`Warning`/`Info`），`false` 只返回已恢复告警（状态 `Ok`）。不传或传 `null` 返回全部。" }, "ever_muted": { "type": [ @@ -37184,7 +37044,7 @@ "items": { "type": "string" }, - "description": "按告警 ID（ObjectID 十六进制字符串）过滤。" + "description": "只查询指定告警 ID（ObjectID 十六进制字符串）。非法 ID 会被忽略；全部非法时结果为空。" }, "alert_keys": { "type": "array", @@ -37193,17 +37053,9 @@ }, "description": "按告警去重键过滤。" }, - "orderby": { - "type": "string", - "enum": [ - "created_at", - "updated_at" - ], - "description": "排序字段。" - }, "asc": { "type": "boolean", - "description": "为 true 时升序排序，默认降序。" + "description": "为 `true` 时按 `start_time` 升序排序；默认降序。" }, "by_updated_at": { "type": "boolean", @@ -37227,7 +37079,7 @@ "data_source_id": { "type": "integer", "format": "int64", - "description": "已废弃，请使用 `integration_id`。 Deprecated: use `integration_id` instead.", + "description": "已废弃：请使用 `integration_id`。", "deprecated": true }, "channel_id": { @@ -37257,10 +37109,9 @@ "enum": [ "Critical", "Warning", - "Info", - "Ok" + "Info" ], - "description": "当前严重程度。" + "description": "当前严重级别，取该告警出现过的最高级别：`Critical`、`Warning` 或 `Info`。" }, "alert_status": { "type": "string", @@ -37270,7 +37121,7 @@ "Info", "Ok" ], - "description": "当前状态。" + "description": "当前状态：未恢复时为 `Critical`/`Warning`/`Info`，恢复后为 `Ok`。" }, "alert_key": { "type": "string", @@ -37330,15 +37181,19 @@ }, "channel_status": { "type": "string", - "description": "协作空间状态（如 `enabled`、`disabled`）。" + "description": "协作空间状态：`enabled`（启用）或 `disabled`（禁用）。", + "enum": [ + "enabled", + "disabled" + ] }, "responder_name": { "type": "string", - "description": "当前处理人姓名（来自关联故障）。" + "description": "响应人名称。本接口恒为空字符串——响应人信息记录在关联故障上。" }, "responder_email": { "type": "string", - "description": "当前处理人邮箱（来自关联故障）。" + "description": "响应人邮箱。本接口恒为空字符串——响应人信息记录在关联故障上。" }, "event_cnt": { "type": "integer", @@ -37354,7 +37209,7 @@ "items": { "$ref": "#/components/schemas/AlertEventItem" }, - "description": "附加到该告警的最近原始事件，仅部分接口返回。" + "description": "告警的原始事件列表。本接口不返回；仅 `POST /incident/alert/list` 填充该字段。" }, "images": { "type": "array", @@ -37365,15 +37220,23 @@ }, "data_source_name": { "type": "string", - "description": "已废弃，请使用 `integration_name`。" + "description": "已废弃：请使用 `integration_name`。", + "deprecated": true }, "data_source_type": { "type": "string", - "description": "已废弃，请使用 `integration_type`。" + "description": "已废弃：请使用 `integration_type`。为空时不返回。", + "deprecated": true }, "data_source_ref_id": { "type": "string", - "description": "已废弃，请使用 `integration_ref_id`。" + "description": "已废弃：请使用 `integration_ref_id`。", + "deprecated": true + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "软删除时间，Unix 时间戳（秒）。未删除时不返回该字段。" } } }, @@ -37405,7 +37268,7 @@ "total": { "type": "integer", "format": "int64", - "description": "符合条件的告警总数。" + "description": "匹配的告警总数，最多统计 1000 条。" }, "has_next_page": { "type": "boolean", @@ -37413,7 +37276,7 @@ }, "search_after_ctx": { "type": "string", - "description": "下一页的游标。" + "description": "下一页游标——本页最后一条告警的 ObjectID 十六进制字符串，请求下一页时作为 `search_after_ctx` 传入。仅在 `has_next_page` 为 true 时返回。" }, "items": { "type": "array", @@ -37432,7 +37295,8 @@ "properties": { "alert_id": { "type": "string", - "description": "告警 ID（ObjectID 十六进制字符串）。" + "description": "告警 ID（ObjectID 十六进制字符串）。", + "pattern": "^[0-9a-fA-F]{24}$" } } }, @@ -37447,7 +37311,8 @@ "items": { "type": "string" }, - "description": "告警 ID 列表（十六进制字符串）。" + "description": "要查询的告警 ID 列表（ObjectID 十六进制字符串）。", + "minItems": 1 } } }, @@ -37468,7 +37333,10 @@ "description": "为 true 时按最早事件优先返回；默认按最新事件优先返回。" }, "limit": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", "minimum": 0, "maximum": 100, @@ -37476,14 +37344,20 @@ "description": "分页大小，默认 20，最大 100。" }, "p": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", "minimum": 0, "default": 1, "description": "页码，从 1 开始；未传 `search_after_ctx` 时生效。" }, "search_after_ctx": { - "type": "string", + "type": [ + "string", + "null" + ], "pattern": "^[0-9a-fA-F]{24}$", "description": "上一页响应返回的游标；传入后使用游标分页而非页码分页。" } @@ -37507,7 +37381,7 @@ "total": { "type": "integer", "format": "int64", - "description": "命中的事件总数。" + "description": "匹配的事件总数，最多统计 1000 条。" }, "has_next_page": { "type": "boolean", @@ -37515,7 +37389,7 @@ }, "search_after_ctx": { "type": "string", - "description": "下一页请求可作为 `search_after_ctx` 传入的游标。" + "description": "下一页游标，请求下一页时作为 `search_after_ctx` 传入。本页为空时不返回；游标分页模式下没有下一页时也不返回。" } } }, @@ -37527,18 +37401,22 @@ "properties": { "alert_id": { "type": "string", - "description": "告警 ID，可通过 `POST /alert/list` 获取。" + "description": "告警 ID（ObjectID 十六进制字符串），可从 `POST /alert/list` 获取。", + "pattern": "^[0-9a-fA-F]{24}$" }, "p": { "type": "integer", "format": "int64", "description": "页码，从 1 开始。", - "default": 1 + "default": 1, + "minimum": 1 }, "limit": { "type": "integer", "format": "int64", - "description": "每页条数，最大 100，默认 20。" + "description": "每页条数，最大 100，默认 20。", + "minimum": 1, + "maximum": 100 }, "asc": { "type": "boolean", @@ -37549,20 +37427,23 @@ "items": { "type": "string" }, - "description": "按动态类型过滤，取值为动态类型代码（如 `a_new`、`a_close`、`a_ack`）。" + "description": "按动态类型码过滤——完整取值见响应条目的 `type` 字段（如 `a_new`、`a_comm`、`a_merge`）。" } } }, "AlertFeedType": { "type": "string", - "description": "告警动态记录类型。每个值标识一个告警生命周期事件；`detail` 的具体结构由该字段决定。\n\n| 类型 | 含义 |\n|---|---|\n| `a_new` | 告警触发。 |\n| `a_update` | 告警被新事件更新（如严重程度、状态变化）。 |\n| `a_merge` | 告警被合并。 |\n| `a_comm` | 在告警上添加了评论。 |\n| `a_m_silence` | 告警被静默规则收敛。 |\n| `a_m_inhibit` | 告警被抑制规则收敛。 |\n| `a_close` | 告警关闭（仅历史数据，当前版本不再产生）。 |", + "description": "告警动态记录类型。每个值标识一个告警生命周期事件；`detail` 的具体结构由该字段决定。\n\n| 类型 | 含义 |\n|---|---|\n| `a_new` | 告警被新事件触发。 |\n| `a_update` | 告警严重程度或状态随新事件变化。 |\n| `a_comm` | 在告警上添加了评论。 |\n| `a_merge` | 告警被合并到故障。 |\n| `a_m_silence` | 告警被静默规则收敛。 |\n| `a_m_inhibit` | 告警被抑制规则收敛。 |\n| `a_m_flapping` | 告警被抖动检测收敛（仅历史数据，当前版本不再产生）。 |\n| `a_ack` | 告警被认领（仅历史数据；告警级认领已移除）。 |\n| `a_unack` | 告警认领被撤销（仅历史数据）。 |\n| `a_close` | 告警关闭（仅历史数据，当前版本不再产生）。 |", "enum": [ "a_new", "a_update", - "a_merge", "a_comm", + "a_merge", "a_m_silence", "a_m_inhibit", + "a_m_flapping", + "a_ack", + "a_unack", "a_close" ] }, @@ -37619,14 +37500,35 @@ "$ref": "#/components/schemas/AlertFeedType" }, "detail": { - "description": "类型特定的详情数据，结构依 `type` 而定。", + "description": "类型特定的详情数据，结构由 `type` 决定。对未存储详情的条目可能为 `null`。", "oneOf": [ { "$ref": "#/components/schemas/FeedDetailAlertTrigger" }, + { + "$ref": "#/components/schemas/FeedDetailAlertUpdate" + }, { "$ref": "#/components/schemas/FeedDetailAlertComment" }, + { + "$ref": "#/components/schemas/FeedDetailAlertMerge" + }, + { + "$ref": "#/components/schemas/FeedDetailAlertMuteBySilence" + }, + { + "$ref": "#/components/schemas/FeedDetailAlertMuteByInhibit" + }, + { + "$ref": "#/components/schemas/FeedDetailAlertMuteByFlapping" + }, + { + "$ref": "#/components/schemas/FeedDetailAlertAck" + }, + { + "$ref": "#/components/schemas/FeedDetailAlertUnack" + }, { "$ref": "#/components/schemas/FeedDetailAlertClose" } @@ -37635,7 +37537,14 @@ "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" } } @@ -37659,6 +37568,11 @@ "type": "integer", "format": "int64", "description": "最后更新时间，Unix 毫秒时间戳。" + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "软删除时间，Unix 时间戳（毫秒）。未删除时不返回该字段。" } } }, @@ -37690,19 +37604,23 @@ "items": { "type": "string" }, - "description": "要合并的告警 ID 列表，可通过 `POST /alert/list` 获取。" + "description": "要合并的告警 ID 列表（ObjectID 十六进制字符串），可从 `POST /alert/list` 获取。所有 ID 必须属于当前账户。", + "minItems": 1 }, "incident_id": { "type": "string", - "description": "目标故障 ID，可通过 `POST /incident/list` 获取。" + "description": "目标故障 ID（ObjectID 十六进制字符串），可从 `POST /incident/list` 获取。", + "pattern": "^[0-9a-fA-F]{24}$" }, "comment": { "type": "string", - "description": "合并操作的可选评论。" + "description": "可选评论，记录在合并动态中。最长 1024 字符。", + "maxLength": 1024 }, "title": { "type": "string", - "description": "目标故障的可选新标题。" + "description": "可选，目标故障的新标题。最长 512 字符。", + "maxLength": 512 }, "owner_id": { "type": "integer", @@ -37720,7 +37638,8 @@ "integration_id": { "type": "integer", "format": "int64", - "description": "集成 ID。" + "description": "集成 ID。必须大于 0。", + "exclusiveMinimum": 0 } } }, @@ -37740,11 +37659,14 @@ "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", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/FilterCondition" }, - "description": "可选 AND 过滤条件列表，全部条件匹配时规则才生效；省略时对所有告警生效。" + "description": "AND 条件列表——仅当所有条件都匹配时规则生效。为 `null` 或不传表示规则对所有事件生效。" }, "settings": { "type": "object", @@ -37767,7 +37689,10 @@ } ] } - } + }, + "required": [ + "kind" + ] }, "AlertPipelineItem": { "type": "object", @@ -37787,7 +37712,10 @@ }, "status": { "type": "string", - "description": "规则状态（如 `active`）。" + "description": "规则状态。接口响应中恒为 `enabled`——已删除的规则会被过滤。", + "enum": [ + "enabled" + ] }, "creator_id": { "type": "integer", @@ -37808,6 +37736,11 @@ "type": "integer", "format": "int64", "description": "最后更新时间，Unix 时间戳（秒）。" + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "软删除时间，Unix 时间戳（秒）。未删除时不返回该字段。" } } }, @@ -37823,7 +37756,8 @@ "type": "integer", "format": "int64" }, - "description": "集成 ID 列表。" + "description": "集成 ID 列表，至少 1 个。", + "minItems": 1 } } }, @@ -37856,8 +37790,9 @@ "items": { "$ref": "#/components/schemas/AlertPipeline" }, - "description": "处理规则列表，最多 50 条。", - "maxItems": 50 + "description": "要应用的规则，按数组顺序执行。1 到 50 条。", + "maxItems": 50, + "minItems": 1 } } }, @@ -37866,28 +37801,47 @@ "description": "全局原始事件列表的过滤和分页条件。", "properties": { "start_time": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "检索窗口开始时间，Unix 时间戳（秒）。" + "description": "查询窗口起点，Unix 时间戳（秒）。提供时必须大于 0。", + "exclusiveMinimum": 0 }, "end_time": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "检索窗口结束时间，Unix 时间戳（秒）。" + "description": "查询窗口终点，Unix 时间戳（秒）。提供时必须大于 `start_time`。" }, "p": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "页码，从 1 开始。未提供 `search_after_ctx` 时使用。" + "description": "页码，从 1 开始。仅在未提供 `search_after_ctx` 时生效。", + "minimum": 0 }, "limit": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "每页条数，最大 100，默认 20。" + "description": "每页条数，最大 100，默认 20。", + "minimum": 0, + "maximum": 100 }, "search_after_ctx": { - "type": "string", - "description": "分页游标：首页留空，翻页时传上一页响应中的 `search_after_ctx`。" + "type": [ + "string", + "null" + ], + "description": "分页游标：首页留空，之后传入上一次响应返回的 `search_after_ctx`。" }, "integration_ids": { "type": "array", @@ -37910,11 +37864,12 @@ "type": "integer", "format": "int64" }, - "description": "按协作空间 ID 过滤，最多 100 个。" + "description": "按协作空间 ID 过滤，最多 100 个。", + "maxItems": 100 }, "severities": { "type": "string", - "description": "逗号分隔的严重程度过滤，如 `Critical,Warning`。" + "description": "逗号分隔的严重级别过滤，如 `Critical,Warning`。可选值：`Critical`、`Warning`、`Info`、`Ok`。" }, "orderby": { "type": "string", @@ -37943,7 +37898,7 @@ }, "search_after_ctx": { "type": "string", - "description": "下一页游标，为本页最后一条事件的 ObjectID，传入下次请求的 `search_after_ctx`；无更多数据或结果为空时不返回。" + "description": "下一页游标——本页最后一条事件的 ObjectID，请求下一页时作为 `search_after_ctx` 传入。本页为空时不返回；游标分页模式下没有下一页时也不返回。" }, "items": { "type": "array", @@ -38117,7 +38072,8 @@ }, "total": { "type": "integer", - "description": "匹配记录总数。" + "description": "匹配记录总数。", + "format": "int64" }, "search_after_ctx": { "type": "string", @@ -38152,11 +38108,15 @@ }, "webhook_type": { "type": "string", - "description": "来源对象类型：`incident` 或 `alert`。" + "description": "来源对象类型：`incident`（故障）或 `alert`（告警）。", + "enum": [ + "incident", + "alert" + ] }, "event_type": { "type": "string", - "description": "事件类型（如 `created`、`acknowledged`、`closed`）。" + "description": "事件类型代码。`i_*` 为故障事件（如 `i_new` 故障创建），`a_*` 为告警事件（如 `a_new` 告警触发）。" }, "channel_id": { "type": "integer", @@ -38213,7 +38173,7 @@ }, "event_time": { "type": "string", - "description": "事件时间的格式化时间串。" + "description": "事件时间，格式 `YYYY-MM-DD HH:MM:SS.ffffff`。" } } }, @@ -38239,7 +38199,7 @@ }, "WebhookHistoryDetail": { "type": "object", - "description": "Webhook 推送的完整详情。相较 `WebhookHistoryItem`，额外附带查询时解析出的引用元信息。", + "description": "单条 Webhook 投递记录的完整详情，在 `WebhookHistoryItem` 基础上增加查询时解析的关联对象信息。无匹配记录时，`data` 为空对象。", "required": [ "integration_id", "event_id", @@ -38264,11 +38224,15 @@ }, "webhook_type": { "type": "string", - "description": "来源对象类型：`incident` 或 `alert`。" + "description": "来源对象类型：`incident`（故障）或 `alert`（告警）。", + "enum": [ + "incident", + "alert" + ] }, "event_type": { "type": "string", - "description": "事件类型。" + "description": "事件类型代码。`i_*` 为故障事件（如 `i_new` 故障创建），`a_*` 为告警事件（如 `a_new` 告警触发）。" }, "channel_id": { "type": "integer", @@ -38325,7 +38289,7 @@ }, "event_time": { "type": "string", - "description": "事件时间的格式化时间串。" + "description": "事件时间，格式 `YYYY-MM-DD HH:MM:SS.ffffff`。" }, "ref_title": { "type": "string", @@ -38344,19 +38308,23 @@ }, "ScheduleSelfRequest": { "type": "object", - "description": "查询当前用户值班表的参数。start 和 end 为 Unix 时间戳（秒），缺省时默认为 0。时间窗口不得超过 30 天。", + "description": "查询当前用户值班表的参数。start 和 end 为必填的 10 位 Unix 秒级时间戳，时间窗口不得超过 45 天。", "properties": { "start": { "type": "integer", "format": "int64", - "description": "时间窗口开始时间（Unix 秒，10 位）。" + "description": "时间窗口开始时间（Unix 秒，10 位），必填。" }, "end": { "type": "integer", "format": "int64", - "description": "时间窗口结束时间（Unix 秒，10 位），与 start 的差值不得超过 30 天。" + "description": "时间窗口结束时间（Unix 秒，10 位），必填，与 start 的差值不得超过 45 天。" } - } + }, + "required": [ + "start", + "end" + ] }, "ScheduleIDResponse": { "type": "object", @@ -38443,7 +38411,8 @@ "role_id": { "type": "integer", "format": "int64", - "description": "值班角色 ID。" + "description": "值班角色 ID。", + "minimum": 0 }, "person_ids": { "type": "array", @@ -38451,7 +38420,8 @@ "type": "integer", "format": "int64" }, - "description": "该角色下的用户 ID 列表。" + "description": "该角色下的用户 ID 列表。", + "minItems": 1 } } }, @@ -38467,8 +38437,11 @@ ], "properties": { "group_name": { - "type": "string", - "description": "值班组显示名称。" + "type": [ + "string", + "null" + ], + "description": "值班组显示名称，仅设置旧字段 name 时为 null。" }, "name": { "type": "string", @@ -38495,7 +38468,7 @@ }, "ScheduleRestrictPeriod": { "type": "object", - "description": "单个值班周期内的限制区间。", + "description": "轮转周期内的限制时段。restrict_start 与 restrict_end 为秒级偏移，除非都为 0，否则不能相等。", "required": [ "restrict_start", "restrict_end" @@ -38518,11 +38491,16 @@ "description": "按星期几生效的掩码配置。", "properties": { "repeat": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { - "type": "integer" + "type": "integer", + "minimum": 0, + "maximum": 6 }, - "description": "生效的星期几（0 = 周日）。" + "description": "参与轮转的星期数（0 = 周日）。与 restrict_mode = 2（按周）互斥。" } } }, @@ -38587,11 +38565,14 @@ "description": "分层权重，用于排序。" }, "groups": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleGroup" }, - "description": "参与轮转的值班组。" + "description": "参与轮转的值班组，未设置时为 null。" }, "rotation_duration": { "type": "integer", @@ -38601,7 +38582,7 @@ "handoff_time": { "type": "integer", "format": "int64", - "description": "值班交接时间，Unix 时间戳（秒）。" + "description": "轮转交接时间，以一周内的秒数偏移表示（星期 x 86400 + 当日秒数），不是 Unix 绝对时间戳。" }, "enable_time": { "type": "integer", @@ -38633,11 +38614,14 @@ "description": "旧版限制区间结束偏移（秒）。" }, "restrict_periods": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleRestrictPeriod" }, - "description": "每个值班周期内的限制区间集合。" + "description": "每个轮转周期内的限制时段，未设置时为 null。" }, "day_mask": { "$ref": "#/components/schemas/ScheduleDayMask", @@ -38664,17 +38648,23 @@ "description": "更新人 ID。" }, "layer_name": { - "type": "string", - "description": "分层显示名称。" + "type": [ + "string", + "null" + ], + "description": "面向用户的层名称，未设置时为 null。" }, "fair_rotation": { "type": "boolean", "description": "是否启用公平轮转。" }, "layer_start": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "分层开始时间（Unix 秒）。" + "description": "层生效时间（Unix 秒），未设置时为 null。" }, "layer_end": { "type": [ @@ -38697,7 +38687,8 @@ "rotation_value": { "type": "integer", "format": "int64", - "description": "轮转数量（每周期的 rotation_unit 个数）。" + "description": "轮转数量（每周期的 rotation_unit 个数）。", + "minimum": 0 }, "mask_continuous_enabled": { "type": "boolean", @@ -38760,7 +38751,8 @@ "description": "IM 提供方类型（如 feishu_app、dingtalk_app、wecom_app、teams_app、slack_app）。" }, "settings": { - "$ref": "#/components/schemas/ScheduleImNotifySettings" + "$ref": "#/components/schemas/ScheduleImNotifySettings", + "description": "Webhook 渠道配置。" } } }, @@ -38774,11 +38766,14 @@ "properties": { "cycle": { "type": "string", - "description": "通知周期。" + "description": "通知周期，仅支持 `day`（按天）。", + "enum": [ + "day" + ] }, "start": { "type": "string", - "description": "周期内的通知开始时间。" + "description": "发送时间，格式 `HH:MM`（24 小时制）。" } } }, @@ -38821,10 +38816,12 @@ "description": "提前通知时间（秒）；为 `0` 时在排班开始时通知；不传则不发送提前通知。" }, "fixed_time": { - "$ref": "#/components/schemas/ScheduleFixedTimeNotifyInfo" + "$ref": "#/components/schemas/ScheduleFixedTimeNotifyInfo", + "description": "定时通知配置，未配置时为 null。" }, "by": { - "$ref": "#/components/schemas/ScheduleNotifyBy" + "$ref": "#/components/schemas/ScheduleNotifyBy", + "description": "接收人通知偏好，未配置时为 null。" }, "im": { "type": "object", @@ -38834,11 +38831,14 @@ "description": "旧版 IM 类型到 token 的映射。" }, "webhooks": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleImNotify" }, - "description": "IM Webhook 通知通道。" + "description": "IM Webhook 通知渠道，未配置时为 null。" } } }, @@ -38863,7 +38863,8 @@ "description": "时段结束时间（Unix 秒）。" }, "group": { - "$ref": "#/components/schemas/ScheduleGroup" + "$ref": "#/components/schemas/ScheduleGroup", + "description": "覆盖该班次的值班组；null 表示覆盖空档。" }, "index": { "type": "integer", @@ -38894,11 +38895,14 @@ "description": "分层模式：0 = 普通轮转，1 = 覆盖。" }, "schedules": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleCalculatedSchedule" }, - "description": "计算出的值班时段。" + "description": "计算出的班次；该层无排班时为 null。" } } }, @@ -38925,7 +38929,8 @@ "description": "时段结束时间（Unix 秒）。" }, "group": { - "$ref": "#/components/schemas/ScheduleGroup" + "$ref": "#/components/schemas/ScheduleGroup", + "description": "该班次正在值班的值班组。" }, "update_at": { "type": "integer", @@ -39025,22 +39030,28 @@ "description": "更新人 ID。" }, "layers": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleLayer" }, - "description": "值班表的轮转分层。" + "description": "值班表定义的轮转层。未加载层信息时为 null（例如 `/schedule/infos`，或未传 start/end 的 `/schedule/list`）。" }, "field": { "type": "string", "description": "旧版字段更新接口使用的字段名。" }, "schedule_layers": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleCalculatedLayer" }, - "description": "按窗口计算出的分层值班结果。" + "description": "按请求时间窗口计算出的各层排班，未计算时为 null。" }, "final_schedule": { "$ref": "#/components/schemas/ScheduleCalculatedLayer", @@ -39049,20 +39060,24 @@ "start": { "type": "integer", "format": "int64", - "description": "窗口开始时间（Unix 秒）。" + "description": "时间窗口开始（Unix 秒）。为 0（未请求窗口）时省略。" }, "end": { "type": "integer", "format": "int64", - "description": "窗口结束时间（Unix 秒）。" + "description": "时间窗口结束（Unix 秒）。为 0（未请求窗口）时省略。" }, "notify": { - "$ref": "#/components/schemas/ScheduleNotify" + "$ref": "#/components/schemas/ScheduleNotify", + "description": "通知配置，未配置时为 null。" }, "schedule_id": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "值班表 ID。" + "description": "值班表 ID。`/schedule/preview` 返回时为 null。" }, "schedule_name": { "type": [ @@ -39087,11 +39102,14 @@ "description": "值班表描述。/schedule/preview 返回时为 null。" }, "layer_schedules": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleCalculatedLayer" }, - "description": "与 schedule_layers 等价，用于旧版兼容。" + "description": "schedule_layers 的兼容别名，未计算时为 null。" }, "status": { "type": [ @@ -39112,7 +39130,7 @@ }, "ScheduleUpsertRequest": { "type": "object", - "description": "值班表创建/更新/预览共用的请求体，结构与值班表详情一致，此处仅列出常用字段。更新时需要 schedule_id；预览时 start、end 必填。", + "description": "值班表创建/更新/预览请求体。服务端接受与值班表详情模型相同的结构，此处仅列出关键字段。创建时必填 `schedule_name`（或旧字段 `name`），更新时必填 `schedule_id`，预览时必填 `start` 和 `end`。", "properties": { "schedule_id": { "type": [ @@ -39174,6 +39192,13 @@ "type": "integer", "format": "int64", "description": "预览窗口结束时间（Unix 秒，10 位），/schedule/preview 必填，且距 start 不超过 45 天。" + }, + "disabled": { + "type": [ + "integer", + "null" + ], + "description": "0 = 启用，1 = 禁用。缺省时为启用。" } } }, @@ -39183,7 +39208,7 @@ "properties": { "query": { "type": "string", - "description": "搜索关键字，匹配值班表名称。" + "description": "按值班表名称或描述匹配的关键字。" }, "p": { "type": "integer", @@ -39233,11 +39258,14 @@ ], "properties": { "items": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleItem" }, - "description": "当前页的值班表列表。" + "description": "当前页的值班表；无匹配时为 null。" }, "total": { "type": "integer", @@ -39254,11 +39282,14 @@ ], "properties": { "items": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/ScheduleItem" }, - "description": "当前用户被分配到的值班表（或请求指定的 ID 对应的值班表）。" + "description": "分配给当前用户的值班表（或匹配请求 ID 的值班表）；无时为 null。" } } }, @@ -39292,7 +39323,7 @@ }, "team_id": { "type": "integer", - "format": "int64", + "format": "uint64", "description": "所属团队 ID，0 表示不关联团队。" }, "workdays": { @@ -39371,7 +39402,7 @@ "integer", "null" ], - "format": "int64", + "format": "uint64", "description": "新的所属团队 ID，可通过 `POST /team/list` 获取。" }, "workdays": { @@ -39465,14 +39496,14 @@ "minimum": 0, "maximum": 6 }, - "description": "工作日（0 = 周日，6 = 周六）。" + "description": "工作日（0 = 周日，6 = 周六）。为空时省略。" }, "extra_cal_ids": { "type": "array", "items": { "type": "string" }, - "description": "继承的公共节假日日历 ID 列表。" + "description": "继承的公共节假日日历 ID 列表。为空时省略。" }, "created_at": { "type": "integer", @@ -39539,7 +39570,8 @@ }, "total": { "type": "integer", - "description": "返回的日历总数。" + "description": "返回的日历总数。", + "format": "int64" } } }, @@ -39583,10 +39615,7 @@ "description": "事件结束日期（不含），格式 YYYY-MM-DD。" }, "is_off": { - "type": [ - "boolean", - "null" - ], + "type": "boolean", "description": "是否为非工作日。true = 休息日，false = 工作日覆盖。" } } @@ -39744,7 +39773,8 @@ }, "total": { "type": "integer", - "description": "返回的事件总数。" + "description": "返回的事件总数。", + "format": "int64" } } }, @@ -39776,7 +39806,8 @@ "creator_id", "updated_by", "created_at", - "updated_at" + "updated_at", + "incident_card_hidden_fields" ], "properties": { "account_id": { @@ -39864,7 +39895,8 @@ "description": "Zoom 机器人消息模板源。" }, "incident_card_hidden_fields": { - "$ref": "#/components/schemas/IncidentCardHiddenFields" + "$ref": "#/components/schemas/IncidentCardHiddenFields", + "description": "按 IM 应用类型配置的故障卡片隐藏字段，未配置时为空对象。" }, "status": { "type": "string", @@ -39911,10 +39943,11 @@ "template_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", - "description": "要操作的模板 ID。传入 `000000000000000000000001` 可访问系统预置模板。", + "description": "目标模板 ID。传入 `6321aad26c12104586a88916` 可访问内置预设模板。", "example": "6605a1b2c3d4e5f6a7b8c9d0" } - } + }, + "description": "携带模板 ID 的请求体。" }, "TemplateListRequest": { "type": "object", @@ -39987,7 +40020,7 @@ "total": { "type": "integer", "format": "int64", - "description": "符合过滤条件的模板总数。", + "description": "符合筛选条件的模板总数（跨页统计，包含内置预设模板）。", "example": 47 }, "has_next_page": { @@ -40022,7 +40055,7 @@ "minLength": 1, "maxLength": 39, "description": "模板名称，同一账户内唯一，长度 1–39 个字符。", - "example": "生产环境默认模板" + "example": "Prod incident default" }, "description": { "type": "string", @@ -40112,9 +40145,10 @@ "template_name": { "type": "string", "description": "从请求中回显的模板名称。", - "example": "生产环境默认模板" + "example": "Prod incident default" } - } + }, + "description": "创建模板响应。" }, "TemplateUpdateRequest": { "type": "object", @@ -40263,10 +40297,6 @@ } } }, - "CsvFileResponse": { - "type": "string", - "description": "以附件形式返回的 CSV 文件内容。" - }, "EnrichmentInfoRequest": { "type": "object", "required": [ @@ -40293,7 +40323,8 @@ "type": "integer", "format": "int64" }, - "description": "待查询的集成 ID 列表。" + "description": "待查询的集成 ID 列表，至少包含 1 个。", + "minItems": 1 } } }, @@ -40334,14 +40365,17 @@ "mapping", "drop" ], - "description": "规则类型。`extraction` 通过正则或 GJson 提取标签；`composition` 通过模板组合标签；`mapping` 通过映射规则或 API 查找填充标签；`drop` 删除标签。" + "description": "规则类型。\n| 值 | 含义 |\n|---|---|\n| `extraction` | 通过正则或 GJson 从告警的 `title`、`description` 或 `labels.*` 键提取值并写入标签。 |\n| `composition` | 用 Go `text/template` 对事件渲染模板，结果写入标签。 |\n| `mapping` | 从映射规则或外部映射 API 查找标签。 |\n| `drop` | 从告警中删除指定标签。 |" }, "if": { - "type": "array", + "type": [ + "array", + "null" + ], "items": { "$ref": "#/components/schemas/EnrichFilter" }, - "description": "可选 AND 过滤条件列表，不匹配时跳过该规则。" + "description": "可选的 AND 过滤条件列表；所有条件都匹配时才执行该规则。无条件时为 `null`。过滤键来自告警/变更事件的键集合（如 `title`、`labels.severity`）。" }, "settings": { "description": "与规则类型对应的配置，具体结构由 `kind` 字段决定。", @@ -40385,11 +40419,12 @@ }, "result_label": { "type": "string", - "description": "写入提取值的目标标签键，须符合 `^[a-z][a-z0-9_]{0,62}$`。" + "description": "提取值写入的目标标签键名，须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`。", + "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "pattern": { "type": "string", - "description": "RE2 正则表达式。使用命名捕获组 `(?P...)` 提取子匹配；无命名组时取全匹配。与 `g_json` 互斥。" + "description": "应用于源值的 RE2 正则表达式，须至少包含一个捕获组；所有捕获组用空格连接后写入 `result_label`。与 `g_json` 互斥。" }, "g_json": { "type": "string", @@ -40411,12 +40446,14 @@ "properties": { "result_label": { "type": "string", - "description": "写入组合值的目标标签键，须符合 `^[a-z][a-z0-9_]{0,62}$`。" + "description": "组合值写入的目标标签键名，须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`。", + "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "template": { "type": "string", "maxLength": 500, - "description": "Go `text/template` 字符串，可引用告警字段 `{{.title}}`、`{{.description}}`、`{{.labels.key}}`。示例：`{{.labels.region}}-{{.labels.env}}`。" + "description": "Go `text/template` 模板串（1–500 字符），基于事件结构体渲染，如 `{{.Title}}`、`{{.Description}}`、`{{.Labels.key}}`。示例：`{{.Labels.region}}-{{.Labels.env}}`。", + "minLength": 1 }, "override": { "type": "boolean", @@ -40434,9 +40471,10 @@ "result_labels": { "type": "array", "items": { - "type": "string" + "type": "string", + "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, - "description": "从映射查找结果中填充的目标标签键列表。" + "description": "映射查找结果要填充的标签键名，每个须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`。" }, "mapping_type": { "type": "string", @@ -40488,7 +40526,8 @@ "properties": { "key": { "type": "string", - "description": "告警标签键。" + "description": "要匹配的事件键（如 `labels.severity`、`title`），不能为空。", + "minLength": 1 }, "oper": { "type": "string", @@ -40503,7 +40542,8 @@ "items": { "type": "string" }, - "description": "待匹配的值列表。" + "description": "匹配值列表，至少包含 1 个。", + "minItems": 1 } } }, @@ -40525,7 +40565,11 @@ }, "status": { "type": "string", - "description": "规则集状态。" + "enum": [ + "enabled", + "deleted" + ], + "description": "规则集状态：`enabled`（生效）或 `deleted`（已软删除）。读取接口会过滤软删除的规则集，响应中始终为 `enabled`。" }, "updated_by": { "type": "integer", @@ -40546,6 +40590,11 @@ "type": "integer", "format": "int64", "description": "最后更新时间，Unix 时间戳（秒）。" + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "删除时间，Unix 时间戳（秒）。规则集未删除时省略；读取接口不会返回已软删除的规则集，因此实际上始终省略。" } }, "required": [ @@ -40611,18 +40660,22 @@ "source_labels": { "type": "array", "items": { - "type": "string" + "type": "string", + "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "maxItems": 3, - "description": "查找键标签名（1–3 个），不得与 `result_labels` 重叠。" + "description": "查找键标签名（1–3 个）。每个须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`；列表内不得重复，且不得与 `result_labels` 重叠。", + "uniqueItems": true }, "result_labels": { "type": "array", "items": { - "type": "string" + "type": "string", + "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "maxItems": 10, - "description": "输出标签名（1–10 个），不得与 `source_labels` 重叠。" + "description": "匹配后写入的输出标签名（1–10 个）。每个须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`；列表内不得重复，且不得与 `source_labels` 重叠。", + "uniqueItems": true } } }, @@ -40711,7 +40764,11 @@ }, "status": { "type": "string", - "description": "映射规则状态。" + "enum": [ + "enabled", + "deleted" + ], + "description": "映射规则状态：`enabled`（生效）或 `deleted`（已软删除）。list 接口不返回 `deleted`，info 接口可能返回。" }, "team_id": { "type": "integer", @@ -40731,12 +40788,17 @@ "created_at": { "type": "integer", "format": "int64", - "description": "创建时间，Unix 时间戳（秒）。" + "description": "创建时间，Unix 时间戳（秒）。为 0（历史数据）时省略。" }, "updated_at": { "type": "integer", "format": "int64", - "description": "最后更新时间，Unix 时间戳（秒）。" + "description": "最后更新时间，Unix 时间戳（秒）。为 0（历史数据）时省略。" + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "删除时间，Unix 时间戳（秒）。未软删除时省略。" } }, "required": [ @@ -40786,7 +40848,7 @@ "additionalProperties": { "type": "string" }, - "description": "按来源标签值精确过滤。若指定 query，须包含全部来源标签。" + "description": "按来源标签值精确过滤。不属于来源标签的键会被静默忽略；一旦指定，必须包含全部来源标签。" }, "orderby": { "type": "string", @@ -40794,25 +40856,37 @@ "created_at", "updated_at" ], - "description": "排序字段。" + "description": "排序字段，默认 `updated_at`。" }, "asc": { "type": "boolean", "description": "为 `true` 时升序排列。" }, "p": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "页码（从 1 开始），用于页码分页。" + "description": "页码（从 1 开始），用于页码分页；省略、`null` 或 0 时默认为 1。设置 `search_after_ctx` 时忽略该参数。页码分页最多可取 10,000 行（`p * limit <= 10000`）。", + "minimum": 0 }, "limit": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "每页数量（1–100，默认 20）。" + "description": "每页数量（0–100）；省略、`null` 或 0 时默认为 20。", + "minimum": 0, + "maximum": 100 }, "search_after_ctx": { - "type": "string", - "description": "用于游标分页的不透明游标令牌。" + "type": [ + "string", + "null" + ], + "description": "游标分页使用的不透明游标——传入上一次响应中的 `search_after_ctx`。须为 MongoDB ObjectID 十六进制字符串；设置后忽略 `p`。" } } }, @@ -40822,24 +40896,24 @@ "properties": { "key": { "type": "string", - "description": "由来源标签值组合生成的唯一键。" + "description": "数据行的组合键——来源标签值（按标签名排序、以 `:` 连接）的 MD5。为空时省略。" }, "fields": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "该行所有标签的键值对。" + "description": "该行的全部标签键值对，为空时省略。" }, "created_at": { "type": "integer", "format": "int64", - "description": "创建时间，Unix 时间戳（秒）。" + "description": "创建时间，Unix 时间戳（秒），为 0 时省略。" }, "updated_at": { "type": "integer", "format": "int64", - "description": "最后更新时间，Unix 时间戳（秒）。" + "description": "最后更新时间，Unix 时间戳（秒），为 0 时省略。" } } }, @@ -40864,7 +40938,7 @@ }, "search_after_ctx": { "type": "string", - "description": "用于获取下一页的游标令牌。" + "description": "下一页游标（本页最后一行的 ObjectID 十六进制）。没有下一页时省略。" } }, "required": [ @@ -40893,7 +40967,7 @@ } }, "maxItems": 1000, - "description": "待插入或更新的数据行，每行须包含所有来源标签和结果标签的值。" + "description": "待插入或更新的数据行。每行须包含所有来源标签和结果标签；未知标签会被静默丢弃；单个值超过 2048 字符将被拒绝。" } } }, @@ -40933,21 +41007,6 @@ } } }, - "MappingDataUploadRequest": { - "type": "object", - "description": "Multipart form-data 上传请求。`schema_id` 通过查询参数传入，`file` 为 CSV 文件字段。", - "properties": { - "schema_id": { - "type": "string", - "description": "映射规则 ID（以查询参数传递），可通过 `POST /enrichment/mapping/schema/list` 获取。" - }, - "file": { - "type": "string", - "format": "binary", - "description": "待上传的 CSV 文件。" - } - } - }, "MappingAPIIDRequest": { "type": "object", "required": [ @@ -40974,7 +41033,7 @@ }, "description": { "type": "string", - "description": "可选描述。" + "description": "可选描述，超过 500 字符会被静默截断。" }, "url": { "type": "string", @@ -40991,15 +41050,19 @@ "additionalProperties": { "type": "string" }, - "description": "自定义 HTTP 请求头。" + "description": "自定义 HTTP 请求头。SaaS 模式下安全敏感的请求头名（`authorization`、`cookie`、`x-forwarded-for` 等）会被拒绝；键须为 RFC 7230 token 字符（最长 1024），值最长 4096 字符。" }, "timeout": { "type": "integer", - "description": "请求超时秒数（1–3），默认 2。" + "description": "请求超时秒数（1–3），默认 2。", + "minimum": 1, + "maximum": 3 }, "retry_count": { "type": "integer", - "description": "失败重试次数（0–1），默认 0。" + "description": "失败重试次数（0–1），默认 0。", + "minimum": 0, + "maximum": 1 }, "team_id": { "type": "integer", @@ -41071,21 +41134,25 @@ "additionalProperties": { "type": "string" }, - "description": "新请求头映射（覆盖原有值）。" + "description": "自定义 HTTP 请求头。SaaS 模式下安全敏感的请求头名（`authorization`、`cookie`、`x-forwarded-for` 等）会被拒绝；键须为 RFC 7230 token 字符（最长 1024），值最长 4096 字符。" }, "timeout": { "type": [ "integer", "null" ], - "description": "新超时秒数。" + "description": "新超时秒数。", + "minimum": 1, + "maximum": 3 }, "retry_count": { "type": [ "integer", "null" ], - "description": "新重试次数。" + "description": "新重试次数。", + "minimum": 0, + "maximum": 1 }, "team_id": { "type": [ @@ -41118,11 +41185,14 @@ "description": "端点 URL。" }, "headers": { - "type": "object", + "type": [ + "object", + "null" + ], "additionalProperties": { "type": "string" }, - "description": "自定义请求头。" + "description": "自定义请求头，未配置时为 `null`。" }, "timeout": { "type": "integer", @@ -41138,7 +41208,11 @@ }, "status": { "type": "string", - "description": "API 状态。" + "enum": [ + "enabled", + "deleted" + ], + "description": "API 状态：`enabled`（生效）或 `deleted`（已软删除）。list 接口不返回 `deleted`，info 接口可能返回。" }, "team_id": { "type": "integer", @@ -41158,12 +41232,17 @@ "created_at": { "type": "integer", "format": "int64", - "description": "创建时间，Unix 时间戳（秒）。" + "description": "创建时间，Unix 时间戳（秒）。为 0（历史数据）时省略。" }, "updated_at": { "type": "integer", "format": "int64", - "description": "最后更新时间，Unix 时间戳（秒）。" + "description": "最后更新时间，Unix 时间戳（秒）。为 0（历史数据）时省略。" + }, + "deleted_at": { + "type": "integer", + "format": "int64", + "description": "删除时间，Unix 时间戳（秒）。未软删除时省略。" } }, "required": [ @@ -41212,7 +41291,8 @@ "start_time": { "type": "integer", "format": "int64", - "description": "起始时间，Unix 秒，必须大于 0。" + "description": "起始时间，Unix 秒。必须大于 0。", + "exclusiveMinimum": 0 }, "end_time": { "type": "integer", @@ -41225,7 +41305,8 @@ "type": "integer", "format": "int64" }, - "description": "按团队 ID 过滤，至多 100 项。" + "description": "按团队 ID 过滤，至多 100 项。", + "maxItems": 100 }, "channel_ids": { "type": "array", @@ -41233,7 +41314,8 @@ "type": "integer", "format": "int64" }, - "description": "按协作空间 ID 过滤，至多 100 项。" + "description": "按协作空间 ID 过滤，至多 100 项。", + "maxItems": 100 }, "responder_ids": { "type": "array", @@ -41241,7 +41323,8 @@ "type": "integer", "format": "int64" }, - "description": "按处理人员 ID 过滤，至多 100 项。" + "description": "按处理人员 ID 过滤，至多 100 项。", + "maxItems": 100 }, "severities": { "type": "array", @@ -41254,7 +41337,8 @@ "Ok" ] }, - "description": "按严重程度过滤，至多 3 项。" + "description": "按严重程度过滤，至多 3 项。", + "maxItems": 3 }, "incident_ids": { "type": "array", @@ -41262,11 +41346,12 @@ "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, - "description": "按故障 ID（MongoDB ObjectID）过滤，至多 100 项。" + "description": "按故障 ID（MongoDB ObjectID）过滤，至多 100 项。", + "maxItems": 100 }, "query": { "type": "string", - "description": "作用于故障标题与描述的全文关键字。" + "description": "对故障标题做子串匹配（SQL `LIKE %query%`）。" }, "labels": { "type": "object", @@ -41285,11 +41370,11 @@ "enum": [ "created_at" ], - "description": "底层故障集合的排序字段。当前仅支持 `created_at`（按故障创建时间）。" + "description": "故障列表的排序字段，目前仅支持 `created_at`（故障创建时间）。仅 `/insight/incident/list` 使用。" }, "asc": { "type": "boolean", - "description": "为 `true` 时升序，否则降序。" + "description": "为 `true` 时升序，否则降序。仅 `/insight/incident/list` 使用。" }, "is_my_team": { "type": "boolean", @@ -41297,65 +41382,39 @@ }, "time_zone": { "type": "string", - "description": "IANA 时区名（如 `Asia/Shanghai`），用于解释时间范围。默认使用账户时区。" + "description": "用于划分 日/周/月 聚合桶的 IANA 时区名（如 `Asia/Shanghai`）。可选，默认 UTC；仅 `/insight/incident/export` 例外：缺省时依次回退到账户时区、`Asia/Shanghai`。" }, "seconds_to_close_from": { "type": "integer", "format": "int64", - "description": "解决时长下界（秒，包含）。" + "description": "解决时长下界（秒，包含）。", + "minimum": 0 }, "seconds_to_close_to": { "type": "integer", "format": "int64", - "description": "解决时长上界（秒，不包含）。两端同时设置时，必须大于 `seconds_to_close_from`。" + "description": "解决时长上界（秒，不包含）。两端同时设置时，必须大于 `seconds_to_close_from`。", + "minimum": 0 }, "seconds_to_ack_from": { "type": "integer", "format": "int64", - "description": "认领时长下界（秒，包含）。" + "description": "认领时长下界（秒，包含）。", + "minimum": 0 }, "seconds_to_ack_to": { "type": "integer", "format": "int64", - "description": "认领时长上界（秒，不包含）。两端同时设置时，必须大于 `seconds_to_ack_from`。" + "description": "认领时长上界（秒，不包含）。两端同时设置时，必须大于 `seconds_to_ack_from`。", + "minimum": 0 }, "export_fields": { "type": "array", "items": { - "type": "string", - "enum": [ - "incident_id", - "title", - "severity", - "progress", - "channel_id", - "channel_name", - "team_id", - "team_name", - "created_at", - "seconds_to_ack", - "seconds_to_close", - "closed_by", - "engaged_seconds", - "hours", - "notifications", - "interruptions", - "acknowledgements", - "assignments", - "reassignments", - "escalations", - "manual_escalations", - "timeout_escalations", - "assigned_to", - "responders", - "description", - "labels", - "fields", - "creator_id", - "creator_name" - ] + "type": "string" }, - "description": "导出 CSV 时要包含的列键子集，至多 50 项。仅导出接口会读取。" + "description": "导出 CSV 的列 key 列表，按给定顺序输出；未知或重复的 key 会被拒绝。各导出接口支持的 key 集合不同，见对应接口的描述。仅导出接口使用；最多 50 个。", + "maxItems": 50 }, "description_html_to_text": { "type": "boolean", @@ -41403,21 +41462,30 @@ "description": "故障分页列表请求。在 InsightFilter 基础上增加分页字段。", "properties": { "p": { - "type": "integer", - "minimum": 1, + "type": [ + "integer", + "null" + ], + "minimum": 0, "default": 1, - "description": "页码，从 1 开始，默认 1。" + "description": "页码，从 1 开始。仅在未提供 `search_after_ctx` 时生效；`p * limit` 不能超过 10,000 条。" }, "limit": { - "type": "integer", - "minimum": 1, + "type": [ + "integer", + "null" + ], + "minimum": 0, "maximum": 100, "default": 20, - "description": "每页条数，范围 1-100，默认 20。" + "description": "每页条数，最大 100，默认 20。" }, "search_after_ctx": { - "type": "string", - "description": "上一页返回的游标 token，下一页请求时回传。" + "type": [ + "string", + "null" + ], + "description": "上一页返回的分页游标（该页最后一行的故障 ID），传入以获取下一页。" } } } @@ -41447,7 +41515,10 @@ }, "k": { "type": "integer", - "description": "返回前 K 条记录，取值范围 1-100。" + "description": "返回的前 K 条记录数，1 到 100，默认 20。", + "minimum": 1, + "maximum": 100, + "default": 20 }, "orderby": { "type": "string", @@ -41455,7 +41526,7 @@ "total_alert_cnt", "total_alert_event_cnt" ], - "description": "排序字段。`total_alert_cnt` 按告警数量排序；`total_alert_event_cnt` 按原始告警事件数量排序。" + "description": "排序字段。`total_alert_cnt` 按告警数排序；`total_alert_event_cnt` 按原始告警事件数排序（默认）。" }, "asc": { "type": "boolean", @@ -41476,12 +41547,12 @@ "sleep", "off" ], - "description": "启用 `split_hours` 时的时段桶。`work` 为周一至周五 08:00–19:00，`sleep` 为每日 23:00–08:00，`off` 为其余时间，均按账户时区判定（`sleep` 优先于 `work` 判定）。" + "description": "启用 `split_hours` 时的小时桶。`work` 为周一至周五 08:00–19:00，`sleep` 为每天 23:00–08:00，`off` 为其余时间，均按账户时区计算（`sleep` 优先于 `work`）。`split_hours` 为 false 时不返回。" }, "ts": { "type": "integer", "format": "int64", - "description": "聚合桶的起始时间（Unix 秒）。在使用 `aggregate_unit` 时返回。" + "description": "聚合桶的起始时间，Unix 时间戳（秒）。未使用 `aggregate_unit` 时等于 `start_time`。" }, "channel_id": { "type": "integer", @@ -41599,22 +41670,22 @@ "mean_seconds_to_ack": { "type": "number", "format": "double", - "description": "平均首次认领耗时（秒）。" + "description": "平均首次认领耗时（秒）；桶内无已认领故障时为 0。" }, "mean_seconds_to_close": { "type": "number", "format": "double", - "description": "平均关闭耗时（秒）。" + "description": "平均关闭耗时（秒）；桶内无已关闭故障时为 0。" }, "noise_reduction_pct": { "type": "number", "format": "double", - "description": "降噪比（%）：`100 − 故障数 ÷ 告警事件数 × 100`；无告警事件对比数据时为 0。" + "description": "降噪比（%）：100 − 故障数 ÷ 告警事件数 × 100，保留两位小数；无告警事件数据或告警事件数不超过故障数时为 0。" }, "acknowledgement_pct": { "type": "number", "format": "double", - "description": "认领率（%）：认领过的故障数 ÷ 故障总数 × 100，保留两位小数；故障总数为 0 时为 100。" + "description": "认领率（%）：已认领故障数 ÷ 故障总数 × 100，保留两位小数且不超过 100；桶内无故障时为 0。" }, "total_alert_cnt": { "type": "integer", @@ -41692,12 +41763,12 @@ "mean_seconds_to_ack": { "type": "number", "format": "double", - "description": "该人员的平均认领耗时（秒）。" + "description": "该响应人的平均认领耗时（秒）；无认领记录时为 0。" }, "acknowledgement_pct": { "type": "number", "format": "double", - "description": "该人员的认领率（%）：认领过的故障数 ÷ 参与的故障数 × 100，保留两位小数。" + "description": "该响应人的认领率（%）：已认领故障数 ÷ 涉及故障数 × 100，保留两位小数且不超过 100；无故障时为 0。" } } } @@ -41764,7 +41835,12 @@ }, "progress": { "type": "string", - "description": "故障处理进度——`Triggered`、`Processing`、`Closed` 之一。" + "description": "故障处理状态——`Triggered`（触发）、`Processing`（处理中）、`Closed`（已关闭）之一。", + "enum": [ + "Triggered", + "Processing", + "Closed" + ] }, "severity": { "type": "string", @@ -41808,11 +41884,11 @@ "owner_id": { "type": "integer", "format": "int64", - "description": "故障负责人的成员 ID。" + "description": "故障负责人的成员 ID。为 0（无负责人）时不返回。" }, "owner_name": { "type": "string", - "description": "故障负责人的显示名称。" + "description": "故障负责人的显示名。为空时不返回。" }, "creator_id": { "type": "integer", @@ -41826,11 +41902,11 @@ "closer_id": { "type": "integer", "format": "int64", - "description": "关闭该故障的成员 ID。" + "description": "关闭人的成员 ID。为 0（非人工关闭）时不返回。" }, "closer_name": { "type": "string", - "description": "关闭该故障的成员显示名称。" + "description": "关闭人的显示名。为空时不返回。" }, "seconds_to_ack": { "type": "integer", @@ -41859,11 +41935,11 @@ "snoozed_before": { "type": "integer", "format": "int64", - "description": "故障被暂缓到何时的 Unix 时间戳（秒）。" + "description": "故障静默到的截止时间，Unix 时间戳（秒）。未静默时不返回该字段。" }, "ever_muted": { "type": "boolean", - "description": "该故障是否曾因抖动（flapping）被收敛静默。" + "description": "故障是否曾被降噪收敛。为 false 时不返回。" }, "frequency": { "type": "string", @@ -41871,7 +41947,7 @@ "frequent", "rare" ], - "description": "故障频次分类：`frequent` 高频、`rare` 低频。" + "description": "频率分类：`frequent`（高频）或 `rare`（低频）。未分类时不返回。" }, "responders": { "type": "array", @@ -41910,8 +41986,11 @@ } }, "assigned_to": { - "type": "object", - "description": "故障的当前分派目标。", + "type": [ + "object", + "null" + ], + "description": "故障的当前分派信息；无分派记录时为 `null`。", "properties": { "person_ids": { "type": "array", @@ -41960,12 +42039,12 @@ "additionalProperties": { "type": "string" }, - "description": "故障标签，键值对形式；无标签时不返回。" + "description": "故障标签键值对。本接口响应中始终不返回（仅供导出使用）。" }, "fields": { "type": "object", "additionalProperties": true, - "description": "故障自定义字段；无自定义字段时不返回。" + "description": "故障自定义字段。本接口响应中始终不返回（仅供导出使用）。" }, "notifications": { "type": "integer", @@ -42023,7 +42102,7 @@ }, "search_after_ctx": { "type": "string", - "description": "用于翻下一页的游标 token，下次请求时通过 `search_after_ctx` 回传。" + "description": "下一页游标——本页最后一行的故障 ID。仅在 `has_next_page` 为 true 时返回。" }, "items": { "type": "array", @@ -42043,7 +42122,12 @@ }, "hours": { "type": "string", - "description": "启用 `split_hours` 时的时段桶。" + "description": "启用 `split_hours` 时的小时桶：`work`、`sleep` 或 `off`。`split_hours` 为 false 时不返回。", + "enum": [ + "work", + "sleep", + "off" + ] }, "total_alert_cnt": { "type": "integer", @@ -42086,7 +42170,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "所属状态页 ID。" + "description": "所属状态页 ID。为 0 时不返回（已存储事件必有值）。" }, "type": { "type": "string", @@ -42102,7 +42186,7 @@ }, "description": { "type": "string", - "description": "事件描述（Markdown）。" + "description": "事件描述（Markdown）。为空时不返回。" }, "status": { "type": "string", @@ -42115,14 +42199,14 @@ "ongoing", "completed" ], - "description": "事件当前状态。故障事件支持 `investigating`/`identified`/`monitoring`/`resolved`；维护事件支持 `scheduled`/`ongoing`/`completed`。" + "description": "事件当前状态。故障事件支持 `investigating`/`identified`/`monitoring`/`resolved`；维护事件支持 `scheduled`/`ongoing`/`completed`。为空时不返回（已存储事件必有值）。" }, "affected_components": { "type": "array", "items": { "$ref": "#/components/schemas/AffectedStatusPageComponentItem" }, - "description": "当前受此事件影响的组件及其状态。" + "description": "当前受此事件影响的组件及其状态。无受影响组件时不返回。" }, "responder_ids": { "type": "array", @@ -42130,43 +42214,43 @@ "type": "integer", "format": "int64" }, - "description": "事件负责成员 ID 列表。" + "description": "事件负责成员 ID 列表。未指派负责成员时不返回。" }, "linked_change_ids": { "type": "array", "items": { "type": "string" }, - "description": "关联的事件 ID 列表（相关故障、发布等）。" + "description": "关联的事件 ID 列表（相关故障、发布等）。为空时不返回。" }, "start_at_seconds": { "type": "integer", "format": "int64", - "description": "事件开始时间（Unix 秒）。" + "description": "事件开始时间（Unix 秒），取自第一条时间线更新。为 0 时不返回。" }, "close_at_seconds": { "type": "integer", "format": "int64", - "description": "计划结束时间（Unix 秒）。回溯事件和维护事件会设置此字段。" + "description": "事件结束时间（Unix 秒）。维护事件为计划结束时间；已关闭事件为进入终态（`resolved`/`completed`）的时间。未设置时不返回。" }, "is_retrospective": { "type": "boolean", - "description": "是否为回溯（历史）事件。" + "description": "是否为回溯（历史）事件。为 false 时不返回。" }, "updates": { "type": "array", "items": { "$ref": "#/components/schemas/StatusPageChangeUpdateItem" }, - "description": "事件的时间线更新列表，按时间排序。" + "description": "事件的时间线更新列表，按时间排序。事件无时间线更新时不返回。" }, "notify_subscribers": { "type": "boolean", - "description": "创建本事件时是否通知订阅者。" + "description": "创建本事件时是否通知订阅者。为 false 时不返回。" }, "auto_update_by_schedule": { "type": "boolean", - "description": "仅维护事件：是否根据计划窗口自动推进状态。" + "description": "仅维护事件：是否按计划窗口自动推进状态。为 false 时不返回。" } } }, @@ -42180,11 +42264,11 @@ "properties": { "component_id": { "type": "string", - "description": "组件 ID。" + "description": "组件 ID。为空时不返回。" }, "section_id": { "type": "string", - "description": "所属区域 ID。" + "description": "所属区域 ID。组件位于顶层时不返回。" }, "name": { "type": "string", @@ -42192,25 +42276,25 @@ }, "description": { "type": "string", - "description": "组件描述。" + "description": "组件描述。为空时不返回。" }, "available_since_seconds": { "type": "integer", "format": "int64", - "description": "组件首次可用时间（Unix 秒）。" + "description": "组件可用起始时间（Unix 时间戳，秒）。为 0 时不返回。" }, "order_id": { "type": "integer", "format": "int64", - "description": "在所属区域内的显示顺序。" + "description": "在所属区域内的显示顺序。为 0 时不返回。" }, "hide_uptime": { "type": "boolean", - "description": "为 true 时在摘要响应中隐藏可用率数据。" + "description": "为 true 时在摘要响应中隐藏可用率数据。为 false 时不返回。" }, "hide_all": { "type": "boolean", - "description": "为 true 时从摘要接口中完全隐藏该组件。" + "description": "为 true 时从摘要接口中完全隐藏该组件。为 false 时不返回。" }, "status": { "type": "string", @@ -42257,14 +42341,14 @@ }, "description": { "type": "string", - "description": "更新说明（Markdown）。" + "description": "更新说明（Markdown）。为空时不返回。" }, "component_changes": { "type": "array", "items": { "$ref": "#/components/schemas/StatusPageComponentChangeItem" }, - "description": "本次更新应用的组件状态变更。" + "description": "本次更新应用的组件状态变更。本次更新无组件状态变更时不返回。" } } }, @@ -42282,7 +42366,7 @@ }, "component_name": { "type": "string", - "description": "组件显示名称。读取时由后端填充，写入时忽略。" + "description": "组件显示名称。读取时由后端填充，写入时忽略。为空时不返回。" }, "status": { "type": "string", @@ -42343,12 +42427,12 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "change_id": { "type": "integer", "format": "int64", - "description": "目标事件 ID，可通过 `POST /status-page/change/list` 获取。" + "description": "目标事件 ID，可通过 `GET /status-page/change/list` 获取。" }, "title": { "type": [ @@ -42386,12 +42470,12 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "change_id": { "type": "integer", "format": "int64", - "description": "目标事件 ID，可通过 `POST /status-page/change/list` 获取。" + "description": "目标事件 ID，可通过 `GET /status-page/change/list` 获取。" } } }, @@ -42410,7 +42494,7 @@ }, "UpdateStatusPageChangeTimelineRequest": { "type": "object", - "description": "更新状态页事件已有时间线条目所需的参数。", + "description": "更新状态页事件已有时间线条目所需的参数。`at_seconds` 与 `description` 至少提供一个；未提供的字段保持原值。", "required": [ "page_id", "change_id", @@ -42420,16 +42504,16 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "change_id": { "type": "integer", "format": "int64", - "description": "所属事件 ID，可通过 `POST /status-page/change/list` 获取。" + "description": "所属事件 ID，可通过 `GET /status-page/change/list` 获取。" }, "update_id": { "type": "string", - "description": "目标时间线更新 ID，可通过 `POST /status-page/change/info` 获取。" + "description": "目标时间线更新 ID，可通过 `GET /status-page/change/info` 获取。" }, "at_seconds": { "type": "integer", @@ -42454,16 +42538,16 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "change_id": { "type": "integer", "format": "int64", - "description": "所属事件 ID，可通过 `POST /status-page/change/list` 获取。" + "description": "所属事件 ID，可通过 `GET /status-page/change/list` 获取。" }, "update_id": { "type": "string", - "description": "要删除的时间线更新 ID，可通过 `POST /status-page/change/info` 获取。" + "description": "要删除的时间线更新 ID，可通过 `GET /status-page/change/info` 获取。" } } }, @@ -42529,7 +42613,7 @@ }, "locale": { "type": "string", - "description": "通知的首选语言。" + "description": "通知的首选语言。为空时不返回。" } } }, @@ -42542,11 +42626,11 @@ "properties": { "component_id": { "type": "string", - "description": "组件 ID。" + "description": "组件 ID。为空时不返回。" }, "section_id": { "type": "string", - "description": "所属区域 ID。" + "description": "所属区域 ID。组件位于顶层（不属于任何分组）时不返回。" }, "name": { "type": "string", @@ -42554,25 +42638,25 @@ }, "description": { "type": "string", - "description": "组件描述。" + "description": "组件描述。为空时不返回。" }, "available_since_seconds": { "type": "integer", "format": "int64", - "description": "组件首次可用时间（Unix 秒）。" + "description": "组件可用起始时间（Unix 时间戳，秒）。为 0 时不返回。" }, "order_id": { "type": "integer", "format": "int64", - "description": "在所属区域内的显示顺序。" + "description": "在所属区域内的显示顺序。为 0 时不返回。" }, "hide_uptime": { "type": "boolean", - "description": "为 true 时在摘要响应中隐藏可用率数据。" + "description": "为 true 时在摘要响应中隐藏可用率数据。为 false 时不返回。" }, "hide_all": { "type": "boolean", - "description": "为 true 时从摘要接口中完全隐藏该组件。" + "description": "为 true 时从摘要接口中完全隐藏该组件。为 false 时不返回。" } } }, @@ -42587,7 +42671,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "目标状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "目标状态页 ID，可通过 `GET /status-page/list` 获取。" }, "method": { "type": "string", @@ -42653,7 +42737,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "component_ids": { "type": "array", @@ -42690,7 +42774,8 @@ "string", "null" ], - "description": "迁移后状态页的目标 URL 名称。省略时沿用源状态页的 URL 名称。" + "description": "新状态页的目标 URL 名称，会被规范化为 URL 安全的别名（最长 255 字符）。省略或传 null 时根据源状态页名称生成；显式传空字符串会被拒绝。", + "maxLength": 255 } } }, @@ -42776,13 +42861,12 @@ "status": { "type": "string", "enum": [ - "pending", "running", "completed", "failed", "cancelled" ], - "description": "任务当前状态。\n| 值 | 含义 |\n|---|---|\n| `pending` | 已创建，等待执行。 |\n| `running` | 执行中。 |\n| `completed` | 已全部完成。 |\n| `failed` | 执行失败，`error` 字段含失败原因。 |\n| `cancelled` | 已被取消。 |" + "description": "任务当前状态。\n| 值 | 含义 |\n|---|---|\n| `running` | 执行中。 |\n| `completed` | 已全部完成。 |\n| `failed` | 执行失败，`error` 字段含失败原因。 |\n| `cancelled` | 已被取消。 |" }, "progress": { "$ref": "#/components/schemas/StatusPageMigrationProgress", @@ -42790,17 +42874,17 @@ }, "error": { "type": "string", - "description": "`status` 为 `failed` 时的终态错误信息。" + "description": "`status` 为 `failed` 时的终态错误信息。任务未失败时不返回该字段。" }, "created_at": { "type": "integer", "format": "int64", - "description": "任务创建时间（Unix 秒）。" + "description": "任务创建时间（Unix 时间戳，秒）。" }, "updated_at": { "type": "integer", "format": "int64", - "description": "任务最近一次状态更新时间（Unix 秒）。" + "description": "任务最近一次状态更新时间（Unix 时间戳，秒）。" } } }, @@ -42860,7 +42944,7 @@ "items": { "type": "string" }, - "description": "任务执行过程中记录的非致命警告。" + "description": "任务执行过程中记录的非致命警告。无告警时不返回该字段。" } } }, @@ -42873,7 +42957,7 @@ "properties": { "job_id": { "type": "string", - "description": "迁移任务 ID，创建迁移任务时返回；可通过 `POST /status-page/migration/status` 查询进度。" + "description": "迁移任务 ID，创建迁移任务时返回；可通过 `GET /status-page/migration/status` 查询进度。" } } }, @@ -42884,6 +42968,7 @@ "page_id", "type", "title", + "description", "status", "updates" ], @@ -42891,7 +42976,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "type": { "type": "string", @@ -42908,7 +42993,7 @@ }, "description": { "type": "string", - "description": "事件描述(支持 Markdown),必填。" + "description": "事件描述（支持 Markdown），必填，不能为空。" }, "status": { "type": "string", @@ -42926,7 +43011,7 @@ "start_at_seconds": { "type": "integer", "format": "int64", - "description": "事件开始时间(Unix 秒)。留空时默认为当前时间。" + "description": "事件开始时间（Unix 秒）。存储的开始时间始终以第一条更新的 `at_seconds` 为准（该字段缺省时取当前时间）；对于开启 `auto_update_by_schedule` 的维护事件，本字段用于调度自动切换为 `ongoing` 的任务。" }, "responders": { "type": "array", @@ -42934,7 +43019,7 @@ "type": "integer", "format": "int64" }, - "description": "事件负责成员 ID 列表，可通过 `POST /member/list` 获取。" + "description": "事件负责成员的 ID 列表。" }, "linked_changes": { "type": "array", @@ -42946,7 +43031,7 @@ "close_at_seconds": { "type": "integer", "format": "int64", - "description": "回溯事件的结束时间,需大于 `start_at_seconds`。" + "description": "事件结束时间（Unix 秒），必须大于或等于第一条更新的 `at_seconds`。回溯事件用它表示结束时间；对于开启 `auto_update_by_schedule` 的维护事件，它用于调度自动切换为 `completed` 的任务，且距当前时间不能超过 30 天。" }, "updates": { "type": "array", @@ -42961,10 +43046,13 @@ "at_seconds": { "type": "integer", "format": "int64", - "description": "更新时间戳(Unix 秒)。" + "description": "更新时间戳（Unix 秒）。第一条更新缺省或为 0 时取当前时间。" }, "status": { - "type": "string", + "type": [ + "string", + "null" + ], "enum": [ "investigating", "identified", @@ -42977,7 +43065,10 @@ "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", + "type": [ + "string", + "null" + ], "description": "更新说明(支持 Markdown)。" }, "component_changes": { @@ -42991,7 +43082,7 @@ "properties": { "component_id": { "type": "string", - "description": "组件 ID，可通过 `POST /status-page/info` 获取。" + "description": "组件 ID，可通过 `GET /status-page/info` 获取。" }, "status": { "type": "string", @@ -43010,7 +43101,8 @@ } } }, - "description": "时间线更新列表。即时事件一般只传一条;回溯事件需传入全部历史更新。" + "description": "时间线更新列表。至少传 1 条，且至少有一条必须包含 `component_changes`。即时事件一般只传一条；回溯事件需传入全部历史更新。", + "minItems": 1 }, "notify_subscribers": { "type": "boolean", @@ -43032,23 +43124,24 @@ "required": [ "page_id", "change_id", - "status" + "status", + "description" ], "properties": { "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "change_id": { "type": "integer", "format": "int64", - "description": "目标事件 ID，可通过 `POST /status-page/change/list` 获取。" + "description": "目标事件 ID，可通过 `GET /status-page/change/list` 获取。" }, "at_seconds": { "type": "integer", "format": "int64", - "description": "更新时间戳(Unix 秒),留空时默认为当前时间。" + "description": "更新时间戳（Unix 秒），缺省或为 0 时取当前时间。" }, "status": { "type": "string", @@ -43061,11 +43154,11 @@ "ongoing", "completed" ], - "description": "更新后的事件状态,需与事件类型匹配。当状态切换为 `resolved` 或 `completed` 时,所有关联组件必须恢复为 `operational`。\n| 值 | 含义 |\n|---|---|\n| `investigating` | 排查中（incident）。 |\n| `identified` | 已定位原因（incident）。 |\n| `monitoring` | 已修复，观察中（incident）。 |\n| `scheduled` | 已计划（maintenance）。 |\n| `ongoing` | 进行中（maintenance）。 |" + "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": { "type": "string", - "description": "更新说明(支持 Markdown),必填。" + "description": "更新说明（支持 Markdown），必填，不能为空。" }, "component_changes": { "type": "array", @@ -43078,7 +43171,7 @@ "properties": { "component_id": { "type": "string", - "description": "组件 ID，可通过 `POST /status-page/info` 获取。" + "description": "组件 ID，可通过 `GET /status-page/info` 获取。" }, "status": { "type": "string", @@ -43104,7 +43197,21 @@ "folder_id": { "type": "integer", "format": "uint64", - "description": "文件夹 ID，设为 0 可列出所有可访问规则。" + "description": "文件夹 ID，必须是已存在的文件夹；传 `0` 会返回 `folder_not_found` 错误。" + }, + "include_descendants": { + "type": "boolean", + "description": "是否同时包含所有子孙文件夹中的规则。为 `true` 时返回的每项仅包含 `id`、`folder_id`、`name` 三个字段；配合 `query` / `limit` 用于规则选择器场景。" + }, + "query": { + "type": "string", + "description": "规则名模糊过滤，仅在 `include_descendants` 为 `true` 时生效。" + }, + "limit": { + "type": "integer", + "default": 50, + "maximum": 100, + "description": "返回规则数量上限，仅在 `include_descendants` 为 `true` 时生效。默认 50，最大 100。" } } }, @@ -43127,7 +43234,10 @@ "updater_name", "created_at", "updated_at", - "triggered" + "triggered", + "labels", + "timezone", + "active_alert_count" ], "properties": { "id": { @@ -43170,7 +43280,7 @@ }, "cron_pattern": { "type": "string", - "description": "5 字段 cron 调度，如 `* * * * *`。不允许以 `CRON_TZ=` 或 `TZ=` 开头，时区请填写到 `timezone` 字段。" + "description": "调度表达式：6 字段 cron（含秒），如 `0 * * * * *`；或 `@every 30s` 形式的间隔描述。不允许以 `CRON_TZ=` 或 `TZ=` 开头，时区请填写到 `timezone` 字段。" }, "timezone": { "type": "string", @@ -43212,6 +43322,25 @@ "triggered": { "type": "boolean", "description": "是否有当前活跃告警。" + }, + "active_alert_count": { + "type": "integer", + "format": "int64", + "description": "该规则当前活跃（未恢复）的告警数量。`triggered` 等价于 `active_alert_count > 0`。" + }, + "runtime_state": { + "type": "string", + "enum": [ + "disabled", + "offline", + "abnormal", + "stale", + "no_datasource", + "config_pending", + "waiting", + "normal" + ], + "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` | 正常评估中。 |" } } }, @@ -43335,6 +43464,20 @@ "condition": { "type": "string", "description": "恢复条件表达式；`mode` 为 `threshold` 或 `ql` 时必填，`invert` 时必须为空。" + }, + "value_fields": { + "type": "array", + "items": { + "type": "string" + }, + "description": "恢复条件 `condition` 以 `$A.` 形式引用的数值结果字段，语义同查询的 `value_fields`。为空时不返回。" + }, + "args": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "恢复查询的数据源附加参数，键约定同查询的 `args`（`<数据源>.<参数>`）。为空时不返回。" } }, "description": "阈值检查的恢复判定配置。" @@ -43445,7 +43588,10 @@ } } } - } + }, + "required": [ + "queries" + ] }, "AlertRule": { "type": "object", @@ -43486,7 +43632,7 @@ "items": { "type": "string" }, - "description": "数据源名称模式（支持通配符）。" + "description": "数据源名称匹配模式（支持通配符）。`ds_list` / `ds_ids` 至少一个非空，两者合并共同决定规则监控哪些数据源。" }, "ds_ids": { "type": "array", @@ -43626,7 +43772,14 @@ "format": "int64", "description": "最近更新时间，Unix 秒级时间戳，由服务端生成，无需提供。" } - } + }, + "required": [ + "folder_id", + "name", + "ds_type", + "cron_pattern", + "rule_configs" + ] }, "AlertRuleInfoResponse": { "allOf": [ @@ -43705,16 +43858,6 @@ "description": "成功时返回空对象。", "additionalProperties": false }, - "RuleFolderIDRequest": { - "type": "object", - "properties": { - "folder_id": { - "type": "integer", - "format": "uint64", - "description": "要统计的文件夹 ID，可通过 `POST /monit/folder/list` 获取。服务端按直属子文件夹分组返回规则触发统计。" - } - } - }, "RuleFieldsUpdateRequest": { "type": "object", "required": [ @@ -43836,6 +43979,14 @@ "type": "integer", "format": "int64", "description": "最大重复通知次数。仅当 `fields` 包含 `repeat_total` 时生效。" + }, + "labels_patch": { + "$ref": "#/components/schemas/StringMapPatch", + "description": "标签的增量更新，仅在 `fields` 包含 `labels` 时生效；与 `labels` 同时发送时优先使用本字段。" + }, + "annotations_patch": { + "$ref": "#/components/schemas/StringMapPatch", + "description": "注解的增量更新，仅在 `fields` 包含 `annotations` 时生效；与 `annotations` 同时发送时优先使用本字段。" } } }, @@ -43941,7 +44092,11 @@ }, "action": { "type": "string", - "description": "操作类型，如 `create`、`update`。" + "description": "操作类型：`create` = 创建规则；`update` = 更新规则（涵盖整体更新、字段批量更新、导入和移动）。", + "enum": [ + "create", + "update" + ] }, "content": { "type": "string", @@ -44229,7 +44384,7 @@ "properties": { "type": { "type": "string", - "description": "按数据源类型过滤，省略则返回所有类型。可选值：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`victorialogs`。" + "description": "按数据源类型标识过滤，省略则返回所有类型。可选值：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`tencent_cls`、`victorialogs`。" } } }, @@ -44263,6 +44418,10 @@ }, "victorialogs": { "$ref": "#/components/schemas/DSVictoriaLogsConfig" + }, + "tencent_cls": { + "$ref": "#/components/schemas/DSTencentCLSConfig", + "description": "腾讯云 CLS 凭证。`type_ident` 为 `tencent_cls` 时必填。" } } }, @@ -44773,7 +44932,8 @@ "note", "address", "edge_cluster_name", - "updated_at" + "updated_at", + "payload" ], "properties": { "id": { @@ -44788,7 +44948,7 @@ }, "type_ident": { "type": "string", - "description": "数据源类型标识，可选值：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`victorialogs`。" + "description": "数据源类型标识，可选值：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`tencent_cls`、`victorialogs`。" }, "name": { "type": "string", @@ -44807,7 +44967,15 @@ "description": "连接地址。Prometheus/Loki/VictoriaLogs 为 HTTP URL；MySQL/Oracle/Postgres/ClickHouse 为 `host:port`；SLS 为不含 http/https 前缀的 endpoint。" }, "payload": { - "$ref": "#/components/schemas/DSPayload" + "anyOf": [ + { + "$ref": "#/components/schemas/DSPayload" + }, + { + "type": "null" + } + ], + "description": "类型相关配置块，必须包含与 `type_ident` 匹配的键。`/monit/datasource/list` 响应中恒为 `null`（列表查询不读取 payload 列）；创建/更新/详情响应中会返回。对于 `tencent_cls`，`secret_key` 会被掩码为空字符串，除非其值为 `${env:...}` 引用。" }, "edge_cluster_name": { "type": "string", @@ -44837,7 +45005,7 @@ }, "type_ident": { "type": "string", - "description": "数据源类型标识，可选值：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`victorialogs`。" + "description": "数据源类型标识，可选值：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`tencent_cls`、`victorialogs`。" }, "name": { "type": "string", @@ -44849,7 +45017,7 @@ }, "address": { "type": "string", - "description": "连接地址。Prometheus/Loki/VictoriaLogs 为 HTTP URL；MySQL/Oracle/Postgres/ClickHouse 为 `host:port`；SLS 为不含 http/https 前缀的 endpoint；Elasticsearch cloud 部署无需填写。" + "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）。" }, "payload": { "$ref": "#/components/schemas/DSPayload", @@ -44858,12 +45026,16 @@ "edge_cluster_name": { "type": "string", "description": "负责使用该数据源评估规则的 Monitors Edge 集群名称。" + }, + "enabled": { + "type": "boolean", + "description": "数据源是否启用（参与规则评估）。创建时省略则默认禁用（`false`）。" } } }, "DataSourceListResponse": { "type": "array", - "description": "数据源列表，不含敏感凭证字段。", + "description": "数据源列表。本接口不读取 payload 列，因此每项的 `payload` 均为 `null`。", "items": { "$ref": "#/components/schemas/DataSourceItem" } @@ -44903,13 +45075,35 @@ "type": "integer", "description": "每页大小，传 0 时服务端默认 200。" } - } + }, + "required": [ + "id" + ] }, "SLSProjectsResponse": { - "type": "array", - "description": "SLS 项目名称列表。", - "items": { - "type": "string" + "type": "object", + "description": "一页阿里云 SLS 项目。", + "required": [ + "projects", + "count", + "total" + ], + "properties": { + "projects": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SLSProject" + }, + "description": "当前页的项目列表。" + }, + "count": { + "type": "integer", + "description": "本页项目数量。" + }, + "total": { + "type": "integer", + "description": "匹配 `query` 的项目总数，与分页无关。" + } } }, "SLSLogstoresRequest": { @@ -44933,7 +45127,10 @@ "type": "integer", "description": "每页大小，传 0 时服务端默认 200。" } - } + }, + "required": [ + "id" + ] }, "SLSLogstoresResponse": { "type": "array", @@ -44966,7 +45163,7 @@ 1, 2 ], - "description": "共享范围：`0` 仅创建者可见，`1` 账户内共享，`2` 公开。省略时默认为 `0`。" + "description": "共享范围：`0` 私有（创建者与账户管理员可见），`1` 账户内共享，`2` 公开。省略时默认为 `0`。" }, "payload": { "type": "string", @@ -45009,7 +45206,7 @@ 1, 2 ], - "description": "共享范围：`0` 仅创建者可见，`1` 账户内共享，`2` 公开。" + "description": "共享范围：`0` 私有（创建者与账户管理员可见），`1` 账户内共享，`2` 公开。" }, "payload": { "type": "string", @@ -45086,7 +45283,7 @@ 1, 2 ], - "description": "新的共享范围：`0` 仅创建者，`1` 账户共享，`2` 公开。" + "description": "新的共享范围：`0` 私有（创建者与账户管理员可见），`1` 账户共享，`2` 公开。" }, "payload": { "type": "string", @@ -45100,11 +45297,14 @@ "properties": { "p": { "type": "integer", - "description": "页码（从 1 开始），默认 1。" + "description": "页码（从 1 开始），默认 1。", + "minimum": 1 }, "limit": { "type": "integer", - "description": "每页条数，范围 1–100，默认 20。" + "description": "每页条数，范围 1–100，默认 20。", + "minimum": 1, + "maximum": 100 }, "orderby": { "type": "string", @@ -45112,7 +45312,7 @@ "created_at", "updated_at" ], - "description": "排序字段；缺省时按 `updated_at` 排序。" + "description": "排序字段：`created_at`（创建时间）或 `updated_at`（最近更新时间）；缺省按 `updated_at` 排序。" }, "asc": { "type": "boolean", @@ -45138,10 +45338,7 @@ "description": "应用的告警配置。", "properties": { "enabled": { - "type": [ - "boolean", - "null" - ], + "type": "boolean", "description": "是否启用告警。" }, "channel_ids": { @@ -45150,12 +45347,25 @@ "type": "integer", "format": "int64" }, - "description": "接收告警的协作空间 ID 列表。" + "description": "接收告警的协作空间 ID 列表，仅在 `delivery_mode` 为 `oncall` 时使用。" }, "integration_id": { "type": "integer", "format": "int64", - "description": "关联的 On-call 集成 ID（只读，自动分配）。" + "description": "关联的 On-call 集成 ID（只读，`delivery_mode` 为 `oncall` 时保存即自动分配）。" + }, + "delivery_mode": { + "type": "string", + "enum": [ + "oncall", + "webhook" + ], + "description": "告警投递方式：`oncall` 经 Flashduty On-call 投递，`webhook` 直接 POST 到 `webhook_url`。空值按 `oncall` 处理；创建/更新时空值会落库为部署默认值（纯 RUM 私有化部署默认 `webhook`，其他场景默认 `oncall`）。为空（历史数据）时省略该字段。" + }, + "webhook_url": { + "type": "string", + "format": "uri", + "description": "`delivery_mode` 为 `webhook` 时接收告警事件的 URL，该模式下必填，其他模式下忽略；为空时省略该字段。" } } }, @@ -45204,7 +45414,7 @@ "all" ] }, - "description": "展示该外部系统链接的 RUM 事件类型。" + "description": "展示该外部系统链接的 RUM 事件类型，至少填一个。\n\n| 值 | 含义 |\n|---|---|\n| `crash` | 崩溃事件（`is_crash` 的错误） |\n| `error` | 错误事件 |\n| `view` | 页面/视图事件 |\n| `action` | 用户操作事件 |\n| `resource` | 资源加载事件 |\n| `session` | 会话事件 |\n| `all` | 所有事件类型 |" }, "enabled": { "type": "boolean", @@ -45286,7 +45496,7 @@ "harmony", "electron" ], - "description": "应用类型。平台标识，取值为 `browser`（浏览器 Web 应用）、`ios`（iOS 应用）、`android`（Android 应用）、`react-native`（React Native 应用）、`flutter`（Flutter 应用）、`kotlin-multiplatform`（Kotlin Multiplatform 应用）、`roku`（Roku 频道应用）、`unity`（Unity 应用）。注意：创建接口还接受 `miniprogram`、`harmony`、`electron`，这些类型的应用同样会出现在响应中（见 Enum gaps）。" + "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 桌面应用 |" }, "client_token": { "type": "string", @@ -45310,13 +45520,16 @@ "description": "为 `true` 时不推断地理位置。" }, "alerting": { - "$ref": "#/components/schemas/RumApplicationAlerting" + "$ref": "#/components/schemas/RumApplicationAlerting", + "description": "应用的告警配置。" }, "tracing": { - "$ref": "#/components/schemas/RumApplicationTracing" + "$ref": "#/components/schemas/RumApplicationTracing", + "description": "APM 链路追踪集成配置。" }, "links": { - "$ref": "#/components/schemas/RumApplicationLinks" + "$ref": "#/components/schemas/RumApplicationLinks", + "description": "外部链接集成配置。" }, "status": { "type": "string", @@ -45395,7 +45608,8 @@ "items": { "type": "string" }, - "description": "最多 200 个应用 ID，可通过 `POST /rum/application/list` 获取。" + "description": "最多 200 个应用 ID，可通过 `POST /rum/application/list` 获取。", + "maxItems": 200 } } }, @@ -45423,7 +45637,9 @@ "properties": { "application_name": { "type": "string", - "description": "应用名称，1–40 个字符。" + "description": "应用名称，1–40 个字符。", + "minLength": 1, + "maxLength": 40 }, "type": { "type": "string", @@ -45440,12 +45656,13 @@ "harmony", "electron" ], - "description": "应用类型。平台标识，取值为 `browser`（浏览器 Web 应用）、`ios`（iOS 应用）、`android`（Android 应用）、`react-native`（React Native 应用）、`flutter`（Flutter 应用）、`kotlin-multiplatform`（Kotlin Multiplatform 应用）、`roku`（Roku 频道应用）、`unity`（Unity 应用）、`miniprogram`（微信小程序）、`harmony`（鸿蒙 HarmonyOS 应用）、`electron`（Electron 桌面应用）。" + "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 桌面应用 |" }, "team_id": { "type": "integer", "format": "int64", - "description": "所属团队 ID，可通过 `POST /team/list` 获取。" + "description": "所属团队 ID，可通过 `POST /team/list` 获取。", + "exclusiveMinimum": 0 }, "is_private": { "type": "boolean", @@ -45503,11 +45720,19 @@ "description": "要更新的应用 ID，可通过 `POST /rum/application/list` 获取。" }, "application_name": { - "type": "string", - "description": "新的应用名称，1–40 个字符；不传则保持不变。" + "type": [ + "string", + "null" + ], + "description": "新的应用名称，1–40 个字符；不传则保持不变。", + "minLength": 1, + "maxLength": 40 }, "type": { - "type": "string", + "type": [ + "string", + "null" + ], "enum": [ "browser", "ios", @@ -45521,12 +45746,16 @@ "harmony", "electron" ], - "description": "应用类型；不传则保持不变。平台标识，取值为 `browser`（浏览器 Web 应用）、`ios`（iOS 应用）、`android`（Android 应用）、`react-native`（React Native 应用）、`flutter`（Flutter 应用）、`kotlin-multiplatform`（Kotlin Multiplatform 应用）、`roku`（Roku 频道应用）、`unity`（Unity 应用）、`miniprogram`（微信小程序）、`harmony`（鸿蒙 HarmonyOS 应用）、`electron`（Electron 桌面应用）。" + "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 桌面应用 |" }, "team_id": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "应用所属团队 ID，可通过 `POST /team/list` 获取；不传则保持不变。" + "description": "应用所属团队 ID，可通过 `POST /team/list` 获取；不传则保持不变。", + "exclusiveMinimum": 0 }, "is_private": { "type": [ @@ -45579,7 +45808,7 @@ "end_time": { "type": "integer", "format": "int64", - "description": "时间范围结束，毫秒时间戳，最大范围 183 天。" + "description": "时间范围结束，Unix 毫秒时间戳。需大于 `start_time`，最大跨度 183 天。" }, "application_ids": { "type": "array", @@ -45607,7 +45836,7 @@ "resolved" ] }, - "description": "按状态过滤，取值见枚举；传入其他值会报参数错误。" + "description": "按处理状态过滤；传入其他值会被参数校验拒绝。\n\n| 值 | 含义 |\n|---|---|\n| `for_review` | 待处理 |\n| `reviewed` | 已查看 |\n| `ignored` | 已忽略 |\n| `resolved` | 已解决 |" }, "suspected_causes": { "type": "array", @@ -45622,7 +45851,7 @@ "unknown" ] }, - "description": "按疑似原因过滤，取值见枚举。" + "description": "按疑似根因分类过滤。\n\n| 值 | 含义 |\n|---|---|\n| `api.failed_request` | API/接口请求失败（如 HTTP 4xx/5xx 响应） |\n| `network.error` | 网络连接错误（断网、请求中断等） |\n| `code.exception` | 代码异常（Syntax/Reference/Range 等运行时异常） |\n| `code.invalid_object_access` | 非法对象访问（如对 `undefined`/`null` 读取属性） |\n| `code.invalid_argument` | 非法参数（向函数传入了无效参数） |\n| `unknown` | 无法判定的未知原因 |" }, "team_ids": { "type": "array", @@ -45634,11 +45863,14 @@ }, "p": { "type": "integer", - "description": "页码（从 1 开始）。导出时忽略——始终读取前 100 条匹配记录。" + "description": "页码（从 1 开始）。导出时忽略——始终读取前 100 条匹配记录。", + "minimum": 1 }, "limit": { "type": "integer", - "description": "每页条数（1–100）。导出时忽略——行数上限固定为 100。" + "description": "每页条数（1–100）。导出时忽略——行数上限固定为 100。", + "minimum": 1, + "maximum": 100 }, "orderby": { "type": "string", @@ -45649,7 +45881,7 @@ "error_count", "severity" ], - "description": "排序字段；缺省时按 `updated_at` 排序。" + "description": "排序字段；缺省按 `updated_at` 排序。\n\n| 值 | 含义 |\n|---|---|\n| `created_at` | Issue 创建时间 |\n| `updated_at` | 最近更新时间 |\n| `session_count` | 受影响会话数 |\n| `error_count` | 错误发生次数 |\n| `severity` | 严重性等级（`Critical` > `Warning` > `Info`） |" }, "asc": { "type": "boolean", @@ -45688,7 +45920,7 @@ "resolved_at" ] }, - "description": "按顺序指定导出的 CSV 列；未知键会被拒绝；空数组使用默认列集。" + "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` 渲染） |" }, "console_origin": { "type": "string", @@ -45733,7 +45965,7 @@ "ignored", "resolved" ], - "description": "Issue 的处理状态：`for_review`（待处理）、`reviewed`（已查看）、`ignored`（已忽略）、`resolved`（已解决）；已软删除（`deleted`）的 Issue 不会出现在响应中。" + "description": "Issue 的处理状态；已软删除（`deleted`）的 Issue 不会出现在响应中。\n\n| 值 | 含义 |\n|---|---|\n| `for_review` | 待处理 |\n| `reviewed` | 已查看 |\n| `ignored` | 已忽略 |\n| `resolved` | 已解决 |" }, "error_count": { "type": "integer", @@ -45752,7 +45984,7 @@ "age": { "type": "integer", "format": "int64", - "description": "从首次出现到最近一次出现的时长，单位秒。注意：`model/issue/issue.go:40` 的字段注释写的是 millisecond，但实际写入与消费（告警严重性判定）均按秒处理，注释已过时。" + "description": "从首次出现到最近一次出现的时长，单位秒。" }, "resolved_at": { "type": "integer", @@ -45860,7 +46092,7 @@ "regressed_at": { "type": "integer", "format": "int64", - "description": "检测到回溯的时间戳。" + "description": "检测到回溯的时间，Unix 毫秒时间戳。" }, "regressed_at_version": { "type": "string", @@ -45882,7 +46114,12 @@ }, "severity": { "type": "string", - "description": "Issue 严重性级别。" + "description": "Issue 严重性：`Critical`（严重）、`Warning`（警告）、`Info`（提示）；引入严重性之前创建的历史 Issue 为空字符串。", + "enum": [ + "Critical", + "Warning", + "Info" + ] } } }, @@ -45902,7 +46139,7 @@ "end_time": { "type": "integer", "format": "int64", - "description": "时间范围结束，毫秒时间戳，最大范围 183 天。" + "description": "时间范围结束，Unix 毫秒时间戳。需大于 `start_time`，最大跨度 183 天。" }, "application_ids": { "type": "array", @@ -45930,7 +46167,7 @@ "resolved" ] }, - "description": "按状态过滤，取值见枚举；传入其他值会报参数错误。" + "description": "按处理状态过滤；传入其他值会被参数校验拒绝。\n\n| 值 | 含义 |\n|---|---|\n| `for_review` | 待处理 |\n| `reviewed` | 已查看 |\n| `ignored` | 已忽略 |\n| `resolved` | 已解决 |" }, "suspected_causes": { "type": "array", @@ -45945,7 +46182,7 @@ "unknown" ] }, - "description": "按疑似原因过滤，取值见枚举。" + "description": "按疑似根因分类过滤。\n\n| 值 | 含义 |\n|---|---|\n| `api.failed_request` | API/接口请求失败（如 HTTP 4xx/5xx 响应） |\n| `network.error` | 网络连接错误（断网、请求中断等） |\n| `code.exception` | 代码异常（Syntax/Reference/Range 等运行时异常） |\n| `code.invalid_object_access` | 非法对象访问（如对 `undefined`/`null` 读取属性） |\n| `code.invalid_argument` | 非法参数（向函数传入了无效参数） |\n| `unknown` | 无法判定的未知原因 |" }, "team_ids": { "type": "array", @@ -45957,11 +46194,14 @@ }, "p": { "type": "integer", - "description": "页码（从 1 开始），默认 1。" + "description": "页码（从 1 开始），默认 1。", + "minimum": 1 }, "limit": { "type": "integer", - "description": "每页条数，范围 1–100，默认 20。" + "description": "每页条数，范围 1–100，默认 20。", + "minimum": 1, + "maximum": 100 }, "orderby": { "type": "string", @@ -45972,7 +46212,7 @@ "error_count", "severity" ], - "description": "排序字段；缺省时按 `updated_at` 排序。" + "description": "排序字段；缺省按 `updated_at` 排序。\n\n| 值 | 含义 |\n|---|---|\n| `created_at` | Issue 创建时间 |\n| `updated_at` | 最近更新时间 |\n| `session_count` | 受影响会话数 |\n| `error_count` | 错误发生次数 |\n| `severity` | 严重性等级（`Critical` > `Warning` > `Info`） |" }, "asc": { "type": "boolean", @@ -46039,7 +46279,7 @@ "ignored", "resolved" ], - "description": "新状态。设置为 `resolved` 时会记录解决时间与操作人；从 `resolved` 改回其他状态会清除解决信息。取值：`for_review`（待处理）、`reviewed`（已查看）、`ignored`（已忽略）、`resolved`（已解决）。" + "description": "新状态。设为 `resolved` 会记录解决时间与操作人；从 `resolved` 改为其他状态会将其清除。\n\n| 值 | 含义 |\n|---|---|\n| `for_review` | 待处理 |\n| `reviewed` | 已查看 |\n| `ignored` | 已忽略 |\n| `resolved` | 已解决 |" }, "suspected_cause": { "type": "string", @@ -46075,11 +46315,16 @@ }, "type": { "type": "string", - "description": "平台类型。省略时默认为 `browser`。取值：`browser`（浏览器 JS Sourcemap）、`android`（Android 符号文件，ProGuard/R8 mapping 或 NDK native 符号，可用 `kind` 区分）、`ios`（iOS dSYM 符号文件）。", + "description": "要查询的符号文件平台。省略时默认为 `browser`；传入其他值会返回空列表。\n\n| 值 | 查询的存储 |\n|---|---|\n| `browser` | JS Sourcemap（共享存储，不含鸿蒙 ArkTS 与 React Native 行） |\n| `android` | ProGuard/R8 mapping 文件；`kind=native` 时为 Android NDK .so 符号 |\n| `ios` | iOS dSYM 符号文件 |\n| `miniprogram` | 微信小程序 Sourcemap |\n| `react-native` | React Native JS Sourcemap |\n| `harmony` | 鸿蒙 ArkTS Sourcemap；`kind=native` 时为鸿蒙 .so 符号 |\n| `flutter` | Flutter Dart AOT 符号 |\n| `electron` | Electron Breakpad 符号 |", "enum": [ "browser", "android", - "ios" + "ios", + "miniprogram", + "react-native", + "harmony", + "flutter", + "electron" ] }, "services": { @@ -46087,26 +46332,39 @@ "items": { "type": "string" }, - "description": "按服务名称过滤，最多 100 个值。" + "description": "按服务名称过滤，最多 100 个值。", + "maxItems": 100 }, "versions": { "type": "array", "items": { "type": "string" }, - "description": "按版本字符串过滤，最多 100 个值。" + "description": "按版本字符串过滤，最多 100 个值。", + "maxItems": 100 }, "query": { "type": "string", - "description": "对 minified URL（browser）或 build_id（android）做子串匹配。最多 200 个字符。" + "description": "自由文本子串匹配。JS 类存储（browser/react-native/harmony/miniprogram）匹配 `minified_url`，android/flutter/electron 及 `kind=native` 的 harmony 匹配 `build_id`，ios 匹配 `uuid`（不区分大小写，忽略连字符）。", + "maxLength": 200 }, "build_id": { "type": "string", - "description": "仅 Android。按 Gradle 插件构建标识过滤。最多 200 个字符。" + "description": "仅 Android。按 Gradle 插件构建标识过滤。最多 200 个字符。", + "maxLength": 200 }, "uuid": { "type": "string", - "description": "仅 iOS。按 dSYM bundle UUID 过滤。最多 200 个字符。" + "description": "仅 iOS。按 dSYM bundle UUID 过滤。最多 200 个字符。", + "maxLength": 200 + }, + "kind": { + "type": "string", + "enum": [ + "mapping", + "native" + ], + "description": "符号类型过滤，仅 Android 与鸿蒙生效（其他平台忽略）：`mapping`（默认）列出 ProGuard/R8 mapping 或 ArkTS Sourcemap，`native` 列出 native .so 符号。" }, "p": { "type": "integer", @@ -46147,11 +46405,13 @@ }, "type": { "type": "string", - "description": "平台类型：`browser`、`android` 或 `ios`。", + "description": "该记录所属的符号平台存储。JS 存储的行一律返回 `browser`（包括鸿蒙 ArkTS 与 React Native 的上传）；native 符号存储的行一律返回 `android`（包括鸿蒙 native 与 Electron 的上传）。\n\n| 值 | 存储 |\n|---|---|\n| `browser` | JS Sourcemap 存储 |\n| `android` | Android mapping 存储或共享的 native 符号存储 |\n| `ios` | iOS dSYM 存储 |\n| `miniprogram` | 微信小程序 Sourcemap 存储 |\n| `flutter` | Flutter Dart AOT 符号存储 |", "enum": [ "browser", "android", - "ios" + "ios", + "miniprogram", + "flutter" ] }, "service": { @@ -46187,23 +46447,31 @@ }, "metadata": { "type": "object", - "description": "附加在 sourcemap 上的自由格式键值元数据。具体结构取决于上传客户端，常见键包括 `git_repository_url` 和 `git_commit_sha`（这两个字段同时也会提升为顶层字段）。", + "description": "平台相关的元数据：`minified_url`（browser/react-native/harmony/miniprogram）；`build_id`、`variant`、`version_code`（android mapping），另含 `arch`、`lib_name`、`code_id`（android/harmony/electron native 符号）；`uuid`（ios）；`build_id`、`platform`、`arch`、`flavor`、`code_id`、`debug_id`（flutter）；`subpackage`、`minified_url`（miniprogram）。为空时省略。", "additionalProperties": true + }, + "minified_url": { + "type": "string", + "description": "已废弃。压缩后文件的 URL，仅 JS 与小程序记录返回；新集成请读取 `metadata.minified_url`。" + }, + "minified_path": { + "type": "string", + "description": "已废弃。压缩后文件的存储路径，仅 JS 记录返回。" + }, + "sourcemap_path": { + "type": "string", + "description": "已废弃。Sourcemap 文件的存储路径，仅 JS 与小程序记录返回。" } } }, "SourcemapListResponse": { "type": "object", "description": "Sourcemap 记录的分页列表。", - "required": [ - "total", - "items" - ], "properties": { "total": { "type": "integer", "format": "int64", - "description": "匹配记录总数。", + "description": "匹配记录总数；为 0 时省略。", "example": 3 }, "items": { @@ -46211,7 +46479,7 @@ "items": { "$ref": "#/components/schemas/SourcemapItem" }, - "description": "当前页的 Sourcemap（含 iOS dSYM、小程序 Sourcemap 等符号文件）记录列表。" + "description": "当前页的 Sourcemap 记录；为空时省略。" } } }, @@ -46256,11 +46524,11 @@ }, "account_locale": { "type": "string", - "description": "账户级语言偏好（如 zh-CN 或 en-US）" + "description": "账户级语言偏好（如 zh-CN、en-US）。账户未设置时不返回。" }, "account_time_zone": { "type": "string", - "description": "账户级时区（如 Asia/Shanghai）" + "description": "账户级时区（如 Asia/Shanghai）。账户未设置时不返回。" }, "domain": { "type": "string", @@ -46301,26 +46569,48 @@ }, "locale": { "type": "string", - "description": "语言偏好" + "description": "成员语言偏好。成员未设置时不返回。" }, "time_zone": { "type": "string", - "description": "时区" + "description": "成员的 IANA 时区。成员未设置时不返回。" }, "is_external": { "type": "boolean", "description": "是否通过 SSO 创建" }, - "status": { + "created_at": { + "type": "integer", + "format": "int64", + "description": "成员创建时间，Unix 秒级时间戳。" + }, + "mp_plat": { "type": "string", - "enum": [ - "enabled", - "pending", - "deleted" - ], - "description": "成员状态。`enabled` — 已激活成员；`pending` — 已邀请但尚未接受；`deleted` — 已从组织移除。" + "description": "账户来源的云市场平台。账户非来自云市场时不返回。" + }, + "mp_account_id": { + "type": "string", + "description": "账户在云市场平台上的标识。与 `mp_plat` 一起省略。" } - } + }, + "required": [ + "account_id", + "account_name", + "account_avatar", + "account_email", + "account_role_ids", + "domain", + "member_id", + "member_name", + "phone", + "phone_verified", + "email", + "email_verified", + "country_code", + "avatar", + "is_external", + "created_at" + ] }, "MemberListRequest": { "type": "object", @@ -46410,11 +46700,11 @@ }, "locale": { "type": "string", - "description": "语言" + "description": "成员语言偏好（如 `zh-CN`）。为空时不返回——列表接口不填充该字段。" }, "time_zone": { "type": "string", - "description": "时区" + "description": "成员的 IANA 时区（如 `Asia/Shanghai`）。为空时不返回——列表接口不填充该字段。" }, "phone_verified": { "type": "boolean", @@ -46488,7 +46778,13 @@ }, "description": "成员列表" } - } + }, + "required": [ + "p", + "limit", + "total", + "items" + ] }, "MemberDeleteRequest": { "type": "object", @@ -46524,25 +46820,52 @@ "description": "是否强制删除。默认 false，会检查成员是否被分派策略、值班表等资源引用；设为 true 则跳过引用检查直接删除", "default": false } - } + }, + "anyOf": [ + { + "required": [ + "member_id" + ] + }, + { + "required": [ + "member_name" + ] + }, + { + "required": [ + "email" + ] + }, + { + "required": [ + "phone" + ] + }, + { + "required": [ + "ref_id" + ] + } + ] }, "InviteMemberItem": { "type": "object", - "description": "待邀请成员", + "description": "待邀请的成员。只需提供 `email`，或同时提供 `member_name` 与 `phone`。", "properties": { "member_name": { "type": "string", "minLength": 2, "maxLength": 39, - "description": "显示名称" + "description": "显示名称，2–39 个字符。未提供 `email` 时必填；省略时取邮箱前缀作为名称。" }, "email": { "type": "string", - "description": "邮箱地址" + "description": "邮箱地址。未提供 `phone` 时必填。" }, "phone": { "type": "string", - "description": "手机号" + "description": "手机号。未提供 `email` 时必填。" }, "country_code": { "type": "string", @@ -46551,7 +46874,8 @@ "role_ids": { "type": "array", "items": { - "type": "integer" + "type": "integer", + "format": "uint64" }, "description": "授予的角色 ID 列表" }, @@ -46585,7 +46909,8 @@ "items": { "$ref": "#/components/schemas/InviteMemberItem" }, - "description": "待邀请成员列表（最多 20 个）" + "description": "单次邀请的成员列表，至少 1 个。每个成员要么提供 `email`，要么同时提供 `member_name` 和 `phone`。", + "minItems": 1 }, "from": { "type": "string", @@ -46671,8 +46996,7 @@ "type": "object", "description": "更新成员角色请求", "required": [ - "member_id", - "role_ids" + "member_id" ], "properties": { "member_id": { @@ -46764,34 +47088,55 @@ "description": "要写入的成员资料字段。未传的字段保持不变。", "properties": { "member_name": { - "type": "string", + "type": [ + "string", + "null" + ], "minLength": 2, "maxLength": 39, "description": "新的显示名称。" }, "password": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "按前端加密格式传入的新登录密码。" }, "phone": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "新的手机号；如不是 E.164 格式，可同时传 country_code。" }, "country_code": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "ISO 3166-1 alpha-2 地区代码（如 \"CN\"、\"US\"）。可独立更新（无需同时传 `phone`），并兼作解析 `phone` 的地区提示；非法值返回 400，显式传空字符串也会被拒绝。" }, "email": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "新的邮箱地址。" }, "avatar": { - "type": "string", + "type": [ + "string", + "null" + ], "maxLength": 499, "description": "新的头像 URL。" }, "locale": { - "type": "string", + "type": [ + "string", + "null" + ], "enum": [ "zh-CN", "en-US" @@ -46799,11 +47144,17 @@ "description": "新的语言偏好。可选值：`zh-CN`（简体中文）、`en-US`（英文）；非法值返回 400。" }, "time_zone": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "新的 IANA 时区名称，例如 Asia/Shanghai。" }, "ref_id": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "新的外部引用 ID。" } } @@ -46847,35 +47198,31 @@ }, "person_name": { "type": "string", - "description": "显示名称" + "description": "显示名称。为空时不返回。" }, "avatar": { "type": "string", - "description": "头像 URL" + "description": "头像 URL。为空时不返回。" }, "locale": { "type": "string", - "description": "语言" + "description": "语言。为空时不返回。" }, "time_zone": { "type": "string", - "description": "时区" + "description": "时区。为空时不返回。" }, "email": { "type": "string", - "description": "邮箱地址" - }, - "country_code": { - "type": "string", - "description": "联系手机的 ISO 3166-1 alpha-2 地区代码（如 \"CN\"、\"US\"、\"HK\"）。" + "description": "邮箱地址。为空时不返回。" }, "phone": { "type": "string", - "description": "手机号" + "description": "手机号。为空时不返回——本接口不填充该字段。" }, "phone_verified": { "type": "boolean", - "description": "手机已验证" + "description": "手机号是否已验证。本接口的响应中恒为 false。" }, "email_verified": { "type": "boolean", @@ -46883,7 +47230,11 @@ }, "as": { "type": "string", - "description": "登录角色（account/member）" + "description": "主体类型：`account` —— 账户主体（注册人）；`member` —— 组织成员。", + "enum": [ + "account", + "member" + ] }, "status": { "type": "string", @@ -46892,7 +47243,7 @@ "pending", "deleted" ], - "description": "人员状态。`enabled` — 已激活；`pending` — 已邀请但尚未接受；`deleted` — 已移除。" + "description": "人员状态。`enabled` — 已激活；`pending` — 已邀请但尚未接受；`deleted` — 已移除。为空时不返回。" } } }, @@ -46907,7 +47258,10 @@ }, "description": "人员资料列表" } - } + }, + "required": [ + "items" + ] }, "TeamItem": { "type": "object", @@ -46950,9 +47304,9 @@ "type": "string", "enum": [ "enabled", - "disabled" + "deleted" ], - "description": "团队状态。" + "description": "团队状态。`enabled` —— 正常；`deleted` —— 已删除（仅按 `team_id` 查询已删除团队时可能返回；列表及按名称/ref_id 查询均排除已删除团队）。" }, "updated_by_name": { "type": "string", @@ -46970,7 +47324,7 @@ }, "creator_name": { "type": "string", - "description": "创建人显示名称。" + "description": "创建者显示名称。当前接口不填充该字段，恒为空字符串；请用 `creator_id` 调用 `POST /person/infos` 解析。" }, "created_at": { "type": "integer", @@ -47013,7 +47367,24 @@ "type": "string", "description": "外部引用 ID。提供时优先于 `team_name` 和 `team_id` 生效。" } - } + }, + "anyOf": [ + { + "required": [ + "team_id" + ] + }, + { + "required": [ + "team_name" + ] + }, + { + "required": [ + "ref_id" + ] + } + ] }, "TeamInfosRequest": { "type": "object", @@ -47028,7 +47399,7 @@ "type": "integer", "format": "uint64" }, - "description": "要查询的团队 ID 列表，最多 100 个。" + "description": "要查询的团队 ID 列表。" } } }, @@ -47053,7 +47424,12 @@ }, "description": "团队成员的人员 ID 数组；团队无成员时为空数组（不为 null）。" } - } + }, + "required": [ + "team_id", + "team_name", + "person_ids" + ] }, "TeamInfosResponse": { "type": "object", @@ -47108,7 +47484,7 @@ }, "query": { "type": "string", - "description": "按团队名称做子串匹配。" + "description": "按团队名称或描述做子串匹配。" } } }, @@ -47187,7 +47563,7 @@ "items": { "type": "string" }, - "description": "按手机号匹配现有成员加入团队；未匹配到成员的号码会被静默忽略，非 E.164 格式号码用 `countryCode` 解析。" + "description": "按手机号把已存在的成员加入团队。非 E.164 格式的号码会按 `countryCode` 解析；无法解析的号码导致整个请求返回 400。能解析但不属于任何现有成员的号码会被静默忽略。" }, "countryCode": { "type": "string", @@ -47199,7 +47575,7 @@ }, "reset_if_name_exist": { "type": "boolean", - "description": "若为 true，当同名团队已存在时重置其成员列表为传入的 person_ids。" + "description": "为 true 且 `team_id` 为 0 时，若已存在同名团队，则原地更新该团队，而不是返回名称冲突错误。" } } }, @@ -47239,7 +47615,24 @@ "type": "string", "description": "外部引用 ID。仅在 `team_id`、`team_name` 均未提供时用于定位。" } - } + }, + "anyOf": [ + { + "required": [ + "team_id" + ] + }, + { + "required": [ + "team_name" + ] + }, + { + "required": [ + "ref_id" + ] + } + ] }, "PlatformEmptyObject": { "type": "object", @@ -47346,6 +47739,10 @@ "asc": { "type": "boolean", "description": "升序排序，默认 false（降序）。" + }, + "no_global": { + "type": "boolean", + "description": "为 true 时排除内置全局角色（Admin、Responder、Viewer），只返回自定义角色。默认 false。" } } }, @@ -47450,7 +47847,9 @@ "description", "class", "scope", - "status" + "status", + "source", + "is_granted" ], "properties": { "id": { @@ -47480,19 +47879,45 @@ }, "scope": { "type": "string", - "description": "权限范围（如 'on-call'、'organization'）。" + "description": "权限生效的功能范围。\n\n| 值 | 含义 |\n| --- | --- |\n| `account` | 账户设置与 API 密钥 |\n| `organization` | 成员、团队、角色、审计 |\n| `on-call` | 值班与故障管理 |\n| `monit` | 监控 |\n| `rum` | 真实用户监控 |\n| `ai-sre` | AI SRE 功能 |\n| `custom_menu` | 账户自定义菜单页面（仅私有化部署） |", + "enum": [ + "account", + "organization", + "on-call", + "monit", + "rum", + "ai-sre", + "custom_menu" + ] }, "status": { "type": "string", "enum": [ "enabled", - "disabled" + "deleted" ], - "description": "权限状态。" + "description": "权限状态。`enabled` —— 生效；`deleted` —— 已删除（已删除的权限会被过滤，不会出现在响应中）。" }, "is_granted": { "type": "boolean", - "description": "当 with_all 为 true 时存在，表示该权限是否已授予所请求的角色。" + "description": "该权限是否已授予 `role_ids` 指定的角色。本接口的响应中始终存在；仅当 `with_all` 为 true 时才会出现 `false` 的条目。" + }, + "account_id": { + "type": "integer", + "format": "uint64", + "description": "所属账户 ID。为 0（系统级权限）时不返回。" + }, + "source": { + "type": "string", + "enum": [ + "system", + "account" + ], + "description": "权限来源。`system` —— 内置种子权限；`account` —— 账户级动态权限（如自定义菜单）。" + }, + "source_ref": { + "type": "string", + "description": "账户级权限来源对象的主键（如自定义菜单 ID）。为空时不返回。" } } }, @@ -47554,6 +47979,18 @@ "url" ], "description": "因子类型。`api`：后端 API 因子，`factor_name` 为接口名（如 `skill:write:upload`），由网关强制校验；`button`：前端操作因子，用于角色配置页渲染操作开关；`visit`：页面访问因子（自定义菜单页面即此类型）；`menu`：菜单可见性因子（历史类型，当前无种子数据）；`url`：页面路由地址因子（历史类型，当前无种子数据）。" + }, + "source": { + "type": "string", + "enum": [ + "system", + "account" + ], + "description": "因子来源。`system` —— 内置种子因子；`account` —— 账户级动态因子（如自定义菜单）。" + }, + "source_ref": { + "type": "string", + "description": "账户级因子来源对象的主键（如自定义菜单 ID）。为空时不返回。" } } }, @@ -47578,7 +48015,7 @@ "type": "integer", "format": "uint64" }, - "description": "要授予/撤销角色的成员 ID 列表，最多 100 个。" + "description": "要授予/撤销角色的成员 ID 列表。" }, "role_id": { "type": "integer", @@ -47598,18 +48035,20 @@ "start_time": { "type": "integer", "format": "int64", - "description": "检索窗口开始时间，Unix 时间戳（秒）。", - "example": 1712620800 + "description": "检索窗口起点，Unix 秒级时间戳（不含该秒本身）。", + "example": 1712620800, + "minimum": 1 }, "end_time": { "type": "integer", "format": "int64", - "description": "检索窗口结束时间，Unix 时间戳（秒）。必须晚于 `start_time`，最大跨度 90 天。", - "example": 1712707200 + "description": "检索窗口终点，Unix 秒级时间戳（含该秒）。必须大于 `start_time`，最大跨度 90 天。", + "example": 1712707200, + "minimum": 1 }, "limit": { "type": "integer", - "description": "每页条数。最小 0，最大 99。", + "description": "分页大小，0–99。省略或传 0 表示不分页——返回时间窗内全部匹配记录。", "minimum": 0, "maximum": 99, "example": 20 @@ -47665,7 +48104,10 @@ "body", "params", "is_dangerous", - "is_write" + "is_write", + "principal_kind", + "credential_type", + "credential_id" ], "properties": { "created_at": { @@ -47681,11 +48123,11 @@ "member_id": { "type": "integer", "format": "uint64", - "description": "操作人的成员 ID。" + "description": "执行操作的成员 ID。由账户主体（owner）亲自执行时为 0。" }, "member_name": { "type": "string", - "description": "操作人的显示名称。" + "description": "成员显示名称。`member_id` 为 0 时为空字符串。" }, "request_id": { "type": "string", @@ -47701,11 +48143,11 @@ }, "operation_name": { "type": "string", - "description": "按账户语种显示的人类可读操作标签。" + "description": "操作的可读中文名称（如 `创建模板`）。" }, "body": { "type": "string", - "description": "JSON 编码的请求体（可能截断至 10 KB）。" + "description": "JSON 编码的请求体。包含敏感字段时整体改为 base64url 编码存储；超过 10 KB 时以截断占位说明替代。" }, "params": { "type": "array", @@ -47731,6 +48173,23 @@ "is_write": { "type": "boolean", "description": "是否为写操作；false 表示只读操作。" + }, + "principal_kind": { + "type": "string", + "enum": [ + "member", + "service" + ], + "description": "调用方类型。`member` —— 成员会话；`service` —— App Key 凭据。" + }, + "credential_type": { + "type": "string", + "description": "调用使用的凭据类型。使用 App Key 调用时为 `app_key`；成员会话为空字符串。" + }, + "credential_id": { + "type": "integer", + "format": "uint64", + "description": "凭据 ID（App Key 的 ID）；`credential_type` 非 `app_key` 时为 0。" } } }, @@ -47757,7 +48216,7 @@ "items": { "$ref": "#/components/schemas/AuditLog" }, - "description": "当前页的审计日志条目。" + "description": "本页的审计日志，按时间倒序。本页为空时不返回。" } } }, @@ -47883,7 +48342,12 @@ }, "status": { "type": "string", - "description": "字段状态，如 `enabled`、`deleted`。" + "enum": [ + "enabled", + "disabled", + "deleted" + ], + "description": "字段状态：`enabled`（生效）、`disabled`（仅内部逻辑可设置，API 无法设置）或 `deleted`（已软删除）。`/field/list` 不返回 `deleted`，`/field/info` 可能返回。" }, "creator_id": { "type": "integer", @@ -47922,7 +48386,10 @@ "creator_id", "updated_by", "created_at", - "updated_at" + "updated_at", + "description", + "options", + "default_value" ] }, "FieldInfoRequest": { @@ -47947,7 +48414,7 @@ "created_at", "updated_at" ], - "description": "排序键，未传时使用后端默认顺序。" + "description": "排序键，省略时默认为 `created_at`。" }, "asc": { "type": "boolean", @@ -47963,7 +48430,7 @@ }, "query": { "type": "string", - "description": "对 `field_name` 与 `display_name` 进行正则过滤；非法正则会回退为字面量子串匹配。" + "description": "正则过滤，仅匹配 `field_name`。非法正则会自动转义为字面量子串匹配。" } } }, @@ -48015,7 +48482,7 @@ "single_select", "text" ], - "description": "字段类型，创建后不可更改：`text` 文本、`single_select` 单选、`multi_select` 多选、`checkbox` 复选。" + "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": { "type": "string", @@ -48080,7 +48547,7 @@ "items": { "type": "string" }, - "description": "替换后的候选项，规则同创建接口。" + "description": "替换后的选项列表，规则与创建时相同。注意：更新接口总是用提交的值覆盖 `display_name`、`description`、`options` 和 `default_value`，因此 `single_select`/`multi_select` 字段每次更新都必须传非空 `options`。" }, "default_value": { "description": "替换后的默认值，类型须与字段当前 `field_type` 匹配。", @@ -48136,7 +48603,7 @@ } }, "QueryDataRequest": { - "description": "稳定结构化查询接口的请求。字段与已弃用的 rows 接口一致。", + "description": "稳定结构化查询接口的请求。字段与已下线的 rows 接口一致。", "allOf": [ { "$ref": "#/components/schemas/QueryRowsRequest" @@ -48406,33 +48873,6 @@ } } }, - "QueryRowsResponse": { - "type": "array", - "description": "结果行。不同数据源对 `fields` 与 `values` 的填充方式不同——指标类数据源(Prometheus、*-stats)将数字放入 `values`;明细类数据源(SQL、SLS、原始日志)将数据放入 `fields`,`values` 可能为 `null`。", - "items": { - "$ref": "#/components/schemas/QueryRow" - } - }, - "QueryRow": { - "type": "object", - "properties": { - "fields": { - "type": "object", - "description": "字符串值字段(标签、日志字段、SQL 列)。", - "additionalProperties": { - "type": "string" - } - }, - "values": { - "type": "object", - "nullable": true, - "description": "数值字段。对于指标查询,规范键名为 `__value__`。对于明细类数据源可能为 `null`。", - "additionalProperties": { - "type": "number" - } - } - } - }, "DiagnoseRequest": { "type": "object", "required": [ @@ -48870,6 +49310,14 @@ "type": "integer", "format": "int64", "description": "最近一次路由投影写入时间,Unix 秒。视为\"最近一次被观测到\",而非实时在线指标。" + }, + "host_id": { + "type": "string", + "description": "上报该目标的 host agent ID。目标未关联主机时不返回。" + }, + "servicemap": { + "$ref": "#/components/schemas/TargetInventoryServiceMapCapability", + "description": "目标所在主机的服务拓扑（ServiceMap）采集能力与最新状态。上报 agent 不具备 ServiceMap 能力时不返回。" } } }, @@ -48884,6 +49332,10 @@ "type": "string", "description": "下一页的不透明游标。缺失 / 为空表示已到末页。", "x-flashduty-preserve-absence": true + }, + "servicemap_coverage": { + "$ref": "#/components/schemas/TargetInventoryServiceMapCoverage", + "description": "本页 ServiceMap 状态拉取覆盖情况。本页没有任何条目携带 ServiceMap 数据时不返回。" } } }, @@ -48931,7 +49383,11 @@ }, "channel_status": { "type": "string", - "description": "协作通道状态。" + "description": "协作空间状态：`enabled`（启用）或 `disabled`（禁用）。", + "enum": [ + "enabled", + "disabled" + ] }, "integration_id": { "type": "integer", @@ -48956,7 +49412,14 @@ }, "change_status": { "type": "string", - "description": "变更当前的生命周期状态。" + "description": "变更的当前生命周期状态。\n| 取值 | 含义 |\n|---|---|\n| `Planned` | 已计划，未开始。 |\n| `Ready` | 就绪，待执行。 |\n| `Processing` | 执行中。 |\n| `Canceled` | 已取消。 |\n| `Done` | 已完成。 |", + "enum": [ + "Planned", + "Ready", + "Processing", + "Canceled", + "Done" + ] }, "start_time": { "type": "integer", @@ -49067,7 +49530,7 @@ "deleted_at": { "type": "integer", "format": "int64", - "description": "变更事件删除时的 Unix 时间戳（秒）。" + "description": "变更事件的删除时间，Unix 时间戳（秒）。未删除时不返回该字段。" } } }, @@ -49128,7 +49591,11 @@ "type": "string", "description": "人员当前状态。" } - } + }, + "required": [ + "account_id", + "person_id" + ] }, "GetWarRoomDefaultObserversRequest": { "type": "object", @@ -49164,7 +49631,13 @@ }, "description": "已应用隐藏规则后，为受支持 IM 预览返回的固定故障卡片字段。" } - } + }, + "required": [ + "success", + "content", + "message" + ], + "description": "模板预览结果。" }, "ResponseEnvelope": { "type": "object", @@ -49192,12 +49665,14 @@ "start_time": { "type": "integer", "format": "int64", - "description": "查询窗口起始的 Unix 时间戳（秒）。" + "description": "查询窗口起点，Unix 时间戳（秒）。可选——`start_time` 和 `end_time` 都不传或为 0 时，默认查询最近一小时。必须小于 `end_time`，跨度不超过 31 天。当变更的 [start_time, last_time] 区间与查询窗口重叠时命中。", + "minimum": 0 }, "end_time": { "type": "integer", "format": "int64", - "description": "查询窗口结束的 Unix 时间戳（秒）。" + "description": "查询窗口终点，Unix 时间戳（秒）。默认值与约束见 `start_time`。", + "minimum": 0 }, "p": { "type": "integer", @@ -49229,11 +49704,12 @@ "description": "", "format": "int64" }, - "description": "按上报集成 ID 过滤。" + "description": "按上报集成 ID 过滤。提供时至少 1 个。", + "minItems": 1 }, "orderby": { "type": "string", - "description": "结果排序字段。", + "description": "排序字段：`start_time` 或 `last_time`，默认 `start_time`。", "enum": [ "start_time", "last_time" @@ -49241,7 +49717,7 @@ }, "asc": { "type": "boolean", - "description": "为 true 时升序排序。" + "description": "为 true 时升序排序，默认降序。" }, "include_events": { "type": "boolean", @@ -49249,7 +49725,39 @@ }, "query": { "type": "string", - "description": "对变更字段进行全文或正则搜索。" + "description": "对变更标题、change_key、描述做大小写不敏感的子串或正则匹配。非法正则按字面量匹配。" + }, + "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": 1, + "deprecated": true, + "description": "已废弃：请使用 `integration_ids`。按单个集成 ID 过滤。" + }, + "integration_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "deprecated": true, + "description": "已废弃：请使用 `integration_ids`。按单个集成 ID 过滤。" } } }, @@ -49263,7 +49771,11 @@ }, "description": "已开启作战室功能的 IM 集成。" } - } + }, + "required": [ + "items" + ], + "description": "已开启作战室功能的 IM 集成列表响应。" }, "WarRoomDataSourceItem": { "type": "object", @@ -49294,15 +49806,19 @@ }, "status": { "type": "string", - "description": "集成当前状态。" + "description": "集成状态：`enabled` 启用、`disabled` 禁用。已删除的集成不会返回。", + "enum": [ + "enabled", + "disabled" + ] }, "category": { "type": "string", - "description": "集成插件的类别。" + "description": "插件类别；本接口返回的 IM 集成固定为 `im`。" }, "plugin_type": { "type": "string", - "description": "集成插件的类型标识。" + "description": "IM 集成插件类型标识，如 `feishu_app`、`dingtalk_app`、`wecom_app`、`slack_app`、`teams_app`。" }, "plugin_type_name": { "type": "string", @@ -49352,11 +49868,11 @@ "last_time": { "type": "integer", "format": "int64", - "description": "集成最近活动的 Unix 时间戳（秒）。" + "description": "该数据源最近活动时间的 Unix 秒级时间戳。固定为 `0`，本接口不填充该字段。" }, "exclusive_data_source_id": { "type": "integer", - "description": "与该集成关联的专属集成 ID。", + "description": "历史遗留的独占集成关联 ID，已废弃。", "format": "int64" }, "integration_id": { @@ -49364,7 +49880,31 @@ "description": "集成 ID，data_source_id 的别名。", "format": "int64" } - } + }, + "required": [ + "data_source_id", + "account_id", + "team_id", + "plugin_id", + "name", + "status", + "category", + "plugin_type", + "plugin_type_name", + "description", + "integration_key", + "ref_id", + "settings", + "no_editable", + "creator_id", + "updated_by", + "created_at", + "updated_at", + "last_time", + "exclusive_data_source_id", + "integration_id" + ], + "description": "IM 集成（数据源）条目。" }, "AddWarRoomMemberRequest": { "type": "object", @@ -49382,7 +49922,6 @@ "type": "array", "items": { "type": "integer", - "description": "", "format": "int64" }, "description": "要加入作战室的人员 ID 列表。" @@ -49399,7 +49938,8 @@ "properties": { "account_id": { "type": "integer", - "description": "主体（账户）标识。" + "description": "主体（账户）标识。", + "format": "uint64" }, "account_name": { "type": "string", @@ -49447,7 +49987,7 @@ }, "restrictions": { "type": "object", - "description": "主体访问限制（仅在已配置时返回）。", + "description": "账户访问限制。未配置时不返回。", "properties": { "ips": { "type": "array", @@ -49471,13 +50011,26 @@ }, "mp_plat": { "type": "string", - "description": "主体所属的云市场平台（仅云市场来源的主体返回）。" + "description": "账户来源的云市场平台。账户非来自云市场时不返回。" }, "mp_account_id": { "type": "string", - "description": "主体在云市场平台上的账户标识（仅云市场来源的主体返回）。" + "description": "账户在云市场平台上的标识。与 `mp_plat` 一起省略。" } - } + }, + "required": [ + "account_id", + "account_name", + "domain", + "extra_domains", + "phone", + "country_code", + "email", + "avatar", + "locale", + "time_zone", + "created_at" + ] }, "PreviewTemplateRequest": { "type": "object", @@ -49488,11 +50041,12 @@ }, "type": { "type": "string", - "description": "决定渲染引擎的模板通道类型。" + "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`。" }, "incident_id": { "type": "string", - "description": "用于渲染模板的故障 ID，省略时使用模拟数据。MongoDB ObjectID 十六进制字符串。" + "description": "用于渲染模板的故障 ID，省略时使用模拟数据。MongoDB ObjectID 十六进制字符串。", + "pattern": "^[0-9a-fA-F]{24}$" }, "incident_card_hidden_fields": { "$ref": "#/components/schemas/IncidentCardHiddenFields", @@ -49502,7 +50056,8 @@ "required": [ "content", "type" - ] + ], + "description": "模板预览请求。" }, "ListStatusPageResponse": { "type": "object", @@ -49514,7 +50069,10 @@ }, "description": "账户拥有的状态页。" } - } + }, + "required": [ + "items" + ] }, "StatusPageItem": { "type": "object", @@ -49542,35 +50100,35 @@ }, "custom_domain": { "type": "string", - "description": "指向状态页的自定义域名。" + "description": "指向状态页的自定义域名。未设置时不返回。" }, "logo": { "type": "string", - "description": "状态页 Logo 图片。" + "description": "状态页 Logo 图片。未设置时不返回。" }, "dark_logo": { "type": "string", - "description": "状态页暗色模式 Logo 图片。" + "description": "状态页暗色模式 Logo 图片。未设置时不返回。" }, "logo_url": { "type": "string", - "description": "点击 Logo 时跳转的 URL。" + "description": "点击 Logo 时跳转的 URL。未设置时不返回。" }, "favicon": { "type": "string", - "description": "状态页的网站图标。" + "description": "状态页的网站图标。未设置时不返回。" }, "page_header": { "type": "string", - "description": "状态页头部内容。" + "description": "状态页头部内容。未设置时不返回。" }, "page_footer": { "type": "string", - "description": "状态页底部内容。" + "description": "状态页底部内容。未设置时不返回。" }, "date_view": { "type": "string", - "description": "时间线的展示方式。`calendar` 以日历视图展示事件日期；`list` 以列表视图展示。", + "description": "时间线的展示方式。`calendar` 以日历视图展示事件日期；`list` 以列表视图展示。未设置时不返回。", "enum": [ "calendar", "list" @@ -49578,7 +50136,7 @@ }, "display_uptime_mode": { "type": "string", - "description": "可用率的展示方式。`chart_and_percentage` 同时展示可用率图表与百分比数值；`chart` 仅展示图表；`none` 不展示可用率。", + "description": "可用率的展示方式。`chart_and_percentage` 同时展示可用率图表与百分比数值；`chart` 仅展示图表；`none` 不展示可用率。未设置时不返回。", "enum": [ "chart_and_percentage", "chart", @@ -49593,11 +50151,11 @@ "type": "string" } }, - "description": "状态页上展示的自定义导航链接。" + "description": "状态页上展示的自定义导航链接。未设置时不返回。" }, "contact_info": { "type": "string", - "description": "联系方式，mailto 或网站 URL。" + "description": "联系方式，mailto 或网站 URL。未设置时不返回。" }, "components": { "type": "array", @@ -49614,13 +50172,23 @@ "description": "对组件进行分组的分组列表。" }, "subscription": { - "$ref": "#/components/schemas/StatusPageSubscriptionItem" + "$ref": "#/components/schemas/StatusPageSubscriptionItem", + "description": "订阅渠道开关。" }, "template_preference": { "type": "string", - "description": "偏好的变更事件模板类型。" + "description": "偏好的事件模板类型：`pre_defined` 或 `message`。从未设置时不返回。" } - } + }, + "required": [ + "page_id", + "name", + "url_name", + "type", + "components", + "sections", + "subscription" + ] }, "StatusPageSubscriptionItem": { "type": "object", @@ -49633,14 +50201,18 @@ "type": "boolean", "description": "是否开启 IM 订阅。" } - } + }, + "required": [ + "email", + "im" + ] }, "StatusPageSectionItem": { "type": "object", "properties": { "section_id": { "type": "string", - "description": "分组 ID。" + "description": "分组 ID。为空时不返回。" }, "name": { "type": "string", @@ -49652,7 +50224,7 @@ }, "order_id": { "type": "integer", - "description": "分组的展示顺序。", + "description": "分组的展示顺序。为 0 时不返回。", "format": "int64" }, "hide_uptime": { @@ -49663,7 +50235,13 @@ "type": "boolean", "description": "是否在汇总接口中隐藏该分组及其组件。" } - } + }, + "required": [ + "name", + "description", + "hide_uptime", + "hide_all" + ] }, "DeletePostMortemTemplateRequest": { "type": "object", @@ -49824,44 +50402,6 @@ } } }, - "PreviewSyncRequest": { - "type": "object", - "required": [ - "ds_type", - "ds_name", - "expr" - ], - "description": "同步数据源查询预览的参数。", - "properties": { - "ds_type": { - "type": "string", - "description": "数据源类型，如 `prometheus`、`loki`、`elasticsearch`。" - }, - "ds_name": { - "type": "string", - "description": "账户中配置的数据源显示名称。" - }, - "expr": { - "type": "string", - "description": "查询表达式，格式因 `ds_type` 而异（Prometheus 为 PromQL，Loki 为 LogQL 等）。" - }, - "delay_seconds": { - "type": "integer", - "description": "将查询窗口向前偏移的秒数，用于补偿数据摄入延迟。" - }, - "args": { - "type": "object", - "additionalProperties": { - "type": "string" - }, - "description": "特定数据源类型的附加查询参数（键值均为字符串），如 SLS 的 `sls.project`、`sls.logstore`，Elasticsearch 的 `es.type`，Loki 的 `loki.type`、`loki.limit`。" - } - } - }, - "PreviewSyncResponse": { - "type": "object", - "description": "数据源返回的原始 JSON，结构随数据源类型而异。" - }, "ResetPostMortemBasicsRequest": { "type": "object", "description": "写回复盘报告的故障基础信息。", @@ -49877,7 +50417,13 @@ }, "incidents_highest_severity": { "type": "string", - "description": "关联故障中的最高严重级别。" + "description": "关联故障中的最高严重级别：`Critical`、`Warning`、`Info` 或 `Ok`。", + "enum": [ + "Critical", + "Warning", + "Info", + "Ok" + ] }, "incidents_earliest_start_seconds": { "type": "integer", @@ -50057,7 +50603,7 @@ }, "TryLinkPersonResponse": { "type": "object", - "description": "本次尝试关联成功的人员。", + "description": "本次调用新关联的人员。如果没有成员可关联，响应中的 `new_linked_person_ids` 可能为空数组，或整个 `data` 字段被省略。", "required": [ "new_linked_person_ids" ], @@ -50118,14 +50664,15 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "component_ids": { "type": "array", "items": { "type": "string" }, - "description": "要删除的组件 ID 列表，可通过 `POST /status-page/info` 获取。" + "description": "要删除的组件 ID 列表，可通过 `GET /status-page/info` 获取。", + "minItems": 1 } } }, @@ -50140,14 +50687,15 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "section_ids": { "type": "array", "items": { "type": "string" }, - "description": "要删除的区域 ID 列表，可通过 `POST /status-page/info` 获取。" + "description": "要删除的区域 ID 列表，可通过 `GET /status-page/info` 获取。", + "minItems": 1 } } }, @@ -50163,7 +50711,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "type": { "type": "string", @@ -50175,7 +50723,7 @@ }, "template_id": { "type": "string", - "description": "要删除的模板 ID，可通过 `POST /status-page/template/list` 获取。" + "description": "要删除的模板 ID，可通过 `GET /status-page/template/list` 获取。" } } }, @@ -50190,7 +50738,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "components": { "type": "array", @@ -50229,9 +50777,15 @@ "hide_all": { "type": "boolean", "description": "为 true 时，在汇总接口中完全隐藏该组件。" + }, + "available_since_seconds": { + "type": "integer", + "format": "int64", + "description": "组件可用起始时间（Unix 秒）。创建时缺省取当前时间；更新时覆盖原值。" } } - } + }, + "minItems": 1 } } }, @@ -50262,7 +50816,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "sections": { "type": "array", @@ -50299,7 +50853,8 @@ "description": "为 true 时，在汇总接口中完全隐藏该区域。" } } - } + }, + "minItems": 1 } } }, @@ -50331,7 +50886,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "type": { "type": "string", @@ -50342,48 +50897,15 @@ "description": "模板分类。`pre_defined` 为预定义事件模板；`message` 为通知消息模板。" }, "template": { - "type": "object", - "description": "模板内容。", - "required": [ - "title", - "event_type", - "status" - ], - "properties": { - "template_id": { - "type": "string", - "description": "模板 ID。省略则创建；提供则更新。" - }, - "title": { - "type": "string", - "description": "模板标题。" - }, - "event_type": { - "type": "string", - "enum": [ - "incident", - "maintenance" - ], - "description": "本模板适用的事件类型：`incident` 故障，`maintenance` 计划维护。" - }, - "status": { - "type": "string", - "enum": [ - "investigating", - "identified", - "monitoring", - "resolved", - "scheduled", - "ongoing", - "completed" - ], - "description": "本模板对应的事件状态。故障用 `investigating`/`identified`/`monitoring`/`resolved`，维护用 `scheduled`/`ongoing`/`completed`。" + "oneOf": [ + { + "$ref": "#/components/schemas/StatusPagePreDefinedTemplate" }, - "description": { - "type": "string", - "description": "模板正文（Markdown）。" + { + "$ref": "#/components/schemas/StatusPageMessageTemplate" } - } + ], + "description": "模板内容。结构取决于 `type`：`pre_defined` 为预定义事件模板，`message` 为消息模板。" } } }, @@ -50419,29 +50941,6 @@ } } }, - "RumDataAggregateFunction": { - "type": "object", - "description": "采样引擎使用的聚合函数元信息。", - "required": [ - "type", - "column_name", - "column_index" - ], - "properties": { - "type": { - "type": "string", - "description": "聚合函数类型。" - }, - "column_name": { - "type": "string", - "description": "聚合函数使用的列名。" - }, - "column_index": { - "type": "integer", - "description": "聚合函数使用的列下标。" - } - } - }, "RumDataFieldMeta": { "type": "object", "description": "单个返回列的元信息。", @@ -50528,10 +51027,12 @@ "description": "单个查询的结果。失败的子查询填充 `error`；成功的子查询填充 `data`。", "properties": { "error": { - "$ref": "#/components/schemas/DutyError" + "$ref": "#/components/schemas/DutyError", + "description": "子查询失败的错误详情；查询成功时省略。" }, "data": { - "$ref": "#/components/schemas/RumDataQueryResult" + "$ref": "#/components/schemas/RumDataQueryResult", + "description": "查询结果；查询失败时省略。" } } }, @@ -50584,7 +51085,7 @@ "properties": { "search_after_ctx": { "type": "string", - "description": "用于继续表格查询分页的不透明游标。" + "description": "用于继续表格查询分页的不透明游标；非游标分页的表格查询或没有更多分页时省略。" }, "fields": { "type": "array", @@ -50604,10 +51105,11 @@ "interval": { "type": "integer", "format": "int64", - "description": "时序查询实际使用的时间桶间隔，单位秒。" + "description": "时序查询实际使用的时间桶间隔，单位秒；`table` 格式查询时省略。" }, "sampling": { - "$ref": "#/components/schemas/RumDataSamplingDecision" + "$ref": "#/components/schemas/RumDataSamplingDecision", + "description": "采样元信息；查询未使用采样时省略。" } } }, @@ -50621,25 +51123,11 @@ "properties": { "enabled": { "type": "boolean", - "description": "是否应用了采样。" + "description": "是否应用了采样。响应中该字段恒为 `true` —— 未使用采样时整个 `sampling` 对象会被省略。" }, "scale_factor": { "type": "number", "description": "将采样计数放大为全量估算值时使用的倍率。" - }, - "selected_tablets": { - "type": "array", - "items": { - "type": "string" - }, - "description": "采样查询选中的存储 tablet。" - }, - "aggregate_funcs": { - "type": "array", - "items": { - "$ref": "#/components/schemas/RumDataAggregateFunction" - }, - "description": "受采样影响的聚合函数。" } } }, @@ -50675,6 +51163,30 @@ "facet_value": { "description": "设置后，统计前会先过滤 `facet_key` 等于该值的事件。接受字符串、数字或布尔值。" }, + "type": { + "type": "string", + "enum": [ + "browser", + "web", + "javascript", + "android", + "ios", + "miniprogram", + "harmony", + "flutter", + "electron", + "react-native" + ], + "description": "符号文件存储的平台，仅在 `scope` 为 `sourcemap` 时使用。省略时默认为 `browser`；`web`、`javascript` 是 `browser` 的别名。\n\n| 值 | 查询的存储 |\n|---|---|\n| `browser` / `web` / `javascript` | JS Sourcemap（不含鸿蒙 ArkTS 与 React Native 行） |\n| `android` | Android ProGuard/R8 mapping；`kind=native` 时为 Android NDK .so 符号 |\n| `ios` | iOS dSYM 符号 |\n| `miniprogram` | 微信小程序 Sourcemap |\n| `harmony` | 鸿蒙 ArkTS Sourcemap；`kind=native` 时为鸿蒙 .so 符号 |\n| `flutter` | Flutter Dart AOT 符号 |\n| `electron` | Electron Breakpad 符号 |\n| `react-native` | React Native JS Sourcemap |" + }, + "kind": { + "type": "string", + "enum": [ + "mapping", + "native" + ], + "description": "符号类型，仅在 `scope` 为 `sourcemap` 时使用，且只对 `android`/`harmony` 有意义：`mapping`（默认）选择 ProGuard/R8 mapping 或 ArkTS Sourcemap，`native` 选择 native .so 符号。" + }, "start_time": { "type": "integer", "format": "int64", @@ -50838,9 +51350,20 @@ "scopes": { "type": "array", "items": { - "type": "string" + "type": "string", + "enum": [ + "session", + "view", + "action", + "error", + "resource", + "long_task", + "vital", + "issue", + "sourcemap" + ] }, - "description": "按 RUM 数据 scope 过滤。合法值：`session`、`view`、`action`、`error`、`resource`、`long_task`、`vital`、`issue`、`sourcemap`。" + "description": "按 RUM 数据 scope 过滤；传入未知值会被参数校验拒绝。不传则返回所有 scope 的字段。\n\n| 值 | 含义 |\n|---|---|\n| `session` | 用户会话 |\n| `view` | 页面/视图 |\n| `action` | 用户操作 |\n| `error` | 错误事件 |\n| `resource` | 资源加载 |\n| `long_task` | 长任务 |\n| `vital` | 性能指标（Web Vitals 等） |\n| `issue` | 异常聚合 Issue |\n| `sourcemap` | Sourcemap 符号文件 |" }, "is_facet": { "type": [ @@ -50956,14 +51479,15 @@ "items": { "$ref": "#/components/schemas/SourcemapCodeSnippet" }, - "description": "该栈帧附近的源码片段。" + "description": "该帧附近的源码片段；未提取到片段时省略（如源码内容不可用或未传 `near`）。" }, "original_frame": { - "$ref": "#/components/schemas/SourcemapStackFrame" + "$ref": "#/components/schemas/SourcemapStackFrame", + "description": "enrich 前的原始混淆/压缩帧；处理器未保留时省略。" }, "third_party": { "type": "boolean", - "description": "该栈帧是否来自第三方或系统库。" + "description": "该帧是否来自第三方或系统库（仅 Android 与 native 符号化场景）；为 `false` 时省略。" } } } @@ -50986,9 +51510,18 @@ "miniprogram", "harmony", "flutter", - "electron" + "electron", + "react-native" + ], + "description": "错误来源平台，决定使用哪类符号存储。省略时默认按 `browser` 处理。\n\n| 值 | 符号化方式 |\n|---|---|\n| `browser` | JS 堆栈，Sourcemap 还原 |\n| `android` | Java/Kotlin 堆栈，ProGuard/R8 mapping 还原；native 堆栈走 NDK 符号（配合 `source_type=ndk` 与 `arch`） |\n| `ios` | iOS 崩溃堆栈，dSYM 符号化（需传 `binary_images`） |\n| `miniprogram` | 微信小程序堆栈，Sourcemap 还原 |\n| `harmony` | 鸿蒙堆栈，ArkTS Sourcemap 或 native 符号化 |\n| `flutter` | Flutter/Dart 堆栈，Dart AOT 符号还原 |\n| `electron` | Electron JS 堆栈，Sourcemap 还原；minidump native 帧走 Breakpad 符号（由 `source_type` 推导） |\n| `react-native` | React Native JS 堆栈，Sourcemap 还原；可用 `platform` 缩小查找范围 |" + }, + "platform": { + "type": "string", + "enum": [ + "ios", + "android" ], - "description": "来源平台。省略时默认按 `browser` 处理。取值：`browser`（浏览器 JS 堆栈，Sourcemap 还原）、`android`（Android 堆栈，mapping/NDK 符号化）、`ios`（iOS 崩溃堆栈，dSYM 符号化）、`miniprogram`（微信小程序堆栈，Sourcemap 还原）、`harmony`（鸿蒙堆栈，Sourcemap/native 符号化）、`flutter`（Flutter 堆栈，符号还原）、`electron`（Electron 堆栈，Sourcemap 还原）。" + "description": "将 `react-native` 的 enrich 限定到应用的 native 平台：`ios` 表示 iOS native 层，`android` 表示 Android native 层（控制台根据事件的 OS 推导）。其他 `type` 取值下忽略。" }, "service": { "type": "string", @@ -51206,7 +51739,7 @@ }, "UpdateStatusPageRequest": { "type": "object", - "description": "更新已有状态页所需的参数。除 `page_id` 外均为可选字段；省略某字段表示保持其原值。", + "description": "更新已有状态页所需的参数。除 `page_id` 外均为可选字段；省略某字段或传 null 表示保持其原值。", "required": [ "page_id" ], @@ -51214,62 +51747,99 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" }, "name": { - "type": "string", - "description": "状态页展示名称。留空表示保持原值。", + "type": [ + "string", + "null" + ], + "description": "状态页展示名称。省略或传 null 表示保持原值。", "maxLength": 255 }, "url_name": { - "type": "string", - "description": "URL 安全的状态页路径，在账户和状态页类型内唯一。留空表示保持原值。", + "type": [ + "string", + "null" + ], + "description": "URL 安全的状态页路径，在账户和状态页类型内唯一。省略或传 null 表示保持原值。", "maxLength": 255 }, "custom_domain": { - "type": "string", - "description": "公开状态页使用的自定义域名。留空表示保持原值。", + "type": [ + "string", + "null" + ], + "description": "公开状态页使用的自定义域名。省略或传 null 表示保持原值。", "maxLength": 255 }, "page_title": { - "type": "string", - "description": "状态页浏览器标题。留空表示保持原值。" + "type": [ + "string", + "null" + ], + "description": "状态页浏览器标题。省略或传 null 表示保持原值。" }, "logo": { - "type": "string", - "description": "状态页 Logo 图片。留空表示保持原值。" + "type": [ + "string", + "null" + ], + "description": "状态页 Logo 图片。省略或传 null 表示保持原值。" }, "dark_logo": { - "type": "string", - "description": "状态页暗色模式 Logo 图片。留空表示保持原值。" + "type": [ + "string", + "null" + ], + "description": "状态页暗色模式 Logo 图片。省略或传 null 表示保持原值。" }, "logo_url": { - "type": "string", - "description": "点击 Logo 时跳转的 URL。留空表示保持原值。" + "type": [ + "string", + "null" + ], + "description": "点击 Logo 时跳转的 URL。省略或传 null 表示保持原值。", + "maxLength": 255 }, "favicon": { - "type": "string", - "description": "状态页的网站图标。留空表示保持原值。" + "type": [ + "string", + "null" + ], + "description": "状态页的网站图标。省略或传 null 表示保持原值。" }, "page_header": { - "type": "string", - "description": "状态页页头内容。留空表示保持原值。" + "type": [ + "string", + "null" + ], + "description": "状态页页头内容。省略或传 null 表示保持原值。" }, "page_footer": { - "type": "string", - "description": "状态页页脚内容。留空表示保持原值。" + "type": [ + "string", + "null" + ], + "description": "状态页页脚内容。省略或传 null 表示保持原值。" }, "date_view": { - "type": "string", - "description": "事件日期展示方式。留空表示保持原值。`calendar` 为日历视图；`list` 为列表视图。", + "type": [ + "string", + "null" + ], + "description": "事件日期展示方式。省略或传 null 表示保持原值。`calendar` 为日历视图；`list` 为列表视图。", "enum": [ "calendar", "list" ] }, "display_uptime_mode": { - "type": "string", - "description": "可用率展示方式。留空表示保持原值。`chart_and_percentage` 同时展示图表与百分比；`chart` 仅展示图表；`none` 不展示。", + "type": [ + "string", + "null" + ], + "description": "可用率展示方式。省略或传 null 表示保持原值。`chart_and_percentage` 同时展示图表与百分比；`chart` 仅展示图表；`none` 不展示。", "enum": [ "chart_and_percentage", "chart", @@ -51278,7 +51848,7 @@ }, "custom_links": { "type": "array", - "description": "状态页展示的自定义导航链接。留空表示保持原值。", + "description": "状态页展示的自定义导航链接。省略或传空数组表示保持当前链接。", "items": { "type": "object", "additionalProperties": { @@ -51287,16 +51857,22 @@ } }, "contact_info": { - "type": "string", - "description": "联系信息，例如 mailto 或网站 URL。留空表示保持原值。" + "type": [ + "string", + "null" + ], + "description": "联系信息，例如 mailto 或网站 URL。省略或传 null 表示保持原值。" }, "subscription": { "$ref": "#/components/schemas/StatusPageSubscriptionItem", - "description": "订阅渠道开关。" + "description": "订阅渠道开关。省略或传 null 表示保持原值。" }, "template_preference": { - "type": "string", - "description": "偏好的变更事件模板类型。留空表示保持原值。" + "type": [ + "string", + "null" + ], + "description": "偏好的事件模板类型：`pre_defined` 或 `message`。省略或传 null 表示保持原值。" } } }, @@ -51310,7 +51886,7 @@ "page_id": { "type": "integer", "format": "int64", - "description": "状态页 ID，可通过 `POST /status-page/list` 获取。" + "description": "状态页 ID，可通过 `GET /status-page/list` 获取。" } } }, @@ -51325,8 +51901,8 @@ }, "instructions": { "type": "string", - "description": "远程智能体的自然语言指令。必填 —— 已弃用的 `description` 字段仍保留以兼容旧客户端，若两者同时传入则必须与 `instructions` 完全一致。", - "maxLength": 2000 + "description": "远程智能体的自然语言指令：Markdown 文档，可带 `summary` frontmatter，正文非空，最大 50 KiB（51200 字节）。必填 —— 已弃用的 `description` 字段仍保留以兼容旧客户端，若两者同时传入则必须与 `instructions` 完全一致。", + "maxLength": 51200 }, "card_url": { "type": "string", @@ -51334,14 +51910,19 @@ }, "auth_type": { "type": "string", - "description": "访问远程智能体的认证类型：`none`、`api_key` 或 `bearer`。" + "description": "访问远程智能体的认证类型：`none`（省略时默认）、`api_key` 或 `bearer`。", + "enum": [ + "none", + "api_key", + "bearer" + ] }, "auth_config": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "认证配置键值对，如 API Key 或 Bearer Token。敏感键（`api_key`、`token`、`client_secret`）的值在返回时会被挖码。" + "description": "认证配置键值，例如 API key 或 bearer token。键名疑似凭据（包含 KEY、SECRET、TOKEN、PASSWORD 等）的值在响应中会被脱敏。" }, "streaming": { "type": "boolean", @@ -51352,17 +51933,12 @@ "description": "团队范围：0 = 账户级；>0 = 团队。在账户级创建需要 owner/admin 角色；创建到某个团队需要真实属于该团队。", "format": "int64" }, - "environment_kind": { - "type": "string", - "enum": [ - "", - "byoc" - ], - "description": "执行环境绑定。省略或传空字符串表示自动路由；`byoc` 将智能体固定到 `environment_id` 指定的 Runner。不接受 `cloud` —— 已配置的 A2A 智能体需要持久 Runner，而非一次性云沙箱。" - }, - "environment_id": { - "type": "string", - "description": "BYOC Runner ID。当 `environment_kind=byoc` 时必填；该 Runner 必须属于账户或调用者所属的团队。" + "environments": { + "type": "array", + "items": { + "type": "string" + }, + "description": "该智能体可运行的执行环境：`cloud` 和/或 BYOC Runner 的环境 ID 列表。省略或为空表示所有环境。" }, "auth_mode": { "type": "string", @@ -51439,17 +52015,12 @@ "type": "boolean", "description": "调用者是否可以编辑该智能体。" }, - "environment_kind": { - "type": "string", - "enum": [ - "", - "byoc" - ], - "description": "执行环境绑定。空字符串表示自动路由；`byoc` 表示固定到 `environment_id` 指定的 Runner。" - }, - "environment_id": { - "type": "string", - "description": "BYOC Runner ID。仅在 `environment_kind=byoc` 时设置，否则为空。" + "environments": { + "type": "array", + "items": { + "type": "string" + }, + "description": "该智能体可运行的执行环境（`cloud` 和/或 BYOC Runner 的环境 ID）。始终返回；`[]` 表示所有环境（该字段引入前的历史数据也是空数组）。" }, "agent_name": { "type": "string", @@ -51458,7 +52029,7 @@ "instructions": { "type": "string", "description": "远程智能体的自然语言指令（旧名 `description`）。", - "maxLength": 2000 + "maxLength": 51200 }, "card_url": { "type": "string", @@ -51466,14 +52037,20 @@ }, "auth_type": { "type": "string", - "description": "访问远程智能体的认证类型：`none`、`api_key` 或 `bearer`。" + "description": "访问远程智能体的认证类型：`none`、`api_key` 或 `bearer`。校验收紧前创建的历史数据可能返回空字符串，等价于 `none`。", + "enum": [ + "", + "none", + "api_key", + "bearer" + ] }, "auth_config": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "认证配置；敏感值（`api_key`、`token`、`client_secret`）会被挖码。" + "description": "认证配置键值。键名疑似凭据（包含 KEY、SECRET、TOKEN、PASSWORD 等）的值会被脱敏；为空时省略。" }, "streaming": { "type": "boolean", @@ -51489,14 +52066,14 @@ }, "agent_card_name": { "type": "string", - "description": "从远程卡片解析得到的智能体名称。" + "description": "从远程卡片解析得到的智能体名称；卡片尚未拉取时省略。" }, "agent_card_skills": { "type": "array", "items": { "type": "string" }, - "description": "远程卡片宣告的技能。" + "description": "远程卡片宣告的技能；卡片尚未拉取时省略。" }, "card_resolve_timeout": { "type": "integer", @@ -51552,8 +52129,6 @@ "account_id", "team_id", "can_edit", - "environment_kind", - "environment_id", "agent_name", "instructions", "card_url", @@ -51564,7 +52139,8 @@ "task_timeout", "created_by", "created_at", - "updated_at" + "updated_at", + "environments" ] }, "A2AAgentListRequest": { @@ -51656,8 +52232,8 @@ "string", "null" ], - "description": "新的指令。省略则保持不变。已弃用的 `description` 字段仍可传入，若两者同时传入则必须一致。", - "maxLength": 2000 + "description": "新的指令文档（约定同创建：可带 `summary` frontmatter，正文非空，最大 50 KiB）。省略则保持不变。已弃用的 `description` 字段仍可传入，若两者同时传入则必须一致。", + "maxLength": 51200 }, "card_url": { "type": [ @@ -51671,14 +52247,19 @@ "string", "null" ], - "description": "新的认证类型。省略则保持不变。" + "description": "新的认证类型：`none`、`api_key` 或 `bearer`。省略则保持不变。", + "enum": [ + "none", + "api_key", + "bearer" + ] }, "auth_config": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "替换认证配置。省略则保持不变。对敏感键回传挖码值（或空字符串）将保留已存储的密钥而非覆盖。" + "description": "整体替换认证配置；省略则保持不变。未包含在 map 中的键会被删除。敏感键回传掩码值时保留已存储的密钥，传空字符串则清除该密钥。" }, "streaming": { "type": [ @@ -51695,19 +52276,15 @@ "description": "重新分配团队范围。省略则保持不变。重新分配需要对目标团队的权限；若团队变更且未同时传入新的环境绑定，则现有 Runner 绑定必须对调用者仍可选，否则更新将被拒绝。", "format": "int64" }, - "environment_kind": { + "environments": { "type": [ - "string", - "null" - ], - "description": "新的执行环境绑定：空字符串表示自动，`byoc` 表示指定 Runner。不接受 `cloud`。省略则保持不变。" - }, - "environment_id": { - "type": [ - "string", + "array", "null" ], - "description": "新的 BYOC Runner ID。与 `environment_kind=byoc` 一同传入。省略则保持不变。" + "items": { + "type": "string" + }, + "description": "该智能体可运行的执行环境：`cloud` 和/或 BYOC Runner 的环境 ID 列表。省略（null）表示保持不变；传入列表即整体设置——空列表表示清除限制、恢复为所有环境。" }, "auth_mode": { "type": [ @@ -51763,7 +52340,7 @@ "type": "integer", "format": "int64", "minimum": 0, - "description": "作用域团队 ID。0 或省略表示个人规则；>0 表示账户下某团队。创建后不可修改。" + "description": "作用域团队 ID。0 或省略表示个人规则；>0 表示账户下某团队。之后可通过 update 改派（团队规则转个人仅规则 owner 可操作；转入团队要求调用者属于该团队）。" }, "enabled": { "type": "boolean", @@ -51917,7 +52494,7 @@ }, "schedule_trigger_id": { "type": "string", - "description": "Schedule trigger ID。" + "description": "定时触发器 ID；规则没有定时触发器时省略。" }, "schedule_trigger_enabled": { "type": "boolean", @@ -51925,11 +52502,11 @@ }, "http_post_trigger_id": { "type": "string", - "description": "HTTP POST trigger ID。" + "description": "HTTP POST 触发器 ID；规则没有 HTTP POST 触发器时省略。" }, "http_post_trigger_url": { "type": "string", - "description": "HTTP POST 触发路径。" + "description": "HTTP POST 触发器路径；规则没有 HTTP POST 触发器时省略。" }, "http_post_trigger_enabled": { "type": "boolean", @@ -51937,7 +52514,7 @@ }, "oncall_incident_trigger_id": { "type": "string", - "description": "On-call 故障触发器 ID。" + "description": "On-call 故障触发器 ID；规则没有 On-call 故障触发器时省略。" }, "oncall_incident_trigger_enabled": { "type": "boolean", @@ -51950,7 +52527,7 @@ "format": "int64", "minimum": 1 }, - "description": "监听的 On-call 集成 ID 列表；创建或启用该触发器时至少需要一个有效 ID。" + "description": "要监听的 On-call 渠道 ID。创建或启用该触发器至少需要一个有效 ID；未配置 On-call 故障触发器时省略。" }, "oncall_incident_severities": { "type": "array", @@ -51962,7 +52539,7 @@ "Info" ] }, - "description": "监听的故障严重程度，支持 Critical、Warning 和 Info；创建或启用该触发器时至少需要一个值。" + "description": "要监听的事故级别。支持的值为 Critical、Warning、Info；创建或启用该触发器至少需要一个值；未配置 On-call 故障触发器时省略。" }, "http_post_token": { "type": "string", @@ -52022,7 +52599,6 @@ "limit": { "type": "integer", "default": 20, - "maximum": 100, "description": "每页数量。" }, "scope": { @@ -52107,7 +52683,7 @@ ], "format": "int64", "minimum": 0, - "description": "只允许传当前值；创建后 personal / team scope 不可修改。" + "description": "改派规则作用域：0 表示转为个人规则（团队规则仅规则 owner 可转）；>0 表示转入调用者所属的团队。省略则保持不变。" }, "enabled": { "type": [ @@ -52215,9 +52791,20 @@ "type": "string", "description": "运行 ID。" }, + "session_id": { + "type": "string", + "description": "本次运行创建的会话 ID，从 `result_json` 中提取；运行尚未启动会话时省略。" + }, + "session_name": { + "type": "string", + "description": "运行会话的显示名称，批量查询填充；为空或查询失败时省略。" + }, "kind": { "type": "string", - "description": "运行类型。" + "description": "运行类型；按规则查询时恒为 `automation_rule`。", + "enum": [ + "automation_rule" + ] }, "account_id": { "type": "integer", @@ -52253,9 +52840,10 @@ "partial", "failed", "skipped", - "abandoned" + "abandoned", + "blocked" ], - "description": "运行状态。可选值（前三个为进行中，其余为终态）：\n| 值 | 含义 |\n| --- | --- |\n| `queued` | 已入队，等待工作器执行 |\n| `running` | 正在执行 |\n| `retrying` | 本次尝试失败，已安排重试 |\n| `succeeded` | 成功完成 |\n| `partial` | 部分成功（当前仅记忆整理类运行会产生；规则运行不会落到该状态） |\n| `failed` | 失败终态，不再重试 |\n| `skipped` | 未执行（如超过宽限期、触发器或规则失效），以运行记录形式留存原因 |\n| `abandoned` | 进行中超过陈旧阈值被后台清扫判为未完成（如工作器异常退出） |" + "description": "运行状态。可选值（前三个为进行中，其余为终态）：\n| 值 | 含义 |\n| --- | --- |\n| `queued` | 已入队，等待工作器执行 |\n| `running` | 正在执行 |\n| `retrying` | 本次尝试失败，已安排重试 |\n| `succeeded` | 成功完成 |\n| `partial` | 部分成功（当前仅记忆整理类运行会产生；规则运行不会落到该状态） |\n| `failed` | 失败终态，不再重试 |\n| `skipped` | 未执行（如超过宽限期、触发器或规则失效），以运行记录形式留存原因 |\n| `abandoned` | 进行中超过陈旧阈值被后台清扫判为未完成（如工作器异常退出） |\n| `blocked` | 终态：有实际产出，但因连接器等待人工完成授权而结束（区别于 `failed`） |" }, "attempts": { "type": "integer", @@ -52278,17 +52866,27 @@ }, "error_code": { "type": "string", - "description": "错误码。" + "description": "错误码；运行未失败时为空字符串。" }, "error_message": { "type": "string", - "description": "错误消息。" + "description": "错误信息；运行未失败时为空字符串。" }, "stats_json": { - "description": "统计 JSON。" + "type": [ + "object", + "null" + ], + "additionalProperties": true, + "description": "运行统计原始 JSON；为空时为 null。" }, "result_json": { - "description": "结果 JSON。" + "type": [ + "object", + "null" + ], + "additionalProperties": true, + "description": "运行结果原始 JSON（运行启动后携带 `session_id`）；为空时为 null。" }, "created_at": { "type": "integer", @@ -52314,7 +52912,11 @@ "completed_at", "duration_ms", "created_at", - "updated_at" + "updated_at", + "error_code", + "error_message", + "stats_json", + "result_json" ] }, "AutomationRunListRequest": { @@ -52332,7 +52934,6 @@ "limit": { "type": "integer", "default": 20, - "maximum": 100, "description": "每页数量。" }, "status": { @@ -52345,9 +52946,10 @@ "partial", "failed", "skipped", - "abandoned" + "abandoned", + "blocked" ], - "description": "运行状态过滤：`queued` 排队中、`running` 运行中、`retrying` 重试中、`succeeded` 成功、`partial` 部分成功、`failed` 失败、`skipped` 已跳过（如规则或触发器失效）、`abandoned` 已放弃（超过时效未完成被系统终结）；省略则不过滤。" + "description": "运行状态过滤：`queued` 排队中、`running` 运行中、`retrying` 重试中、`succeeded` 成功、`partial` 部分成功、`failed` 失败、`skipped` 已跳过（如规则或触发器失效）、`abandoned` 已放弃（超过时效未完成被系统终结）、`blocked` 已阻塞（终态：有产出但某个连接器正等待人工完成授权）；省略则不过滤。" }, "trigger_kind": { "type": "string", @@ -52363,12 +52965,14 @@ "started_after_ms": { "type": "integer", "format": "int64", - "description": "开始时间下界，Unix 毫秒。" + "description": "开始时间下界，Unix 毫秒。早于 180 天运行记录保留下限的值会被截断到下限（省略时默认即为该下限）。", + "minimum": 0 }, "started_before_ms": { "type": "integer", "format": "int64", - "description": "开始时间上界，Unix 毫秒。" + "description": "开始时间上界，Unix 毫秒。必须不早于生效后的 `started_after_ms`；早于保留下限时返回空结果。", + "minimum": 0 } }, "required": [ @@ -52430,7 +53034,7 @@ }, "enabled": { "type": "boolean", - "description": "模板是否可用。" + "description": "从该模板创建规则时默认是否启用（预填值）。" }, "prompt": { "type": "string", @@ -52625,7 +53229,7 @@ "properties": { "server_name": { "type": "string", - "description": "MCP 服务器名称，在账户内唯一。", + "description": "MCP 服务器名称：必须以字母开头，仅含字母、数字、`-`、`_`（`@` 为保留字符）；在其作用域（账户范围或单个团队）内唯一，大小写不敏感。", "minLength": 1, "maxLength": 255 }, @@ -52707,16 +53311,12 @@ "description": "团队范围：0 表示账户级；>0 表示团队。", "format": "int64" }, - "environment_kind": { - "type": "string", - "description": "绑定到指定 BYOC 运行器（需同时提供 environment_id）。省略或留空表示自动选择；MCP 服务器不支持 cloud。唯一可选值：`byoc`（账户内自托管的 BYOC 运行器；MCP 服务器进程运行在客户自己的基础设施上）。", - "enum": [ - "byoc" - ] - }, - "environment_id": { - "type": "string", - "description": "运行器 ID；environment_kind 为 byoc 时必填。" + "environments": { + "type": "array", + "items": { + "type": "string" + }, + "description": "该服务器可运行的执行环境：`cloud` 和/或 BYOC Runner 的环境 ID 列表。省略或为空表示所有环境。" }, "allow_insecure_oauth_http": { "type": "boolean", @@ -52785,21 +53385,16 @@ "type": "boolean", "description": "调用者是否可编辑该服务器。" }, - "environment_kind": { - "type": "string", - "description": "运行环境类型：留空表示自动选择，`byoc` 表示绑定到指定运行器；MCP 服务器不支持绑定 `cloud`。", - "enum": [ - "", - "byoc" - ] - }, - "environment_id": { - "type": "string", - "description": "environment_kind 为 byoc 时对应的运行器 ID；否则为空。" + "environments": { + "type": "array", + "items": { + "type": "string" + }, + "description": "该服务器可运行的执行环境（`cloud` 和/或 BYOC Runner 的环境 ID）。始终返回；`[]` 表示所有环境（该字段引入前的历史数据也是空数组）。" }, "server_name": { "type": "string", - "description": "MCP 服务器名称，在账户内唯一。" + "description": "MCP 服务器名称，在其作用域（账户范围或单个团队）内唯一，大小写不敏感。" }, "description": { "type": "string", @@ -52807,7 +53402,7 @@ }, "ai_description": { "type": "string", - "description": "LLM 生成的描述，存在时优先于 `description`。" + "description": "LLM 生成的描述，存在时优先于 `description`；尚未生成时省略。" }, "transport": { "type": "string", @@ -52869,26 +53464,11 @@ }, "allow_insecure_oauth_http": { "type": "boolean", - "description": "允许该服务器的 OAuth 令牌交换使用明文 HTTP；仅用于测试。" + "description": "允许该服务器的 OAuth token 交换走明文 HTTP；仅供测试使用。为 false 时省略。" }, "allow_insecure_tls_skip_verify": { "type": "boolean", - "description": "连接该服务器时跳过 TLS 证书校验；仅用于测试。" - }, - "tools": { - "type": "array", - "items": { - "$ref": "#/components/schemas/MCPToolInfo" - }, - "description": "实时工具列表；由 get/test 接口填充。" - }, - "tool_count": { - "type": "integer", - "description": "实时工具列表的数量。" - }, - "list_error": { - "type": "string", - "description": "实时获取工具列表失败时的错误信息。" + "description": "连接该服务器时跳过 TLS 证书校验；仅供测试使用。为 false 时省略。" }, "auth_mode": { "type": "string", @@ -52932,8 +53512,6 @@ "account_id", "team_id", "can_edit", - "environment_kind", - "environment_id", "server_name", "description", "transport", @@ -52942,7 +53520,8 @@ "call_timeout", "created_by", "created_at", - "updated_at" + "updated_at", + "environments" ] }, "MCPServerListRequest": { @@ -53070,7 +53649,7 @@ "additionalProperties": { "type": "string" }, - "description": "环境变量（`stdio` 传输）；整体替换，但回填的掩码敏感值会保留服务端存储的原值；省略则不修改。" + "description": "环境变量（`stdio` 传输）；整体替换，但敏感键回传掩码值或空字符串时保留服务端存储的原值；省略则不修改。" }, "url": { "type": "string", @@ -53081,7 +53660,7 @@ "additionalProperties": { "type": "string" }, - "description": "HTTP 头（sse / streamable-http）。" + "description": "HTTP 头（`sse` / `streamable-http` 传输）；整体替换，掩码/空值保留规则同 `env`；省略则不修改。" }, "connect_timeout": { "type": "integer", @@ -53111,19 +53690,15 @@ "description": "重新分配团队范围：0 表示账户级；>0 表示团队。省略则不变。", "format": "int64" }, - "environment_kind": { - "type": [ - "string", - "null" - ], - "description": "重新指定运行器绑定：byoc（需同时提供 environment_id）或空字符串表示重置为自动选择。省略（null）表示保持当前绑定不变。" - }, - "environment_id": { + "environments": { "type": [ - "string", + "array", "null" ], - "description": "与 environment_kind=byoc 配对的运行器 ID。省略（null）表示保持当前绑定不变。" + "items": { + "type": "string" + }, + "description": "该服务器可运行的执行环境：`cloud` 和/或 BYOC Runner 的环境 ID 列表。省略（null）表示保持不变；传入列表即整体设置——空列表表示清除限制、恢复为所有环境。" }, "allow_insecure_oauth_http": { "type": [ @@ -53144,29 +53719,6 @@ "server_id" ] }, - "MCPToolInfo": { - "type": "object", - "description": "MCP 服务器暴露的单个工具的元数据。", - "properties": { - "name": { - "type": "string", - "description": "工具名称。" - }, - "description": { - "type": "string", - "description": "工具描述。" - }, - "input_schema": { - "type": "object", - "additionalProperties": true, - "description": "描述工具输入参数的 JSON Schema。" - } - }, - "required": [ - "name", - "description" - ] - }, "ManualRunRuleResult": { "type": "object", "description": "手动运行一次自动化规则（跳过其计划触发时间）的结果。", @@ -53609,7 +54161,7 @@ }, "asc": { "type": "boolean", - "description": "为 true 时升序，false 时降序；`orderby` 省略时也生效（此时按 `updated_at` 排序）。" + "description": "为 true 时升序，false 时降序。仅在与 `orderby` 同时提供时生效；省略 `orderby` 时始终按 `updated_at` 降序。" }, "include_subagent_sessions": { "type": "boolean", @@ -53769,7 +54321,7 @@ }, "skill_name": { "type": "string", - "description": "技能名称，在账户内唯一。" + "description": "技能名称，在其作用域内唯一（账户范围或单个团队内）。" }, "description": { "type": "string", @@ -53809,6 +54361,13 @@ }, "description": "所需工具（内置或 `mcp:server/tool`）。" }, + "venues": { + "type": "array", + "items": { + "type": "string" + }, + "description": "限定技能可用的执行环境类型（EnvironmentKind 字符串，如 `byoc`）；为空时省略，表示所有环境均可用。" + }, "s3_key": { "type": "string", "description": "技能压缩包在对象存储中的 key。" @@ -54035,7 +54594,8 @@ "ts": { "type": "integer", "format": "int64", - "description": "会话起始时间的 Unix 毫秒时间戳。可选；当 `session_id` 在不同时间窗口内被复用时用于区分。" + "description": "会话起始时间的 Unix 毫秒时间戳。可选；当 `session_id` 在不同时间窗口内被复用时用于区分。", + "exclusiveMinimum": 0 } } }, @@ -54073,16 +54633,18 @@ "type": "string", "enum": [ "browser", - "android", "ios", - "miniprogram", + "android", "react-native", "flutter", "kotlin-multiplatform", "roku", - "unity" + "unity", + "miniprogram", + "harmony", + "electron" ], - "description": "记录该会话的 SDK 平台。平台标识，取值为 `browser`、`android`、`ios`、`miniprogram`、`react-native`、`flutter`、`kotlin-multiplatform`、`roku`、`unity`。" + "description": "录制该会话的 SDK 平台。平台标识：\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 桌面应用 |" }, "start": { "type": "integer", @@ -54103,16 +54665,18 @@ "type": "string", "enum": [ "browser", - "android", "ios", - "miniprogram", + "android", "react-native", "flutter", "kotlin-multiplatform", "roku", - "unity" + "unity", + "miniprogram", + "harmony", + "electron" ], - "description": "记录该视图的 SDK 平台。平台标识，取值为 `browser`、`android`、`ios`、`miniprogram`、`react-native`、`flutter`、`kotlin-multiplatform`、`roku`、`unity`。" + "description": "录制该视图的 SDK 平台。平台标识：\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 桌面应用 |" }, "view_id": { "type": "string", @@ -54132,11 +54696,11 @@ }, "container_source": { "type": "string", - "description": "当该视图被嵌入时（如原生 App 内的 WebView），容器 App 的 SDK 平台。" + "description": "该视图嵌套展示时，容器应用的 SDK 平台（如原生应用内的 WebView）；未嵌套时省略。" }, "container_view_id": { "type": "string", - "description": "当该视图被嵌入时，所属容器视图的 ID。" + "description": "该视图嵌套展示时，容器视图的 View ID；未嵌套时省略。" }, "server_time_delta": { "type": "integer", @@ -54184,13 +54748,16 @@ "description": "会话的回放元数据：所属应用、设备、会话时间范围及全部录制视图。", "properties": { "application": { - "$ref": "#/components/schemas/RumReplayApplication" + "$ref": "#/components/schemas/RumReplayApplication", + "description": "会话所属的应用。" }, "device": { - "$ref": "#/components/schemas/RumReplayDevice" + "$ref": "#/components/schemas/RumReplayDevice", + "description": "录制该会话的设备。" }, "session": { - "$ref": "#/components/schemas/RumReplaySession" + "$ref": "#/components/schemas/RumReplaySession", + "description": "会话的起止时间与状态。" }, "views": { "type": "array", @@ -54230,7 +54797,8 @@ "ts": { "type": "integer", "format": "int64", - "description": "Unix 毫秒时间戳。设置该字段且 `search_after_ctx` 为空时，将从该时间点之前最近的一个全量快照分段开始，而非从头开始。" + "description": "Unix 毫秒时间戳。设置该字段且 `search_after_ctx` 为空时，将从该时间点之前最近的一个全量快照分段开始，而非从头开始。", + "exclusiveMinimum": 0 }, "url_mode": { "type": "boolean", @@ -54359,7 +54927,7 @@ }, "name": { "type": "string", - "description": "引用该字段的自定义表单显示名称。" + "description": "引用该字段的自定义表单类型名称（如 `解决故障` 表示解决故障表单）。" }, "href": { "type": "string", @@ -55283,7 +55851,18 @@ "format": "int64", "description": "最后更新时间，Unix 秒级时间戳。" } - } + }, + "required": [ + "comment_type_id", + "account_id", + "name", + "color", + "position", + "creator_id", + "updated_by", + "created_at", + "updated_at" + ] }, "ListIncidentCommentTypesRequest": { "type": "object", @@ -55305,7 +55884,7 @@ }, "CreateIncidentCommentTypeRequest": { "type": "object", - "description": "创建评论类型的参数。", + "description": "创建评论类型的参数。每个账户最多 10 个评论类型。", "required": [ "name", "color" @@ -55335,7 +55914,11 @@ "item": { "$ref": "#/components/schemas/IncidentCommentTypeItem" } - } + }, + "required": [ + "comment_type_id", + "item" + ] }, "UpdateIncidentCommentTypeRequest": { "type": "object", @@ -55625,7 +56208,7 @@ "limit": { "type": "integer", "format": "int64", - "minimum": 1, + "minimum": 0, "maximum": 200, "default": 50, "description": "每页条数，最多 200，默认 50。" @@ -57865,7 +58448,7 @@ "properties": { "id": { "type": "integer", - "format": "uint64", + "format": "int64", "description": "内部行 ID。" }, "account_id": { @@ -58633,7 +59216,7 @@ }, "id": { "type": "integer", - "format": "uint64", + "format": "int64", "description": "内部自增行 ID。历史回滚后会以新 ID 重新插入，因此该值在回滚前后并不稳定。" }, "deleted_at": { @@ -58944,7 +59527,7 @@ }, "team_name": { "type": "string", - "description": "所属团队的显示名称（仅团队范围）；账户范围为空。" + "description": "所属团队的显示名称（仅团队范围）；为空时省略（账户范围，或团队名称解析失败）。" }, "file_count": { "type": "integer", @@ -59105,7 +59688,7 @@ }, "query": { "type": "string", - "description": "对知识包 ID、范围和团队名称做大小写不敏感的子串过滤。", + "description": "对知识包 ID、范围、范围 ID/账户 ID 和团队名称做大小写不敏感的子串过滤。", "maxLength": 128 }, "team_ids": { @@ -59163,8 +59746,7 @@ "description": "目标范围；不传则为空操作，返回当前知识包。", "enum": [ "account", - "team", - null + "team" ] }, "scope_id": { @@ -59216,11 +59798,11 @@ }, "p": { "type": "integer", - "description": "页码，从 1 开始。" + "description": "页码，从 1 开始。目前接受但忽略——响应始终返回完整文件列表。" }, "limit": { "type": "integer", - "description": "每页条数。" + "description": "每页条数。目前接受但忽略——响应始终返回完整文件列表。" } } }, @@ -59255,7 +59837,7 @@ }, "content_b64": { "type": "string", - "description": "Base64 编码的文件内容；解码后必须是合法的 UTF-8 文本。" + "description": "Base64 编码的文件内容；解码后必须是合法的 UTF-8 文本（拒绝二进制）。单文件上限 1 MiB。" }, "content_type": { "type": "string", @@ -59399,6 +59981,503 @@ "description": "删除后的非阻塞警告数组；`code=still_referenced_by` 表示被（强制）删除的文件仍被包内其他文件 @ref 引用（`refs` 列出引用方）。无警告时该字段缺省（omitempty）。" } } + }, + "FeedDetailAlertMerge": { + "type": "object", + "title": "a_merge", + "description": "`a_merge` 的详情数据：告警被合并到故障。", + "properties": { + "comment": { + "type": "string", + "description": "合并时记录的评论。为空时不返回。" + }, + "target_incident": { + "$ref": "#/components/schemas/IncidentShort", + "description": "告警合并到的目标故障。未记录时不返回。" + }, + "source_alerts": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AlertShort" + }, + "description": "被合并进目标故障的源告警。为空时不返回。" + }, + "owner_id": { + "type": "integer", + "format": "int64", + "description": "目标故障被设置的新负责人成员 ID。未变更时不返回。" + }, + "title": { + "type": "string", + "description": "目标故障被设置的新标题。未变更时不返回。" + } + } + }, + "AlertShort": { + "type": "object", + "description": "告警简要引用。", + "properties": { + "alert_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "告警 ID（ObjectID 十六进制字符串）。" + }, + "title": { + "type": "string", + "description": "告警标题，读取时解析填充。为空时不返回。" + } + } + }, + "EventGroup": { + "type": "object", + "description": "告警事件合并配置。启用后，同一告警的重复事件会在时间窗口内并入已有告警，而不是新建告警。", + "properties": { + "is_enabled": { + "type": "boolean", + "description": "为 true 时，重复事件并入已有告警；为 false 时，每个事件都单独生成告警。默认为 true。" + }, + "time_window": { + "type": "integer", + "minimum": 1, + "description": "合并窗口，单位分钟，范围 1-1440（24 小时）；开通扩展额度的账号最大可设 10080（7 天）。默认 1440。" + } + } + }, + "StatusPageInfoResponse": { + "type": "object", + "description": "`GET /status-page/info` 返回的状态页详情：完整页面配置及特性开关。", + "allOf": [ + { + "$ref": "#/components/schemas/StatusPageItem" + }, + { + "type": "object", + "properties": { + "managed_domain_feature_enabled": { + "type": "boolean", + "description": "该页面是否启用托管自定义域名特性。公开页面为 `true`，内部页面恒为 `false`。" + } + }, + "required": [ + "managed_domain_feature_enabled" + ] + } + ] + }, + "StatusPagePreDefinedTemplate": { + "type": "object", + "description": "预定义事件模板：可复用的事件草稿（标题、类型、状态、描述）。在 `POST /status-page/template/upsert` 中，省略 `template_id` 表示创建，提供则表示更新；更新时仅应用非空字段。", + "properties": { + "template_id": { + "type": "string", + "description": "模板 ID。省略表示创建新模板；提供表示更新已有模板。" + }, + "title": { + "type": "string", + "description": "模板标题。" + }, + "type": { + "type": "string", + "enum": [ + "incident", + "maintenance" + ], + "description": "模板适用的事件类型：`incident` 故障，`maintenance` 计划维护。" + }, + "status": { + "type": "string", + "enum": [ + "investigating", + "identified", + "monitoring", + "resolved", + "scheduled", + "ongoing", + "completed" + ], + "description": "模板对应的事件状态。故障事件支持 `investigating`/`identified`/`monitoring`/`resolved`；维护事件支持 `scheduled`/`ongoing`/`completed`。" + }, + "description": { + "type": "string", + "description": "模板正文（Markdown）。" + } + } + }, + "StatusPageMessageTemplate": { + "type": "object", + "description": "消息模板：某一事件类型下、按状态划分的通知文案。在 `POST /status-page/template/upsert` 中，省略 `template_id` 表示创建，提供则表示更新；更新时仅应用非空字段。", + "properties": { + "template_id": { + "type": "string", + "description": "模板 ID。省略表示创建新模板；提供表示更新已有模板。" + }, + "title": { + "type": "string", + "description": "模板标题。" + }, + "type": { + "type": "string", + "enum": [ + "incident", + "maintenance" + ], + "description": "模板适用的事件类型：`incident` 故障，`maintenance` 计划维护。" + }, + "messages": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "按事件状态划分的通知文案（Markdown）。键为与模板 `type` 匹配的事件状态（如故障事件的 `investigating`、`resolved`），值为事件进入该状态时使用的文本。" + } + } + }, + "ListStatusPageTemplatesResponse": { + "type": "object", + "description": "事件模板列表。条目结构取决于请求的 `type`：`pre_defined` 为预定义事件模板，`message` 为消息模板。", + "required": [ + "items" + ], + "properties": { + "items": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/StatusPagePreDefinedTemplate" + }, + { + "$ref": "#/components/schemas/StatusPageMessageTemplate" + } + ] + }, + "description": "所请求类别的模板列表。" + } + } + }, + "FeedDetailAlertUpdate": { + "type": "object", + "title": "a_update", + "description": "`a_update` 的详情数据：更新后的严重程度/状态。", + "properties": { + "severity": { + "$ref": "#/components/schemas/FeedSeverity" + }, + "status": { + "$ref": "#/components/schemas/FeedSeverity" + } + } + }, + "FeedDetailAlertMuteBySilence": { + "type": "object", + "title": "a_m_silence", + "description": "`a_m_silence` 的详情数据：告警被静默规则收敛。", + "properties": { + "rule_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "收敛该告警的静默规则 ID。为空时不返回。" + }, + "rule_name": { + "type": "string", + "description": "静默规则名称，读取时解析填充。为空时不返回。" + } + } + }, + "FeedDetailAlertMuteByInhibit": { + "type": "object", + "title": "a_m_inhibit", + "description": "`a_m_inhibit` 的详情数据：告警因源告警被抑制规则收敛。", + "properties": { + "rule_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "收敛该告警的抑制规则 ID。为空时不返回。" + }, + "rule_name": { + "type": "string", + "description": "抑制规则名称，读取时解析填充。为空时不返回。" + }, + "source_alert_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "触发抑制的源告警 ID。为空时不返回。" + }, + "source_alert_title": { + "type": "string", + "description": "源告警标题，读取时解析填充。为空时不返回。" + } + } + }, + "FeedDetailAlertMuteByFlapping": { + "type": "object", + "title": "a_m_flapping", + "description": "`a_m_flapping` 的详情数据（历史）：告警被抖动检测收敛。", + "properties": { + "max_changes": { + "type": "integer", + "description": "触发抖动检测的状态变化次数阈值。为 0 时不返回。" + }, + "in_secs": { + "type": "integer", + "description": "统计状态变化的时间窗口（秒）。为 0 时不返回。" + }, + "mute_secs": { + "type": "integer", + "description": "静默时长（秒）。为 0 时不返回。" + } + } + }, + "FeedDetailAlertAck": { + "type": "object", + "title": "a_ack", + "description": "`a_ack` 的详情数据（历史），无字段。", + "properties": {} + }, + "FeedDetailAlertUnack": { + "type": "object", + "title": "a_unack", + "description": "`a_unack` 的详情数据（历史），无字段。", + "properties": {} + }, + "DSTencentCLSConfig": { + "type": "object", + "description": "腾讯云日志服务（CLS）凭证配置。", + "required": [ + "secret_id" + ], + "properties": { + "secret_id": { + "type": "string", + "description": "腾讯云 API SecretId，创建和更新时均必填。支持 `${env:VAR}` 引用（在 edge 侧解析）。" + }, + "secret_key": { + "type": "string", + "description": "腾讯云 API SecretKey。创建时必填；更新时省略则保留已存储的密钥。支持 `${env:VAR}` 引用。读取接口永不返回该值：响应中为空字符串，除非存储的值是 `${env:...}` 引用。" + } + } + }, + "SLSProject": { + "type": "object", + "description": "一个阿里云 SLS 项目。", + "required": [ + "projectName", + "description", + "status", + "owner", + "region", + "createTime", + "lastModifyTime" + ], + "properties": { + "projectName": { + "type": "string", + "description": "项目名称。" + }, + "description": { + "type": "string", + "description": "项目描述。" + }, + "status": { + "type": "string", + "description": "项目状态，例如 `Normal`。" + }, + "owner": { + "type": "string", + "description": "项目属主的阿里云账户 ID；SLS 未返回时为空。" + }, + "region": { + "type": "string", + "description": "地域 ID，例如 `cn-shanghai`。" + }, + "createTime": { + "type": "string", + "description": "创建时间，以字符串表示的 Unix 秒，例如 `\"1524539357\"`。" + }, + "lastModifyTime": { + "type": "string", + "description": "最后修改时间，以字符串表示的 Unix 秒。" + }, + "dataRedundancyType": { + "type": "string", + "enum": [ + "LRS", + "ZRS" + ], + "description": "数据冗余类型：`LRS` = 本地冗余存储，`ZRS` = 同城冗余存储。未设置时不返回。" + }, + "location": { + "type": "string", + "description": "存储位置，例如 `cn-beijing-b`。未设置时不返回。" + } + } + }, + "StringMapPatch": { + "type": "object", + "description": "map 字段的增量更新：`set` 中的键会被插入或覆盖，`delete` 中的键会被删除，其余键保持不变。", + "properties": { + "set": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "要插入或覆盖的键值对。" + }, + "delete": { + "type": "array", + "items": { + "type": "string" + }, + "description": "要删除的键。" + } + } + }, + "TargetInventoryServiceMapCapability": { + "type": "object", + "description": "目标主机的 ServiceMap 采集能力与实时状态。", + "required": [ + "enabled", + "status", + "snapshot_ready", + "authoritative", + "graph_available", + "node_count", + "edge_count" + ], + "properties": { + "enabled": { + "type": "boolean", + "description": "agent 是否启用了 ServiceMap 采集。" + }, + "status": { + "type": "string", + "enum": [ + "active", + "degraded", + "stale", + "initializing", + "disabled", + "unsupported", + "no_data" + ], + "description": "主机的 ServiceMap 采集状态。\n\n| 值 | 含义 |\n|---|---|\n| `active` | 采集正常：有新鲜快照且无降级。 |\n| `degraded` | 采集在进行但质量受损：健康上报晚于快照、快照被截断/降级，或采集报错。 |\n| `stale` | 有快照但已过期（超过 2× 上报间隔未更新）。 |\n| `initializing` | Agent 已上报采集能力，但首个快照尚未就绪。 |\n| `disabled` | 该主机的拓扑采集被禁用。 |\n| `unsupported` | Agent 或内核不支持该采集。 |\n| `no_data` | 未收到任何快照或健康数据。 |" + }, + "capability_status": { + "type": "string", + "description": "agent 上报的能力状态，例如 `running`、`disabled`、`starting`、`failed`、`unsupported`。agent 未上报时不返回。" + }, + "capture_mode": { + "type": "string", + "description": "采集模式，例如 `ebpf` 或 `polling`。未知时不返回。" + }, + "report_interval_ms": { + "type": "integer", + "format": "int64", + "description": "配置的上报间隔（毫秒）。未知时不返回。" + }, + "snapshot_ready": { + "type": "boolean", + "description": "agent 是否已产出至少一份完整快照。" + }, + "authoritative": { + "type": "boolean", + "description": "当前状态是否来自权威（authoritative）图快照。" + }, + "graph_available": { + "type": "boolean", + "description": "当前是否可以拉取到该主机的实时拓扑图。" + }, + "freshness_status": { + "type": "string", + "enum": [ + "fresh", + "stale", + "unknown" + ], + "description": "主机拓扑图的新鲜度分类。`fresh` = 最新快照在 2× 上报间隔内收到；`stale` = 超过该窗口未收到新快照；`unknown` = 尚未分类。未知时不返回。" + }, + "max_age_ms": { + "type": "integer", + "format": "int64", + "description": "快照被视为过期前可容忍的最大年龄（毫秒）。不适用时不返回。" + }, + "observed_at_ms": { + "type": "integer", + "format": "int64", + "description": "agent 最近一次观测到图生成的时间，Unix 毫秒时间戳。未知时不返回。" + }, + "received_at_ms": { + "type": "integer", + "format": "int64", + "description": "服务端最近一次收到快照的时间，Unix 毫秒时间戳。未知时不返回。" + }, + "node_count": { + "type": "integer", + "description": "该主机当前拓扑图中的节点数。" + }, + "edge_count": { + "type": "integer", + "description": "该主机当前拓扑图中的边数。" + }, + "reason_codes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "解释当前能力状态的机器可读原因码。为空时不返回。" + }, + "error_code": { + "type": "string", + "description": "实时状态读取失败时置为 `status_unavailable`，此时其余字段回退为清单侧的值。否则不返回。" + } + } + }, + "TargetInventoryServiceMapCoverage": { + "type": "object", + "description": "某一页目标的 ServiceMap 状态拉取覆盖情况。", + "required": [ + "requested", + "succeeded", + "failed", + "partial" + ], + "properties": { + "requested": { + "type": "integer", + "description": "本页携带 ServiceMap 数据的条目数。" + }, + "succeeded": { + "type": "integer", + "description": "实时 ServiceMap 状态读取成功的条目数。" + }, + "failed": { + "type": "integer", + "description": "实时 ServiceMap 状态读取失败的条目数（`servicemap.error_code` 已设置）。" + }, + "partial": { + "type": "boolean", + "description": "至少一个条目状态读取失败时为 true。" + } + } + }, + "RoleDeleteRequest": { + "type": "object", + "required": [ + "role_id" + ], + "description": "删除角色请求。", + "properties": { + "role_id": { + "type": "integer", + "format": "uint64", + "description": "要删除的角色 ID。可通过 `POST /role/list` 获取（内置角色：2=Admin，6=Responder，8=Viewer）。" + }, + "is_force": { + "type": "boolean", + "default": false, + "description": "为 false（默认）时，若仍有成员持有该角色，删除失败并返回 `ReferenceExist` 错误，`data.refs` 中列出持有成员；为 true 时先从所有持有成员解除该角色，再删除角色。" + } + } } } } diff --git a/api-reference/platform.openapi.en.json b/api-reference/platform.openapi.en.json index e40a1153..c6a8e823 100644 --- a/api-reference/platform.openapi.en.json +++ b/api-reference/platform.openapi.en.json @@ -144,7 +144,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- Up to 100 team 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 deduplicated; IDs that match no team are ignored.", "href": "/en/api-reference/platform/teams/team-read-infos", "metadata": { "sidebarTitle": "Batch get teams" @@ -235,7 +235,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 held this role lose its permissions immediately.\n- Only custom roles can be disabled.\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 | **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" @@ -303,12 +303,12 @@ "post": { "operationId": "role-write-delete", "summary": "Delete a role", - "description": "Permanently delete a custom role and revoke it from all members.", + "description": "Delete a custom role. While members still hold the role, the call fails with `ReferenceExist` unless `is_force` is true.", "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 cannot be deleted.\n- All members who held this role lose its permissions immediately.\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 | **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" @@ -362,7 +362,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RoleIDRequest" + "$ref": "#/components/schemas/RoleDeleteRequest" }, "example": { "role_id": 150 @@ -475,12 +475,12 @@ "post": { "operationId": "memberInfo", "summary": "Get current member info", - "description": "Return the current session member's full profile.", + "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.", "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 |", + "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" @@ -609,7 +609,8 @@ "class": "On-call", "scope": "on-call", "status": "enabled", - "is_granted": true + "is_granted": true, + "source": "system" } ] } @@ -933,6 +934,10 @@ { "member_id": 5068740052131, "member_name": "Charlie" + }, + { + "member_id": 5068740052132, + "member_name": "Dave" } ] } @@ -994,7 +999,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- Only custom roles can be enabled/disabled. Built-in roles always remain enabled.\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 | **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" @@ -1227,7 +1232,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- Default page size is 20 rows; maximum is 99.", + "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" @@ -1271,7 +1276,10 @@ "body": "{\"template_name\":\"Prod default\"}", "params": [], "is_dangerous": false, - "is_write": true + "is_write": true, + "principal_kind": "member", + "credential_type": "", + "credential_id": 0 } ] } @@ -1322,7 +1330,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- Up to 100 member IDs per request.\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 | **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" @@ -1394,7 +1402,7 @@ "post": { "operationId": "memberUpdateRole", "summary": "Update member roles", - "description": "Replace all role assignments for a member at once.", + "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).", "tags": [ "Platform/Members" ], @@ -1549,12 +1557,12 @@ "post": { "operationId": "role-read-list-permission-factor", "summary": "List permission factors", - "description": "Return all permission factors (API, button, menu, URL, visit) optionally filtered by type.", + "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.", "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- 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 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" @@ -1585,7 +1593,8 @@ "data": [ { "factor_name": "template:read:info", - "factor_type": "api" + "factor_type": "api", + "source": "system" } ] } @@ -1790,7 +1799,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 invite members who don't yet have accounts.\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 | **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" @@ -1866,7 +1875,7 @@ "post": { "operationId": "memberGrantRole", "summary": "Grant role to member", - "description": "Add a role assignment to a 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.", "tags": [ "Platform/Members" ], @@ -1939,7 +1948,7 @@ "post": { "operationId": "memberRevokeRole", "summary": "Revoke role from member", - "description": "Remove a role assignment from a 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.", "tags": [ "Platform/Members" ], @@ -2238,7 +2247,7 @@ ] }, "example": { - "error_code": 0, + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "account_id": 1001, "account_name": "acme", @@ -2443,7 +2452,10 @@ "body", "params", "is_dangerous", - "is_write" + "is_write", + "principal_kind", + "credential_type", + "credential_id" ], "properties": { "created_at": { @@ -2459,11 +2471,11 @@ "member_id": { "type": "integer", "format": "uint64", - "description": "ID of the member who performed the action." + "description": "ID of the member who performed the action. 0 when the action was performed by the account principal itself." }, "member_name": { "type": "string", - "description": "Display name of the member." + "description": "Display name of the member. Empty when `member_id` is 0." }, "request_id": { "type": "string", @@ -2479,11 +2491,11 @@ }, "operation_name": { "type": "string", - "description": "Human-readable operation label in the account's locale." + "description": "Human-readable Chinese label of the operation (e.g. `创建模板`)." }, "body": { "type": "string", - "description": "JSON-encoded request body (may be truncated at 10 KB)." + "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", @@ -2509,6 +2521,23 @@ "is_write": { "type": "boolean", "description": "True for mutating operations; false for read-only ones." + }, + "principal_kind": { + "type": "string", + "enum": [ + "member", + "service" + ], + "description": "Kind of the caller. `member` — an interactive member session; `service` — an app key credential." + }, + "credential_type": { + "type": "string", + "description": "Credential type used for the call. `app_key` when authenticated with an app key; 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." } } }, @@ -2564,18 +2593,20 @@ "start_time": { "type": "integer", "format": "int64", - "description": "Start of the search window, Unix epoch seconds.", - "example": 1712620800 + "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. Must be after `start_time`. Maximum span 90 days.", - "example": 1712707200 + "description": "End of the search window, Unix epoch seconds. Inclusive. Must be after `start_time`; maximum span 90 days.", + "example": 1712707200, + "minimum": 1 }, "limit": { "type": "integer", - "description": "Page size. Minimum 0, maximum 99.", + "description": "Page size, 0–99. Omit or set to 0 for no page-size cap — all matching rows in the window are returned.", "minimum": 0, "maximum": 99, "example": 20 @@ -2639,7 +2670,7 @@ "items": { "$ref": "#/components/schemas/AuditLog" }, - "description": "Audit log entries for this page." + "description": "Audit log entries for this page, newest first. Omitted when the page is empty." } } }, @@ -2661,21 +2692,6 @@ "message" ] }, - "EmptyObject": { - "type": "object", - "description": "An empty object. Returned as the `data` payload by operations whose success signal is simply the absence of an error.", - "additionalProperties": false - }, - "EmptyRequest": { - "type": "object", - "description": "No parameters required.", - "additionalProperties": false - }, - "EmptyResponse": { - "type": "object", - "description": "Empty response body. The server returns `data: null` on success.", - "properties": {} - }, "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. |", @@ -2745,21 +2761,21 @@ }, "InviteMemberItem": { "type": "object", - "description": "Member to invite", + "description": "A member to invite. Identify the invitee by `email` alone, or by `member_name` + `phone` together.", "properties": { "member_name": { "type": "string", "minLength": 2, "maxLength": 39, - "description": "Display name" + "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" + "description": "Email address. Required when `phone` is not provided." }, "phone": { "type": "string", - "description": "Phone number" + "description": "Phone number. Required when `email` is not provided." }, "country_code": { "type": "string", @@ -2768,7 +2784,8 @@ "role_ids": { "type": "array", "items": { - "type": "integer" + "type": "integer", + "format": "uint64" }, "description": "Role IDs to assign" }, @@ -2824,7 +2841,34 @@ "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", "default": false } - } + }, + "anyOf": [ + { + "required": [ + "member_id" + ] + }, + { + "required": [ + "member_name" + ] + }, + { + "required": [ + "email" + ] + }, + { + "required": [ + "phone" + ] + }, + { + "required": [ + "ref_id" + ] + } + ] }, "MemberEmptyObject": { "type": "object", @@ -2867,11 +2911,11 @@ }, "account_locale": { "type": "string", - "description": "Account-level locale preference (e.g. zh-CN or en-US)" + "description": "Account-level locale preference (e.g. zh-CN or en-US). Omitted when the account has none set." }, "account_time_zone": { "type": "string", - "description": "Account-level time zone (e.g. Asia/Shanghai)" + "description": "Account-level time zone (e.g. Asia/Shanghai). Omitted when the account has none set." }, "domain": { "type": "string", @@ -2912,26 +2956,48 @@ }, "locale": { "type": "string", - "description": "Locale preference" + "description": "Member's locale preference. Omitted when the member has none set." }, "time_zone": { "type": "string", - "description": "Time zone" + "description": "Member's IANA time zone. Omitted when the member has none set." }, "is_external": { "type": "boolean", "description": "Whether provisioned via SSO" }, - "status": { + "created_at": { + "type": "integer", + "format": "int64", + "description": "Member creation time, Unix timestamp in seconds." + }, + "mp_plat": { "type": "string", - "enum": [ - "enabled", - "pending", - "deleted" - ], - "description": "Member status. `enabled` — active member; `pending` — invited but not yet accepted; `deleted` — removed from the organization." + "description": "Cloud marketplace platform the account was provisioned from. Omitted when the account did not come from a marketplace." + }, + "mp_account_id": { + "type": "string", + "description": "Account identifier on the marketplace platform. Omitted together with `mp_plat`." } - } + }, + "required": [ + "account_id", + "account_name", + "account_avatar", + "account_email", + "account_role_ids", + "domain", + "member_id", + "member_name", + "phone", + "phone_verified", + "email", + "email_verified", + "country_code", + "avatar", + "is_external", + "created_at" + ] }, "MemberInviteRequest": { "type": "object", @@ -2945,7 +3011,8 @@ "items": { "$ref": "#/components/schemas/InviteMemberItem" }, - "description": "Members to invite (max 20)" + "description": "Members to invite in one call (at least 1). Each entry needs either an `email`, or `member_name` + `phone` together.", + "minItems": 1 }, "from": { "type": "string", @@ -3015,11 +3082,11 @@ }, "locale": { "type": "string", - "description": "Locale" + "description": "Member's locale preference (e.g. `zh-CN`). Omitted when empty — the list endpoint does not populate it." }, "time_zone": { "type": "string", - "description": "Time zone" + "description": "Member's IANA time zone (e.g. `Asia/Shanghai`). Omitted when empty — the list endpoint does not populate it." }, "phone_verified": { "type": "boolean", @@ -3132,7 +3199,13 @@ }, "description": "Member items" } - } + }, + "required": [ + "p", + "limit", + "total", + "items" + ] }, "MemberResetInfoRequest": { "type": "object", @@ -3208,34 +3281,55 @@ "description": "Member profile fields to write. Omitted fields remain unchanged.", "properties": { "member_name": { - "type": "string", + "type": [ + "string", + "null" + ], "minLength": 2, "maxLength": 39, "description": "New display name." }, "password": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "New login password in the encrypted format accepted by the backend." }, "phone": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "New phone number. Include country_code when the number is not in E.164 format." }, "country_code": { - "type": "string", + "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." }, "email": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "New email address." }, "avatar": { - "type": "string", + "type": [ + "string", + "null" + ], "maxLength": 499, "description": "New avatar URL." }, "locale": { - "type": "string", + "type": [ + "string", + "null" + ], "enum": [ "zh-CN", "en-US" @@ -3243,11 +3337,17 @@ "description": "New locale preference. One of: `zh-CN` (Simplified Chinese), `en-US` (English); other values are rejected with a 400." }, "time_zone": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "New IANA time zone name, such as Asia/Shanghai." }, "ref_id": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "New external reference ID." } } @@ -3302,8 +3402,7 @@ "type": "object", "description": "Update member roles request", "required": [ - "member_id", - "role_ids" + "member_id" ], "properties": { "member_id": { @@ -3358,6 +3457,18 @@ "url" ], "description": "Factor type. `api`: backend API factor — `factor_name` is the API name (e.g. `skill:write:upload`), enforced at the gateway; `button`: UI action factor, used by the role-config page to render action toggles; `visit`: page-visit factor (custom menu pages use this type); `menu`: menu-visibility factor (legacy, no current seed data); `url`: page route-path factor (legacy, no current seed data)." + }, + "source": { + "type": "string", + "enum": [ + "system", + "account" + ], + "description": "Origin of the factor. `system` — seeded built-in factor; `account` — dynamic factor created for this account (e.g. custom menus)." + }, + "source_ref": { + "type": "string", + "description": "Primary key of the source object (e.g. the custom menu ID) for account-scoped factors. Omitted when empty." } } }, @@ -3398,7 +3509,9 @@ "description", "class", "scope", - "status" + "status", + "source", + "is_granted" ], "properties": { "id": { @@ -3428,19 +3541,45 @@ }, "scope": { "type": "string", - "description": "Permission scope (e.g., 'on-call', 'organization')." + "description": "Functional scope the permission applies to.\n\n| value | meaning |\n| --- | --- |\n| `account` | Account settings and API keys |\n| `organization` | Members, teams, roles, audit |\n| `on-call` | On-call incident management |\n| `monit` | Monitoring |\n| `rum` | Real user monitoring |\n| `ai-sre` | AI SRE features |\n| `custom_menu` | Account-defined custom menu pages (on-premises only) |", + "enum": [ + "account", + "organization", + "on-call", + "monit", + "rum", + "ai-sre", + "custom_menu" + ] }, "status": { "type": "string", "enum": [ "enabled", - "disabled" + "deleted" ], - "description": "Permission status." + "description": "Permission status. `enabled` — active; `deleted` — removed (deleted permissions are filtered out and never returned)." }, "is_granted": { "type": "boolean", - "description": "Present when with_all is true. Indicates whether this permission is granted to the requested roles." + "description": "Whether this permission is granted to the roles given in `role_ids`. Always present in this endpoint's response; `false` entries only appear when `with_all` is true." + }, + "account_id": { + "type": "integer", + "format": "uint64", + "description": "Owning account ID. Omitted when 0, i.e. for system-level permissions." + }, + "source": { + "type": "string", + "enum": [ + "system", + "account" + ], + "description": "Origin of the permission. `system` — seeded built-in permission; `account` — dynamic permission created for this account (e.g. custom menus)." + }, + "source_ref": { + "type": "string", + "description": "Primary key of the source object (e.g. the custom menu ID) for account-scoped permissions. Omitted when empty." } } }, @@ -3472,7 +3611,10 @@ }, "description": "Person profiles" } - } + }, + "required": [ + "items" + ] }, "PersonItem": { "type": "object", @@ -3496,35 +3638,31 @@ }, "person_name": { "type": "string", - "description": "Display name" + "description": "Display name. Omitted when empty." }, "avatar": { "type": "string", - "description": "Avatar URL" + "description": "Avatar URL. Omitted when empty." }, "locale": { "type": "string", - "description": "Locale" + "description": "Locale. Omitted when empty." }, "time_zone": { "type": "string", - "description": "Time zone" + "description": "Time zone. Omitted when empty." }, "email": { "type": "string", - "description": "Email address" - }, - "country_code": { - "type": "string", - "description": "ISO 3166-1 alpha-2 region code of the contact phone (e.g. \"CN\", \"US\", \"HK\")." + "description": "Email address. Omitted when empty." }, "phone": { "type": "string", - "description": "Phone number" + "description": "Phone number. Omitted when empty — this endpoint never populates it." }, "phone_verified": { "type": "boolean", - "description": "Phone verified" + "description": "Whether the phone is verified. Always false in this endpoint's response." }, "email_verified": { "type": "boolean", @@ -3532,7 +3670,11 @@ }, "as": { "type": "string", - "description": "Login role (account/member)" + "description": "Principal kind: `account` — the account owner principal; `member` — an organization member.", + "enum": [ + "account", + "member" + ] }, "status": { "type": "string", @@ -3541,7 +3683,7 @@ "pending", "deleted" ], - "description": "Person status. `enabled` — active; `pending` — invited but not yet accepted; `deleted` — removed." + "description": "Person status. `enabled` — active; `pending` — invited but not yet accepted; `deleted` — removed. Omitted when empty." } } }, @@ -3564,7 +3706,7 @@ "type": "integer", "format": "uint64" }, - "description": "Member IDs to grant/revoke the role. Max 100." + "description": "Member IDs to grant/revoke the role." }, "role_id": { "type": "integer", @@ -3673,6 +3815,10 @@ "asc": { "type": "boolean", "description": "Ascending sort order. Default: false (descending)." + }, + "no_global": { + "type": "boolean", + "description": "When true, exclude the built-in global roles (Admin, Responder, Viewer) and return only custom roles. Default: false." } } }, @@ -3822,7 +3968,12 @@ }, "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" + ] }, "TeamDeleteRequest": { "type": "object", @@ -3841,7 +3992,24 @@ "type": "string", "description": "External reference ID. Only used when neither `team_id` nor `team_name` is provided." } - } + }, + "anyOf": [ + { + "required": [ + "team_id" + ] + }, + { + "required": [ + "team_name" + ] + }, + { + "required": [ + "ref_id" + ] + } + ] }, "TeamInfoRequest": { "type": "object", @@ -3860,7 +4028,24 @@ "type": "string", "description": "External reference ID. When provided, takes precedence over `team_name` and `team_id`." } - } + }, + "anyOf": [ + { + "required": [ + "team_id" + ] + }, + { + "required": [ + "team_name" + ] + }, + { + "required": [ + "ref_id" + ] + } + ] }, "TeamInfosRequest": { "type": "object", @@ -3875,7 +4060,7 @@ "type": "integer", "format": "uint64" }, - "description": "List of team IDs to look up. Max 100." + "description": "List of team IDs to look up." } } }, @@ -3936,9 +4121,9 @@ "type": "string", "enum": [ "enabled", - "disabled" + "deleted" ], - "description": "Team 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)." }, "updated_by_name": { "type": "string", @@ -3956,7 +4141,7 @@ }, "creator_name": { "type": "string", - "description": "Display name of the creator." + "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", @@ -4019,7 +4204,7 @@ }, "query": { "type": "string", - "description": "Substring match on team name." + "description": "Substring match on team name or description." } } }, @@ -4098,7 +4283,7 @@ "items": { "type": "string" }, - "description": "Add existing members to the team by phone number. Numbers that don't match an existing member are silently ignored; non-E.164 numbers are parsed with `countryCode`." + "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." }, "countryCode": { "type": "string", @@ -4110,7 +4295,7 @@ }, "reset_if_name_exist": { "type": "boolean", - "description": "If true and a team with the same name already exists, reset its membership to the provided person_ids." + "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." } } }, @@ -4138,7 +4323,8 @@ "properties": { "account_id": { "type": "integer", - "description": "Account identifier." + "description": "Account identifier.", + "format": "uint64" }, "account_name": { "type": "string", @@ -4186,7 +4372,7 @@ }, "restrictions": { "type": "object", - "description": "Account access restrictions (present only when configured).", + "description": "Account access restrictions. Omitted when none are configured.", "properties": { "ips": { "type": "array", @@ -4210,11 +4396,43 @@ }, "mp_plat": { "type": "string", - "description": "Cloud marketplace platform the account was provisioned from (present only for marketplace accounts)." + "description": "Cloud marketplace platform the account was provisioned from. Omitted when the account did not come from a marketplace." }, "mp_account_id": { "type": "string", - "description": "Account identifier on the cloud marketplace platform (present only for marketplace accounts)." + "description": "Account identifier on the marketplace platform. Omitted together with `mp_plat`." + } + }, + "required": [ + "account_id", + "account_name", + "domain", + "extra_domains", + "phone", + "country_code", + "email", + "avatar", + "locale", + "time_zone", + "created_at" + ] + }, + "RoleDeleteRequest": { + "type": "object", + "required": [ + "role_id" + ], + "description": "Request to delete a role.", + "properties": { + "role_id": { + "type": "integer", + "format": "uint64", + "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 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." } } } diff --git a/api-reference/platform.openapi.zh.json b/api-reference/platform.openapi.zh.json index bc2a73fb..b0f06275 100644 --- a/api-reference/platform.openapi.zh.json +++ b/api-reference/platform.openapi.zh.json @@ -84,7 +84,7 @@ { "account_id": 10023, "team_id": 1001, - "team_name": "后端 SRE", + "team_name": "Backend SRE", "status": "enabled", "creator_id": 80011, "created_at": 1710000000, @@ -144,7 +144,7 @@ "平台/团队管理" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 每次最多传入 100 个团队 ID。", + "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": "批量查看团队信息" @@ -176,7 +176,7 @@ "items": [ { "team_id": 1001, - "team_name": "后端 SRE", + "team_name": "Backend SRE", "person_ids": [ 80011, 80012 @@ -184,7 +184,7 @@ }, { "team_id": 1002, - "team_name": "前端", + "team_name": "Frontend", "person_ids": [ 80013 ] @@ -235,7 +235,7 @@ "平台/角色与权限" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 持有该角色的成员将立即失去其权限。\n- 只有自定义角色可被禁用。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", + "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": "禁用角色" @@ -303,12 +303,12 @@ "post": { "operationId": "role-write-delete", "summary": "删除角色", - "description": "永久删除自定义角色并从所有成员处撤销授权。", + "description": "删除一个自定义角色。当仍有成员持有该角色时，除非 `is_force` 为 true，否则调用失败并返回 `ReferenceExist`。", "tags": [ "平台/角色与权限" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 内置角色无法删除。\n- 持有该角色的所有成员将立即失去其权限。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", + "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": "删除角色" @@ -362,7 +362,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RoleIDRequest" + "$ref": "#/components/schemas/RoleDeleteRequest" }, "example": { "role_id": 150 @@ -475,12 +475,12 @@ "post": { "operationId": "memberInfo", "summary": "获取当前成员信息", - "description": "返回当前会话成员的完整资料。", + "description": "返回当前凭据所属成员的完整资料。需要成员级凭据——以账户主体身份（如账户级 App Key）调用会被拒绝并返回 400。", "tags": [ "平台/成员管理" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 但凭据必须属于某个成员；以账户主体身份（如账户级 App Key）调用会被拒绝并返回 400 |", "href": "/zh/api-reference/platform/members/member-info", "metadata": { "sidebarTitle": "获取当前成员信息" @@ -603,13 +603,14 @@ "items": [ { "id": 501, - "permission_name": "模板查看", + "permission_name": "Templates Read", "permission_type": "read", - "description": "查看通知模板", + "description": "View notification templates", "class": "On-call", "scope": "on-call", "status": "enabled", - "is_granted": true + "is_granted": true, + "source": "system" } ] } @@ -688,8 +689,8 @@ "data": { "account_id": 10023, "team_id": 1001, - "team_name": "后端 SRE", - "description": "后端可靠性工程团队", + "team_name": "Backend SRE", + "description": "Backend reliability engineering team", "status": "enabled", "updated_by_name": "alice", "updated_by": 80011, @@ -847,8 +848,8 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "role_id": 2, - "role_name": "账户管理员", - "description": "拥有所有权限的账户管理员。", + "role_name": "Account Admin", + "description": "Account admin with all permissions.", "status": "enabled", "permission_ids": [ 101, @@ -933,6 +934,10 @@ { "member_id": 5068740052131, "member_name": "Charlie" + }, + { + "member_id": 5068740052132, + "member_name": "Dave" } ] } @@ -994,7 +999,7 @@ "平台/角色与权限" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 只有自定义角色可以被启用/禁用，内置角色始终保持启用状态。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", + "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": "启用角色" @@ -1100,7 +1105,7 @@ "items": [ { "role_id": 2, - "role_name": "账户管理员", + "role_name": "Account Admin", "description": "", "status": "enabled", "permission_ids": [], @@ -1227,7 +1232,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- 默认每页 20 条，最大 99 条。", + "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": "检索审计日志" @@ -1268,10 +1273,13 @@ "ip": "203.0.113.42", "operation": "template:write:create", "operation_name": "创建模板", - "body": "{\"template_name\":\"生产默认模板\"}", + "body": "{\"template_name\":\"Prod default\"}", "params": [], "is_dangerous": false, - "is_write": true + "is_write": true, + "principal_kind": "member", + "credential_type": "", + "credential_id": 0 } ] } @@ -1322,7 +1330,7 @@ "平台/角色与权限" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 每次最多传入 100 个成员 ID。\n- 已持有该角色的成员会被静默跳过。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", + "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": "授予成员账户权限" @@ -1394,7 +1402,7 @@ "post": { "operationId": "memberUpdateRole", "summary": "更新成员角色", - "description": "一次性替换成员的全部角色授权。", + "description": "一次性整体替换成员的角色。不存在的角色 ID 会被静默丢弃；`role_ids` 为空时重置为内置 Viewer 角色（ID 8）。", "tags": [ "平台/成员管理" ], @@ -1503,7 +1511,7 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "role_id": 150, - "role_name": "值班管理员" + "role_name": "On-call Manager" } } } @@ -1533,8 +1541,8 @@ "$ref": "#/components/schemas/RoleUpsertRequest" }, "example": { - "role_name": "值班管理员", - "description": "管理值班排班和故障处理。", + "role_name": "On-call Manager", + "description": "Manage on-call rotations and incidents.", "permission_ids": [ 501, 502 @@ -1549,12 +1557,12 @@ "post": { "operationId": "role-read-list-permission-factor", "summary": "查看权限因子集合", - "description": "返回所有权限因子（API、按钮、菜单、URL、访问），可按类型过滤。", + "description": "返回当前成员拥有的权限因子（API、按钮、菜单、URL、页面访问），可按类型过滤。需要成员级凭据——以账户主体身份（如账户级 App Key）调用会被拒绝并返回 400，因为账户主体天然拥有全部权限。", "tags": [ "平台/角色与权限" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 权限因子是每个权限的细粒度控制项。\n- `factor_types` 可选值：`api`、`button`、`visit`、`menu`、`url`。", + "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": "查看权限因子集合" @@ -1585,7 +1593,8 @@ "data": [ { "factor_name": "template:read:info", - "factor_type": "api" + "factor_type": "api", + "source": "system" } ] } @@ -1790,7 +1799,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| 速率限制 | 每个账户 **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": "变更团队信息" @@ -1820,7 +1829,7 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "team_id": 1001, - "team_name": "后端 SRE" + "team_name": "Backend SRE" } } } @@ -1850,8 +1859,8 @@ "$ref": "#/components/schemas/TeamUpsertRequest" }, "example": { - "team_name": "后端 SRE", - "description": "后端可靠性工程团队", + "team_name": "Backend SRE", + "description": "Backend reliability engineering team", "person_ids": [ 80011, 80012 @@ -1866,7 +1875,7 @@ "post": { "operationId": "memberGrantRole", "summary": "授予成员角色", - "description": "为成员添加角色授权。", + "description": "为成员追加角色授权。不存在的角色 ID 会被静默忽略；若全部无法解析，则调用成功但不产生任何变更。", "tags": [ "平台/成员管理" ], @@ -1939,7 +1948,7 @@ "post": { "operationId": "memberRevokeRole", "summary": "解除成员角色", - "description": "移除成员的角色授权。", + "description": "解除成员的角色授权。不存在的角色 ID 会被静默忽略；若全部无法解析，则调用成功但不产生任何变更。", "tags": [ "平台/成员管理" ], @@ -2238,7 +2247,7 @@ ] }, "example": { - "error_code": 0, + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "account_id": 1001, "account_name": "acme", @@ -2443,7 +2452,10 @@ "body", "params", "is_dangerous", - "is_write" + "is_write", + "principal_kind", + "credential_type", + "credential_id" ], "properties": { "created_at": { @@ -2459,11 +2471,11 @@ "member_id": { "type": "integer", "format": "uint64", - "description": "操作人的成员 ID。" + "description": "执行操作的成员 ID。由账户主体（owner）亲自执行时为 0。" }, "member_name": { "type": "string", - "description": "操作人的显示名称。" + "description": "成员显示名称。`member_id` 为 0 时为空字符串。" }, "request_id": { "type": "string", @@ -2479,11 +2491,11 @@ }, "operation_name": { "type": "string", - "description": "按账户语种显示的人类可读操作标签。" + "description": "操作的可读中文名称（如 `创建模板`）。" }, "body": { "type": "string", - "description": "JSON 编码的请求体（可能截断至 10 KB）。" + "description": "JSON 编码的请求体。包含敏感字段时整体改为 base64url 编码存储；超过 10 KB 时以截断占位说明替代。" }, "params": { "type": "array", @@ -2509,6 +2521,23 @@ "is_write": { "type": "boolean", "description": "是否为写操作；false 表示只读操作。" + }, + "principal_kind": { + "type": "string", + "enum": [ + "member", + "service" + ], + "description": "调用方类型。`member` —— 成员会话；`service` —— App Key 凭据。" + }, + "credential_type": { + "type": "string", + "description": "调用使用的凭据类型。使用 App Key 调用时为 `app_key`；成员会话为空字符串。" + }, + "credential_id": { + "type": "integer", + "format": "uint64", + "description": "凭据 ID（App Key 的 ID）；`credential_type` 非 `app_key` 时为 0。" } } }, @@ -2564,18 +2593,20 @@ "start_time": { "type": "integer", "format": "int64", - "description": "检索窗口开始时间，Unix 时间戳（秒）。", - "example": 1712620800 + "description": "检索窗口起点，Unix 秒级时间戳（不含该秒本身）。", + "example": 1712620800, + "minimum": 1 }, "end_time": { "type": "integer", "format": "int64", - "description": "检索窗口结束时间，Unix 时间戳（秒）。必须晚于 `start_time`，最大跨度 90 天。", - "example": 1712707200 + "description": "检索窗口终点，Unix 秒级时间戳（含该秒）。必须大于 `start_time`，最大跨度 90 天。", + "example": 1712707200, + "minimum": 1 }, "limit": { "type": "integer", - "description": "每页条数。最小 0，最大 99。", + "description": "分页大小，0–99。省略或传 0 表示不分页——返回时间窗内全部匹配记录。", "minimum": 0, "maximum": 99, "example": 20 @@ -2639,7 +2670,7 @@ "items": { "$ref": "#/components/schemas/AuditLog" }, - "description": "当前页的审计日志条目。" + "description": "本页的审计日志，按时间倒序。本页为空时不返回。" } } }, @@ -2661,21 +2692,6 @@ "message" ] }, - "EmptyObject": { - "type": "object", - "description": "空对象。当操作的成功信号就是不报错时，作为 `data` 返回。", - "additionalProperties": false - }, - "EmptyRequest": { - "type": "object", - "description": "无参数。", - "additionalProperties": false - }, - "EmptyResponse": { - "type": "object", - "description": "空响应体。成功时服务端返回 `data: null`。", - "properties": {} - }, "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 | 后端依赖不可用，请稍后重试。 |", @@ -2745,21 +2761,21 @@ }, "InviteMemberItem": { "type": "object", - "description": "待邀请成员", + "description": "待邀请的成员。只需提供 `email`，或同时提供 `member_name` 与 `phone`。", "properties": { "member_name": { "type": "string", "minLength": 2, "maxLength": 39, - "description": "显示名称" + "description": "显示名称，2–39 个字符。未提供 `email` 时必填；省略时取邮箱前缀作为名称。" }, "email": { "type": "string", - "description": "邮箱地址" + "description": "邮箱地址。未提供 `phone` 时必填。" }, "phone": { "type": "string", - "description": "手机号" + "description": "手机号。未提供 `email` 时必填。" }, "country_code": { "type": "string", @@ -2768,7 +2784,8 @@ "role_ids": { "type": "array", "items": { - "type": "integer" + "type": "integer", + "format": "uint64" }, "description": "授予的角色 ID 列表" }, @@ -2824,7 +2841,34 @@ "description": "是否强制删除。默认 false，会检查成员是否被分派策略、值班表等资源引用；设为 true 则跳过引用检查直接删除", "default": false } - } + }, + "anyOf": [ + { + "required": [ + "member_id" + ] + }, + { + "required": [ + "member_name" + ] + }, + { + "required": [ + "email" + ] + }, + { + "required": [ + "phone" + ] + }, + { + "required": [ + "ref_id" + ] + } + ] }, "MemberEmptyObject": { "type": "object", @@ -2867,11 +2911,11 @@ }, "account_locale": { "type": "string", - "description": "账户级语言偏好（如 zh-CN 或 en-US）" + "description": "账户级语言偏好（如 zh-CN、en-US）。账户未设置时不返回。" }, "account_time_zone": { "type": "string", - "description": "账户级时区（如 Asia/Shanghai）" + "description": "账户级时区（如 Asia/Shanghai）。账户未设置时不返回。" }, "domain": { "type": "string", @@ -2912,26 +2956,48 @@ }, "locale": { "type": "string", - "description": "语言偏好" + "description": "成员语言偏好。成员未设置时不返回。" }, "time_zone": { "type": "string", - "description": "时区" + "description": "成员的 IANA 时区。成员未设置时不返回。" }, "is_external": { "type": "boolean", "description": "是否通过 SSO 创建" }, - "status": { + "created_at": { + "type": "integer", + "format": "int64", + "description": "成员创建时间，Unix 秒级时间戳。" + }, + "mp_plat": { "type": "string", - "enum": [ - "enabled", - "pending", - "deleted" - ], - "description": "成员状态。`enabled` — 已激活成员；`pending` — 已邀请但尚未接受；`deleted` — 已从组织移除。" + "description": "账户来源的云市场平台。账户非来自云市场时不返回。" + }, + "mp_account_id": { + "type": "string", + "description": "账户在云市场平台上的标识。与 `mp_plat` 一起省略。" } - } + }, + "required": [ + "account_id", + "account_name", + "account_avatar", + "account_email", + "account_role_ids", + "domain", + "member_id", + "member_name", + "phone", + "phone_verified", + "email", + "email_verified", + "country_code", + "avatar", + "is_external", + "created_at" + ] }, "MemberInviteRequest": { "type": "object", @@ -2945,7 +3011,8 @@ "items": { "$ref": "#/components/schemas/InviteMemberItem" }, - "description": "待邀请成员列表（最多 20 个）" + "description": "单次邀请的成员列表，至少 1 个。每个成员要么提供 `email`，要么同时提供 `member_name` 和 `phone`。", + "minItems": 1 }, "from": { "type": "string", @@ -3015,11 +3082,11 @@ }, "locale": { "type": "string", - "description": "语言" + "description": "成员语言偏好（如 `zh-CN`）。为空时不返回——列表接口不填充该字段。" }, "time_zone": { "type": "string", - "description": "时区" + "description": "成员的 IANA 时区（如 `Asia/Shanghai`）。为空时不返回——列表接口不填充该字段。" }, "phone_verified": { "type": "boolean", @@ -3132,7 +3199,13 @@ }, "description": "成员列表" } - } + }, + "required": [ + "p", + "limit", + "total", + "items" + ] }, "MemberResetInfoRequest": { "type": "object", @@ -3208,34 +3281,55 @@ "description": "要写入的成员资料字段。未传的字段保持不变。", "properties": { "member_name": { - "type": "string", + "type": [ + "string", + "null" + ], "minLength": 2, "maxLength": 39, "description": "新的显示名称。" }, "password": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "按前端加密格式传入的新登录密码。" }, "phone": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "新的手机号；如不是 E.164 格式，可同时传 country_code。" }, "country_code": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "ISO 3166-1 alpha-2 地区代码（如 \"CN\"、\"US\"）。可独立更新（无需同时传 `phone`），并兼作解析 `phone` 的地区提示；非法值返回 400，显式传空字符串也会被拒绝。" }, "email": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "新的邮箱地址。" }, "avatar": { - "type": "string", + "type": [ + "string", + "null" + ], "maxLength": 499, "description": "新的头像 URL。" }, "locale": { - "type": "string", + "type": [ + "string", + "null" + ], "enum": [ "zh-CN", "en-US" @@ -3243,11 +3337,17 @@ "description": "新的语言偏好。可选值：`zh-CN`（简体中文）、`en-US`（英文）；非法值返回 400。" }, "time_zone": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "新的 IANA 时区名称，例如 Asia/Shanghai。" }, "ref_id": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "新的外部引用 ID。" } } @@ -3302,8 +3402,7 @@ "type": "object", "description": "更新成员角色请求", "required": [ - "member_id", - "role_ids" + "member_id" ], "properties": { "member_id": { @@ -3358,6 +3457,18 @@ "url" ], "description": "因子类型。`api`：后端 API 因子，`factor_name` 为接口名（如 `skill:write:upload`），由网关强制校验；`button`：前端操作因子，用于角色配置页渲染操作开关；`visit`：页面访问因子（自定义菜单页面即此类型）；`menu`：菜单可见性因子（历史类型，当前无种子数据）；`url`：页面路由地址因子（历史类型，当前无种子数据）。" + }, + "source": { + "type": "string", + "enum": [ + "system", + "account" + ], + "description": "因子来源。`system` —— 内置种子因子；`account` —— 账户级动态因子（如自定义菜单）。" + }, + "source_ref": { + "type": "string", + "description": "账户级因子来源对象的主键（如自定义菜单 ID）。为空时不返回。" } } }, @@ -3398,7 +3509,9 @@ "description", "class", "scope", - "status" + "status", + "source", + "is_granted" ], "properties": { "id": { @@ -3428,19 +3541,45 @@ }, "scope": { "type": "string", - "description": "权限范围（如 'on-call'、'organization'）。" + "description": "权限生效的功能范围。\n\n| 值 | 含义 |\n| --- | --- |\n| `account` | 账户设置与 API 密钥 |\n| `organization` | 成员、团队、角色、审计 |\n| `on-call` | 值班与故障管理 |\n| `monit` | 监控 |\n| `rum` | 真实用户监控 |\n| `ai-sre` | AI SRE 功能 |\n| `custom_menu` | 账户自定义菜单页面（仅私有化部署） |", + "enum": [ + "account", + "organization", + "on-call", + "monit", + "rum", + "ai-sre", + "custom_menu" + ] }, "status": { "type": "string", "enum": [ "enabled", - "disabled" + "deleted" ], - "description": "权限状态。" + "description": "权限状态。`enabled` —— 生效；`deleted` —— 已删除（已删除的权限会被过滤，不会出现在响应中）。" }, "is_granted": { "type": "boolean", - "description": "当 with_all 为 true 时存在，表示该权限是否已授予所请求的角色。" + "description": "该权限是否已授予 `role_ids` 指定的角色。本接口的响应中始终存在；仅当 `with_all` 为 true 时才会出现 `false` 的条目。" + }, + "account_id": { + "type": "integer", + "format": "uint64", + "description": "所属账户 ID。为 0（系统级权限）时不返回。" + }, + "source": { + "type": "string", + "enum": [ + "system", + "account" + ], + "description": "权限来源。`system` —— 内置种子权限；`account` —— 账户级动态权限（如自定义菜单）。" + }, + "source_ref": { + "type": "string", + "description": "账户级权限来源对象的主键（如自定义菜单 ID）。为空时不返回。" } } }, @@ -3472,7 +3611,10 @@ }, "description": "人员资料列表" } - } + }, + "required": [ + "items" + ] }, "PersonItem": { "type": "object", @@ -3496,35 +3638,31 @@ }, "person_name": { "type": "string", - "description": "显示名称" + "description": "显示名称。为空时不返回。" }, "avatar": { "type": "string", - "description": "头像 URL" + "description": "头像 URL。为空时不返回。" }, "locale": { "type": "string", - "description": "语言" + "description": "语言。为空时不返回。" }, "time_zone": { "type": "string", - "description": "时区" + "description": "时区。为空时不返回。" }, "email": { "type": "string", - "description": "邮箱地址" - }, - "country_code": { - "type": "string", - "description": "联系手机的 ISO 3166-1 alpha-2 地区代码（如 \"CN\"、\"US\"、\"HK\"）。" + "description": "邮箱地址。为空时不返回。" }, "phone": { "type": "string", - "description": "手机号" + "description": "手机号。为空时不返回——本接口不填充该字段。" }, "phone_verified": { "type": "boolean", - "description": "手机已验证" + "description": "手机号是否已验证。本接口的响应中恒为 false。" }, "email_verified": { "type": "boolean", @@ -3532,7 +3670,11 @@ }, "as": { "type": "string", - "description": "登录角色（account/member）" + "description": "主体类型：`account` —— 账户主体（注册人）；`member` —— 组织成员。", + "enum": [ + "account", + "member" + ] }, "status": { "type": "string", @@ -3541,7 +3683,7 @@ "pending", "deleted" ], - "description": "人员状态。`enabled` — 已激活；`pending` — 已邀请但尚未接受；`deleted` — 已移除。" + "description": "人员状态。`enabled` — 已激活；`pending` — 已邀请但尚未接受；`deleted` — 已移除。为空时不返回。" } } }, @@ -3564,7 +3706,7 @@ "type": "integer", "format": "uint64" }, - "description": "要授予/撤销角色的成员 ID 列表，最多 100 个。" + "description": "要授予/撤销角色的成员 ID 列表。" }, "role_id": { "type": "integer", @@ -3673,6 +3815,10 @@ "asc": { "type": "boolean", "description": "升序排序，默认 false（降序）。" + }, + "no_global": { + "type": "boolean", + "description": "为 true 时排除内置全局角色（Admin、Responder、Viewer），只返回自定义角色。默认 false。" } } }, @@ -3822,7 +3968,12 @@ }, "description": "团队成员的人员 ID 数组；团队无成员时为空数组（不为 null）。" } - } + }, + "required": [ + "team_id", + "team_name", + "person_ids" + ] }, "TeamDeleteRequest": { "type": "object", @@ -3841,7 +3992,24 @@ "type": "string", "description": "外部引用 ID。仅在 `team_id`、`team_name` 均未提供时用于定位。" } - } + }, + "anyOf": [ + { + "required": [ + "team_id" + ] + }, + { + "required": [ + "team_name" + ] + }, + { + "required": [ + "ref_id" + ] + } + ] }, "TeamInfoRequest": { "type": "object", @@ -3860,7 +4028,24 @@ "type": "string", "description": "外部引用 ID。提供时优先于 `team_name` 和 `team_id` 生效。" } - } + }, + "anyOf": [ + { + "required": [ + "team_id" + ] + }, + { + "required": [ + "team_name" + ] + }, + { + "required": [ + "ref_id" + ] + } + ] }, "TeamInfosRequest": { "type": "object", @@ -3875,7 +4060,7 @@ "type": "integer", "format": "uint64" }, - "description": "要查询的团队 ID 列表，最多 100 个。" + "description": "要查询的团队 ID 列表。" } } }, @@ -3936,9 +4121,9 @@ "type": "string", "enum": [ "enabled", - "disabled" + "deleted" ], - "description": "团队状态。" + "description": "团队状态。`enabled` —— 正常；`deleted` —— 已删除（仅按 `team_id` 查询已删除团队时可能返回；列表及按名称/ref_id 查询均排除已删除团队）。" }, "updated_by_name": { "type": "string", @@ -3956,7 +4141,7 @@ }, "creator_name": { "type": "string", - "description": "创建人显示名称。" + "description": "创建者显示名称。当前接口不填充该字段，恒为空字符串；请用 `creator_id` 调用 `POST /person/infos` 解析。" }, "created_at": { "type": "integer", @@ -4019,7 +4204,7 @@ }, "query": { "type": "string", - "description": "按团队名称做子串匹配。" + "description": "按团队名称或描述做子串匹配。" } } }, @@ -4098,7 +4283,7 @@ "items": { "type": "string" }, - "description": "按手机号匹配现有成员加入团队；未匹配到成员的号码会被静默忽略，非 E.164 格式号码用 `countryCode` 解析。" + "description": "按手机号把已存在的成员加入团队。非 E.164 格式的号码会按 `countryCode` 解析；无法解析的号码导致整个请求返回 400。能解析但不属于任何现有成员的号码会被静默忽略。" }, "countryCode": { "type": "string", @@ -4110,7 +4295,7 @@ }, "reset_if_name_exist": { "type": "boolean", - "description": "若为 true，当同名团队已存在时重置其成员列表为传入的 person_ids。" + "description": "为 true 且 `team_id` 为 0 时，若已存在同名团队，则原地更新该团队，而不是返回名称冲突错误。" } } }, @@ -4138,7 +4323,8 @@ "properties": { "account_id": { "type": "integer", - "description": "主体（账户）标识。" + "description": "主体（账户）标识。", + "format": "uint64" }, "account_name": { "type": "string", @@ -4186,7 +4372,7 @@ }, "restrictions": { "type": "object", - "description": "主体访问限制（仅在已配置时返回）。", + "description": "账户访问限制。未配置时不返回。", "properties": { "ips": { "type": "array", @@ -4210,11 +4396,43 @@ }, "mp_plat": { "type": "string", - "description": "主体所属的云市场平台（仅云市场来源的主体返回）。" + "description": "账户来源的云市场平台。账户非来自云市场时不返回。" }, "mp_account_id": { "type": "string", - "description": "主体在云市场平台上的账户标识（仅云市场来源的主体返回）。" + "description": "账户在云市场平台上的标识。与 `mp_plat` 一起省略。" + } + }, + "required": [ + "account_id", + "account_name", + "domain", + "extra_domains", + "phone", + "country_code", + "email", + "avatar", + "locale", + "time_zone", + "created_at" + ] + }, + "RoleDeleteRequest": { + "type": "object", + "required": [ + "role_id" + ], + "description": "删除角色请求。", + "properties": { + "role_id": { + "type": "integer", + "format": "uint64", + "description": "要删除的角色 ID。可通过 `POST /role/list` 获取（内置角色：2=Admin，6=Responder，8=Viewer）。" + }, + "is_force": { + "type": "boolean", + "default": false, + "description": "为 false（默认）时，若仍有成员持有该角色，删除失败并返回 `ReferenceExist` 错误，`data.refs` 中列出持有成员；为 true 时先从所有持有成员解除该角色，再删除角色。" } } } diff --git a/api-reference/rum.openapi.en.json b/api-reference/rum.openapi.en.json index c87536a6..30f3d980 100644 --- a/api-reference/rum.openapi.en.json +++ b/api-reference/rum.openapi.en.json @@ -3806,10 +3806,7 @@ "description": "Alert settings for the application.", "properties": { "enabled": { - "type": [ - "boolean", - "null" - ], + "type": "boolean", "description": "Whether alerting is enabled." }, "channel_ids": { @@ -3818,12 +3815,25 @@ "type": "integer", "format": "int64" }, - "description": "Channel IDs to send alerts to." + "description": "Channel IDs to send alerts to. Used only when `delivery_mode` is `oncall`." }, "integration_id": { "type": "integer", "format": "int64", - "description": "Associated on-call integration ID (read-only, auto-assigned)." + "description": "Associated on-call integration ID (read-only, auto-assigned on save when `delivery_mode` is `oncall`)." + }, + "delivery_mode": { + "type": "string", + "enum": [ + "oncall", + "webhook" + ], + "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)." + }, + "webhook_url": { + "type": "string", + "format": "uri", + "description": "URL that receives alert events when `delivery_mode` is `webhook`; required in that mode, ignored otherwise. Omitted when empty." } } }, @@ -3838,7 +3848,9 @@ "properties": { "application_name": { "type": "string", - "description": "Application name. 1–40 characters." + "description": "Application name. 1–40 characters.", + "minLength": 1, + "maxLength": 40 }, "type": { "type": "string", @@ -3855,12 +3867,13 @@ "harmony", "electron" ], - "description": "Application type. Platform identifier, one of `browser` (web), `ios`, `android`, `react-native`, `flutter`, `kotlin-multiplatform`, `roku`, `unity`, `miniprogram` (WeChat mini program), `harmony` (HarmonyOS), `electron`." + "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 |" }, "team_id": { "type": "integer", "format": "int64", - "description": "Owning team ID. Get team IDs via `POST /team/list`." + "description": "Owning team ID. Get team IDs via `POST /team/list`.", + "exclusiveMinimum": 0 }, "is_private": { "type": "boolean", @@ -3931,7 +3944,8 @@ "items": { "type": "string" }, - "description": "Up to 200 application IDs. Get IDs via `POST /rum/application/list`." + "description": "Up to 200 application IDs. Get IDs via `POST /rum/application/list`.", + "maxItems": 200 } } }, @@ -3980,7 +3994,7 @@ "harmony", "electron" ], - "description": "Application type. Platform identifier, one of `browser` (web), `ios`, `android`, `react-native`, `flutter`, `kotlin-multiplatform`, `roku`, `unity`. Note: the create API also accepts `miniprogram`, `harmony`, and `electron`, and applications of those types appear in responses too (see Enum gaps)." + "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 |" }, "client_token": { "type": "string", @@ -4004,13 +4018,16 @@ "description": "If `true`, geographic location is not inferred from IP." }, "alerting": { - "$ref": "#/components/schemas/RumApplicationAlerting" + "$ref": "#/components/schemas/RumApplicationAlerting", + "description": "Alerting configuration of the application." }, "tracing": { - "$ref": "#/components/schemas/RumApplicationTracing" + "$ref": "#/components/schemas/RumApplicationTracing", + "description": "APM tracing integration configuration." }, "links": { - "$ref": "#/components/schemas/RumApplicationLinks" + "$ref": "#/components/schemas/RumApplicationLinks", + "description": "External-link integration configuration." }, "status": { "type": "string", @@ -4088,7 +4105,7 @@ "all" ] }, - "description": "RUM event types where this external system link is shown." + "description": "RUM event types where this external system link is shown; at least one is required.\n\n| Value | Meaning |\n|---|---|\n| `crash` | Crash events (errors flagged `is_crash`) |\n| `error` | Error events |\n| `view` | Page/screen view events |\n| `action` | User action events |\n| `resource` | Resource load events |\n| `session` | Session events |\n| `all` | All event types |" }, "enabled": { "type": "boolean", @@ -4122,11 +4139,14 @@ "properties": { "p": { "type": "integer", - "description": "Page number (1-based). Default: 1." + "description": "Page number (1-based). Default: 1.", + "minimum": 1 }, "limit": { "type": "integer", - "description": "Page size. Range: 1–100. Default: 20." + "description": "Page size. Range: 1–100. Default: 20.", + "minimum": 1, + "maximum": 100 }, "orderby": { "type": "string", @@ -4134,7 +4154,7 @@ "created_at", "updated_at" ], - "description": "Sort field; defaults to `updated_at` when omitted." + "description": "Sort field: `created_at` (creation time) or `updated_at` (last update time); defaults to `updated_at` when omitted." }, "asc": { "type": "boolean", @@ -4210,11 +4230,19 @@ "description": "Application ID to update. Get application IDs via `POST /rum/application/list`." }, "application_name": { - "type": "string", - "description": "New application name, 1–40 characters. Omit to leave unchanged." + "type": [ + "string", + "null" + ], + "description": "New application name, 1–40 characters. Omit to leave unchanged.", + "minLength": 1, + "maxLength": 40 }, "type": { - "type": "string", + "type": [ + "string", + "null" + ], "enum": [ "browser", "ios", @@ -4228,12 +4256,16 @@ "harmony", "electron" ], - "description": "Application type. Omit to leave unchanged. Platform identifier, one of `browser` (web), `ios`, `android`, `react-native`, `flutter`, `kotlin-multiplatform`, `roku`, `unity`, `miniprogram` (WeChat mini program), `harmony` (HarmonyOS), `electron`." + "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 |" }, "team_id": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "Owning team ID. Get team IDs via `POST /team/list`. Omit to leave unchanged." + "description": "Owning team ID. Get team IDs via `POST /team/list`. Omit to leave unchanged.", + "exclusiveMinimum": 0 }, "is_private": { "type": [ @@ -4270,29 +4302,6 @@ } } }, - "RumDataAggregateFunction": { - "type": "object", - "description": "Aggregate function metadata used by the sampling engine.", - "required": [ - "type", - "column_name", - "column_index" - ], - "properties": { - "type": { - "type": "string", - "description": "Aggregate function type." - }, - "column_name": { - "type": "string", - "description": "Column name used by the aggregate." - }, - "column_index": { - "type": "integer", - "description": "Column index used by the aggregate." - } - } - }, "RumDataFieldMeta": { "type": "object", "description": "Metadata for one returned column.", @@ -4379,10 +4388,12 @@ "description": "Result for one query. Failed subqueries populate `error`; successful ones populate `data`.", "properties": { "error": { - "$ref": "#/components/schemas/DutyError" + "$ref": "#/components/schemas/DutyError", + "description": "Subquery failure details. Omitted when the query succeeded." }, "data": { - "$ref": "#/components/schemas/RumDataQueryResult" + "$ref": "#/components/schemas/RumDataQueryResult", + "description": "Query result. Omitted when the query failed." } } }, @@ -4435,7 +4446,7 @@ "properties": { "search_after_ctx": { "type": "string", - "description": "Opaque cursor for continuing paginated table queries." + "description": "Opaque cursor for continuing paginated table queries. Omitted when the query is not a cursor-paginated table query or no further pages exist." }, "fields": { "type": "array", @@ -4455,16 +4466,17 @@ "interval": { "type": "integer", "format": "int64", - "description": "Effective time bucket interval in seconds for time-series queries." + "description": "Effective time bucket interval in seconds. Omitted for `table`-format queries." }, "sampling": { - "$ref": "#/components/schemas/RumDataSamplingDecision" + "$ref": "#/components/schemas/RumDataSamplingDecision", + "description": "Sampling metadata. Omitted when the query did not use sampling." } } }, "RumDataSamplingDecision": { "type": "object", - "description": "Sampling metadata when the query engine uses sampled data.", + "description": "Sampling metadata returned when the query engine used sampled data.", "required": [ "enabled", "scale_factor" @@ -4472,25 +4484,11 @@ "properties": { "enabled": { "type": "boolean", - "description": "Whether sampling was applied." + "description": "Whether sampling was applied. Always `true` here — the `sampling` object is omitted entirely when sampling was not used." }, "scale_factor": { "type": "number", "description": "Multiplier used to scale sampled counts back to estimated full counts." - }, - "selected_tablets": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Storage tablets selected for the sampled query." - }, - "aggregate_funcs": { - "type": "array", - "items": { - "$ref": "#/components/schemas/RumDataAggregateFunction" - }, - "description": "Aggregate functions affected by sampling." } } }, @@ -4526,6 +4524,30 @@ "facet_value": { "description": "When set, filter events where `facet_key` equals this value before counting. Accepts string, number, or boolean." }, + "type": { + "type": "string", + "enum": [ + "browser", + "web", + "javascript", + "android", + "ios", + "miniprogram", + "harmony", + "flutter", + "electron", + "react-native" + ], + "description": "Symbol-store platform, used only when `scope` is `sourcemap`. Defaults to `browser` when omitted; `web` and `javascript` are accepted aliases of `browser`.\n\n| Value | Store queried |\n|---|---|\n| `browser` / `web` / `javascript` | JavaScript sourcemaps (excluding HarmonyOS ArkTS and React Native rows) |\n| `android` | Android ProGuard/R8 mappings; with `kind=native`, Android NDK .so symbols |\n| `ios` | iOS dSYM symbols |\n| `miniprogram` | WeChat mini program sourcemaps |\n| `harmony` | HarmonyOS ArkTS sourcemaps; with `kind=native`, HarmonyOS .so symbols |\n| `flutter` | Flutter Dart AOT symbols |\n| `electron` | Electron Breakpad symbols |\n| `react-native` | React Native JS sourcemaps |" + }, + "kind": { + "type": "string", + "enum": [ + "mapping", + "native" + ], + "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." + }, "start_time": { "type": "integer", "format": "int64", @@ -4689,9 +4711,20 @@ "scopes": { "type": "array", "items": { - "type": "string" + "type": "string", + "enum": [ + "session", + "view", + "action", + "error", + "resource", + "long_task", + "vital", + "issue", + "sourcemap" + ] }, - "description": "Filter by RUM data scopes. Valid values: `session`, `view`, `action`, `error`, `resource`, `long_task`, `vital`, `issue`, `sourcemap`." + "description": "Filter by RUM data scopes; unknown values are rejected with a parameter error. Omit to list fields of all scopes.\n\n| Value | Meaning |\n|---|---|\n| `session` | User sessions |\n| `view` | Page views |\n| `action` | User actions |\n| `error` | Error events |\n| `resource` | Resource loads |\n| `long_task` | Long tasks |\n| `vital` | Performance vitals (Web Vitals, etc.) |\n| `issue` | Aggregated error-tracking issues |\n| `sourcemap` | Sourcemap / symbol files |" }, "is_facet": { "type": [ @@ -4734,7 +4767,7 @@ "end_time": { "type": "integer", "format": "int64", - "description": "End of time range, millisecond timestamp. Maximum range: 183 days." + "description": "End of the time range, Unix epoch milliseconds. Must be greater than `start_time`; maximum range: 183 days." }, "application_ids": { "type": "array", @@ -4762,7 +4795,7 @@ "resolved" ] }, - "description": "Filter by status; only the enum values are accepted — any other value is rejected with a parameter error." + "description": "Filter by triage status; any other value is rejected with a parameter error.\n\n| Value | Meaning |\n|---|---|\n| `for_review` | Pending triage |\n| `reviewed` | Reviewed |\n| `ignored` | Ignored |\n| `resolved` | Resolved |" }, "suspected_causes": { "type": "array", @@ -4777,7 +4810,7 @@ "unknown" ] }, - "description": "Filter by suspected cause; see the enum for valid values." + "description": "Filter by suspected cause category.\n\n| Value | Meaning |\n|---|---|\n| `api.failed_request` | API request failure (e.g. HTTP 4xx/5xx responses) |\n| `network.error` | Network connectivity error (offline, aborted requests, etc.) |\n| `code.exception` | Code exception (Syntax/Reference/Range and similar runtime errors) |\n| `code.invalid_object_access` | Invalid object access (e.g. reading a property of `undefined`/`null`) |\n| `code.invalid_argument` | Invalid argument passed to a function |\n| `unknown` | Cause could not be determined |" }, "team_ids": { "type": "array", @@ -4789,11 +4822,14 @@ }, "p": { "type": "integer", - "description": "Page number (1-based). Ignored by the export — the first 100 matching rows are always read." + "description": "Page number (1-based). Ignored by the export — the first 100 matching rows are always read.", + "minimum": 1 }, "limit": { "type": "integer", - "description": "Page size (1–100). Ignored by the export — the row cap is fixed at 100." + "description": "Page size (1–100). Ignored by the export — the row cap is fixed at 100.", + "minimum": 1, + "maximum": 100 }, "orderby": { "type": "string", @@ -4804,7 +4840,7 @@ "error_count", "severity" ], - "description": "Sort field; defaults to `updated_at` when omitted." + "description": "Sort field; defaults to `updated_at` when omitted.\n\n| Value | Meaning |\n|---|---|\n| `created_at` | Issue creation time |\n| `updated_at` | Last update time |\n| `session_count` | Affected session count |\n| `error_count` | Error occurrence count |\n| `severity` | Severity rank (`Critical` > `Warning` > `Info`) |" }, "asc": { "type": "boolean", @@ -4843,7 +4879,7 @@ "resolved_at" ] }, - "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." + "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`) |" }, "console_origin": { "type": "string", @@ -4900,7 +4936,7 @@ "ignored", "resolved" ], - "description": "Triage status of the issue: `for_review`, `reviewed`, `ignored`, or `resolved`; soft-deleted (`deleted`) issues are never returned." + "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 |" }, "error_count": { "type": "integer", @@ -4919,7 +4955,7 @@ "age": { "type": "integer", "format": "int64", - "description": "Time span between the first and most recent occurrence, in seconds. Note: the struct comment at `model/issue/issue.go:40` says millisecond, but the value is computed and consumed (severity rules) in seconds — the comment is stale." + "description": "Time span between the first and most recent occurrence, in seconds." }, "resolved_at": { "type": "integer", @@ -5027,7 +5063,7 @@ "regressed_at": { "type": "integer", "format": "int64", - "description": "Timestamp when the regression was detected." + "description": "Time the regression was detected, Unix timestamp in milliseconds." }, "regressed_at_version": { "type": "string", @@ -5049,7 +5085,12 @@ }, "severity": { "type": "string", - "description": "Issue severity level." + "description": "Issue severity: `Critical`, `Warning`, or `Info`. Empty string on legacy issues created before severity existed.", + "enum": [ + "Critical", + "Warning", + "Info" + ] } } }, @@ -5069,7 +5110,7 @@ "end_time": { "type": "integer", "format": "int64", - "description": "End of time range, millisecond timestamp. Maximum range: 183 days." + "description": "End of the time range, Unix epoch milliseconds. Must be greater than `start_time`; maximum range: 183 days." }, "application_ids": { "type": "array", @@ -5097,7 +5138,7 @@ "resolved" ] }, - "description": "Filter by status; only the enum values are accepted — any other value is rejected with a parameter error." + "description": "Filter by triage status; any other value is rejected with a parameter error.\n\n| Value | Meaning |\n|---|---|\n| `for_review` | Pending triage |\n| `reviewed` | Reviewed |\n| `ignored` | Ignored |\n| `resolved` | Resolved |" }, "suspected_causes": { "type": "array", @@ -5112,7 +5153,7 @@ "unknown" ] }, - "description": "Filter by suspected cause; see the enum for valid values." + "description": "Filter by suspected cause category.\n\n| Value | Meaning |\n|---|---|\n| `api.failed_request` | API request failure (e.g. HTTP 4xx/5xx responses) |\n| `network.error` | Network connectivity error (offline, aborted requests, etc.) |\n| `code.exception` | Code exception (Syntax/Reference/Range and similar runtime errors) |\n| `code.invalid_object_access` | Invalid object access (e.g. reading a property of `undefined`/`null`) |\n| `code.invalid_argument` | Invalid argument passed to a function |\n| `unknown` | Cause could not be determined |" }, "team_ids": { "type": "array", @@ -5124,11 +5165,14 @@ }, "p": { "type": "integer", - "description": "Page number (1-based). Default: 1." + "description": "Page number (1-based). Default: 1.", + "minimum": 1 }, "limit": { "type": "integer", - "description": "Page size. Range: 1–100. Default: 20." + "description": "Page size. Range: 1–100. Default: 20.", + "minimum": 1, + "maximum": 100 }, "orderby": { "type": "string", @@ -5139,7 +5183,7 @@ "error_count", "severity" ], - "description": "Sort field; defaults to `updated_at` when omitted." + "description": "Sort field; defaults to `updated_at` when omitted.\n\n| Value | Meaning |\n|---|---|\n| `created_at` | Issue creation time |\n| `updated_at` | Last update time |\n| `session_count` | Affected session count |\n| `error_count` | Error occurrence count |\n| `severity` | Severity rank (`Critical` > `Warning` > `Info`) |" }, "asc": { "type": "boolean", @@ -5194,7 +5238,7 @@ "ignored", "resolved" ], - "description": "New status. Setting `resolved` records the resolution time and operator; switching away from `resolved` clears them. One of `for_review` (pending triage), `reviewed`, `ignored`, `resolved`." + "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 |" }, "suspected_cause": { "type": "string", @@ -5341,14 +5385,15 @@ "items": { "$ref": "#/components/schemas/SourcemapCodeSnippet" }, - "description": "Source-code snippets around this frame." + "description": "Source-code snippets around this frame. Omitted when no snippet was extracted (for example the source content was unavailable or `near` was not requested)." }, "original_frame": { - "$ref": "#/components/schemas/SourcemapStackFrame" + "$ref": "#/components/schemas/SourcemapStackFrame", + "description": "The original minified/obfuscated frame before enrichment. Omitted when the processor did not retain one." }, "third_party": { "type": "boolean", - "description": "Whether the frame is from third-party or system libraries." + "description": "Whether the frame is from third-party or system libraries (Android and native symbolication only). Omitted when `false`." } } } @@ -5364,11 +5409,13 @@ }, "type": { "type": "string", - "description": "Platform type: `browser`, `android`, or `ios`.", + "description": "Platform store this record belongs to. JavaScript rows always report `browser` (including HarmonyOS ArkTS and React Native uploads); native-symbol rows always report `android` (including HarmonyOS native and Electron uploads).\n\n| Value | Store |\n|---|---|\n| `browser` | JavaScript sourcemap store |\n| `android` | Android mapping store, or the shared native symbol store |\n| `ios` | iOS dSYM store |\n| `miniprogram` | WeChat mini program sourcemap store |\n| `flutter` | Flutter Dart AOT symbol store |", "enum": [ "browser", "android", - "ios" + "ios", + "miniprogram", + "flutter" ] }, "service": { @@ -5404,8 +5451,20 @@ }, "metadata": { "type": "object", - "description": "Free-form key-value metadata attached to the sourcemap. Shape depends on the upload client; common keys include `git_repository_url` and `git_commit_sha` (though those are also promoted to top-level fields).", + "description": "Platform-specific metadata: `minified_url` (browser/react-native/harmony/miniprogram); `build_id`, `variant`, `version_code` (android mappings), plus `arch`, `lib_name`, `code_id` (android/harmony/electron native symbols); `uuid` (ios); `build_id`, `platform`, `arch`, `flavor`, `code_id`, `debug_id` (flutter); `subpackage`, `minified_url` (miniprogram). Omitted when empty.", "additionalProperties": true + }, + "minified_url": { + "type": "string", + "description": "Deprecated. URL of the minified file; present only on JavaScript and miniprogram records. New integrations should read `metadata.minified_url`." + }, + "minified_path": { + "type": "string", + "description": "Deprecated. Storage path of the minified file; present only on JavaScript records." + }, + "sourcemap_path": { + "type": "string", + "description": "Deprecated. Storage path of the sourcemap file; present only on JavaScript and miniprogram records." } } }, @@ -5429,11 +5488,16 @@ }, "type": { "type": "string", - "description": "Platform type. Defaults to `browser` when omitted. One of `browser` (JavaScript sourcemaps), `android` (ProGuard/R8 mappings or NDK native symbols, distinguishable via `kind`), `ios` (dSYM symbol files).", + "description": "Platform whose symbol store to list. Defaults to `browser` when omitted; any other value returns an empty list.\n\n| Value | Store listed |\n|---|---|\n| `browser` | JavaScript sourcemaps (shared store; excludes HarmonyOS ArkTS and React Native rows) |\n| `android` | ProGuard/R8 mapping files; with `kind=native`, Android NDK .so symbols |\n| `ios` | iOS dSYM symbol files |\n| `miniprogram` | WeChat mini program sourcemaps |\n| `react-native` | React Native JS sourcemaps |\n| `harmony` | HarmonyOS ArkTS sourcemaps; with `kind=native`, HarmonyOS .so symbols |\n| `flutter` | Flutter Dart AOT symbols |\n| `electron` | Electron Breakpad symbols |", "enum": [ "browser", "android", - "ios" + "ios", + "miniprogram", + "react-native", + "harmony", + "flutter", + "electron" ] }, "services": { @@ -5441,26 +5505,39 @@ "items": { "type": "string" }, - "description": "Filter by service names. Up to 100 values." + "description": "Filter by service names. Up to 100 values.", + "maxItems": 100 }, "versions": { "type": "array", "items": { "type": "string" }, - "description": "Filter by version strings. Up to 100 values." + "description": "Filter by version strings. Up to 100 values.", + "maxItems": 100 }, "query": { "type": "string", - "description": "Substring match on the minified URL (browser) or build ID (android). Max 200 characters." + "description": "Free-text substring match. Matches `minified_url` for the JS stores (browser/react-native/harmony/miniprogram), `build_id` for android/flutter/electron and harmony with `kind=native`, or `uuid` for ios (case-insensitive, hyphens ignored).", + "maxLength": 200 }, "build_id": { "type": "string", - "description": "Android only. Filter by Gradle plugin build identifier. Max 200 characters." + "description": "Android only. Filter by Gradle plugin build identifier. Max 200 characters.", + "maxLength": 200 }, "uuid": { "type": "string", - "description": "iOS only. Filter by dSYM bundle UUID. Max 200 characters." + "description": "iOS only. Filter by dSYM bundle UUID. Max 200 characters.", + "maxLength": 200 + }, + "kind": { + "type": "string", + "enum": [ + "mapping", + "native" + ], + "description": "Symbol type filter, Android and HarmonyOS only (ignored for other platforms): `mapping` (default) lists ProGuard/R8 mappings or ArkTS sourcemaps, `native` lists native .so symbols." }, "p": { "type": "integer", @@ -5494,15 +5571,11 @@ "SourcemapListResponse": { "type": "object", "description": "Paginated list of sourcemap records.", - "required": [ - "total", - "items" - ], "properties": { "total": { "type": "integer", "format": "int64", - "description": "Total number of matching records.", + "description": "Total number of matching records. Omitted when 0.", "example": 3 }, "items": { @@ -5510,7 +5583,7 @@ "items": { "$ref": "#/components/schemas/SourcemapItem" }, - "description": "Sourcemap records of the current page (including iOS dSYM and miniprogram symbol files)." + "description": "Sourcemap records of the current page. Omitted when empty." } } }, @@ -5531,9 +5604,18 @@ "miniprogram", "harmony", "flutter", - "electron" + "electron", + "react-native" + ], + "description": "Source platform whose symbol store is used. Defaults to `browser` when omitted.\n\n| Value | Symbolication |\n|---|---|\n| `browser` | JavaScript stacks via sourcemaps |\n| `android` | Java/Kotlin stacks via ProGuard/R8 mappings; native stacks via NDK symbols (send `source_type=ndk` with `arch`) |\n| `ios` | iOS crash stacks via dSYM (send `binary_images`) |\n| `miniprogram` | WeChat mini program stacks via sourcemaps |\n| `harmony` | HarmonyOS stacks via ArkTS sourcemaps or native symbols |\n| `flutter` | Flutter/Dart stacks via Dart AOT symbols |\n| `electron` | Electron JavaScript stacks via sourcemaps; minidump native frames via Breakpad symbols (derived from `source_type`) |\n| `react-native` | React Native JS stacks via sourcemaps; narrow the lookup with `platform` |" + }, + "platform": { + "type": "string", + "enum": [ + "ios", + "android" ], - "description": "Source platform. Defaults to `browser` when omitted. One of `browser` (JS stacks, sourcemap-based), `android` (mapping/NDK symbolication), `ios` (dSYM symbolication), `miniprogram` (WeChat mini program, sourcemap-based), `harmony` (HarmonyOS, sourcemap/native symbolication), `flutter` (Flutter stack symbolication), `electron` (Electron, sourcemap-based)." + "description": "Narrows a `react-native` enrich to the app's native platform: `ios` for the iOS native layer, `android` for the Android native layer (the console derives it from the event's OS). Ignored for other `type` values." }, "service": { "type": "string", @@ -5676,7 +5758,8 @@ "ts": { "type": "integer", "format": "int64", - "description": "Unix timestamp in milliseconds of the session start time. Optional; disambiguates when a session ID has been reused across different time windows." + "description": "Unix timestamp in milliseconds of the session start time. Optional; disambiguates when a session ID has been reused across different time windows.", + "exclusiveMinimum": 0 } } }, @@ -5714,16 +5797,18 @@ "type": "string", "enum": [ "browser", - "android", "ios", - "miniprogram", + "android", "react-native", "flutter", "kotlin-multiplatform", "roku", - "unity" + "unity", + "miniprogram", + "harmony", + "electron" ], - "description": "SDK platform that recorded the session. Platform identifier, one of `browser`, `android`, `ios`, `miniprogram`, `react-native`, `flutter`, `kotlin-multiplatform`, `roku`, `unity`." + "description": "SDK platform that recorded the session. 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 |" }, "start": { "type": "integer", @@ -5744,16 +5829,18 @@ "type": "string", "enum": [ "browser", - "android", "ios", - "miniprogram", + "android", "react-native", "flutter", "kotlin-multiplatform", "roku", - "unity" + "unity", + "miniprogram", + "harmony", + "electron" ], - "description": "SDK platform that recorded the view. Platform identifier, one of `browser`, `android`, `ios`, `miniprogram`, `react-native`, `flutter`, `kotlin-multiplatform`, `roku`, `unity`." + "description": "SDK platform that recorded the view. 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 |" }, "view_id": { "type": "string", @@ -5773,11 +5860,11 @@ }, "container_source": { "type": "string", - "description": "SDK platform of the container app, when this view is embedded (e.g. a WebView inside a native app)." + "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." }, "container_view_id": { "type": "string", - "description": "View ID of the containing view, when this view is embedded." + "description": "View ID of the containing view, when this view is embedded. Omitted when the view is not embedded." }, "server_time_delta": { "type": "integer", @@ -5825,13 +5912,16 @@ "description": "Replay metadata for a session: the application, device, session bounds, and every recorded view.", "properties": { "application": { - "$ref": "#/components/schemas/RumReplayApplication" + "$ref": "#/components/schemas/RumReplayApplication", + "description": "Application the session belongs to." }, "device": { - "$ref": "#/components/schemas/RumReplayDevice" + "$ref": "#/components/schemas/RumReplayDevice", + "description": "Device that recorded the session." }, "session": { - "$ref": "#/components/schemas/RumReplaySession" + "$ref": "#/components/schemas/RumReplaySession", + "description": "Session bounds and state." }, "views": { "type": "array", @@ -5871,7 +5961,8 @@ "ts": { "type": "integer", "format": "int64", - "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), seeks to the most recent full-snapshot segment at or before this time instead of starting from the beginning.", + "exclusiveMinimum": 0 }, "url_mode": { "type": "boolean", @@ -6003,7 +6094,7 @@ "properties": { "id": { "type": "integer", - "format": "uint64", + "format": "int64", "description": "Internal row ID." }, "account_id": { @@ -6771,7 +6862,7 @@ }, "id": { "type": "integer", - "format": "uint64", + "format": "int64", "description": "Internal auto-increment row ID. Not stable across a history revert — reverting reinserts rows with new IDs." }, "deleted_at": { diff --git a/api-reference/rum.openapi.zh.json b/api-reference/rum.openapi.zh.json index 09eaa4e2..cb37780a 100644 --- a/api-reference/rum.openapi.zh.json +++ b/api-reference/rum.openapi.zh.json @@ -289,7 +289,7 @@ "suspected_cause": { "source": "auto", "value": "code.exception", - "reason": "错误信息 'Script error.' 通常表示 JavaScript 中的未处理异常。", + "reason": "The error message 'Script error.' typically indicates an unhandled exception in JavaScript.", "person_id": 0 }, "versions": [ @@ -760,7 +760,7 @@ "suspected_cause": { "source": "auto", "value": "code.exception", - "reason": "错误信息 'Script error.' 通常表示 JavaScript 中的未处理异常。", + "reason": "The error message 'Script error.' typically indicates an unhandled exception in JavaScript.", "person_id": 0 }, "versions": [ @@ -798,7 +798,7 @@ "suspected_cause": { "source": "auto", "value": "api.failed_request", - "reason": "错误信息表明 POST /api/access/logout 请求时服务端发生内部错误。", + "reason": "The error indicates an internal server error during a POST request to /api/access/logout.", "person_id": 0 }, "versions": [ @@ -1211,7 +1211,7 @@ "field_key": "error.type", "field_name": "Error type", "group": "Error", - "description": "错误类型。", + "description": "The type of the error.", "value_type": "string", "show_type": "list", "unit_family": "", @@ -1485,7 +1485,7 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "application_id": "qLpu24Dz4CAzWsESPbJYWA", - "application_name": "我的 Web 应用", + "application_name": "My Web App", "client_token": "e090078724855a4ca168c3884880dfbc131" } } @@ -1513,7 +1513,7 @@ "$ref": "#/components/schemas/RumApplicationCreateRequest" }, "example": { - "application_name": "我的 Web 应用", + "application_name": "My Web App", "type": "browser", "team_id": 2477033058131, "is_private": false, @@ -1604,7 +1604,7 @@ }, "example": { "application_id": "WoyQQ3BohkdtPivubEvE8o", - "application_name": "我的 Web 应用 v2", + "application_name": "My Web App v2", "alerting": { "enabled": true, "channel_ids": [ @@ -2664,8 +2664,8 @@ "items": [ { "rule_id": "n8mZQ2VbXk4wPRs6DfC9Ay", - "rule_name": "已知浏览器插件噪声错误", - "description": "将已知浏览器插件错误降级为 Info", + "rule_name": "Known noisy browser extension errors", + "description": "Downgrade known extension errors to Info", "filters": [ [ { @@ -2685,8 +2685,8 @@ }, { "rule_id": "TAHUYnQmXKzgMS4TFVUKvz", - "rule_name": "生产环境崩溃升级", - "description": "将生产环境的崩溃错误升级为 Critical 严重级别", + "rule_name": "Critical crash spikes", + "description": "Escalate production crashes to Critical severity", "filters": [ [ { @@ -2784,7 +2784,7 @@ "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "rule_id": "TAHUYnQmXKzgMS4TFVUKvz", - "rule_name": "生产环境崩溃升级", + "rule_name": "Critical crash spikes", "priority": 2 } } @@ -2813,8 +2813,8 @@ }, "example": { "application_id": "WoyQQ3BohkdtPivubEvE8o", - "rule_name": "生产环境崩溃升级", - "description": "将生产环境的崩溃错误升级为 Critical 严重级别", + "rule_name": "Critical crash spikes", + "description": "Escalate production crashes to Critical severity", "filters": [ [ { @@ -2905,7 +2905,7 @@ "example": { "application_id": "WoyQQ3BohkdtPivubEvE8o", "rule_id": "TAHUYnQmXKzgMS4TFVUKvz", - "rule_name": "生产环境崩溃升级（已更新）", + "rule_name": "Critical crash spikes (updated)", "severity": "Critical" } } @@ -3245,8 +3245,8 @@ "account_id": 3790925372131, "application_id": "WoyQQ3BohkdtPivubEvE8o", "rule_id": "n8mZQ2VbXk4wPRs6DfC9Ay", - "rule_name": "已知浏览器插件噪声错误", - "description": "将已知浏览器插件错误降级为 Info", + "rule_name": "Known noisy browser extension errors", + "description": "Downgrade known extension errors to Info", "filters": [ [ { @@ -3272,8 +3272,8 @@ "account_id": 3790925372131, "application_id": "WoyQQ3BohkdtPivubEvE8o", "rule_id": "TAHUYnQmXKzgMS4TFVUKvz", - "rule_name": "生产环境崩溃升级", - "description": "将生产环境的崩溃错误升级为 Critical 严重级别", + "rule_name": "Critical crash spikes", + "description": "Escalate production crashes to Critical severity", "filters": [ [ { @@ -3314,8 +3314,8 @@ "account_id": 3790925372131, "application_id": "WoyQQ3BohkdtPivubEvE8o", "rule_id": "n8mZQ2VbXk4wPRs6DfC9Ay", - "rule_name": "已知浏览器插件噪声错误", - "description": "将已知浏览器插件错误降级为 Info", + "rule_name": "Known noisy browser extension errors", + "description": "Downgrade known extension errors to Info", "filters": [ [ { @@ -3806,10 +3806,7 @@ "description": "应用的告警配置。", "properties": { "enabled": { - "type": [ - "boolean", - "null" - ], + "type": "boolean", "description": "是否启用告警。" }, "channel_ids": { @@ -3818,12 +3815,25 @@ "type": "integer", "format": "int64" }, - "description": "接收告警的协作空间 ID 列表。" + "description": "接收告警的协作空间 ID 列表，仅在 `delivery_mode` 为 `oncall` 时使用。" }, "integration_id": { "type": "integer", "format": "int64", - "description": "关联的 On-call 集成 ID（只读，自动分配）。" + "description": "关联的 On-call 集成 ID（只读，`delivery_mode` 为 `oncall` 时保存即自动分配）。" + }, + "delivery_mode": { + "type": "string", + "enum": [ + "oncall", + "webhook" + ], + "description": "告警投递方式：`oncall` 经 Flashduty On-call 投递，`webhook` 直接 POST 到 `webhook_url`。空值按 `oncall` 处理；创建/更新时空值会落库为部署默认值（纯 RUM 私有化部署默认 `webhook`，其他场景默认 `oncall`）。为空（历史数据）时省略该字段。" + }, + "webhook_url": { + "type": "string", + "format": "uri", + "description": "`delivery_mode` 为 `webhook` 时接收告警事件的 URL，该模式下必填，其他模式下忽略；为空时省略该字段。" } } }, @@ -3838,7 +3848,9 @@ "properties": { "application_name": { "type": "string", - "description": "应用名称，1–40 个字符。" + "description": "应用名称，1–40 个字符。", + "minLength": 1, + "maxLength": 40 }, "type": { "type": "string", @@ -3855,12 +3867,13 @@ "harmony", "electron" ], - "description": "应用类型。平台标识，取值为 `browser`（浏览器 Web 应用）、`ios`（iOS 应用）、`android`（Android 应用）、`react-native`（React Native 应用）、`flutter`（Flutter 应用）、`kotlin-multiplatform`（Kotlin Multiplatform 应用）、`roku`（Roku 频道应用）、`unity`（Unity 应用）、`miniprogram`（微信小程序）、`harmony`（鸿蒙 HarmonyOS 应用）、`electron`（Electron 桌面应用）。" + "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 桌面应用 |" }, "team_id": { "type": "integer", "format": "int64", - "description": "所属团队 ID，可通过 `POST /team/list` 获取。" + "description": "所属团队 ID，可通过 `POST /team/list` 获取。", + "exclusiveMinimum": 0 }, "is_private": { "type": "boolean", @@ -3931,7 +3944,8 @@ "items": { "type": "string" }, - "description": "最多 200 个应用 ID，可通过 `POST /rum/application/list` 获取。" + "description": "最多 200 个应用 ID，可通过 `POST /rum/application/list` 获取。", + "maxItems": 200 } } }, @@ -3980,7 +3994,7 @@ "harmony", "electron" ], - "description": "应用类型。平台标识，取值为 `browser`（浏览器 Web 应用）、`ios`（iOS 应用）、`android`（Android 应用）、`react-native`（React Native 应用）、`flutter`（Flutter 应用）、`kotlin-multiplatform`（Kotlin Multiplatform 应用）、`roku`（Roku 频道应用）、`unity`（Unity 应用）。注意：创建接口还接受 `miniprogram`、`harmony`、`electron`，这些类型的应用同样会出现在响应中（见 Enum gaps）。" + "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 桌面应用 |" }, "client_token": { "type": "string", @@ -4004,13 +4018,16 @@ "description": "为 `true` 时不推断地理位置。" }, "alerting": { - "$ref": "#/components/schemas/RumApplicationAlerting" + "$ref": "#/components/schemas/RumApplicationAlerting", + "description": "应用的告警配置。" }, "tracing": { - "$ref": "#/components/schemas/RumApplicationTracing" + "$ref": "#/components/schemas/RumApplicationTracing", + "description": "APM 链路追踪集成配置。" }, "links": { - "$ref": "#/components/schemas/RumApplicationLinks" + "$ref": "#/components/schemas/RumApplicationLinks", + "description": "外部链接集成配置。" }, "status": { "type": "string", @@ -4088,7 +4105,7 @@ "all" ] }, - "description": "展示该外部系统链接的 RUM 事件类型。" + "description": "展示该外部系统链接的 RUM 事件类型，至少填一个。\n\n| 值 | 含义 |\n|---|---|\n| `crash` | 崩溃事件（`is_crash` 的错误） |\n| `error` | 错误事件 |\n| `view` | 页面/视图事件 |\n| `action` | 用户操作事件 |\n| `resource` | 资源加载事件 |\n| `session` | 会话事件 |\n| `all` | 所有事件类型 |" }, "enabled": { "type": "boolean", @@ -4122,11 +4139,14 @@ "properties": { "p": { "type": "integer", - "description": "页码（从 1 开始），默认 1。" + "description": "页码（从 1 开始），默认 1。", + "minimum": 1 }, "limit": { "type": "integer", - "description": "每页条数，范围 1–100，默认 20。" + "description": "每页条数，范围 1–100，默认 20。", + "minimum": 1, + "maximum": 100 }, "orderby": { "type": "string", @@ -4134,7 +4154,7 @@ "created_at", "updated_at" ], - "description": "排序字段；缺省时按 `updated_at` 排序。" + "description": "排序字段：`created_at`（创建时间）或 `updated_at`（最近更新时间）；缺省按 `updated_at` 排序。" }, "asc": { "type": "boolean", @@ -4210,11 +4230,19 @@ "description": "要更新的应用 ID，可通过 `POST /rum/application/list` 获取。" }, "application_name": { - "type": "string", - "description": "新的应用名称，1–40 个字符；不传则保持不变。" + "type": [ + "string", + "null" + ], + "description": "新的应用名称，1–40 个字符；不传则保持不变。", + "minLength": 1, + "maxLength": 40 }, "type": { - "type": "string", + "type": [ + "string", + "null" + ], "enum": [ "browser", "ios", @@ -4228,12 +4256,16 @@ "harmony", "electron" ], - "description": "应用类型；不传则保持不变。平台标识，取值为 `browser`（浏览器 Web 应用）、`ios`（iOS 应用）、`android`（Android 应用）、`react-native`（React Native 应用）、`flutter`（Flutter 应用）、`kotlin-multiplatform`（Kotlin Multiplatform 应用）、`roku`（Roku 频道应用）、`unity`（Unity 应用）、`miniprogram`（微信小程序）、`harmony`（鸿蒙 HarmonyOS 应用）、`electron`（Electron 桌面应用）。" + "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 桌面应用 |" }, "team_id": { - "type": "integer", + "type": [ + "integer", + "null" + ], "format": "int64", - "description": "应用所属团队 ID，可通过 `POST /team/list` 获取；不传则保持不变。" + "description": "应用所属团队 ID，可通过 `POST /team/list` 获取；不传则保持不变。", + "exclusiveMinimum": 0 }, "is_private": { "type": [ @@ -4270,29 +4302,6 @@ } } }, - "RumDataAggregateFunction": { - "type": "object", - "description": "采样引擎使用的聚合函数元信息。", - "required": [ - "type", - "column_name", - "column_index" - ], - "properties": { - "type": { - "type": "string", - "description": "聚合函数类型。" - }, - "column_name": { - "type": "string", - "description": "聚合函数使用的列名。" - }, - "column_index": { - "type": "integer", - "description": "聚合函数使用的列下标。" - } - } - }, "RumDataFieldMeta": { "type": "object", "description": "单个返回列的元信息。", @@ -4379,10 +4388,12 @@ "description": "单个查询的结果。失败的子查询填充 `error`；成功的子查询填充 `data`。", "properties": { "error": { - "$ref": "#/components/schemas/DutyError" + "$ref": "#/components/schemas/DutyError", + "description": "子查询失败的错误详情；查询成功时省略。" }, "data": { - "$ref": "#/components/schemas/RumDataQueryResult" + "$ref": "#/components/schemas/RumDataQueryResult", + "description": "查询结果；查询失败时省略。" } } }, @@ -4435,7 +4446,7 @@ "properties": { "search_after_ctx": { "type": "string", - "description": "用于继续表格查询分页的不透明游标。" + "description": "用于继续表格查询分页的不透明游标；非游标分页的表格查询或没有更多分页时省略。" }, "fields": { "type": "array", @@ -4455,10 +4466,11 @@ "interval": { "type": "integer", "format": "int64", - "description": "时序查询实际使用的时间桶间隔，单位秒。" + "description": "时序查询实际使用的时间桶间隔，单位秒；`table` 格式查询时省略。" }, "sampling": { - "$ref": "#/components/schemas/RumDataSamplingDecision" + "$ref": "#/components/schemas/RumDataSamplingDecision", + "description": "采样元信息；查询未使用采样时省略。" } } }, @@ -4472,25 +4484,11 @@ "properties": { "enabled": { "type": "boolean", - "description": "是否应用了采样。" + "description": "是否应用了采样。响应中该字段恒为 `true` —— 未使用采样时整个 `sampling` 对象会被省略。" }, "scale_factor": { "type": "number", "description": "将采样计数放大为全量估算值时使用的倍率。" - }, - "selected_tablets": { - "type": "array", - "items": { - "type": "string" - }, - "description": "采样查询选中的存储 tablet。" - }, - "aggregate_funcs": { - "type": "array", - "items": { - "$ref": "#/components/schemas/RumDataAggregateFunction" - }, - "description": "受采样影响的聚合函数。" } } }, @@ -4526,6 +4524,30 @@ "facet_value": { "description": "设置后，统计前会先过滤 `facet_key` 等于该值的事件。接受字符串、数字或布尔值。" }, + "type": { + "type": "string", + "enum": [ + "browser", + "web", + "javascript", + "android", + "ios", + "miniprogram", + "harmony", + "flutter", + "electron", + "react-native" + ], + "description": "符号文件存储的平台，仅在 `scope` 为 `sourcemap` 时使用。省略时默认为 `browser`；`web`、`javascript` 是 `browser` 的别名。\n\n| 值 | 查询的存储 |\n|---|---|\n| `browser` / `web` / `javascript` | JS Sourcemap（不含鸿蒙 ArkTS 与 React Native 行） |\n| `android` | Android ProGuard/R8 mapping；`kind=native` 时为 Android NDK .so 符号 |\n| `ios` | iOS dSYM 符号 |\n| `miniprogram` | 微信小程序 Sourcemap |\n| `harmony` | 鸿蒙 ArkTS Sourcemap；`kind=native` 时为鸿蒙 .so 符号 |\n| `flutter` | Flutter Dart AOT 符号 |\n| `electron` | Electron Breakpad 符号 |\n| `react-native` | React Native JS Sourcemap |" + }, + "kind": { + "type": "string", + "enum": [ + "mapping", + "native" + ], + "description": "符号类型，仅在 `scope` 为 `sourcemap` 时使用，且只对 `android`/`harmony` 有意义：`mapping`（默认）选择 ProGuard/R8 mapping 或 ArkTS Sourcemap，`native` 选择 native .so 符号。" + }, "start_time": { "type": "integer", "format": "int64", @@ -4689,9 +4711,20 @@ "scopes": { "type": "array", "items": { - "type": "string" + "type": "string", + "enum": [ + "session", + "view", + "action", + "error", + "resource", + "long_task", + "vital", + "issue", + "sourcemap" + ] }, - "description": "按 RUM 数据 scope 过滤。合法值：`session`、`view`、`action`、`error`、`resource`、`long_task`、`vital`、`issue`、`sourcemap`。" + "description": "按 RUM 数据 scope 过滤；传入未知值会被参数校验拒绝。不传则返回所有 scope 的字段。\n\n| 值 | 含义 |\n|---|---|\n| `session` | 用户会话 |\n| `view` | 页面/视图 |\n| `action` | 用户操作 |\n| `error` | 错误事件 |\n| `resource` | 资源加载 |\n| `long_task` | 长任务 |\n| `vital` | 性能指标（Web Vitals 等） |\n| `issue` | 异常聚合 Issue |\n| `sourcemap` | Sourcemap 符号文件 |" }, "is_facet": { "type": [ @@ -4734,7 +4767,7 @@ "end_time": { "type": "integer", "format": "int64", - "description": "时间范围结束，毫秒时间戳，最大范围 183 天。" + "description": "时间范围结束，Unix 毫秒时间戳。需大于 `start_time`，最大跨度 183 天。" }, "application_ids": { "type": "array", @@ -4762,7 +4795,7 @@ "resolved" ] }, - "description": "按状态过滤，取值见枚举；传入其他值会报参数错误。" + "description": "按处理状态过滤；传入其他值会被参数校验拒绝。\n\n| 值 | 含义 |\n|---|---|\n| `for_review` | 待处理 |\n| `reviewed` | 已查看 |\n| `ignored` | 已忽略 |\n| `resolved` | 已解决 |" }, "suspected_causes": { "type": "array", @@ -4777,7 +4810,7 @@ "unknown" ] }, - "description": "按疑似原因过滤，取值见枚举。" + "description": "按疑似根因分类过滤。\n\n| 值 | 含义 |\n|---|---|\n| `api.failed_request` | API/接口请求失败（如 HTTP 4xx/5xx 响应） |\n| `network.error` | 网络连接错误（断网、请求中断等） |\n| `code.exception` | 代码异常（Syntax/Reference/Range 等运行时异常） |\n| `code.invalid_object_access` | 非法对象访问（如对 `undefined`/`null` 读取属性） |\n| `code.invalid_argument` | 非法参数（向函数传入了无效参数） |\n| `unknown` | 无法判定的未知原因 |" }, "team_ids": { "type": "array", @@ -4789,11 +4822,14 @@ }, "p": { "type": "integer", - "description": "页码（从 1 开始）。导出时忽略——始终读取前 100 条匹配记录。" + "description": "页码（从 1 开始）。导出时忽略——始终读取前 100 条匹配记录。", + "minimum": 1 }, "limit": { "type": "integer", - "description": "每页条数（1–100）。导出时忽略——行数上限固定为 100。" + "description": "每页条数（1–100）。导出时忽略——行数上限固定为 100。", + "minimum": 1, + "maximum": 100 }, "orderby": { "type": "string", @@ -4804,7 +4840,7 @@ "error_count", "severity" ], - "description": "排序字段；缺省时按 `updated_at` 排序。" + "description": "排序字段；缺省按 `updated_at` 排序。\n\n| 值 | 含义 |\n|---|---|\n| `created_at` | Issue 创建时间 |\n| `updated_at` | 最近更新时间 |\n| `session_count` | 受影响会话数 |\n| `error_count` | 错误发生次数 |\n| `severity` | 严重性等级（`Critical` > `Warning` > `Info`） |" }, "asc": { "type": "boolean", @@ -4843,7 +4879,7 @@ "resolved_at" ] }, - "description": "按顺序指定导出的 CSV 列；未知键会被拒绝；空数组使用默认列集。" + "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` 渲染） |" }, "console_origin": { "type": "string", @@ -4900,7 +4936,7 @@ "ignored", "resolved" ], - "description": "Issue 的处理状态：`for_review`（待处理）、`reviewed`（已查看）、`ignored`（已忽略）、`resolved`（已解决）；已软删除（`deleted`）的 Issue 不会出现在响应中。" + "description": "Issue 的处理状态；已软删除（`deleted`）的 Issue 不会出现在响应中。\n\n| 值 | 含义 |\n|---|---|\n| `for_review` | 待处理 |\n| `reviewed` | 已查看 |\n| `ignored` | 已忽略 |\n| `resolved` | 已解决 |" }, "error_count": { "type": "integer", @@ -4919,7 +4955,7 @@ "age": { "type": "integer", "format": "int64", - "description": "从首次出现到最近一次出现的时长，单位秒。注意：`model/issue/issue.go:40` 的字段注释写的是 millisecond，但实际写入与消费（告警严重性判定）均按秒处理，注释已过时。" + "description": "从首次出现到最近一次出现的时长，单位秒。" }, "resolved_at": { "type": "integer", @@ -5027,7 +5063,7 @@ "regressed_at": { "type": "integer", "format": "int64", - "description": "检测到回溯的时间戳。" + "description": "检测到回溯的时间，Unix 毫秒时间戳。" }, "regressed_at_version": { "type": "string", @@ -5049,7 +5085,12 @@ }, "severity": { "type": "string", - "description": "Issue 严重性级别。" + "description": "Issue 严重性：`Critical`（严重）、`Warning`（警告）、`Info`（提示）；引入严重性之前创建的历史 Issue 为空字符串。", + "enum": [ + "Critical", + "Warning", + "Info" + ] } } }, @@ -5069,7 +5110,7 @@ "end_time": { "type": "integer", "format": "int64", - "description": "时间范围结束，毫秒时间戳，最大范围 183 天。" + "description": "时间范围结束，Unix 毫秒时间戳。需大于 `start_time`，最大跨度 183 天。" }, "application_ids": { "type": "array", @@ -5097,7 +5138,7 @@ "resolved" ] }, - "description": "按状态过滤，取值见枚举；传入其他值会报参数错误。" + "description": "按处理状态过滤；传入其他值会被参数校验拒绝。\n\n| 值 | 含义 |\n|---|---|\n| `for_review` | 待处理 |\n| `reviewed` | 已查看 |\n| `ignored` | 已忽略 |\n| `resolved` | 已解决 |" }, "suspected_causes": { "type": "array", @@ -5112,7 +5153,7 @@ "unknown" ] }, - "description": "按疑似原因过滤，取值见枚举。" + "description": "按疑似根因分类过滤。\n\n| 值 | 含义 |\n|---|---|\n| `api.failed_request` | API/接口请求失败（如 HTTP 4xx/5xx 响应） |\n| `network.error` | 网络连接错误（断网、请求中断等） |\n| `code.exception` | 代码异常（Syntax/Reference/Range 等运行时异常） |\n| `code.invalid_object_access` | 非法对象访问（如对 `undefined`/`null` 读取属性） |\n| `code.invalid_argument` | 非法参数（向函数传入了无效参数） |\n| `unknown` | 无法判定的未知原因 |" }, "team_ids": { "type": "array", @@ -5124,11 +5165,14 @@ }, "p": { "type": "integer", - "description": "页码（从 1 开始），默认 1。" + "description": "页码（从 1 开始），默认 1。", + "minimum": 1 }, "limit": { "type": "integer", - "description": "每页条数，范围 1–100，默认 20。" + "description": "每页条数，范围 1–100，默认 20。", + "minimum": 1, + "maximum": 100 }, "orderby": { "type": "string", @@ -5139,7 +5183,7 @@ "error_count", "severity" ], - "description": "排序字段；缺省时按 `updated_at` 排序。" + "description": "排序字段；缺省按 `updated_at` 排序。\n\n| 值 | 含义 |\n|---|---|\n| `created_at` | Issue 创建时间 |\n| `updated_at` | 最近更新时间 |\n| `session_count` | 受影响会话数 |\n| `error_count` | 错误发生次数 |\n| `severity` | 严重性等级（`Critical` > `Warning` > `Info`） |" }, "asc": { "type": "boolean", @@ -5194,7 +5238,7 @@ "ignored", "resolved" ], - "description": "新状态。设置为 `resolved` 时会记录解决时间与操作人；从 `resolved` 改回其他状态会清除解决信息。取值：`for_review`（待处理）、`reviewed`（已查看）、`ignored`（已忽略）、`resolved`（已解决）。" + "description": "新状态。设为 `resolved` 会记录解决时间与操作人；从 `resolved` 改为其他状态会将其清除。\n\n| 值 | 含义 |\n|---|---|\n| `for_review` | 待处理 |\n| `reviewed` | 已查看 |\n| `ignored` | 已忽略 |\n| `resolved` | 已解决 |" }, "suspected_cause": { "type": "string", @@ -5341,14 +5385,15 @@ "items": { "$ref": "#/components/schemas/SourcemapCodeSnippet" }, - "description": "该栈帧附近的源码片段。" + "description": "该帧附近的源码片段；未提取到片段时省略（如源码内容不可用或未传 `near`）。" }, "original_frame": { - "$ref": "#/components/schemas/SourcemapStackFrame" + "$ref": "#/components/schemas/SourcemapStackFrame", + "description": "enrich 前的原始混淆/压缩帧；处理器未保留时省略。" }, "third_party": { "type": "boolean", - "description": "该栈帧是否来自第三方或系统库。" + "description": "该帧是否来自第三方或系统库（仅 Android 与 native 符号化场景）；为 `false` 时省略。" } } } @@ -5364,11 +5409,13 @@ }, "type": { "type": "string", - "description": "平台类型：`browser`、`android` 或 `ios`。", + "description": "该记录所属的符号平台存储。JS 存储的行一律返回 `browser`（包括鸿蒙 ArkTS 与 React Native 的上传）；native 符号存储的行一律返回 `android`（包括鸿蒙 native 与 Electron 的上传）。\n\n| 值 | 存储 |\n|---|---|\n| `browser` | JS Sourcemap 存储 |\n| `android` | Android mapping 存储或共享的 native 符号存储 |\n| `ios` | iOS dSYM 存储 |\n| `miniprogram` | 微信小程序 Sourcemap 存储 |\n| `flutter` | Flutter Dart AOT 符号存储 |", "enum": [ "browser", "android", - "ios" + "ios", + "miniprogram", + "flutter" ] }, "service": { @@ -5404,8 +5451,20 @@ }, "metadata": { "type": "object", - "description": "附加在 sourcemap 上的自由格式键值元数据。具体结构取决于上传客户端，常见键包括 `git_repository_url` 和 `git_commit_sha`（这两个字段同时也会提升为顶层字段）。", + "description": "平台相关的元数据：`minified_url`（browser/react-native/harmony/miniprogram）；`build_id`、`variant`、`version_code`（android mapping），另含 `arch`、`lib_name`、`code_id`（android/harmony/electron native 符号）；`uuid`（ios）；`build_id`、`platform`、`arch`、`flavor`、`code_id`、`debug_id`（flutter）；`subpackage`、`minified_url`（miniprogram）。为空时省略。", "additionalProperties": true + }, + "minified_url": { + "type": "string", + "description": "已废弃。压缩后文件的 URL，仅 JS 与小程序记录返回；新集成请读取 `metadata.minified_url`。" + }, + "minified_path": { + "type": "string", + "description": "已废弃。压缩后文件的存储路径，仅 JS 记录返回。" + }, + "sourcemap_path": { + "type": "string", + "description": "已废弃。Sourcemap 文件的存储路径，仅 JS 与小程序记录返回。" } } }, @@ -5429,11 +5488,16 @@ }, "type": { "type": "string", - "description": "平台类型。省略时默认为 `browser`。取值：`browser`（浏览器 JS Sourcemap）、`android`（Android 符号文件，ProGuard/R8 mapping 或 NDK native 符号，可用 `kind` 区分）、`ios`（iOS dSYM 符号文件）。", + "description": "要查询的符号文件平台。省略时默认为 `browser`；传入其他值会返回空列表。\n\n| 值 | 查询的存储 |\n|---|---|\n| `browser` | JS Sourcemap（共享存储，不含鸿蒙 ArkTS 与 React Native 行） |\n| `android` | ProGuard/R8 mapping 文件；`kind=native` 时为 Android NDK .so 符号 |\n| `ios` | iOS dSYM 符号文件 |\n| `miniprogram` | 微信小程序 Sourcemap |\n| `react-native` | React Native JS Sourcemap |\n| `harmony` | 鸿蒙 ArkTS Sourcemap；`kind=native` 时为鸿蒙 .so 符号 |\n| `flutter` | Flutter Dart AOT 符号 |\n| `electron` | Electron Breakpad 符号 |", "enum": [ "browser", "android", - "ios" + "ios", + "miniprogram", + "react-native", + "harmony", + "flutter", + "electron" ] }, "services": { @@ -5441,26 +5505,39 @@ "items": { "type": "string" }, - "description": "按服务名称过滤，最多 100 个值。" + "description": "按服务名称过滤，最多 100 个值。", + "maxItems": 100 }, "versions": { "type": "array", "items": { "type": "string" }, - "description": "按版本字符串过滤，最多 100 个值。" + "description": "按版本字符串过滤，最多 100 个值。", + "maxItems": 100 }, "query": { "type": "string", - "description": "对 minified URL（browser）或 build_id（android）做子串匹配。最多 200 个字符。" + "description": "自由文本子串匹配。JS 类存储（browser/react-native/harmony/miniprogram）匹配 `minified_url`，android/flutter/electron 及 `kind=native` 的 harmony 匹配 `build_id`，ios 匹配 `uuid`（不区分大小写，忽略连字符）。", + "maxLength": 200 }, "build_id": { "type": "string", - "description": "仅 Android。按 Gradle 插件构建标识过滤。最多 200 个字符。" + "description": "仅 Android。按 Gradle 插件构建标识过滤。最多 200 个字符。", + "maxLength": 200 }, "uuid": { "type": "string", - "description": "仅 iOS。按 dSYM bundle UUID 过滤。最多 200 个字符。" + "description": "仅 iOS。按 dSYM bundle UUID 过滤。最多 200 个字符。", + "maxLength": 200 + }, + "kind": { + "type": "string", + "enum": [ + "mapping", + "native" + ], + "description": "符号类型过滤，仅 Android 与鸿蒙生效（其他平台忽略）：`mapping`（默认）列出 ProGuard/R8 mapping 或 ArkTS Sourcemap，`native` 列出 native .so 符号。" }, "p": { "type": "integer", @@ -5494,15 +5571,11 @@ "SourcemapListResponse": { "type": "object", "description": "Sourcemap 记录的分页列表。", - "required": [ - "total", - "items" - ], "properties": { "total": { "type": "integer", "format": "int64", - "description": "匹配记录总数。", + "description": "匹配记录总数；为 0 时省略。", "example": 3 }, "items": { @@ -5510,7 +5583,7 @@ "items": { "$ref": "#/components/schemas/SourcemapItem" }, - "description": "当前页的 Sourcemap（含 iOS dSYM、小程序 Sourcemap 等符号文件）记录列表。" + "description": "当前页的 Sourcemap 记录；为空时省略。" } } }, @@ -5531,9 +5604,18 @@ "miniprogram", "harmony", "flutter", - "electron" + "electron", + "react-native" + ], + "description": "错误来源平台，决定使用哪类符号存储。省略时默认按 `browser` 处理。\n\n| 值 | 符号化方式 |\n|---|---|\n| `browser` | JS 堆栈，Sourcemap 还原 |\n| `android` | Java/Kotlin 堆栈，ProGuard/R8 mapping 还原；native 堆栈走 NDK 符号（配合 `source_type=ndk` 与 `arch`） |\n| `ios` | iOS 崩溃堆栈，dSYM 符号化（需传 `binary_images`） |\n| `miniprogram` | 微信小程序堆栈，Sourcemap 还原 |\n| `harmony` | 鸿蒙堆栈，ArkTS Sourcemap 或 native 符号化 |\n| `flutter` | Flutter/Dart 堆栈，Dart AOT 符号还原 |\n| `electron` | Electron JS 堆栈，Sourcemap 还原；minidump native 帧走 Breakpad 符号（由 `source_type` 推导） |\n| `react-native` | React Native JS 堆栈，Sourcemap 还原；可用 `platform` 缩小查找范围 |" + }, + "platform": { + "type": "string", + "enum": [ + "ios", + "android" ], - "description": "来源平台。省略时默认按 `browser` 处理。取值：`browser`（浏览器 JS 堆栈，Sourcemap 还原）、`android`（Android 堆栈，mapping/NDK 符号化）、`ios`（iOS 崩溃堆栈，dSYM 符号化）、`miniprogram`（微信小程序堆栈，Sourcemap 还原）、`harmony`（鸿蒙堆栈，Sourcemap/native 符号化）、`flutter`（Flutter 堆栈，符号还原）、`electron`（Electron 堆栈，Sourcemap 还原）。" + "description": "将 `react-native` 的 enrich 限定到应用的 native 平台：`ios` 表示 iOS native 层，`android` 表示 Android native 层（控制台根据事件的 OS 推导）。其他 `type` 取值下忽略。" }, "service": { "type": "string", @@ -5676,7 +5758,8 @@ "ts": { "type": "integer", "format": "int64", - "description": "会话起始时间的 Unix 毫秒时间戳。可选；当 `session_id` 在不同时间窗口内被复用时用于区分。" + "description": "会话起始时间的 Unix 毫秒时间戳。可选；当 `session_id` 在不同时间窗口内被复用时用于区分。", + "exclusiveMinimum": 0 } } }, @@ -5714,16 +5797,18 @@ "type": "string", "enum": [ "browser", - "android", "ios", - "miniprogram", + "android", "react-native", "flutter", "kotlin-multiplatform", "roku", - "unity" + "unity", + "miniprogram", + "harmony", + "electron" ], - "description": "记录该会话的 SDK 平台。平台标识，取值为 `browser`、`android`、`ios`、`miniprogram`、`react-native`、`flutter`、`kotlin-multiplatform`、`roku`、`unity`。" + "description": "录制该会话的 SDK 平台。平台标识：\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 桌面应用 |" }, "start": { "type": "integer", @@ -5744,16 +5829,18 @@ "type": "string", "enum": [ "browser", - "android", "ios", - "miniprogram", + "android", "react-native", "flutter", "kotlin-multiplatform", "roku", - "unity" + "unity", + "miniprogram", + "harmony", + "electron" ], - "description": "记录该视图的 SDK 平台。平台标识，取值为 `browser`、`android`、`ios`、`miniprogram`、`react-native`、`flutter`、`kotlin-multiplatform`、`roku`、`unity`。" + "description": "录制该视图的 SDK 平台。平台标识：\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 桌面应用 |" }, "view_id": { "type": "string", @@ -5773,11 +5860,11 @@ }, "container_source": { "type": "string", - "description": "当该视图被嵌入时（如原生 App 内的 WebView），容器 App 的 SDK 平台。" + "description": "该视图嵌套展示时，容器应用的 SDK 平台（如原生应用内的 WebView）；未嵌套时省略。" }, "container_view_id": { "type": "string", - "description": "当该视图被嵌入时，所属容器视图的 ID。" + "description": "该视图嵌套展示时，容器视图的 View ID；未嵌套时省略。" }, "server_time_delta": { "type": "integer", @@ -5825,13 +5912,16 @@ "description": "会话的回放元数据：所属应用、设备、会话时间范围及全部录制视图。", "properties": { "application": { - "$ref": "#/components/schemas/RumReplayApplication" + "$ref": "#/components/schemas/RumReplayApplication", + "description": "会话所属的应用。" }, "device": { - "$ref": "#/components/schemas/RumReplayDevice" + "$ref": "#/components/schemas/RumReplayDevice", + "description": "录制该会话的设备。" }, "session": { - "$ref": "#/components/schemas/RumReplaySession" + "$ref": "#/components/schemas/RumReplaySession", + "description": "会话的起止时间与状态。" }, "views": { "type": "array", @@ -5871,7 +5961,8 @@ "ts": { "type": "integer", "format": "int64", - "description": "Unix 毫秒时间戳。设置该字段且 `search_after_ctx` 为空时，将从该时间点之前最近的一个全量快照分段开始，而非从头开始。" + "description": "Unix 毫秒时间戳。设置该字段且 `search_after_ctx` 为空时，将从该时间点之前最近的一个全量快照分段开始，而非从头开始。", + "exclusiveMinimum": 0 }, "url_mode": { "type": "boolean", @@ -6003,7 +6094,7 @@ "properties": { "id": { "type": "integer", - "format": "uint64", + "format": "int64", "description": "内部行 ID。" }, "account_id": { @@ -6771,7 +6862,7 @@ }, "id": { "type": "integer", - "format": "uint64", + "format": "int64", "description": "内部自增行 ID。历史回滚后会以新 ID 重新插入，因此该值在回滚前后并不稳定。" }, "deleted_at": { diff --git a/api-reference/safari.openapi.en.json b/api-reference/safari.openapi.en.json index e59ed418..07877eae 100644 --- a/api-reference/safari.openapi.en.json +++ b/api-reference/safari.openapi.en.json @@ -55,7 +55,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- `environment_kind` accepts only empty (automatic) or `byoc`; `cloud` is rejected. `byoc` requires `environment_id`, and the 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 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", "metadata": { "sidebarTitle": "Create A2A agent" @@ -120,8 +120,9 @@ "auth_type": "bearer", "streaming": true, "team_id": 0, - "environment_kind": "byoc", - "environment_id": "env_8s7Hn2kLpQ3xYbVc4Wd2m" + "environments": [ + "env_8s7Hn2kLpQ3xYbVc4Wd2m" + ] } } } @@ -412,8 +413,9 @@ "account_id": 10023, "team_id": 0, "can_edit": true, - "environment_kind": "", - "environment_id": "", + "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", @@ -513,8 +515,9 @@ "account_id": 10023, "team_id": 0, "can_edit": true, - "environment_kind": "", - "environment_id": "", + "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", @@ -664,7 +667,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` is immutable after creation.\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 | 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", "metadata": { "sidebarTitle": "Create Automation rule" @@ -917,7 +920,6 @@ "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, @@ -1030,7 +1032,6 @@ "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, @@ -1193,7 +1194,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` cannot be changed from its current value.\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 | 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", "metadata": { "sidebarTitle": "Update Automation rule" @@ -1347,6 +1348,8 @@ "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", @@ -1507,7 +1510,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 the account (case-insensitive); violations return InvalidParameter.\n- `environment_kind` accepts only `byoc` (with `environment_id`) or empty for automatic selection — `cloud` cannot be bound directly to an MCP server.\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 | **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", "metadata": { "sidebarTitle": "Create MCP server" @@ -1540,8 +1543,7 @@ "account_id": 10023, "team_id": 0, "can_edit": true, - "environment_kind": "", - "environment_id": "", + "environments": [], "server_name": "prometheus", "description": "Query Prometheus metrics and alerts.", "transport": "streamable-http", @@ -1549,17 +1551,6 @@ "status": "enabled", "connect_timeout": 10, "call_timeout": 60, - "tool_count": 2, - "tools": [ - { - "name": "query", - "description": "Run a PromQL instant query." - }, - { - "name": "query_range", - "description": "Run a PromQL range query." - } - ], "auth_mode": "shared", "created_by": 80011, "created_at": 1716960000000, @@ -1845,7 +1836,7 @@ "post": { "operationId": "mcp-read-server-get", "summary": "Get MCP server detail", - "description": "Get one MCP server and run a live probe of its tool list.", + "description": "Get one MCP server as a pure database read — no live probe is performed.", "tags": [ "AI SRE/MCP servers" ], @@ -1855,7 +1846,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 detail call live-probes tools; on failure `list_error` is set and the request still succeeds.\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 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", "metadata": { "sidebarTitle": "Get MCP server detail" @@ -1888,8 +1879,7 @@ "account_id": 10023, "team_id": 0, "can_edit": true, - "environment_kind": "", - "environment_id": "", + "environments": [], "server_name": "prometheus", "description": "Query Prometheus metrics and alerts.", "transport": "streamable-http", @@ -1897,17 +1887,6 @@ "status": "enabled", "connect_timeout": 10, "call_timeout": 60, - "tool_count": 2, - "tools": [ - { - "name": "query", - "description": "Run a PromQL instant query." - }, - { - "name": "query_range", - "description": "Run a PromQL range query." - } - ], "auth_mode": "shared", "created_by": 80011, "created_at": 1716960000000, @@ -1959,7 +1938,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 live tool list is not included; fetch a single server to probe its tools.\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- 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", "metadata": { "sidebarTitle": "List MCP servers" @@ -1995,8 +1974,7 @@ "account_id": 10023, "team_id": 0, "can_edit": true, - "environment_kind": "", - "environment_id": "", + "environments": [], "server_name": "prometheus", "description": "Query Prometheus metrics and alerts.", "transport": "streamable-http", @@ -2004,17 +1982,6 @@ "status": "enabled", "connect_timeout": 10, "call_timeout": 60, - "tool_count": 2, - "tools": [ - { - "name": "query", - "description": "Run a PromQL instant query." - }, - { - "name": "query_range", - "description": "Run a PromQL range query." - } - ], "auth_mode": "shared", "created_by": 80011, "created_at": 1716960000000, @@ -2070,7 +2037,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- `environment_kind`/`environment_id` are independent partial-update fields: omit both to leave the runner binding unchanged; set either to change it, subject to the same `byoc`-or-empty constraint as create.\n- Changing `team_id` requires reassignment permission on the destination team; if the runner binding is left unchanged, it 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 | **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", "metadata": { "sidebarTitle": "Update MCP server" @@ -2103,8 +2070,7 @@ "account_id": 10023, "team_id": 0, "can_edit": true, - "environment_kind": "", - "environment_id": "", + "environments": [], "server_name": "prometheus", "description": "Query Prometheus metrics, alerts, and rules.", "transport": "streamable-http", @@ -2112,17 +2078,6 @@ "status": "enabled", "connect_timeout": 10, "call_timeout": 60, - "tool_count": 2, - "tools": [ - { - "name": "query", - "description": "Run a PromQL instant query." - }, - { - "name": "query_range", - "description": "Run a PromQL range query." - } - ], "auth_mode": "shared", "created_by": 80011, "created_at": 1716960000000, @@ -3189,8 +3144,7 @@ "updated_at": 1717046400000, "can_edit": true, "update_available": false, - "is_modified": false, - "created": true + "is_modified": false } } } @@ -4205,8 +4159,8 @@ }, "instructions": { "type": "string", - "description": "Natural-language instructions for the remote agent. Required — a deprecated `description` field is still accepted for legacy clients and, if both are sent, must exactly match `instructions`.", - "maxLength": 2000 + "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 }, "card_url": { "type": "string", @@ -4214,14 +4168,19 @@ }, "auth_type": { "type": "string", - "description": "Authentication type for reaching the remote agent: `none`, `api_key`, or `bearer`." + "description": "Authentication type for reaching the remote agent: `none` (default when omitted), `api_key`, or `bearer`.", + "enum": [ + "none", + "api_key", + "bearer" + ] }, "auth_config": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "Authentication config key-values, e.g. the API key or bearer token. Values for sensitive keys (`api_key`, `token`, `client_secret`) are masked back in responses." + "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." }, "streaming": { "type": "boolean", @@ -4232,17 +4191,12 @@ "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" }, - "environment_kind": { - "type": "string", - "enum": [ - "", - "byoc" - ], - "description": "Execution environment binding. Omit or send empty for automatic routing; `byoc` pins the agent to a specific runner given by `environment_id`. `cloud` is not accepted — configured A2A agents need a persistent runner, not a disposable cloud sandbox." - }, - "environment_id": { - "type": "string", - "description": "BYOC runner ID. Required when `environment_kind=byoc`; the runner must belong to the account or a team the caller belongs to." + "environments": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Execution environments this agent is callable from: `cloud` and/or BYOC runner environment IDs. Omitted or empty means all environments." }, "auth_mode": { "type": "string", @@ -4319,17 +4273,12 @@ "type": "boolean", "description": "Whether the caller may edit this agent." }, - "environment_kind": { - "type": "string", - "enum": [ - "", - "byoc" - ], - "description": "Execution environment binding. Empty selects automatic routing; `byoc` pins the agent to a specific runner named by `environment_id`." - }, - "environment_id": { - "type": "string", - "description": "BYOC runner ID. Set only when `environment_kind=byoc`; empty otherwise." + "environments": { + "type": "array", + "items": { + "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": { "type": "string", @@ -4338,7 +4287,7 @@ "instructions": { "type": "string", "description": "Natural-language instructions for the remote agent (formerly named `description`).", - "maxLength": 2000 + "maxLength": 51200 }, "card_url": { "type": "string", @@ -4346,14 +4295,20 @@ }, "auth_type": { "type": "string", - "description": "Authentication type for reaching the remote agent: `none`, `api_key`, or `bearer`." + "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`.", + "enum": [ + "", + "none", + "api_key", + "bearer" + ] }, "auth_config": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "Authentication config; sensitive values (`api_key`, `token`, `client_secret`) are masked." + "description": "Authentication config key-values. Values under credential-looking keys (name containing KEY, SECRET, TOKEN, PASSWORD, etc.) are masked. Omitted when empty." }, "streaming": { "type": "boolean", @@ -4369,14 +4324,14 @@ }, "agent_card_name": { "type": "string", - "description": "Agent name resolved from the remote card." + "description": "Agent name resolved from the remote card. Omitted until the card has been fetched." }, "agent_card_skills": { "type": "array", "items": { "type": "string" }, - "description": "Skills advertised by the remote card." + "description": "Skills advertised by the remote card. Omitted until the card has been fetched." }, "card_resolve_timeout": { "type": "integer", @@ -4432,8 +4387,6 @@ "account_id", "team_id", "can_edit", - "environment_kind", - "environment_id", "agent_name", "instructions", "card_url", @@ -4444,7 +4397,8 @@ "task_timeout", "created_by", "created_at", - "updated_at" + "updated_at", + "environments" ] }, "A2AAgentListRequest": { @@ -4536,8 +4490,8 @@ "string", "null" ], - "description": "New instructions. Omit to leave unchanged. A deprecated `description` field is also accepted; if both are sent they must match.", - "maxLength": 2000 + "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 }, "card_url": { "type": [ @@ -4551,14 +4505,19 @@ "string", "null" ], - "description": "New auth type. Omit to leave unchanged." + "description": "New auth type: `none`, `api_key`, or `bearer`. Omit to leave unchanged.", + "enum": [ + "none", + "api_key", + "bearer" + ] }, "auth_config": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "Replace the auth config. Omit to leave unchanged. Sending back the masked value (or an empty string) for a sensitive key keeps the stored secret instead of overwriting it." + "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": [ @@ -4575,19 +4534,15 @@ "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" }, - "environment_kind": { - "type": [ - "string", - "null" - ], - "description": "New execution environment binding: empty for automatic, `byoc` for a specific runner. `cloud` is rejected. Omit to leave unchanged." - }, - "environment_id": { + "environments": { "type": [ - "string", + "array", "null" ], - "description": "New BYOC runner ID. Required alongside `environment_kind=byoc`. Omit to leave unchanged." + "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." }, "auth_mode": { "type": [ @@ -4643,7 +4598,7 @@ "type": "integer", "format": "int64", "minimum": 0, - "description": "Scope team ID. 0 or omitted means a personal rule; >0 means a team in the account. Immutable after creation." + "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)." }, "enabled": { "type": "boolean", @@ -4797,7 +4752,7 @@ }, "schedule_trigger_id": { "type": "string", - "description": "Schedule trigger ID." + "description": "Schedule trigger ID. Omitted if the rule has no schedule trigger." }, "schedule_trigger_enabled": { "type": "boolean", @@ -4805,11 +4760,11 @@ }, "http_post_trigger_id": { "type": "string", - "description": "HTTP POST trigger ID." + "description": "HTTP POST trigger ID. Omitted when the rule has no HTTP POST trigger." }, "http_post_trigger_url": { "type": "string", - "description": "HTTP POST trigger path." + "description": "HTTP POST trigger path. Omitted when the rule has no HTTP POST trigger." }, "http_post_trigger_enabled": { "type": "boolean", @@ -4817,7 +4772,7 @@ }, "oncall_incident_trigger_id": { "type": "string", - "description": "On-call incident trigger ID." + "description": "On-call incident trigger ID. Omitted when the rule has no On-call incident trigger." }, "oncall_incident_trigger_enabled": { "type": "boolean", @@ -4830,7 +4785,7 @@ "format": "int64", "minimum": 1 }, - "description": "On-call integration IDs to watch. Creating or enabling this trigger requires at least one valid ID." + "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." }, "oncall_incident_severities": { "type": "array", @@ -4842,7 +4797,7 @@ "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. 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." }, "http_post_token": { "type": "string", @@ -4902,7 +4857,6 @@ "limit": { "type": "integer", "default": 20, - "maximum": 100, "description": "Page size." }, "scope": { @@ -4987,7 +4941,7 @@ ], "format": "int64", "minimum": 0, - "description": "Only the current value is accepted; personal/team scope is immutable after creation." + "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." }, "enabled": { "type": [ @@ -5095,9 +5049,20 @@ "type": "string", "description": "Run ID." }, + "session_id": { + "type": "string", + "description": "Session created for this run, extracted from `result_json`. Omitted when the run has not (yet) started a session." + }, + "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." + }, "kind": { "type": "string", - "description": "Run kind." + "description": "Run kind; runs listed for a rule are always `automation_rule`.", + "enum": [ + "automation_rule" + ] }, "account_id": { "type": "integer", @@ -5133,9 +5098,10 @@ "partial", "failed", "skipped", - "abandoned" + "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) |" + "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`) |" }, "attempts": { "type": "integer", @@ -5158,17 +5124,27 @@ }, "error_code": { "type": "string", - "description": "Error code." + "description": "Error code; empty when the run did not fail." }, "error_message": { "type": "string", - "description": "Error message." + "description": "Error message; empty when the run did not fail." }, "stats_json": { - "description": "Run stats JSON." + "type": [ + "object", + "null" + ], + "additionalProperties": true, + "description": "Raw run statistics JSON; null when empty." }, "result_json": { - "description": "Run result JSON." + "type": [ + "object", + "null" + ], + "additionalProperties": true, + "description": "Raw run result JSON (carries the run's `session_id` once started); null when empty." }, "created_at": { "type": "integer", @@ -5194,7 +5170,11 @@ "completed_at", "duration_ms", "created_at", - "updated_at" + "updated_at", + "error_code", + "error_message", + "stats_json", + "result_json" ] }, "AutomationRunListRequest": { @@ -5212,7 +5192,6 @@ "limit": { "type": "integer", "default": 20, - "maximum": 100, "description": "Page size." }, "status": { @@ -5225,9 +5204,10 @@ "partial", "failed", "skipped", - "abandoned" + "abandoned", + "blocked" ], - "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); omit for no filter." + "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": { "type": "string", @@ -5243,12 +5223,14 @@ "started_after_ms": { "type": "integer", "format": "int64", - "description": "Start-time lower bound, Unix milliseconds." + "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." + "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": [ @@ -5310,7 +5292,7 @@ }, "enabled": { "type": "boolean", - "description": "Whether the template is enabled." + "description": "Whether a rule created from this template starts out enabled (prefill value)." }, "prompt": { "type": "string", @@ -5590,7 +5572,7 @@ "properties": { "server_name": { "type": "string", - "description": "MCP server name, unique within the account.", + "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.", "minLength": 1, "maxLength": 255 }, @@ -5672,16 +5654,12 @@ "description": "Team scope: 0 = account-wide; >0 = team.", "format": "int64" }, - "environment_kind": { - "type": "string", - "description": "Pin the server to a specific BYOC runner (`environment_id` required). Omit or send empty for automatic selection; `cloud` is not supported for MCP servers. The only accepted value: `byoc` (a self-hosted BYOC runner in the account; the MCP server process runs on the customer's own infrastructure).", - "enum": [ - "byoc" - ] - }, - "environment_id": { - "type": "string", - "description": "Runner ID; required when environment_kind is byoc." + "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", @@ -5750,21 +5728,16 @@ "type": "boolean", "description": "Whether the caller may edit this server." }, - "environment_kind": { - "type": "string", - "description": "Runtime environment kind: empty for automatic selection, or `byoc` when pinned to a specific runner. `cloud` cannot be bound to an MCP server.", - "enum": [ - "", - "byoc" - ] - }, - "environment_id": { - "type": "string", - "description": "Runner ID when environment_kind is byoc; empty otherwise." + "environments": { + "type": "array", + "items": { + "type": "string" + }, + "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)." }, "server_name": { "type": "string", - "description": "MCP server name, unique within the account." + "description": "MCP server name, unique within its scope (account-wide or one team), case-insensitive." }, "description": { "type": "string", @@ -5772,7 +5745,7 @@ }, "ai_description": { "type": "string", - "description": "LLM-generated description, preferred over `description` when present." + "description": "LLM-generated description, preferred over `description` when present. Omitted when not yet generated." }, "transport": { "type": "string", @@ -5834,26 +5807,11 @@ }, "allow_insecure_oauth_http": { "type": "boolean", - "description": "Allow this server's OAuth token exchange over plaintext HTTP; testing use only." + "description": "Allow this server's OAuth token exchange over plaintext HTTP; testing use only. Omitted when false." }, "allow_insecure_tls_skip_verify": { "type": "boolean", - "description": "Skip TLS certificate verification when connecting to this server; testing use only." - }, - "tools": { - "type": "array", - "items": { - "$ref": "#/components/schemas/MCPToolInfo" - }, - "description": "Live tool list; populated by the get/test endpoints." - }, - "tool_count": { - "type": "integer", - "description": "Number of tools in the live list." - }, - "list_error": { - "type": "string", - "description": "Error message when the live tool list failed." + "description": "Skip TLS certificate verification when connecting to this server; testing use only. Omitted when false." }, "auth_mode": { "type": "string", @@ -5897,8 +5855,6 @@ "account_id", "team_id", "can_edit", - "environment_kind", - "environment_id", "server_name", "description", "transport", @@ -5907,7 +5863,8 @@ "call_timeout", "created_by", "created_at", - "updated_at" + "updated_at", + "environments" ] }, "MCPServerListRequest": { @@ -6035,7 +5992,7 @@ "additionalProperties": { "type": "string" }, - "description": "Environment variables (`stdio` transport); replaces the whole map, but masked secret values sent back as-is keep their stored values; omit to leave unchanged." + "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." }, "url": { "type": "string", @@ -6046,7 +6003,7 @@ "additionalProperties": { "type": "string" }, - "description": "HTTP headers (sse / streamable-http)." + "description": "HTTP headers (`sse` / `streamable-http` transport); replaces the whole map, with the same masked/empty-value preservation as `env`; omit to leave unchanged." }, "connect_timeout": { "type": "integer", @@ -6076,19 +6033,15 @@ "description": "Reassign team scope: 0 = account-wide; >0 = team. Omit to leave unchanged.", "format": "int64" }, - "environment_kind": { + "environments": { "type": [ - "string", + "array", "null" ], - "description": "Reassign the runner binding: `byoc` (with environment_id) or empty string to reset to automatic selection. Omit (null) to leave the current binding unchanged." - }, - "environment_id": { - "type": [ - "string", - "null" - ], - "description": "Runner ID paired with environment_kind=byoc. Omit (null) to leave the current binding unchanged." + "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." }, "allow_insecure_oauth_http": { "type": [ @@ -6109,29 +6062,6 @@ "server_id" ] }, - "MCPToolInfo": { - "type": "object", - "description": "Metadata for one tool exposed by an MCP server.", - "properties": { - "name": { - "type": "string", - "description": "Tool name." - }, - "description": { - "type": "string", - "description": "Tool description." - }, - "input_schema": { - "type": "object", - "additionalProperties": true, - "description": "JSON Schema describing the tool's input parameters." - } - }, - "required": [ - "name", - "description" - ] - }, "ManualRunRuleResult": { "type": "object", "description": "Result of manually running an Automation rule outside its schedule.", @@ -6487,7 +6417,7 @@ "pinned_at": { "type": "integer", "format": "int64", - "description": "Caller's per-user pin timestamp in milliseconds; 0 means not pinned." + "description": "Caller's per-user pin time as a Unix timestamp in milliseconds; 0 means not pinned." }, "last_event_at": { "type": "integer", @@ -6594,7 +6524,7 @@ }, "asc": { "type": "boolean", - "description": "Ascending order when true, descending when false; also applies when `orderby` is omitted (sorted by `updated_at`)." + "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", @@ -6754,7 +6684,7 @@ }, "skill_name": { "type": "string", - "description": "Skill name, unique within the account." + "description": "Skill name, unique within its scope (account-wide or within one team)." }, "description": { "type": "string", @@ -6794,6 +6724,13 @@ }, "description": "Required tools (builtin or `mcp:server/tool`)." }, + "venues": { + "type": "array", + "items": { + "type": "string" + }, + "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." + }, "s3_key": { "type": "string", "description": "Object-storage key of the skill zip." @@ -7035,7 +6972,7 @@ }, "team_name": { "type": "string", - "description": "Display name of the owning team (team scope only); empty for account scope." + "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", @@ -7196,7 +7133,7 @@ }, "query": { "type": "string", - "description": "Case-insensitive substring filter over pack ID, scope, and team name.", + "description": "Case-insensitive substring filter over pack ID, scope, scope ID/account ID, and team name.", "maxLength": 128 }, "team_ids": { @@ -7254,8 +7191,7 @@ "description": "Destination scope; omit for a no-op that returns the current pack.", "enum": [ "account", - "team", - null + "team" ] }, "scope_id": { @@ -7307,11 +7243,11 @@ }, "p": { "type": "integer", - "description": "Page number, 1-based." + "description": "Page number, 1-based. Accepted but currently ignored — the response always contains the full file list." }, "limit": { "type": "integer", - "description": "Page size." + "description": "Page size. Accepted but currently ignored — the response always contains the full file list." } } }, @@ -7346,7 +7282,7 @@ }, "content_b64": { "type": "string", - "description": "Base64-encoded file content; must decode to valid UTF-8 text." + "description": "Base64-encoded file content; must decode to valid UTF-8 text (binary is rejected). Per-file limit 1 MiB." }, "content_type": { "type": "string", diff --git a/api-reference/safari.openapi.zh.json b/api-reference/safari.openapi.zh.json index cb59532e..fb0fba52 100644 --- a/api-reference/safari.openapi.zh.json +++ b/api-reference/safari.openapi.zh.json @@ -55,7 +55,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- `environment_kind` 仅接受空字符串（自动）或 `byoc`；`cloud` 将被拒绝。`byoc` 需要 `environment_id`，且该 Runner 对调用者可见。\n- 创建到某个团队（`team_id > 0`）需要调用者真实属于该团队；只有账户 owner/admin 可以在账户级（`team_id=0`）创建。\n- 每次调用都会记录到账户审计日志。\n", + "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", "metadata": { "sidebarTitle": "创建 A2A 智能体" @@ -120,8 +120,9 @@ "auth_type": "bearer", "streaming": true, "team_id": 0, - "environment_kind": "byoc", - "environment_id": "env_8s7Hn2kLpQ3xYbVc4Wd2m" + "environments": [ + "env_8s7Hn2kLpQ3xYbVc4Wd2m" + ] } } } @@ -412,8 +413,9 @@ "account_id": 10023, "team_id": 0, "can_edit": true, - "environment_kind": "", - "environment_id": "", + "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", @@ -513,8 +515,9 @@ "account_id": 10023, "team_id": 0, "can_edit": true, - "environment_kind": "", - "environment_id": "", + "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", @@ -664,7 +667,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 有效 `app_key`；管理操作要求调用者可管理目标规则 |\n\n## 使用说明\n\n- 可以创建个人规则，也可以创建当前账户下任意团队的规则；`team_id` 创建后不可修改。\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| 权限要求 | 有效 `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", "metadata": { "sidebarTitle": "创建自动化规则" @@ -917,7 +920,6 @@ "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, @@ -1030,7 +1032,6 @@ "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, @@ -1193,7 +1194,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 有效 `app_key`；管理操作要求调用者可管理目标规则 |\n\n## 使用说明\n\n- 省略或传 `null` 的字段保持不变；`team_id` 不能修改为与当前值不同的值。\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| 权限要求 | 有效 `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", "metadata": { "sidebarTitle": "更新自动化规则" @@ -1347,6 +1348,8 @@ "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", @@ -1507,7 +1510,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- `environment_kind` 仅支持 `byoc`（需同时提供 `environment_id`）或留空表示自动选择——MCP 服务器不支持直接绑定 `cloud`。\n- `per_user_secret` 认证模式要求 `secret_schema` 为合法 JSON 且包含非空的 `header_name`。\n- 每次调用都会记录到账户审计日志。\n", + "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", "metadata": { "sidebarTitle": "创建 MCP 服务器" @@ -1540,8 +1543,7 @@ "account_id": 10023, "team_id": 0, "can_edit": true, - "environment_kind": "", - "environment_id": "", + "environments": [], "server_name": "prometheus", "description": "Query Prometheus metrics and alerts.", "transport": "streamable-http", @@ -1549,17 +1551,6 @@ "status": "enabled", "connect_timeout": 10, "call_timeout": 60, - "tool_count": 2, - "tools": [ - { - "name": "query", - "description": "Run a PromQL instant query." - }, - { - "name": "query_range", - "description": "Run a PromQL range query." - } - ], "auth_mode": "shared", "created_by": 80011, "created_at": 1716960000000, @@ -1845,7 +1836,7 @@ "post": { "operationId": "mcp-read-server-get", "summary": "查看 MCP 服务器详情", - "description": "查看单个 MCP 服务器并实时探测其工具列表。", + "description": "查看单个 MCP 服务器（纯数据库读取，不实时探测远端服务器）。", "tags": [ "AI SRE/MCP 服务器" ], @@ -1855,7 +1846,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 详情接口会实时探测工具；探测失败时设置 `list_error`，请求本身仍成功。\n", + "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", "metadata": { "sidebarTitle": "查看 MCP 服务器详情" @@ -1888,8 +1879,7 @@ "account_id": 10023, "team_id": 0, "can_edit": true, - "environment_kind": "", - "environment_id": "", + "environments": [], "server_name": "prometheus", "description": "Query Prometheus metrics and alerts.", "transport": "streamable-http", @@ -1897,17 +1887,6 @@ "status": "enabled", "connect_timeout": 10, "call_timeout": 60, - "tool_count": 2, - "tools": [ - { - "name": "query", - "description": "Run a PromQL instant query." - }, - { - "name": "query_range", - "description": "Run a PromQL range query." - } - ], "auth_mode": "shared", "created_by": 80011, "created_at": 1716960000000, @@ -1959,7 +1938,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| 速率限制 | 每个 `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", "metadata": { "sidebarTitle": "查询 MCP 服务器列表" @@ -1995,8 +1974,7 @@ "account_id": 10023, "team_id": 0, "can_edit": true, - "environment_kind": "", - "environment_id": "", + "environments": [], "server_name": "prometheus", "description": "Query Prometheus metrics and alerts.", "transport": "streamable-http", @@ -2004,17 +1982,6 @@ "status": "enabled", "connect_timeout": 10, "call_timeout": 60, - "tool_count": 2, - "tools": [ - { - "name": "query", - "description": "Run a PromQL instant query." - }, - { - "name": "query_range", - "description": "Run a PromQL range query." - } - ], "auth_mode": "shared", "created_by": 80011, "created_at": 1716960000000, @@ -2070,7 +2037,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- `env`/`headers` 中的脱敏密钥会被保留——回传脱敏值不会覆盖已存储的真实密钥。\n- `environment_kind`/`environment_id` 是相互独立的部分更新字段：两者都省略表示运行器绑定不变；设置任一字段即可修改绑定，约束与创建时相同（byoc 或留空）。\n- 变更 `team_id` 需要对目标团队具有重新分配权限；若运行器绑定未随之修改，则该绑定在新团队下仍须对调用者可选，否则更新会被拒绝。\n- 每次调用都会记录到账户审计日志。\n", + "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", "metadata": { "sidebarTitle": "更新 MCP 服务器" @@ -2103,8 +2070,7 @@ "account_id": 10023, "team_id": 0, "can_edit": true, - "environment_kind": "", - "environment_id": "", + "environments": [], "server_name": "prometheus", "description": "Query Prometheus metrics, alerts, and rules.", "transport": "streamable-http", @@ -2112,17 +2078,6 @@ "status": "enabled", "connect_timeout": 10, "call_timeout": 60, - "tool_count": 2, - "tools": [ - { - "name": "query", - "description": "Run a PromQL instant query." - }, - { - "name": "query_range", - "description": "Run a PromQL range query." - } - ], "auth_mode": "shared", "created_by": 80011, "created_at": 1716960000000, @@ -3189,8 +3144,7 @@ "updated_at": 1717046400000, "can_edit": true, "update_available": false, - "is_modified": false, - "created": true + "is_modified": false } } } @@ -4205,8 +4159,8 @@ }, "instructions": { "type": "string", - "description": "远程智能体的自然语言指令。必填 —— 已弃用的 `description` 字段仍保留以兼容旧客户端，若两者同时传入则必须与 `instructions` 完全一致。", - "maxLength": 2000 + "description": "远程智能体的自然语言指令：Markdown 文档，可带 `summary` frontmatter，正文非空，最大 50 KiB（51200 字节）。必填 —— 已弃用的 `description` 字段仍保留以兼容旧客户端，若两者同时传入则必须与 `instructions` 完全一致。", + "maxLength": 51200 }, "card_url": { "type": "string", @@ -4214,14 +4168,19 @@ }, "auth_type": { "type": "string", - "description": "访问远程智能体的认证类型：`none`、`api_key` 或 `bearer`。" + "description": "访问远程智能体的认证类型：`none`（省略时默认）、`api_key` 或 `bearer`。", + "enum": [ + "none", + "api_key", + "bearer" + ] }, "auth_config": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "认证配置键值对，如 API Key 或 Bearer Token。敏感键（`api_key`、`token`、`client_secret`）的值在返回时会被挖码。" + "description": "认证配置键值，例如 API key 或 bearer token。键名疑似凭据（包含 KEY、SECRET、TOKEN、PASSWORD 等）的值在响应中会被脱敏。" }, "streaming": { "type": "boolean", @@ -4232,17 +4191,12 @@ "description": "团队范围：0 = 账户级；>0 = 团队。在账户级创建需要 owner/admin 角色；创建到某个团队需要真实属于该团队。", "format": "int64" }, - "environment_kind": { - "type": "string", - "enum": [ - "", - "byoc" - ], - "description": "执行环境绑定。省略或传空字符串表示自动路由；`byoc` 将智能体固定到 `environment_id` 指定的 Runner。不接受 `cloud` —— 已配置的 A2A 智能体需要持久 Runner，而非一次性云沙箱。" - }, - "environment_id": { - "type": "string", - "description": "BYOC Runner ID。当 `environment_kind=byoc` 时必填；该 Runner 必须属于账户或调用者所属的团队。" + "environments": { + "type": "array", + "items": { + "type": "string" + }, + "description": "该智能体可运行的执行环境：`cloud` 和/或 BYOC Runner 的环境 ID 列表。省略或为空表示所有环境。" }, "auth_mode": { "type": "string", @@ -4319,17 +4273,12 @@ "type": "boolean", "description": "调用者是否可以编辑该智能体。" }, - "environment_kind": { - "type": "string", - "enum": [ - "", - "byoc" - ], - "description": "执行环境绑定。空字符串表示自动路由；`byoc` 表示固定到 `environment_id` 指定的 Runner。" - }, - "environment_id": { - "type": "string", - "description": "BYOC Runner ID。仅在 `environment_kind=byoc` 时设置，否则为空。" + "environments": { + "type": "array", + "items": { + "type": "string" + }, + "description": "该智能体可运行的执行环境（`cloud` 和/或 BYOC Runner 的环境 ID）。始终返回；`[]` 表示所有环境（该字段引入前的历史数据也是空数组）。" }, "agent_name": { "type": "string", @@ -4338,7 +4287,7 @@ "instructions": { "type": "string", "description": "远程智能体的自然语言指令（旧名 `description`）。", - "maxLength": 2000 + "maxLength": 51200 }, "card_url": { "type": "string", @@ -4346,14 +4295,20 @@ }, "auth_type": { "type": "string", - "description": "访问远程智能体的认证类型：`none`、`api_key` 或 `bearer`。" + "description": "访问远程智能体的认证类型：`none`、`api_key` 或 `bearer`。校验收紧前创建的历史数据可能返回空字符串，等价于 `none`。", + "enum": [ + "", + "none", + "api_key", + "bearer" + ] }, "auth_config": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "认证配置；敏感值（`api_key`、`token`、`client_secret`）会被挖码。" + "description": "认证配置键值。键名疑似凭据（包含 KEY、SECRET、TOKEN、PASSWORD 等）的值会被脱敏；为空时省略。" }, "streaming": { "type": "boolean", @@ -4369,14 +4324,14 @@ }, "agent_card_name": { "type": "string", - "description": "从远程卡片解析得到的智能体名称。" + "description": "从远程卡片解析得到的智能体名称；卡片尚未拉取时省略。" }, "agent_card_skills": { "type": "array", "items": { "type": "string" }, - "description": "远程卡片宣告的技能。" + "description": "远程卡片宣告的技能；卡片尚未拉取时省略。" }, "card_resolve_timeout": { "type": "integer", @@ -4432,8 +4387,6 @@ "account_id", "team_id", "can_edit", - "environment_kind", - "environment_id", "agent_name", "instructions", "card_url", @@ -4444,7 +4397,8 @@ "task_timeout", "created_by", "created_at", - "updated_at" + "updated_at", + "environments" ] }, "A2AAgentListRequest": { @@ -4536,8 +4490,8 @@ "string", "null" ], - "description": "新的指令。省略则保持不变。已弃用的 `description` 字段仍可传入，若两者同时传入则必须一致。", - "maxLength": 2000 + "description": "新的指令文档（约定同创建：可带 `summary` frontmatter，正文非空，最大 50 KiB）。省略则保持不变。已弃用的 `description` 字段仍可传入，若两者同时传入则必须一致。", + "maxLength": 51200 }, "card_url": { "type": [ @@ -4551,14 +4505,19 @@ "string", "null" ], - "description": "新的认证类型。省略则保持不变。" + "description": "新的认证类型：`none`、`api_key` 或 `bearer`。省略则保持不变。", + "enum": [ + "none", + "api_key", + "bearer" + ] }, "auth_config": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "替换认证配置。省略则保持不变。对敏感键回传挖码值（或空字符串）将保留已存储的密钥而非覆盖。" + "description": "整体替换认证配置；省略则保持不变。未包含在 map 中的键会被删除。敏感键回传掩码值时保留已存储的密钥，传空字符串则清除该密钥。" }, "streaming": { "type": [ @@ -4575,19 +4534,15 @@ "description": "重新分配团队范围。省略则保持不变。重新分配需要对目标团队的权限；若团队变更且未同时传入新的环境绑定，则现有 Runner 绑定必须对调用者仍可选，否则更新将被拒绝。", "format": "int64" }, - "environment_kind": { - "type": [ - "string", - "null" - ], - "description": "新的执行环境绑定：空字符串表示自动，`byoc` 表示指定 Runner。不接受 `cloud`。省略则保持不变。" - }, - "environment_id": { + "environments": { "type": [ - "string", + "array", "null" ], - "description": "新的 BYOC Runner ID。与 `environment_kind=byoc` 一同传入。省略则保持不变。" + "items": { + "type": "string" + }, + "description": "该智能体可运行的执行环境：`cloud` 和/或 BYOC Runner 的环境 ID 列表。省略（null）表示保持不变；传入列表即整体设置——空列表表示清除限制、恢复为所有环境。" }, "auth_mode": { "type": [ @@ -4643,7 +4598,7 @@ "type": "integer", "format": "int64", "minimum": 0, - "description": "作用域团队 ID。0 或省略表示个人规则；>0 表示账户下某团队。创建后不可修改。" + "description": "作用域团队 ID。0 或省略表示个人规则；>0 表示账户下某团队。之后可通过 update 改派（团队规则转个人仅规则 owner 可操作；转入团队要求调用者属于该团队）。" }, "enabled": { "type": "boolean", @@ -4797,7 +4752,7 @@ }, "schedule_trigger_id": { "type": "string", - "description": "Schedule trigger ID。" + "description": "定时触发器 ID；规则没有定时触发器时省略。" }, "schedule_trigger_enabled": { "type": "boolean", @@ -4805,11 +4760,11 @@ }, "http_post_trigger_id": { "type": "string", - "description": "HTTP POST trigger ID。" + "description": "HTTP POST 触发器 ID；规则没有 HTTP POST 触发器时省略。" }, "http_post_trigger_url": { "type": "string", - "description": "HTTP POST 触发路径。" + "description": "HTTP POST 触发器路径；规则没有 HTTP POST 触发器时省略。" }, "http_post_trigger_enabled": { "type": "boolean", @@ -4817,7 +4772,7 @@ }, "oncall_incident_trigger_id": { "type": "string", - "description": "On-call 故障触发器 ID。" + "description": "On-call 故障触发器 ID；规则没有 On-call 故障触发器时省略。" }, "oncall_incident_trigger_enabled": { "type": "boolean", @@ -4830,7 +4785,7 @@ "format": "int64", "minimum": 1 }, - "description": "监听的 On-call 集成 ID 列表；创建或启用该触发器时至少需要一个有效 ID。" + "description": "要监听的 On-call 渠道 ID。创建或启用该触发器至少需要一个有效 ID；未配置 On-call 故障触发器时省略。" }, "oncall_incident_severities": { "type": "array", @@ -4842,7 +4797,7 @@ "Info" ] }, - "description": "监听的故障严重程度，支持 Critical、Warning 和 Info；创建或启用该触发器时至少需要一个值。" + "description": "要监听的事故级别。支持的值为 Critical、Warning、Info；创建或启用该触发器至少需要一个值；未配置 On-call 故障触发器时省略。" }, "http_post_token": { "type": "string", @@ -4902,7 +4857,6 @@ "limit": { "type": "integer", "default": 20, - "maximum": 100, "description": "每页数量。" }, "scope": { @@ -4987,7 +4941,7 @@ ], "format": "int64", "minimum": 0, - "description": "只允许传当前值；创建后 personal / team scope 不可修改。" + "description": "改派规则作用域：0 表示转为个人规则（团队规则仅规则 owner 可转）；>0 表示转入调用者所属的团队。省略则保持不变。" }, "enabled": { "type": [ @@ -5095,9 +5049,20 @@ "type": "string", "description": "运行 ID。" }, + "session_id": { + "type": "string", + "description": "本次运行创建的会话 ID，从 `result_json` 中提取；运行尚未启动会话时省略。" + }, + "session_name": { + "type": "string", + "description": "运行会话的显示名称，批量查询填充；为空或查询失败时省略。" + }, "kind": { "type": "string", - "description": "运行类型。" + "description": "运行类型；按规则查询时恒为 `automation_rule`。", + "enum": [ + "automation_rule" + ] }, "account_id": { "type": "integer", @@ -5133,9 +5098,10 @@ "partial", "failed", "skipped", - "abandoned" + "abandoned", + "blocked" ], - "description": "运行状态。可选值（前三个为进行中，其余为终态）：\n| 值 | 含义 |\n| --- | --- |\n| `queued` | 已入队，等待工作器执行 |\n| `running` | 正在执行 |\n| `retrying` | 本次尝试失败，已安排重试 |\n| `succeeded` | 成功完成 |\n| `partial` | 部分成功（当前仅记忆整理类运行会产生；规则运行不会落到该状态） |\n| `failed` | 失败终态，不再重试 |\n| `skipped` | 未执行（如超过宽限期、触发器或规则失效），以运行记录形式留存原因 |\n| `abandoned` | 进行中超过陈旧阈值被后台清扫判为未完成（如工作器异常退出） |" + "description": "运行状态。可选值（前三个为进行中，其余为终态）：\n| 值 | 含义 |\n| --- | --- |\n| `queued` | 已入队，等待工作器执行 |\n| `running` | 正在执行 |\n| `retrying` | 本次尝试失败，已安排重试 |\n| `succeeded` | 成功完成 |\n| `partial` | 部分成功（当前仅记忆整理类运行会产生；规则运行不会落到该状态） |\n| `failed` | 失败终态，不再重试 |\n| `skipped` | 未执行（如超过宽限期、触发器或规则失效），以运行记录形式留存原因 |\n| `abandoned` | 进行中超过陈旧阈值被后台清扫判为未完成（如工作器异常退出） |\n| `blocked` | 终态：有实际产出，但因连接器等待人工完成授权而结束（区别于 `failed`） |" }, "attempts": { "type": "integer", @@ -5158,17 +5124,27 @@ }, "error_code": { "type": "string", - "description": "错误码。" + "description": "错误码；运行未失败时为空字符串。" }, "error_message": { "type": "string", - "description": "错误消息。" + "description": "错误信息；运行未失败时为空字符串。" }, "stats_json": { - "description": "统计 JSON。" + "type": [ + "object", + "null" + ], + "additionalProperties": true, + "description": "运行统计原始 JSON；为空时为 null。" }, "result_json": { - "description": "结果 JSON。" + "type": [ + "object", + "null" + ], + "additionalProperties": true, + "description": "运行结果原始 JSON（运行启动后携带 `session_id`）；为空时为 null。" }, "created_at": { "type": "integer", @@ -5194,7 +5170,11 @@ "completed_at", "duration_ms", "created_at", - "updated_at" + "updated_at", + "error_code", + "error_message", + "stats_json", + "result_json" ] }, "AutomationRunListRequest": { @@ -5212,7 +5192,6 @@ "limit": { "type": "integer", "default": 20, - "maximum": 100, "description": "每页数量。" }, "status": { @@ -5225,9 +5204,10 @@ "partial", "failed", "skipped", - "abandoned" + "abandoned", + "blocked" ], - "description": "运行状态过滤：`queued` 排队中、`running` 运行中、`retrying` 重试中、`succeeded` 成功、`partial` 部分成功、`failed` 失败、`skipped` 已跳过（如规则或触发器失效）、`abandoned` 已放弃（超过时效未完成被系统终结）；省略则不过滤。" + "description": "运行状态过滤：`queued` 排队中、`running` 运行中、`retrying` 重试中、`succeeded` 成功、`partial` 部分成功、`failed` 失败、`skipped` 已跳过（如规则或触发器失效）、`abandoned` 已放弃（超过时效未完成被系统终结）、`blocked` 已阻塞（终态：有产出但某个连接器正等待人工完成授权）；省略则不过滤。" }, "trigger_kind": { "type": "string", @@ -5243,12 +5223,14 @@ "started_after_ms": { "type": "integer", "format": "int64", - "description": "开始时间下界，Unix 毫秒。" + "description": "开始时间下界，Unix 毫秒。早于 180 天运行记录保留下限的值会被截断到下限（省略时默认即为该下限）。", + "minimum": 0 }, "started_before_ms": { "type": "integer", "format": "int64", - "description": "开始时间上界，Unix 毫秒。" + "description": "开始时间上界，Unix 毫秒。必须不早于生效后的 `started_after_ms`；早于保留下限时返回空结果。", + "minimum": 0 } }, "required": [ @@ -5310,7 +5292,7 @@ }, "enabled": { "type": "boolean", - "description": "模板是否可用。" + "description": "从该模板创建规则时默认是否启用（预填值）。" }, "prompt": { "type": "string", @@ -5590,7 +5572,7 @@ "properties": { "server_name": { "type": "string", - "description": "MCP 服务器名称，在账户内唯一。", + "description": "MCP 服务器名称：必须以字母开头，仅含字母、数字、`-`、`_`（`@` 为保留字符）；在其作用域（账户范围或单个团队）内唯一，大小写不敏感。", "minLength": 1, "maxLength": 255 }, @@ -5672,16 +5654,12 @@ "description": "团队范围：0 表示账户级；>0 表示团队。", "format": "int64" }, - "environment_kind": { - "type": "string", - "description": "绑定到指定 BYOC 运行器（需同时提供 environment_id）。省略或留空表示自动选择；MCP 服务器不支持 cloud。唯一可选值：`byoc`（账户内自托管的 BYOC 运行器；MCP 服务器进程运行在客户自己的基础设施上）。", - "enum": [ - "byoc" - ] - }, - "environment_id": { - "type": "string", - "description": "运行器 ID；environment_kind 为 byoc 时必填。" + "environments": { + "type": "array", + "items": { + "type": "string" + }, + "description": "该服务器可运行的执行环境：`cloud` 和/或 BYOC Runner 的环境 ID 列表。省略或为空表示所有环境。" }, "allow_insecure_oauth_http": { "type": "boolean", @@ -5750,21 +5728,16 @@ "type": "boolean", "description": "调用者是否可编辑该服务器。" }, - "environment_kind": { - "type": "string", - "description": "运行环境类型：留空表示自动选择，`byoc` 表示绑定到指定运行器；MCP 服务器不支持绑定 `cloud`。", - "enum": [ - "", - "byoc" - ] - }, - "environment_id": { - "type": "string", - "description": "environment_kind 为 byoc 时对应的运行器 ID；否则为空。" + "environments": { + "type": "array", + "items": { + "type": "string" + }, + "description": "该服务器可运行的执行环境（`cloud` 和/或 BYOC Runner 的环境 ID）。始终返回；`[]` 表示所有环境（该字段引入前的历史数据也是空数组）。" }, "server_name": { "type": "string", - "description": "MCP 服务器名称，在账户内唯一。" + "description": "MCP 服务器名称，在其作用域（账户范围或单个团队）内唯一，大小写不敏感。" }, "description": { "type": "string", @@ -5772,7 +5745,7 @@ }, "ai_description": { "type": "string", - "description": "LLM 生成的描述，存在时优先于 `description`。" + "description": "LLM 生成的描述，存在时优先于 `description`；尚未生成时省略。" }, "transport": { "type": "string", @@ -5834,26 +5807,11 @@ }, "allow_insecure_oauth_http": { "type": "boolean", - "description": "允许该服务器的 OAuth 令牌交换使用明文 HTTP；仅用于测试。" + "description": "允许该服务器的 OAuth token 交换走明文 HTTP；仅供测试使用。为 false 时省略。" }, "allow_insecure_tls_skip_verify": { "type": "boolean", - "description": "连接该服务器时跳过 TLS 证书校验；仅用于测试。" - }, - "tools": { - "type": "array", - "items": { - "$ref": "#/components/schemas/MCPToolInfo" - }, - "description": "实时工具列表；由 get/test 接口填充。" - }, - "tool_count": { - "type": "integer", - "description": "实时工具列表的数量。" - }, - "list_error": { - "type": "string", - "description": "实时获取工具列表失败时的错误信息。" + "description": "连接该服务器时跳过 TLS 证书校验；仅供测试使用。为 false 时省略。" }, "auth_mode": { "type": "string", @@ -5897,8 +5855,6 @@ "account_id", "team_id", "can_edit", - "environment_kind", - "environment_id", "server_name", "description", "transport", @@ -5907,7 +5863,8 @@ "call_timeout", "created_by", "created_at", - "updated_at" + "updated_at", + "environments" ] }, "MCPServerListRequest": { @@ -6035,7 +5992,7 @@ "additionalProperties": { "type": "string" }, - "description": "环境变量（`stdio` 传输）；整体替换，但回填的掩码敏感值会保留服务端存储的原值；省略则不修改。" + "description": "环境变量（`stdio` 传输）；整体替换，但敏感键回传掩码值或空字符串时保留服务端存储的原值；省略则不修改。" }, "url": { "type": "string", @@ -6046,7 +6003,7 @@ "additionalProperties": { "type": "string" }, - "description": "HTTP 头（sse / streamable-http）。" + "description": "HTTP 头（`sse` / `streamable-http` 传输）；整体替换，掩码/空值保留规则同 `env`；省略则不修改。" }, "connect_timeout": { "type": "integer", @@ -6076,19 +6033,15 @@ "description": "重新分配团队范围：0 表示账户级；>0 表示团队。省略则不变。", "format": "int64" }, - "environment_kind": { + "environments": { "type": [ - "string", + "array", "null" ], - "description": "重新指定运行器绑定：byoc（需同时提供 environment_id）或空字符串表示重置为自动选择。省略（null）表示保持当前绑定不变。" - }, - "environment_id": { - "type": [ - "string", - "null" - ], - "description": "与 environment_kind=byoc 配对的运行器 ID。省略（null）表示保持当前绑定不变。" + "items": { + "type": "string" + }, + "description": "该服务器可运行的执行环境：`cloud` 和/或 BYOC Runner 的环境 ID 列表。省略（null）表示保持不变；传入列表即整体设置——空列表表示清除限制、恢复为所有环境。" }, "allow_insecure_oauth_http": { "type": [ @@ -6109,29 +6062,6 @@ "server_id" ] }, - "MCPToolInfo": { - "type": "object", - "description": "MCP 服务器暴露的单个工具的元数据。", - "properties": { - "name": { - "type": "string", - "description": "工具名称。" - }, - "description": { - "type": "string", - "description": "工具描述。" - }, - "input_schema": { - "type": "object", - "additionalProperties": true, - "description": "描述工具输入参数的 JSON Schema。" - } - }, - "required": [ - "name", - "description" - ] - }, "ManualRunRuleResult": { "type": "object", "description": "手动运行一次自动化规则（跳过其计划触发时间）的结果。", @@ -6594,7 +6524,7 @@ }, "asc": { "type": "boolean", - "description": "为 true 时升序，false 时降序；`orderby` 省略时也生效（此时按 `updated_at` 排序）。" + "description": "为 true 时升序，false 时降序。仅在与 `orderby` 同时提供时生效；省略 `orderby` 时始终按 `updated_at` 降序。" }, "include_subagent_sessions": { "type": "boolean", @@ -6754,7 +6684,7 @@ }, "skill_name": { "type": "string", - "description": "技能名称，在账户内唯一。" + "description": "技能名称，在其作用域内唯一（账户范围或单个团队内）。" }, "description": { "type": "string", @@ -6794,6 +6724,13 @@ }, "description": "所需工具（内置或 `mcp:server/tool`）。" }, + "venues": { + "type": "array", + "items": { + "type": "string" + }, + "description": "限定技能可用的执行环境类型（EnvironmentKind 字符串，如 `byoc`）；为空时省略，表示所有环境均可用。" + }, "s3_key": { "type": "string", "description": "技能压缩包在对象存储中的 key。" @@ -7035,7 +6972,7 @@ }, "team_name": { "type": "string", - "description": "所属团队的显示名称（仅团队范围）；账户范围为空。" + "description": "所属团队的显示名称（仅团队范围）；为空时省略（账户范围，或团队名称解析失败）。" }, "file_count": { "type": "integer", @@ -7196,7 +7133,7 @@ }, "query": { "type": "string", - "description": "对知识包 ID、范围和团队名称做大小写不敏感的子串过滤。", + "description": "对知识包 ID、范围、范围 ID/账户 ID 和团队名称做大小写不敏感的子串过滤。", "maxLength": 128 }, "team_ids": { @@ -7254,8 +7191,7 @@ "description": "目标范围；不传则为空操作，返回当前知识包。", "enum": [ "account", - "team", - null + "team" ] }, "scope_id": { @@ -7307,11 +7243,11 @@ }, "p": { "type": "integer", - "description": "页码，从 1 开始。" + "description": "页码，从 1 开始。目前接受但忽略——响应始终返回完整文件列表。" }, "limit": { "type": "integer", - "description": "每页条数。" + "description": "每页条数。目前接受但忽略——响应始终返回完整文件列表。" } } }, @@ -7346,7 +7282,7 @@ }, "content_b64": { "type": "string", - "description": "Base64 编码的文件内容；解码后必须是合法的 UTF-8 文本。" + "description": "Base64 编码的文件内容；解码后必须是合法的 UTF-8 文本（拒绝二进制）。单文件上限 1 MiB。" }, "content_type": { "type": "string", diff --git a/docs.json b/docs.json index 300922ac..dfd5a96f 100644 --- a/docs.json +++ b/docs.json @@ -1386,6 +1386,14 @@ { "source": "/en/flashduty/Wecom-alert-integration-guide", "destination": "/en/on-call/integration/alert-integration/alert-sources/wecom-alert" + }, + { + "source": "/zh/on-call/integration/alert-integration/alert-sources/overview", + "destination": "/zh/on-call/integration/alert-integration/alert-sources/standard-alert" + }, + { + "source": "/en/on-call/integration/alert-integration/alert-sources/overview", + "destination": "/en/on-call/integration/alert-integration/alert-sources/standard-alert" } ], "navigation": { @@ -1538,6 +1546,7 @@ "icon": "rocket", "pages": [ "zh/on-call/quickstart/quickstart", + "zh/on-call/quickstart/mobile-app", "zh/on-call/quickstart/faq", "zh/on-call/quickstart/comparison" ] @@ -1564,7 +1573,8 @@ "zh/on-call/incident/alert-management", "zh/on-call/incident/custom-actions", "zh/on-call/incident/past-incidents", - "zh/on-call/incident/outlier-incidents" + "zh/on-call/incident/outlier-incidents", + "zh/on-call/incident/external-submission" ] }, { @@ -1640,6 +1650,7 @@ "expanded": false, "pages": [ "zh/on-call/integration/alert-integration/alert-sources/standard-alert", + "zh/on-call/integration/alert-integration/alert-sources/email", "zh/on-call/integration/alert-integration/alert-sources/http-pull", "zh/on-call/integration/alert-integration/alert-sources/db-pull", "zh/on-call/integration/alert-integration/alert-sources/prometheus", @@ -1660,9 +1671,13 @@ "zh/on-call/integration/alert-integration/alert-sources/aliyun-prometheus", "zh/on-call/integration/alert-integration/alert-sources/aws-cloudwatch", "zh/on-call/integration/alert-integration/alert-sources/aws-eventbridge", + "zh/on-call/integration/alert-integration/alert-sources/azure-monitor", + "zh/on-call/integration/alert-integration/alert-sources/google-cloud-monitoring", "zh/on-call/integration/alert-integration/alert-sources/tencent-cls", "zh/on-call/integration/alert-integration/alert-sources/tencent-cm", "zh/on-call/integration/alert-integration/alert-sources/tencent-eventbridge", + "zh/on-call/integration/alert-integration/alert-sources/baidu-bcm", + "zh/on-call/integration/alert-integration/alert-sources/ctyun", "zh/on-call/integration/alert-integration/alert-sources/huawei-ces", "zh/on-call/integration/alert-integration/alert-sources/huawei-lts", "zh/on-call/integration/alert-integration/alert-sources/huawei-apm", @@ -1685,11 +1700,18 @@ "zh/on-call/integration/alert-integration/alert-sources/cloudflare", "zh/on-call/integration/alert-integration/alert-sources/meraki", "zh/on-call/integration/alert-integration/alert-sources/monit", + "zh/on-call/integration/alert-integration/alert-sources/rum-alert", "zh/on-call/integration/alert-integration/alert-sources/harbor", "zh/on-call/integration/alert-integration/alert-sources/ucloud-cloudwatch", "zh/on-call/integration/alert-integration/alert-sources/jdcloud", "zh/on-call/integration/alert-integration/alert-sources/volcengine-rtc", - "zh/on-call/integration/alert-integration/alert-sources/nagios" + "zh/on-call/integration/alert-integration/alert-sources/volcengine-dial", + "zh/on-call/integration/alert-integration/alert-sources/nagios", + "zh/on-call/integration/alert-integration/alert-sources/emqx", + "zh/on-call/integration/alert-integration/alert-sources/rizhiyi", + "zh/on-call/integration/alert-integration/alert-sources/dingtalk-alert", + "zh/on-call/integration/alert-integration/alert-sources/lark-alert", + "zh/on-call/integration/alert-integration/alert-sources/wecom-alert" ] }, { @@ -2444,7 +2466,6 @@ "POST /monit/rule/import", "POST /monit/rule/export", "POST /monit/rule/move", - "POST /monit/rule/status", "POST /monit/rule/audits", "POST /monit/rule/audit/detail", "POST /monit/rule/dstypes", @@ -2483,20 +2504,12 @@ "icon": "stethoscope", "pages": [ "POST /monit/query/data", - "POST /monit/query/rows", "POST /monit/query/diagnose", "POST /monit/tools/catalog", "POST /monit/tools/invoke", "POST /monit/targets" ] }, - { - "group": "通用工具", - "icon": "wrench", - "pages": [ - "POST /monit/preview/sync" - ] - }, { "group": "服务拓扑", "icon": "diagram-project", @@ -2908,6 +2921,7 @@ "icon": "rocket", "pages": [ "en/on-call/quickstart/quickstart", + "en/on-call/quickstart/mobile-app", "en/on-call/quickstart/faq", "en/on-call/quickstart/comparison" ] @@ -2934,7 +2948,8 @@ "en/on-call/incident/alert-management", "en/on-call/incident/custom-actions", "en/on-call/incident/past-incidents", - "en/on-call/incident/outlier-incidents" + "en/on-call/incident/outlier-incidents", + "en/on-call/incident/external-submission" ] }, { @@ -3010,6 +3025,7 @@ "expanded": false, "pages": [ "en/on-call/integration/alert-integration/alert-sources/standard-alert", + "en/on-call/integration/alert-integration/alert-sources/email", "en/on-call/integration/alert-integration/alert-sources/http-pull", "en/on-call/integration/alert-integration/alert-sources/db-pull", "en/on-call/integration/alert-integration/alert-sources/prometheus", @@ -3030,9 +3046,13 @@ "en/on-call/integration/alert-integration/alert-sources/aliyun-prometheus", "en/on-call/integration/alert-integration/alert-sources/aws-cloudwatch", "en/on-call/integration/alert-integration/alert-sources/aws-eventbridge", + "en/on-call/integration/alert-integration/alert-sources/azure-monitor", + "en/on-call/integration/alert-integration/alert-sources/google-cloud-monitoring", "en/on-call/integration/alert-integration/alert-sources/tencent-cls", "en/on-call/integration/alert-integration/alert-sources/tencent-cm", "en/on-call/integration/alert-integration/alert-sources/tencent-eventbridge", + "en/on-call/integration/alert-integration/alert-sources/baidu-bcm", + "en/on-call/integration/alert-integration/alert-sources/ctyun", "en/on-call/integration/alert-integration/alert-sources/huawei-ces", "en/on-call/integration/alert-integration/alert-sources/huawei-lts", "en/on-call/integration/alert-integration/alert-sources/huawei-apm", @@ -3055,11 +3075,18 @@ "en/on-call/integration/alert-integration/alert-sources/cloudflare", "en/on-call/integration/alert-integration/alert-sources/meraki", "en/on-call/integration/alert-integration/alert-sources/monit", + "en/on-call/integration/alert-integration/alert-sources/rum-alert", "en/on-call/integration/alert-integration/alert-sources/harbor", "en/on-call/integration/alert-integration/alert-sources/ucloud-cloudwatch", "en/on-call/integration/alert-integration/alert-sources/jdcloud", "en/on-call/integration/alert-integration/alert-sources/volcengine-rtc", - "en/on-call/integration/alert-integration/alert-sources/nagios" + "en/on-call/integration/alert-integration/alert-sources/volcengine-dial", + "en/on-call/integration/alert-integration/alert-sources/nagios", + "en/on-call/integration/alert-integration/alert-sources/emqx", + "en/on-call/integration/alert-integration/alert-sources/rizhiyi", + "en/on-call/integration/alert-integration/alert-sources/dingtalk-alert", + "en/on-call/integration/alert-integration/alert-sources/lark-alert", + "en/on-call/integration/alert-integration/alert-sources/wecom-alert" ] }, { @@ -3814,7 +3841,6 @@ "POST /monit/rule/import", "POST /monit/rule/export", "POST /monit/rule/move", - "POST /monit/rule/status", "POST /monit/rule/audits", "POST /monit/rule/audit/detail", "POST /monit/rule/dstypes", @@ -3853,20 +3879,12 @@ "icon": "stethoscope", "pages": [ "POST /monit/query/data", - "POST /monit/query/rows", "POST /monit/query/diagnose", "POST /monit/tools/catalog", "POST /monit/tools/invoke", "POST /monit/targets" ] }, - { - "group": "Monitor utilities", - "icon": "wrench", - "pages": [ - "POST /monit/preview/sync" - ] - }, { "group": "Service map", "icon": "diagram-project", diff --git a/en/changelog/changelog.mdx b/en/changelog/changelog.mdx index c136d7dc..1ec8a9f0 100644 --- a/en/changelog/changelog.mdx +++ b/en/changelog/changelog.mdx @@ -210,6 +210,18 @@ See [AI SRE](/en/ai-sre) and the [quickstart](/en/ai-sre/quickstart). + + +### @mention notifications in incident comments + +Mention a member with `@` in incident comments or postmortem reports, and the mentioned person is notified in real time — key collaboration signals no longer get buried: + +- Type `@` in the incident detail comment area or in a postmortem report to select and mention a member. The notification carries the comment content, an incident summary, and a detail link that jumps straight to the incident +- Notification channels follow the mentioned person's preferences: SMS, email, and all IM apps (DingTalk, Feishu/Lark, WeCom, Slack, Microsoft Teams) are supported, with email as the default +- Adjust how you receive these under **Personal Center → Notification Preferences → Collaboration & follow-up → Collaboration Mention**; the same comment never triggers duplicate notifications + + + ### AI SRE autonomous investigation Agent diff --git a/en/developer/cli.mdx b/en/developer/cli.mdx index 19a0345f..f01fe5e8 100644 --- a/en/developer/cli.mdx +++ b/en/developer/cli.mdx @@ -474,12 +474,11 @@ FDUTY ### monit-query — Monitoring datasource queries -Probe monitoring back-end datasources directly, bypassing the alert-rule layer. The `data` subcommand supports 9 datasource types (Prometheus, VictoriaLogs, Loki, MySQL, SLS, Elasticsearch, PostgreSQL, Oracle, ClickHouse); `diagnose` supports `prometheus` (metric trends), `victorialogs`, `loki` (log patterns); the deprecated `rows` supports `prometheus`, `victorialogs`, `loki`, `mysql`. +Probe monitoring back-end datasources directly, bypassing the alert-rule layer. The `data` subcommand supports 9 datasource types (Prometheus, VictoriaLogs, Loki, MySQL, SLS, Elasticsearch, PostgreSQL, Oracle, ClickHouse); `diagnose` supports `prometheus` (metric trends), `victorialogs`, and `loki` (log patterns). ```bash flashduty monit-query diagnose [flags] # Pre-clustered RCA findings (log patterns or metric trends) -flashduty monit-query data [flags] # Structured datasource query (recommended) -flashduty monit-query rows [flags] # Raw datasource passthrough query (deprecated — use data) +flashduty monit-query data [flags] # Structured datasource query ``` Common flags for `diagnose`: diff --git a/en/developer/go-sdk.mdx b/en/developer/go-sdk.mdx index aedace5c..81cb2853 100644 --- a/en/developer/go-sdk.mdx +++ b/en/developer/go-sdk.mdx @@ -161,7 +161,6 @@ Endpoints are grouped by service and hang off the client: the call convention is | `client.NotificationTemplates` | Notification templates | | `client.Changes` | Changes | | `client.Diagnostics` | Diagnostics | -| `client.MonitorUtilities` | Monitor datasource preview | | `client.ServiceMap` | Service map (ServiceMap) | | `client.Analytics` | Analytics | | `client.A2aAgents` | A2A Agents | @@ -182,7 +181,7 @@ Endpoints are grouped by service and hang off the client: the call convention is `client.Knowledge` covers the 9 operations under `/safari/knowledge/*`: on the pack side `PackReadGet` (get the account pack), `PackReadList` (list packs), `PackWriteEnsure` (ensure a pack exists), `PackWriteUpdate` (change a pack's scope), and `PackWriteDelete` (delete a pack); on the file side `FileReadGet`, `FileReadList`, `FileWritePut` (upload/overwrite), and `FileWriteDelete`. Exported types include `KnowledgePackItem`, `KnowledgeFileItem`, `KnowledgeWarning`, and the various `Knowledge*Request` / `Knowledge*Response` structs. -`client.Diagnostics` (diagnostics) provides datasource query methods: `QueryData` runs a synchronous query via `POST /monit/query/data` and returns a stable `query_result.v1` structured result (`format` is always `query_result.v1`; `result.kind` is one of `frames` / `records` / `samples`). This API requires monit-edge v0.65.0 or later. `QueryRows` (`POST /monit/query/rows`) is deprecated and returns the legacy flattened rows shape — migrate to `QueryData`. `QueryDiagnose` (`POST /monit/query/diagnose`) runs pre-clustered RCA analysis (log patterns or metric trends) and can take up to 35 seconds. +`client.Diagnostics` (diagnostics) provides datasource query methods: `QueryData` runs a synchronous query via `POST /monit/query/data` and returns a stable `query_result.v1` structured result (`format` is always `query_result.v1`; `result.kind` is one of `frames` / `records` / `samples`). This API requires monit-edge v0.65.0 or later. `QueryDiagnose` (`POST /monit/query/diagnose`) runs pre-clustered RCA analysis (log patterns or metric trends) and can take up to 35 seconds. All identifiers, service field names, and method names match the generated code. For exactly which methods each service has and their request and response types, rely on `services_gen.go` and the per-service files, plus the [Open API reference](/en/openapi/introduction). diff --git a/en/on-call/analytics/insights.mdx b/en/on-call/analytics/insights.mdx index 05786052..ba9aa119 100644 --- a/en/on-call/analytics/insights.mdx +++ b/en/on-call/analytics/insights.mdx @@ -35,7 +35,7 @@ When customizing filter conditions, the system remembers your selections. Even a | Team | Select team names to query, supports multiple selection. Dashboard data updates based on selected teams | | Channel | Select channel names to query, supports multiple selection. Dashboard data updates based on selected channels | | Severity | Select severity levels to query, supports multiple selection. Dashboard data updates based on selected severity levels | -| Time Range | Select time range to query. Supports this week, last two weeks, this month, last month, and custom time ranges, but only up to the last **1 year** of data | +| Time Range | Select time range to query. Supports this week, last two weeks, this month, last month, and custom time ranges, querying up to the last **2 years (720 days)** of data (the exact limit depends on your plan) | | Data Interval | Supports day, week, and month dimensions. Defaults to hourly queries, but when time range exceeds 31 days, daily preview is not available | | Sorting | Team, channel, and individual dimension dashboards support ascending and descending order. Defaults to showing TOP 10 data; expand to show more | @@ -107,9 +107,19 @@ All dimensions support downloading dashboards in PDF format for further data ana -Export incident list, team, channel, and individual dimension data in CSV format. Before exporting, choose the fields you need in the popover. Incident list exports use a **fixed set** of 28 fields: incident ID, title, severity, progress, channel ID, channel, team ID, team, triggered at, time to acknowledge, time to close, closed by, response engagement, notification count, interruption count, acknowledgement count, assignment count, reassignment count, escalation count, manual escalation count, timeout escalation count, assigned to, responders, description, labels, custom fields, creator ID, and creator name. Enable **Extract text content from HTML** to write incident descriptions as plain text in the CSV, which makes them easier to read in spreadsheet tools. +Export incident list, team, channel, and individual dimension data in CSV format, with a maximum of **10,000** records per export. Before exporting, choose the fields you need in the popover. The incident list export offers **42 selectable fields** (all selected by default), grouped by purpose: -Incident list export fields do not change with the extended fields shown on the page: alert count, active alert count, alert events, owner, closer, snoozed until, ever muted, and outlier incident are display-only extended fields and are not included in CSV exports. +| Group | Fields | +| :--- | :--- | +| Basics | Incident ID, Incident title, Severity, Progress, Description, Labels, Custom fields | +| Ownership | Channel ID, Channel, Team ID, Team | +| Time & Efficiency | Triggered at, Time to ack, Time to close, Close by, Response effort, Hours | +| Notifications & Assignment | Notifications, Interruptions, Acknowledgements, Assignments, Reassignments, Escalations, Manual escalations, Auto escalations, Assign method, Responders, Raw assigned to, Raw responders, Escalation rules | +| Associated Alerts | Alerts, Active alerts, Alert events | +| People | Owner ID, Owner, Creator ID, Creator, Closer ID, Closer | +| Others | Snoozed until, Ever muted, Rare incident | + +Enable **Extract text content from HTML** (on by default) to write incident descriptions as plain text in the CSV, which makes them easier to read in spreadsheet tools. Data Export Diagram @@ -140,7 +150,7 @@ Usage statistics help you understand overall platform usage for capacity plannin -Currently, insights only supports querying the last 1 year (depending on your plan's data retention period) of data. For older data, use the [API Query](/en/api-reference/on-call/analytics/insight-incident-list). +Currently, insights supports querying up to the last **2 years (720 days)** of data (the exact limit depends on your plan). For older data, use the [API Query](/en/api-reference/on-call/analytics/insight-incident-list). diff --git a/en/on-call/channel/create-edit.mdx b/en/on-call/channel/create-edit.mdx index b3052ed2..b8c91403 100644 --- a/en/on-call/channel/create-edit.mdx +++ b/en/on-call/channel/create-edit.mdx @@ -106,7 +106,7 @@ Statistics cards can be collapsed. Open the **Metric Analysis** page for richer After creating a channel, go to the **Configuration** tab on the details page to complete the following configurations. The Configuration tab uses a sidebar menu organized into functional groups: - **Integrate Data**: Dedicated Integrations, Drop Rules -- **Noise Reduction**: Alert Grouping, Flapping Detection, Silence Rules, Inhibit Rules +- **Noise Reduction**: Event Aggregation, Alert Grouping, Flapping Detection, Silence Rules, Inhibit Rules - **Notification & Assignment**: Escalation Rules - **Settings**: Basic Info, Advanced Settings @@ -162,6 +162,7 @@ Configure noise reduction capabilities under **Configuration** → **Noise Reduc | Capability | Navigation Path | Description | | :--- | :--- | :--- | +| **Event Aggregation** | Noise Reduction → Event Aggregation | Control whether events with the same `alert_key` merge into the same alert within the aggregation window | | **Alert Grouping** | Noise Reduction → Alert Grouping | Merge similar alerts from the same host or service into one incident | | **Flapping Detection** | Noise Reduction → Flapping Detection | Automatically identify and suppress alerts that oscillate repeatedly in a short time | | **Silence Rules** | Noise Reduction → Silence Rules | Temporarily suppress alert notifications under specific conditions during scheduled maintenance windows or specific time periods | diff --git a/en/on-call/channel/escalation-rule.mdx b/en/on-call/channel/escalation-rule.mdx index cbf52db0..4aeb9bdd 100644 --- a/en/on-call/channel/escalation-rule.mdx +++ b/en/on-call/channel/escalation-rule.mdx @@ -67,7 +67,7 @@ Determines how users are reached. - Point-to-point messaging to specific assignees, supports phone calls, SMS, email, app push, IM direct messages (Feishu/Lark, Dingtalk, WeCom). + Point-to-point messaging to specific assignees, supports phone calls, SMS, email, app push, IM direct messages (Feishu/Lark, Dingtalk, WeCom, Slack, Microsoft Teams). - **Follow Personal Preferences (Recommended)**: Notification methods configured by members in [Personal Settings](/en/on-call/configuration/personal-settings) - **Follow Unified Settings**: Enforce notification methods (e.g., must send SMS), overriding member personal preferences @@ -75,8 +75,8 @@ Determines how users are reached. Send to instant messaging groups, with support for @ mentioning relevant personnel. - - **IM App Groups**: Supports Feishu/Lark, Dingtalk, WeCom, Slack, and Microsoft Teams groups, requires completing [IM Integration](/en/on-call/integration/instant-messaging/lark) first - - **Group Bots**: Supports Feishu/Lark, Dingtalk, WeCom, Telegram, Zoom, and other Webhook bots. Telegram requires configuring a Webhook notification address and Chat IDs, Zoom requires configuring a Webhook address and Verify Token, and supports enabling @ mention functionality. See [Notification Channel Configuration](/en/on-call/configuration/notifications) + - **IM App Groups**: Supports Feishu/Lark, Dingtalk, WeCom, Slack, and Microsoft Teams groups (WeCom is only available for existing configurations and cannot be selected when creating new rules), requires completing [IM Integration](/en/on-call/integration/instant-messaging/lark) first + - **Group Bots**: Supports Feishu/Lark, Dingtalk, WeCom, Slack, Telegram, Zoom, and other Webhook bots. Telegram requires configuring a Webhook notification address and Chat IDs, Zoom requires configuring a Webhook address and Verify Token, and supports enabling @ mention functionality. See [Notification Channel Configuration](/en/on-call/configuration/notifications) **Don't use any of the above IM platforms?** You can select any bot type and set the webhook URL to your own server endpoint (the system does not validate domains), then implement the corresponding message protocol on your server. See [FAQ](/en/on-call/quickstart/faq#custom-bot-notifications). diff --git a/en/on-call/channel/integrate-data.mdx b/en/on-call/channel/integrate-data.mdx index 332fafd1..bdf5ff75 100644 --- a/en/on-call/channel/integrate-data.mdx +++ b/en/on-call/channel/integrate-data.mdx @@ -113,15 +113,16 @@ See [Routing Rules](/en/on-call/integration/alert-integration/routing-rules) for ## Rate Limits -To ensure system stability, each integration has the following request rate limits: +To ensure system stability, the gateway enforces the following rate limits on alert push APIs: -| Limit Type | Limit Value | +| Limit Dimension | Limit Value | | :--- | :--- | -| **QPS** | 100 requests/second | -| **QPM** | 1000 requests/minute | +| **Per API** | 8000 requests/second (QPS) | +| **Per account** | 2000 requests/minute | +| **Per integration** | 2000 requests/minute | -Exceeding limits will return a `429` status code, please retry after waiting. Contact technical support if you need higher limits. +Exceeding any of these limits returns a `429` status code — please wait and retry. Contact technical support if you need higher limits. ## FAQ diff --git a/en/on-call/channel/noise-reduction.mdx b/en/on-call/channel/noise-reduction.mdx index 8bca6237..5d6db1e6 100644 --- a/en/on-call/channel/noise-reduction.mdx +++ b/en/on-call/channel/noise-reduction.mdx @@ -93,7 +93,7 @@ Event Aggregation controls the "Event → Alert" merge behavior: when the upstre | Configuration | Description | Default | Range | | :--- | :--- | :--- | :--- | | **Enable Event Aggregation** | When enabled, events with the same `alert_key` merge into the same alert within the aggregation window; when disabled, every event creates its own alert | Enabled | Enabled / Disabled | -| **Aggregation Window** | Starts counting from the alert's creation time; events arriving after this duration create a new alert. Only configurable when Event Aggregation is enabled | 1440 minutes (24 hours) | 1–1440 minutes | +| **Aggregation Window** | Starts counting from the alert's creation time; events arriving after this duration create a new alert. Only configurable when Event Aggregation is enabled | 1440 minutes (24 hours) | 1–1440 minutes; capped at 24 hours by default, extendable up to 7 days on request (contact the Flashduty team) | `alert_key` is the identifier used for alert correlation and deduplication. It is either reported by the upstream integration or generated automatically by integration rules. @@ -225,7 +225,7 @@ Go to Channel Details → Noise Reduction → **Flapping Detection**: | **Alert Then Silence** | Mark flapping status, no more notifications after first alert | - Flapping detection is enabled by default for new channels (Alert Only mode). + Flapping detection is enabled by default for new channels in **Alert Then Silence** mode, with default parameters: 60-minute observation window, 4 state changes, and a 120-minute mute duration. ### Configurable Parameters @@ -344,7 +344,7 @@ When a root cause alert exists, automatically inhibit related secondary alerts. ### Inhibit Conditions -When a new alert meets the conditions and there is a matching **active alert** (not acknowledged and not recovered) within the last 10 minutes, and both share equal items, the new alert is inhibited. +When a new alert meets the conditions and there is a matching **active alert** (any alert in an active, unrecovered state can serve as the inhibit source, whether or not it has been acknowledged) within the last 10 minutes, and both share equal items, the new alert is inhibited. | Configuration | Description | | :--------- | :------------------------------ | @@ -384,7 +384,7 @@ When a new alert meets the conditions and there is a matching **active alert** ( Up to 5000, mainly to ensure console rendering performance. Due to backend concurrent processing, actual count may slightly exceed this limit. - Whether an event can merge into an existing alert is controlled by the channel's **Event Aggregation** setting (which governs the "Event → Alert" stage — enabled by default with a 24-hour window, configurable from 1 to 1440 minutes, or can be turned off entirely): + Whether an event can merge into an existing alert is controlled by the channel's **Event Aggregation** setting (which governs the "Event → Alert" stage — enabled by default with a 24-hour window, configurable from 1 to 1440 minutes, extendable up to 7 days on request, or can be turned off entirely): - **Event Aggregation enabled**: events with the same `alert_key` merge into the same alert within the window; events arriving after the window expires create a new alert - **Event Aggregation disabled**: every event creates an independent alert, with no merging diff --git a/en/on-call/configuration/custom-forms.mdx b/en/on-call/configuration/custom-forms.mdx index cda32af8..b4d2a0df 100644 --- a/en/on-call/configuration/custom-forms.mdx +++ b/en/on-call/configuration/custom-forms.mdx @@ -12,7 +12,7 @@ Use forms to collect handoff context, impact details, resolution notes, or scree - In the console, go to **Incident Management → Custom Forms**, then choose **Create incident**, **Acknowledge incident**, or **Close incident**. + In the console, go to **Configuration → Custom Forms**, then choose **Create incident**, **Acknowledge incident**, or **Close incident**. Click **Add Field** and add the elements you need: @@ -41,6 +41,8 @@ Use forms to collect handoff context, impact details, resolution notes, or scree Visibility and required rules are evaluated when the user performs the action. For example, you can require a field only when a specific severity, label, or team member matches. +These forms also work in the Flashduty App: creating, acknowledging, and closing an incident in the App presents the same form. Both platforms share one configuration, with consistent visibility conditions, required rules, and behaviors such as image upload. + If an action has no configured form elements, or no element is visible for the current incident and user, Flashduty runs the normal create, acknowledge, or close flow without asking for additional input. diff --git a/en/on-call/configuration/notifications.mdx b/en/on-call/configuration/notifications.mdx index 67d7fafb..61ed2485 100644 --- a/en/on-call/configuration/notifications.mdx +++ b/en/on-call/configuration/notifications.mdx @@ -43,7 +43,7 @@ The Flashduty App is the most efficient mobile work tool for On-call engineers. - Search "Flashduty" in App Store or major Android markets, or scan QR code in console personal center + For download options, see [Personal Settings - Flashduty APP](/en/on-call/configuration/personal-settings#flashduty-app) Open App and login with your Flashduty account, or scan to login from console. After login, current device automatically links to your account @@ -60,6 +60,11 @@ The Flashduty App is the most efficient mobile work tool for On-call engineers. 1. Check if notification permissions are enabled for Flashduty App in phone system settings 2. Confirm App push is set as one of the notification channels in your escalation rules 3. If "Follow Personal Preferences" is set, check if Flashduty App is selected in personal notification settings + 4. **Android users**: Check that both notification channels are enabled in system notification settings (channel names appear in Chinese) — "故障通知 (Incident notifications)" carries regular (Warning/Info) incident notifications, while "紧急通知 (Urgent notifications)" carries Critical-severity incident notifications (visible on the lock screen, able to bypass Do Not Disturb). The two channels are managed separately in system settings; disabling one of them mutes the corresponding severity + + **What opens when I tap a push notification?** + + Tapping a notification opens the corresponding incident detail page directly in the App, where you can immediately acknowledge, close, and perform other actions. @@ -380,6 +385,14 @@ Flashduty On-call allows you to customize personalized notification messages for For example, you can configure: P1 level incidents first notify primary on-call via Flashduty App and Feishu/Lark app; if no one acknowledges within 5 minutes, notify their supervisor via voice call. + + + When you type `@` to mention a member in an incident detail comment or a postmortem report, the system sends the mentioned person a notification containing the comment summary, incident information, and a detail link that jumps straight to the incident. + + - **Channels**: Delivered per the mentioned person's preferences — **SMS, email, and all IM apps** (direct messages via DingTalk, Feishu/Lark, WeCom, Slack, Microsoft Teams) are supported, with **email** as the default; voice and Flashduty App push are not offered for this scenario + - **Preference**: The mentioned person can adjust this under **Personal Center → Notification Preferences → Collaboration & follow-up → Collaboration Mention** + - **No duplicates**: The same comment never triggers duplicate notifications + ## Related Topics diff --git a/en/on-call/configuration/schedule.mdx b/en/on-call/configuration/schedule.mdx index a76c8f0f..d177fe03 100644 --- a/en/on-call/configuration/schedule.mdx +++ b/en/on-call/configuration/schedule.mdx @@ -43,6 +43,8 @@ Understanding these concepts before configuration will help you better plan your - **Schedule Name**: 1–40 characters, must be unique within the account - **Owning Team**: Specifies which team manages this schedule; team members gain edit permissions for this schedule - **Schedule Description**: Supports Markdown syntax, content can be included in notifications; up to 500 characters + + The Free plan allows you to create only 1 schedule. Upgrade to the Standard plan or higher to create more. To prevent forgetting shifts or handoffs, the system provides two notification triggers: @@ -85,19 +87,29 @@ Understanding these concepts before configuration will help you better plan your +## Delete a schedule + +--- + +You can delete a schedule from the schedule list or the schedule detail page. The system asks for confirmation before deletion. + + +If a schedule is referenced by escalation rules, the delete button is disabled. Hover over it to see the list of referencing escalation rules (channel → rule name). Remove the references in the corresponding channels before deleting the schedule, so that you don't miss new incident notifications after deletion. + + ## On-call roles --- -On-call roles in Flashduty aren't limited to "primary / backup" — they are an account-level resource. You can maintain any number of named roles (such as "R&D primary on-call", "DBA backup on-call", or "SRE responder") on the account role-management page, and map members to the corresponding roles when configuring a schedule. +On-call roles distinguish responders with different responsibilities within the same schedule (e.g., "primary" and "backup") and are an account-level resource: -- **Account-level resource**: Roles are managed centrally at the account level and shared across all schedules -- **Grouped by role inside a rule**: When adding personnel to a schedule rule, you can bind members to a specific role ID, forming a "role → member" mapping +- **Shared across the account**: Roles take effect at the account level and are shared by all schedules +- **Grouped by role inside a rule**: When adding personnel to a schedule rule, you can bind members to a specific role, forming a "role → member" mapping - **Escalation rules target by role**: Escalation rules support notifying **all on-call personnel**, **specific roles** (e.g., notify primary only), or **specific members**, enabling finer-grained alert routing - -If your team only needs "primary / backup" roles, simply use the built-in primary and backup roles — there's no need to create new roles. - + +By default, each account has only one on-call role, so you don't need to choose a role when adding responders. If you need multiple roles (such as primary/backup), contact Flashduty support to enable them. Once enabled, you can assign roles to members both in schedule rules and in overrides. Self-service role management is not available in the console. + ## Override and time off @@ -123,7 +135,7 @@ Overrides have a smaller field set than regular rules and only include: - **Start Time** / **End Time**: Define the override window. Defaults to `[today 00:00, next day 00:00]` - **Replacement Person**: The member who replaces the original on-call person within that window -Overrides do not support rotation cycle, date mask, primary/backup roles, grouping, or other regular-rule fields. +Overrides do not support rotation cycle, date mask, grouping, or other regular-rule fields. For accounts with multiple on-call roles enabled, you can also assign a role to the replacement person in an override. - **Preemption semantics**: Within its time window, an override **fully replaces** all regular on-call rules (regardless of which layer they belong to), rather than stacking with them. Once the window ends, the original rules automatically resume @@ -224,25 +236,13 @@ Click a schedule name to enter the detail page, where you can view the schedulin Click any time slot in the calendar to view the current responders or create an override. -## View Personal Schedule +## View My Schedule --- -Go to **Schedule** → **Personal Schedule** to view all your on-call assignments in a unified view. - -The top of the page shows the names of schedules where you are currently on-call. Click a name to navigate to the corresponding schedule details. - -You can switch the viewing range using the time range buttons in the upper right corner: - -| Option | Description | -| :--- | :--- | -| **1 Day** | View today's on-call assignments | -| **4 Days** | View on-call assignments for the next 4 days | -| **1 Week** | View on-call assignments for the next week | -| **2 Weeks** | View on-call assignments for the next 2 weeks (default) | -| **1 Month** | View on-call assignments for the next month | +The **Schedules** list page embeds a **My Schedule** section at the top, summarizing your on-call assignments in a week view: the left column lists the schedules in which you have shifts this week, and the calendar on the right shows your on-call time slots in each schedule. -Use the left and right arrow buttons to navigate to previous or future time periods, and click the **Today** button to quickly return to the current time. +Click the left and right arrows next to the section title to browse previous or upcoming weeks, and click the dot button in the middle to quickly jump back to the current week. ## Related Topics diff --git a/en/on-call/configuration/service-calendar.mdx b/en/on-call/configuration/service-calendar.mdx index 24a3c344..d3aafec9 100644 --- a/en/on-call/configuration/service-calendar.mdx +++ b/en/on-call/configuration/service-calendar.mdx @@ -28,17 +28,20 @@ description: Service calendars define workdays and rest days, working with escal --- -Go to Incident Management → Service Calendar → **New Calendar**. +Go to **Configuration → Service Calendar** and click **Add Calendar**. | Configuration | Description | | --- | --- | -| **Calendar Name** | Recommend naming by business dimension, e.g., "Settlement Business System" | +| **Calendar Name** | Required, 1–40 characters. Recommend naming by business dimension, e.g., "Settlement Business System" | +| **Management Team** | Required. The calendar belongs to this team, and team members gain edit permissions for it | | **Calendar Description** | Overview of business characteristics for quick team understanding | -| **Management Team** | Once configured, team members have full permissions for this calendar | -| **Link Holidays** | Recommend linking national holidays for automatic holiday schedules, can also be adjusted manually | + + +Each account can create up to 5 service calendars by default. If you need more, please contact Flashduty support. + -New calendars default to all workdays. After linking holidays, statutory holidays are automatically marked as rest days. +New calendars default to all workdays. After creation, open the calendar detail page to link national holidays — the system automatically marks statutory holidays as rest days, and you can adjust them manually. ![Service Calendar](https://fcpub-1301667576.cos.ap-nanjing.myqcloud.com/flashduty/doc/rili.png) @@ -50,6 +53,7 @@ New calendars default to all workdays. After linking holidays, statutory holiday | Action | Description | | --- | --- | | **Modify Basic Info** | Calendar name, description, management team | +| **Link Holidays** | On the calendar detail page, link national holiday calendars. The system automatically marks statutory holidays as rest days; you can adjust or unlink them at any time | | **Bulk Mark Rest Days** | Quickly mark by day of week, e.g., every Saturday and Sunday as rest days | | **Single Day Adjustment** | Click on a date to toggle workday/rest day status | diff --git a/en/on-call/incident/alert-management.mdx b/en/on-call/incident/alert-management.mdx index 1407c106..5925e3f8 100644 --- a/en/on-call/incident/alert-management.mdx +++ b/en/on-call/incident/alert-management.mdx @@ -33,7 +33,7 @@ The alert list involves three easily confused field dimensions — please distin | Field | Values | Description | | :--- | :--- | :--- | -| **alert_severity** (Severity) | Critical / Warning / Info | Determined when the alert is created and **never changes afterward**. The severity filter at the top of the list also acts on this field | +| **alert_severity** (Severity) | Critical / Warning / Info | Determined when the alert is created; when new events merge into the alert afterward, the severity escalates to the worst of the historical and incoming levels — in other words, it **can only escalate, never de-escalate**. The severity filter at the top of the list also acts on this field | | **alert_status** (Alert Status) | Critical / Warning / Info / Ok | Reflects the alert's current recovery state, where **Ok means recovered** and any other value means unrecovered | | **Incident Progress** | Triggered / Processing / Closed | This column shows the progress of the incident the alert is associated with, not the alert's own status | diff --git a/en/on-call/incident/escalate-dispatch-incident.mdx b/en/on-call/incident/escalate-dispatch-incident.mdx index 12d97e19..820d18d7 100644 --- a/en/on-call/incident/escalate-dispatch-incident.mdx +++ b/en/on-call/incident/escalate-dispatch-incident.mdx @@ -33,6 +33,10 @@ Similar to **Reassign**, adding responders only allows selecting schedules or in Add Responders Interface + +These operations are also available in the [Flashduty App](/en/on-call/quickstart/mobile-app): **Reassign** and **Escalate** live under **More actions (⋮)** on the incident detail page, while **Add responders** lives in the **Responders** section of the incident detail page. + + ## FAQ diff --git a/en/on-call/incident/external-submission.mdx b/en/on-call/incident/external-submission.mdx new file mode 100644 index 00000000..3910659c --- /dev/null +++ b/en/on-call/incident/external-submission.mdx @@ -0,0 +1,75 @@ +--- +title: "External Incident Submission" +description: "Once external reporting is enabled, customers or partners can submit incidents to a channel through a dedicated link or API without logging in to Flashduty, and the incidents automatically enter the assignment and notification flow" +keywords: ["external incident submission", "external reporting", "submit without login", "incident ticket", "customer reporting"] +--- + +**Plan requirement**: This feature requires an On-call Pro or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) + +External incident submission allows external personnel (such as your customers or partners) to submit incidents through a standalone page or an API **without logging in** to Flashduty. Once submitted, the incident is created directly in the corresponding channel, where it automatically matches the escalation rules and notifies responders — ideal for routing customer-facing issue reporting into your unified incident handling process. + +## Enable External Reporting + +Go to **Channel Details → Configuration → Settings → Advanced Configuration** and turn on the **External Reporting** switch (you can also enable it in the channel creation wizard). Once enabled, the system generates a dedicated external reporting link for the channel — copy it and share it with external personnel. + + +- The external reporting link is a login-free submission entry. Anyone with the link can submit incidents, so share it only with intended recipients +- **Turning off external reporting immediately invalidates any shared link; turning it back on generates a new link** — the old link cannot be restored + + +## Submission Page + +External personnel open the reporting link, fill in the incident on a standalone page, and submit it — no login required: + +| Field | Required | Description | +| :--- | :--- | :--- | +| Title | Yes | Up to 500 characters | +| Description | Yes | Supports Markdown, up to 10,000 characters | +| Attachments or screenshots | No | Up to 10 files; supports JPEG, PNG, WebP, GIF, TIFF, BMP, and ICO; each file must be under 5 MB | +| Email | Yes | The reporter's contact, so responders can follow up for more information | +| Company | No | The reporter's company name | + +A human verification (CAPTCHA) is required before submission. After a successful submission, the page shows a success message; if the link has been disabled or regenerated, the page shows **Invalid Link**, and the reporter needs to contact your team for a new link. + +## What Happens After Submission + +An externally submitted incident is created in the channel the link belongs to, with the following characteristics: + +- **Severity**: fixed at **Warning** +- **Progress**: Triggered, the same as incidents triggered automatically by alerts +- **Reporter info**: the email and company are recorded as the incident's `reporter_email` and `reporter_company` labels, visible in the label area of the incident details +- **Auto assignment**: after creation, the incident automatically matches the channel's escalation rules and sends notifications + + +If the channel has no escalation rule configured, an externally submitted incident is not assigned to anyone and no notification is sent. Before enabling external reporting, make sure the channel has a valid [escalation rule](/en/on-call/channel/escalation-rule). + + +## Submit via API + +Besides the standalone page, you can integrate the submission capability into your own system. The external reporting link looks like `https:///incident/external-create/` — take the `token` from it and call the API with `multipart/form-data`: + +```bash +curl -X POST "https:///api/incident/external-create?token=" \ + -F 'data={"title":"Payment API errors","description":"All payment requests have returned 500 since 14:00","reporter_email":"ops@example.com","reporter_company":"Example Inc.","captcha_verify_param":""}' \ + -F "images=@/path/to/screenshot.png" +``` + +| Part | Description | +| :--- | :--- | +| `data` | Required, a JSON string. Fields: `title` (required, up to 500 characters), `description` (required, up to 10,000 characters), `reporter_email` (required, up to 100 characters), `reporter_company` (optional, up to 100 characters), `captcha_verify_param` (human-verification CAPTCHA parameter, required in the SaaS environment; not needed for on-premises deployments) | +| `images` | Optional image files; multiple allowed. Each file must be under 5 MB and the whole request under 50 MB; excess images are silently ignored and only the first 10 are kept | + +A successful call returns the created incident ID: + +```json +{ + "data": { + "incident_id": "664f1b2c8f2a1c0012ab34cd" + } +} +``` + +## Further Reading + +- [Create and Configure Channels](/en/on-call/channel/create-edit): where the external reporting switch lives +- [Configure Escalation Rules](/en/on-call/channel/escalation-rule): decides who gets notified for externally submitted incidents diff --git a/en/on-call/incident/handle-update-incident.mdx b/en/on-call/incident/handle-update-incident.mdx index 09e3ef8a..eb536fdb 100644 --- a/en/on-call/incident/handle-update-incident.mdx +++ b/en/on-call/incident/handle-update-incident.mdx @@ -76,6 +76,10 @@ You have three ways to acknowledge a newly triggered incident. Flashduty On-call voice alerts remind you to **press 1 to acknowledge** at the end of the voice broadcast. Press key 1, and the system acknowledges the incident on your behalf. + + +Open the incident detail in the [Flashduty App](/en/on-call/quickstart/mobile-app) and tap the **Acknowledge** button at the bottom; you can also swipe left on an incident card in the list to acknowledge it quickly. + @@ -123,6 +127,10 @@ Click incident details in console, click **Snooze** button, select snooze durati Click **Snooze** button on incident message card, select snooze duration, done. + + +Open the incident detail in the [Flashduty App](/en/on-call/quickstart/mobile-app), tap **More actions (⋮)** → **Snooze** at the bottom, and select a snooze duration. Only processing incidents can be snoozed. + ## Close Incident @@ -138,6 +146,10 @@ You have multiple ways to close an incident. App message main card provides a **Close** button, click the card to complete closure. If clicking the card has no effect, you may not have completed login account linking in the app or other reasons. See [Feishu/Lark Integration Guide](/en/on-call/integration/instant-messaging/lark) for details. + + +Open the incident detail in the [Flashduty App](/en/on-call/quickstart/mobile-app) and tap the **Close** button at the bottom; you can also swipe left on an incident card in the list to close it quickly. A closed incident can be reopened from its detail page via **Reopen** with a required reason. + diff --git a/en/on-call/incident/search-view-incident.mdx b/en/on-call/incident/search-view-incident.mdx index d35c369d..ca14552a 100644 --- a/en/on-call/incident/search-view-incident.mdx +++ b/en/on-call/incident/search-view-incident.mdx @@ -17,8 +17,8 @@ Flashduty On-call provides two entry points to view the incident list. One is wi | 2 | My Channels | Defaults to all channels, can switch to view incidents in **My Channels** | | 3 | Processing Progress | Filter incidents by progress, defaults to **All** | | 4 | Time Filter | Supports relative time and custom range filtering | -| 5 | Search | Supports searching by incident ID; if assignee is set to "Assigned to Me", also supports fuzzy matching on "Incident Title" | -| 6 | More Filters | Supports rich dimension filtering including severity, channels, teams, labels, or custom fields. The **Teams** filter is only visible under the global Incident Management entry and narrows incidents by the team that owns each channel | +| 5 | Search | Supports searching by incident title, ID, labels, and custom fields. After an incident's title, labels, or custom fields are updated, query results may be slightly delayed | +| 6 | More Filters | Supports rich dimension filtering, including severity, responders, related to me, creator, acknowledger, closer, snooze status, ever converged due to flapping, rare incidents, labels, and custom fields. The **Channels** and **Teams** filters are only visible under the global Incident Management entry, and Teams narrows incidents by the team that owns each channel; **Related to me** matches incidents where you are the creator, acknowledger, closer, or a responder | | 7 | View Settings | Supports rich rendering options including **custom display attributes** and even aggregate views | | 8 | Pagination | Pagination and items per page adjustment | @@ -66,6 +66,18 @@ Flashduty On-call provides filtering capabilities across various dimensions with Flexibility often means lower performance, and Flashduty On-call is no exception, despite our many performance optimizations. We always recommend narrowing your query time range and using conditions like **Assigned to Me** and **Processing Progress** to reduce query scope. +### Saving Filter Views + +You can save the current filter conditions on the filter bar as a named **filter view** and reapply it with one click later — ideal for frequently used search combinations: + +- **Save a view**: After configuring your filter conditions, save them as a named view; names must be unique, and each user can save at most **10** views +- **Apply a view**: Select a saved view to apply its filter conditions to the current list +- **Manage views**: Saved views support **renaming**, **updating** (overwriting the view with the current filter conditions), and **deletion** + + +Filter views are saved per user and are only visible to you. A view saves all filter conditions except the **time range** — when you apply a view, the time range keeps your current selection. + + ### Row content Beyond the title and progress, each incident row surfaces two key counters: @@ -75,6 +87,21 @@ Beyond the title and progress, each incident row surfaces two key counters: Hovering over the counters opens a tooltip with the associated alert count, associated event count, and the relative time since the last merge. +### Batch Operations + +After selecting one or more incidents in the list, use the action bar above the list to perform batch operations: + +| Operation | Description | +| :--- | :--- | +| **Acknowledge** | Acknowledge the selected incidents in bulk | +| **Snooze** | Snooze the selected incidents in bulk. Choose a quick duration preset (defaulting to 2, 4, and 12 hours — open settings from the dropdown to configure 3 presets) or a custom duration (in hours or minutes, up to 30 days). Only incidents in the Processing state can be snoozed; the button is disabled if your selection contains incidents in other states | +| **Assign** | Assign the selected incidents to specific members in bulk. Closed incidents cannot be assigned; the button is disabled if your selection contains closed incidents | +| **Close** | Close the selected incidents in bulk | +| **Merge** | Merge the selected incidents into a single incident | +| **AI Analysis** | Send the selected incidents as context to the AI SRE Agent for batch analysis. Requires the AI SRE module to be enabled with the corresponding permission; if all selected incidents belong to the same team, that team is automatically used as the conversation scope | + +Except for **AI Analysis**, the above batch operations require incident update permission. + ### Custom Rendering Click the **Settings** button in the upper right corner of the incident list to customize display content and interaction behavior: @@ -256,7 +283,7 @@ The incident details page supports one-click AI summary generation to help you q - **Impacts**: Key affected resources such as services, systems, environments, and instances - **Actions**: Immediately actionable investigation and remediation steps (up to 3) -You can choose from different AI models (default is DeepSeek V3; DeepSeek R1 is also available for deep thinking and reasoning capabilities) and regenerate as needed. The generated summary supports real-time streaming output and can be saved as the incident description. +AI Summary is always generated with the DeepSeek V4 Pro (`deepseek-v4-pro`) model; the console does not offer a model selector. The generated summary supports real-time streaming output, can be regenerated, and can be saved as the incident description. AI Summary is only available for incidents automatically triggered by alerts. Manually created incidents do not support this feature. diff --git a/en/on-call/incident/what-is-incident.mdx b/en/on-call/incident/what-is-incident.mdx index d78fc99c..aa9687ca 100644 --- a/en/on-call/incident/what-is-incident.mdx +++ b/en/on-call/incident/what-is-incident.mdx @@ -21,7 +21,7 @@ Simply put: **An incident is a combination of similar alerts**. Without noise re Incidents, alerts, and events all use these three severity levels. **Severity is capitalized**, which is important when using APIs. The severity generation rules are: - **Event Severity**: Alert events from different integration sources (like Zabbix and Nightingale) have different severity enumerations. Flashduty On-call maps them to these three standard severities according to specific rules. For mapping details, refer to the specific integration documentation. To customize severity, see [Alert Processing](/en/on-call/integration/alert-integration/alert-pipelines). -- **Alert Severity**: Equals the highest severity among associated events. +- **Alert Severity**: Equals the highest severity among associated events. As new events keep merging in, the alert severity only escalates to the worst level and never drops because of a lower-severity event. - **Incident Severity**: Equals the highest severity among associated alerts. ### Processing Progress @@ -83,7 +83,7 @@ Incidents can be triggered in the following ways: - **Auto-trigger**: Flashduty On-call receives an alert event from an integration (like Zabbix notification), event auto-triggers an alert, alert auto-triggers an incident - **Manual trigger**: Click **Create Incident** button in Flashduty On-call console, fill in title, description, severity, etc. to trigger a new incident -- **External reporting**: After enabling external reporting, external personnel can submit incident tickets through a dedicated link without logging into a Flashduty account. See [Channel Configuration](/en/on-call/channel/create-edit) for details +- **External reporting**: After enabling external reporting, external personnel can submit incident tickets through a dedicated link without logging into a Flashduty account. See [External Incident Submission](/en/on-call/incident/external-submission) for details @@ -140,7 +140,7 @@ Flashduty On-call supports dedicated and shared integration modes: Flashduty On-call provides a custom event standard, allowing you to report alerts via standard protocol, suitable for any non-integrated monitoring system. For details, read [Custom Alert Events](/en/on-call/integration/alert-integration/alert-sources/standard-alert). -To ensure system stability, Flashduty On-call enforces rate limits per integration (**100 requests/second**, **1000 requests/minute**). Exceeding these limits returns a `429` status code — please wait and retry. See [Integrate Data - Rate Limits](/en/on-call/channel/integrate-data#rate-limits) for details. +To ensure system stability, Flashduty On-call enforces rate limits on alert push APIs (**8000 requests/second** per API, **2000 requests/minute** per account, **2000 requests/minute** per integration). Exceeding these limits returns a `429` status code — please wait and retry. See [Integrate Data - Rate Limits](/en/on-call/channel/integrate-data#rate-limits) for details. diff --git a/en/on-call/incident/work-items.mdx b/en/on-call/incident/work-items.mdx index 25e7978b..26d2ddad 100644 --- a/en/on-call/incident/work-items.mdx +++ b/en/on-call/incident/work-items.mdx @@ -22,7 +22,7 @@ In the **Actions** panel on the right side of the incident overview page, click | **Description** | No | Additional details about what needs to be done, up to **65535** characters | | **Assignees** | No | Search and multi-select from account members; no limit on the number | -Once created, the action item appears in the panel and an "action created" event is recorded on the incident timeline. Members assigned as assignees receive a personal notification prompting them to follow through (sent by email by default; you can adjust notification channels in [Personal Settings](/en/on-call/configuration/personal-settings)). +Once created, the action item appears in the panel and an "action created" event is recorded on the incident timeline. Members assigned as assignees receive a personal notification prompting them to follow through (sent via **email and in-app push** by default; you can adjust notification channels in [Personal Settings](/en/on-call/configuration/personal-settings)). ### Edit and Delete diff --git a/en/on-call/integration/alert-integration/alert-sources/emqx.mdx b/en/on-call/integration/alert-integration/alert-sources/emqx.mdx new file mode 100644 index 00000000..ac955127 --- /dev/null +++ b/en/on-call/integration/alert-integration/alert-sources/emqx.mdx @@ -0,0 +1,168 @@ +--- +title: "EMQX Alert Integration" +description: "Push EMQX alert events to Flashduty via Webhook for automated alert noise reduction" +keywords: ["alert integration", "EMQX", "MQTT", "monitoring alert", "data ingestion"] +--- + +
+ +## In Flashduty +--- + +You can obtain an integration push URL through either of these two methods: + +### Using Private Integration + +Choose this simpler option when you don't need to route alert events to different channels. + +
+ Expand + + 1. Go to the Flashduty console, select **Channel**, and enter a channel's details page + 2. Select the **Integration** tab, click **Add Integration** to enter the integration page + 3. Select **EMQX** integration and click **Save** to generate a card + 4. Click the generated card to view the **push URL**, copy it for later use, and you're done + +
+ +### Using Shared Integration + +Choose this option when you need to route alerts to different channels based on the alert event's payload information. + +
+ Expand + + 1. Go to the Flashduty console, select **Integration Center=>Alert Events** to enter the integration selection page + 2. Select **EMQX** integration: + - **Integration Name**: Define a name for this integration + 3. Configure the default route and select the corresponding channel (after the integration is created, you can go to `Route` to configure more routing rules) + 4. Click **Save** and copy the newly generated **push URL** for later use + 5. Done + +
+
+ +## In EMQX +--- + +EMQX Cloud (hosted service) and self-hosted EMQX are integrated differently. Choose the steps that match your deployment. + +### EMQX Cloud (Hosted Service) + +EMQX Cloud provides a built-in Flashduty alert integration type: + +
+ +1. Log in to the EMQX Cloud console, enter your deployment, and go to **Alerts → Alert Integrations** +2. Click **+ New** under Webhook integration and select **FlashDuty** as the type +3. Paste the Flashduty integration push URL into the URL field +4. Click **Confirm** to save. You can then click **Test** to send a sample alert and verify that Flashduty receives it + +
+ +Once configured, EMQX Cloud pushes alerts to the push URL with POST requests, carrying four labels: `deployment_id`, `level`, `message`, and `region`. + +### Self-hosted EMQX + +For self-hosted EMQX, forward system alarm events to the push URL through the rule engine. + + +The rule engine supports the `$events/sys/alarm_activated` and `$events/sys/alarm_deactivated` system alarm events starting from EMQX 5.8.5. Make sure your EMQX version is 5.8.5 or later. + + + +The quick Webhook setup on the EMQX Dashboard **Monitoring → Alarms** page pushes EMQX's native alarm format, which does not match the event format required by Flashduty. Follow the steps below to customize the request body through the rule engine. + + +
+ +**Step 1: Create a rule for alarm activation** + +1. Log in to the EMQX Dashboard, go to **Integration → Rules**, and click **Create Rule** +2. Enter the following statement in the SQL editor to match system alarm activation events: + + ```sql + SELECT + name, + message, + node + FROM + "$events/sys/alarm_activated" + ``` + +3. Add an **HTTP Server** action: + - Set the connector URL to the Flashduty integration push URL (with the integration_key parameter) + - Select `POST` as the request method + - Fill in the request body with the following template, which converts alarm fields into the Flashduty standard alert event format: + + ```json + { + "event_status": "Critical", + "alert_key": "emqx::${node}::${name}", + "title_rule": "EMQX alarm: ${message}", + "description": "${message}", + "labels": { + "alarm_name": "${name}", + "node": "${node}" + } + } + ``` + + The `${name}`, `${message}`, and `${node}` variables in the template are replaced with the field values output by the rule SQL. + +4. Save the rule + +**Step 2: Create a rule for alarm deactivation** + +Create another rule following Step 1, with the SQL statement matching alarm deactivation events: + +```sql +SELECT + name, + message, + node +FROM + "$events/sys/alarm_deactivated" +``` + +Use the same request body template as Step 1, but set `event_status` to `Ok`, so the corresponding alert in Flashduty is automatically recovered when the alarm is deactivated. + +
+ +## Severity Mapping +--- + +
+ +**EMQX Cloud (hosted service)**: EMQX Cloud automatically maps alert levels as follows: + +| EMQX Cloud Alert Level | Flashduty | Status | +| --- | --- | --- | +| Critical | Critical | Critical | +| Error / Warning | Warning | Warning | +| Info | Info | Info | + +**Self-hosted EMQX**: The alert severity is determined by the `event_status` field in the rule's request body template. In the examples above, alarm activation pushes `Critical` and alarm deactivation pushes `Ok`. You can change the activation severity to `Warning` or `Info` in the template. Valid values of `event_status` are `Critical`, `Warning`, `Info`, and `Ok`. + +
+ +## FAQ +--- + +
+Why am I not receiving alerts in Flashduty? + +**In Flashduty** + +1. Check whether the integration shows a **latest event time**. If not, Flashduty has not received any push; troubleshoot the EMQX side first. +2. If you are using a **shared integration**, confirm that you have configured **routing rules**. Without routing rules, the system rejects new pushes because there is no channel to receive your alerts. In this case, simply configure a routing rule to the target channel. + +**In EMQX** + +1. Self-hosted EMQX: Make sure the rule's request body template matches the examples above, and `event_status` is one of `Critical`, `Warning`, `Info`, `Ok`; otherwise Flashduty rejects the request. +2. On the rule details page of the EMQX Dashboard, check the rule's runtime statistics and confirm the action succeeds without failures. +3. Make sure the EMQX nodes can access the public domain `api.flashcat.cloud`. + +If the issue persists after these steps, please contact us **with the request_id from the push response**. + +
diff --git a/en/on-call/integration/alert-integration/alert-sources/lark-alert.mdx b/en/on-call/integration/alert-integration/alert-sources/lark-alert.mdx index 6aeee0f6..109bc885 100644 --- a/en/on-call/integration/alert-integration/alert-sources/lark-alert.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/lark-alert.mdx @@ -38,7 +38,7 @@ Choose this method when you need to route alerts to different channels based on 1. Go to the Flashduty console, select **Integration Center => Alert Events** to enter the integration selection page 2. Select **Feishu Alert** integration: - **Integration Name**: Define a name for the current integration - - **Message Type**: Select Feishu alert message type, currently only Text and Markdown are supported + - **Message Type**: Select Feishu alert message type, currently only Text and Post (rich text) are supported - **Push Mode**: Choose when to trigger or recover alerts for Feishu notifications 3. Copy the **Feishu Alert Integration URL** for later use 4. Configure the default route and select the corresponding channel (after integration creation, you can go to `Routes` to configure more routing rules) diff --git a/en/on-call/integration/alert-integration/alert-sources/rizhiyi.mdx b/en/on-call/integration/alert-integration/alert-sources/rizhiyi.mdx new file mode 100644 index 00000000..48e3d2da --- /dev/null +++ b/en/on-call/integration/alert-integration/alert-sources/rizhiyi.mdx @@ -0,0 +1,173 @@ +--- +title: "Logease Alert Integration" +description: "Push Logease (rizhiyi) alert events to Flashduty through a custom alarm plugin for automated alert noise reduction" +keywords: ["alert integration", "Logease", "rizhiyi", "log monitoring", "data ingestion"] +--- + +
+ +## In Flashduty +--- + +You can obtain an integration push URL through either of these two methods: + +### Using Private Integration + +Choose this simpler option when you don't need to route alert events to different channels. + +
+ Expand + + 1. Go to the Flashduty console, select **Channel**, and enter a channel's details page + 2. Select the **Integration** tab, click **Add Integration** to enter the integration page + 3. Select **Logease** integration and click **Save** to generate a card + 4. Click the generated card to view the **push URL**, copy it for later use, and you're done + +
+ +### Using Shared Integration + +Choose this option when you need to route alerts to different channels based on the alert event's payload information. + +
+ Expand + + 1. Go to the Flashduty console, select **Integration Center=>Alert Events** to enter the integration selection page + 2. Select **Logease** integration: + - **Integration Name**: Define a name for this integration + 3. Configure the default route and select the corresponding channel (after the integration is created, you can go to `Route` to configure more routing rules) + 4. Click **Save** and copy the newly generated **push URL** for later use + 5. Done + +
+
+ +## In Logease +--- + +Logease alerts can be delivered via email, syslog, alert forwarding, or custom alarm plugins. The JSON structure pushed by **alert forwarding** is a fixed Logease format that does not match the event format required by Flashduty. Therefore, use a **custom alarm plugin** (a Python script) to convert alerts into the standard format before pushing them to Flashduty. + +
+ +**Step 1: Write the alarm plugin script** + +Create a Python file (for example, `FlashdutyWebhook.py`) with the following content, and replace `push_url` at the top with your Flashduty integration push URL: + +```python +# -*- coding: utf-8 -*- +import json + +import requests + +# Flashduty integration push URL; replace with the push URL of your Logease integration +push_url = "https://api.flashcat.cloud/event/push/alert/standard?integration_key=YOUR_INTEGRATION_KEY" + +# HTTP forward proxy for hosts without direct Internet access; leave empty if not needed +proxies = { + 'http': '', + 'https': '', +} + +# Mapping from Logease alert levels to Flashduty alert severities +LEVEL_MAP = { + "critical": "Critical", + "high": "Critical", + "mid": "Warning", + "low": "Info", + "info": "Info", +} + +META = { + "name": "FlashdutyWebhook", + "version": 1, + "alias": "Flashduty alert push", + "configs": [] +} + + +def set_logger(reset_logger): + global logger + logger = reset_logger + + +def content(params, alert): + return alert.get("description", "") + + +def handle(params, alert): + level = alert.get("strategy", {}).get("trigger", {}).get("level", "low") + if alert.get("is_alert_recovery"): + event_status = "Ok" + else: + event_status = LEVEL_MAP.get(level, "Info") + event = { + "event_status": event_status, + "title_rule": alert.get("name", "Logease alert"), + "alert_key": "rizhiyi::" + alert.get("name", ""), + "description": alert.get("description", ""), + "labels": { + "alert_name": alert.get("name", ""), + "alert_level": level, + }, + } + resp = requests.post(push_url, json=event, timeout=10, proxies=proxies) + logger.info("push to flashduty, status: %s, resp: %s", resp.status_code, resp.text) + + +def execute_reply(params, alert): + handle(params, alert) + return "push to flashduty done" +``` + +**Step 2: Upload the plugin** + +Go to the Logease **Monitoring** page and upload the script under **Others → Alarm Plugins**. + +**Step 3: Reference the plugin in monitoring items** + +Edit the monitoring items that need to be connected to Flashduty, select the uploaded plugin under **Add Alarm Method**, and save. Logease also supports Manager plugins (for the platform's own monitoring) and Soar plugins (for playbooks); they are written in the same way as the example above and can be extended as needed. + +
+ + +The events pushed by the plugin must follow the Flashduty standard alert event format: `event_status` is required (one of `Critical`, `Warning`, `Info`, `Ok`), `title_rule` is the alert title, `alert_key` is used to update or automatically recover alerts, and `labels` carries alert labels. For the full field reference, see [Standard Alert Event](/en/on-call/integration/alert-integration/alert-sources/standard-alert). + + +## Severity Mapping +--- + +
+ +The mapping from Logease alert levels to Flashduty severities is defined by `LEVEL_MAP` in the plugin script. The example above uses the following mapping, which you can adjust as needed: + +| Logease Alert Level | Flashduty | Status | +| --- | --- | --- | +| critical | Critical | Critical | +| high | Critical | Critical | +| mid | Warning | Warning | +| low | Info | Info | +| info | Info | Info | +| Alert recovery (is_alert_recovery) | Ok | Recovered | + +
+ +## FAQ +--- + +
+Why am I not receiving alerts in Flashduty? + +**In Flashduty** + +1. Check whether the integration shows a **latest event time**. If not, Flashduty has not received any push; troubleshoot the Logease side first. +2. If you are using a **shared integration**, confirm that you have configured **routing rules**. Without routing rules, the system rejects new pushes because there is no channel to receive your alerts. In this case, simply configure a routing rule to the target channel. + +**In Logease** + +1. Check the plugin's runtime logs (stored by default in `/data/rizhiyi/logs/cruxee/plugins`, with the file name matching the name shown at upload) and confirm the script runs without errors and the push request returns successfully. +2. Make sure the push URL in the script exactly matches the one on the Flashduty integration details page, and `event_status` is one of `Critical`, `Warning`, `Info`, `Ok`; otherwise Flashduty rejects the request. +3. Make sure the Logease host can access the public domain `api.flashcat.cloud`. If direct access is unavailable, configure an HTTP forward proxy in the script's `proxies` field. + +If the issue persists after these steps, please contact us **with the request_id from the push response**. + +
diff --git a/en/on-call/integration/alert-integration/alert-sources/wecom-alert.mdx b/en/on-call/integration/alert-integration/alert-sources/wecom-alert.mdx index b1570b19..7045cc3c 100644 --- a/en/on-call/integration/alert-integration/alert-sources/wecom-alert.mdx +++ b/en/on-call/integration/alert-integration/alert-sources/wecom-alert.mdx @@ -38,7 +38,7 @@ Choose this method when you need to route alerts to different channels based on 1. Go to the Flashduty console, select **Integration Center => Alert Events** to enter the integration selection page 2. Select **Wecom Alert** integration: - **Integration Name**: Define a name for the current integration - - **Message Type**: Select Wecom alert message type, currently only Text and Markdown are supported + - **Message Type**: Select Wecom alert message type, currently only Text and Post (rich text) are supported - **Push Mode**: Choose when to trigger or recover alerts for Wecom notifications 3. Copy the **Wecom Alert Integration URL** for later use 4. Configure the default route and select the corresponding channel (after integration creation, you can go to `Routes` to configure more routing rules) diff --git a/en/on-call/integration/alert-integration/label-enhancement.mdx b/en/on-call/integration/alert-integration/label-enhancement.mdx index 3fc63e82..19c125a2 100644 --- a/en/on-call/integration/alert-integration/label-enhancement.mdx +++ b/en/on-call/integration/alert-integration/label-enhancement.mdx @@ -228,6 +228,10 @@ When an alert is triggered, Flashduty automatically calls the configured API ser ## Mapping Data Management + +Each account can create up to 20 mapping tables and 50 mapping services (APIs). Creation fails with a limit-exceeded error once the quota is reached. + + ### Mapping Table Data Management In the mapping table details page, you can manage mapping table data: diff --git a/en/on-call/integration/alert-integration/routing-rules.mdx b/en/on-call/integration/alert-integration/routing-rules.mdx index d98a26c3..c1437f11 100644 --- a/en/on-call/integration/alert-integration/routing-rules.mdx +++ b/en/on-call/integration/alert-integration/routing-rules.mdx @@ -25,7 +25,7 @@ Go to Integration Center → Alert Events → Integration Details → **Routing* | **Match Condition** | Filter alerts by labels, attributes, etc.; supports exact, wildcard, regex matching | | **Routing Mode** | See detailed description below | | **Flow Control** | **Continue Matching** (default): Continue matching subsequent rules after hit; **Stop Matching**: Don't match further after hit | -| **Default Route** | Fallback rule that takes effect when no rules match | +| **Default Route** | Fallback rule that takes effect when no rule actually delivers the alert to any channel | ### Routing Modes @@ -137,7 +137,7 @@ Confirm reported alerts can hit configured routing rules. We recommend configuri -No. The default route only takes effect when no routing rules match the alert. If any rule has already matched (regardless of whether flow control is set to 'continue' or 'stop'), the default route will not be triggered. +No. The default route is independent of flow control: it only takes effect when no rule actually delivers the alert to any channel. As long as a matched rule delivers the alert to at least one channel (whether flow control is set to 'Continue' or 'Stop'), the default route will not be triggered. Note that if a name mapping rule matches but the mapped channel does not exist (so nothing is actually delivered), the default route will still be triggered. diff --git a/en/on-call/integration/instant-messaging/lark.mdx b/en/on-call/integration/instant-messaging/lark.mdx index 52215a25..a5bcadeb 100644 --- a/en/on-call/integration/instant-messaging/lark.mdx +++ b/en/on-call/integration/instant-messaging/lark.mdx @@ -67,6 +67,8 @@ Go to Development Configuration → Events & Callbacks → **Encryption Strategy Return to Flashduty On-call **Integration Center** page, select Instant Messaging → **Feishu/Lark**, fill in `Name` and the `App ID`, `App Secret`, `Verification Token`, and `Encrypt Key` copied in the previous step, then click **Save** to complete creation. +If you use Lark (the international version), also turn on the **Is Lark Version** toggle. When enabled, the system communicates via Lark international endpoints. The Lark Developer Console is at [open.larksuite.com](https://open.larksuite.com) — complete the app creation and permission configuration steps described above on that site. + After successful creation, you'll see the added Feishu/Lark integration in the list. Click its name to enter the details page to view **Web Configuration** URL, **Redirect URL**, and **Message Card Request URL**, which will be used in subsequent steps. ![2025-09-18-10-44-00](https://docs-cdn.flashcat.cloud/images/png/1e8ffb6c39f99ef12bd85ae49992ebad.png) @@ -84,10 +86,10 @@ After successful creation, you'll see the added Feishu/Lark integration in the l ![2025-09-18-10-47-46](https://docs-cdn.flashcat.cloud/images/png/d91efc598bda17e1bfcb367aec47c779.png) -3. Go to Event Callbacks → **Event Configuration** page, configure `Subscription Method` (content is the **Message Card Request URL** from integration details). Then add the following two events: +3. Go to Event Callbacks → **Event Configuration** page, configure `Subscription Method` (content is the **Message Card Request URL** from integration details). Then add the following events: -- `im.chat.disbanded_v1` - `im.message.receive_v1` +- `im.chat.disbanded_v1` (optional; no consumer logic currently) ![2025-09-18-11-06-05](https://docs-cdn.flashcat.cloud/images/png/71910d8af8d60b5f30baf009081646df.png) diff --git a/en/on-call/integration/instant-messaging/slack.mdx b/en/on-call/integration/instant-messaging/slack.mdx index 83ae14aa..09bf2244 100644 --- a/en/on-call/integration/instant-messaging/slack.mdx +++ b/en/on-call/integration/instant-messaging/slack.mdx @@ -18,25 +18,55 @@ The following list includes all permissions required when the Slack IM integrati | Official scope name | Purpose | | :--- | :--- | | `app_mentions:read` | Receive messages that mention the app in channels for the AI SRE conversation entry point | -| `im:history` | Read direct message history for AI SRE context | | `chat:write` | Send basic notifications, War Room messages, and AI SRE replies | | `chat:write.public` | Send notifications and War Room messages to public channels the app has not joined | +| `chat:write.customize` | Send messages with a customized username and avatar | +| `commands` | Provide the `/fd` slash command | | `channels:read` | Read public channel information and channel lists | | `channels:history` | Read public channel message history; required for AI SRE context and AI-generated post-mortem reports | +| `channels:join` | Allow the app to join public channels | +| `channels:manage` | Create and manage public channels; required for the War Room feature | | `groups:read` | Read private channel information and channel lists | | `groups:history` | Read private channel message history; required for AI SRE context and AI-generated post-mortem reports | -| `groups:write` | Create and manage private-channel War Rooms | -| `groups:write.invites` | Invite members to private-channel War Rooms | +| `groups:write` | Create and manage private-channel War Rooms and invite members to them | +| `im:read` | Read the list of direct message conversations | +| `im:history` | Read direct message history for AI SRE context | +| `im:write` | Start direct message conversations | +| `mpim:read` | Read the list of group direct message conversations | +| `mpim:history` | Read group direct message history | +| `mpim:write` | Start group direct message conversations | | `users:read` | Read basic user information for user linking, display, and invitations | | `users:read.email` | Read user email addresses for user linking | +| `users.profile:read` | Read user profile information | +| `users:write` | Modify user profile and presence | +| `usergroups:read` | Read user group information | +| `usergroups:write` | Create and manage user groups | +| `team:read` | Read workspace information | +| `reactions:read` | Read message reactions for AI SRE processing status confirmation | | `reactions:write` | Add or remove message reactions for AI SRE processing status confirmation | -| `files:read` | Read files in messages for AI SRE context and attachment handling | +| `files:write` | Upload files, such as post-mortem report attachments | ### User Token Scopes | Official scope name | Purpose | | :--- | :--- | +| `identify` | Obtain the authorizing user's basic identity information | | `channels:read` | Read public channels visible to the authorizing user for channel lists and escalation rule configuration | +| `channels:write` | Manage public channels the authorizing user belongs to | +| `groups:read` | Read private channels visible to the authorizing user | +| `groups:write` | Manage private channels the authorizing user belongs to | +| `im:read` | Read the authorizing user's direct message conversations | +| `im:write` | Start direct message conversations as the authorizing user | +| `mpim:read` | Read the authorizing user's group direct message conversations | +| `mpim:write` | Start group direct message conversations as the authorizing user | +| `chat:write` | Send messages as the authorizing user | +| `users:read` | Read basic user information | +| `users:read.email` | Read user email addresses for user linking | +| `users.profile:read` | Read user profile information | +| `reactions:read` | Read message reactions | +| `reactions:write` | Add or remove message reactions | + +The list above matches the current OAuth authorization request. If it differs from what the Slack authorization page shows, the actual request on the authorization page prevails. If you use Slack Incoming Webhook-based Slack bot notifications instead of the Slack App integration on this page, enable Incoming Webhooks in the corresponding Slack app and include the `incoming-webhook` scope in the OAuth flow. diff --git a/en/on-call/integration/sso/keycloak.mdx b/en/on-call/integration/sso/keycloak.mdx index 884cf446..106857f7 100644 --- a/en/on-call/integration/sso/keycloak.mdx +++ b/en/on-call/integration/sso/keycloak.mdx @@ -18,7 +18,7 @@ This article does not cover deployment or explanation of Keycloak. For more info Login to Flashduty console and obtain the ACS URL (needed in subsequent steps). -Path: **Access Control => Single Sign-On => Settings => SAML2.0 Protocol => Flashduty Service Provider Info => Assertion Consumer Service URL** +Path: **Access Control => Single Sign-On => SAML2.0 Protocol => Flashcat Service Provider Info => Assertion Consumer Service URL** ![Get ACS URL](https://api.apifox.com/api/v1/projects/4169655/resources/437194/image-preview) @@ -93,7 +93,7 @@ Create user (must bind an email address): ![Create user](https://api.apifox.com/api/v1/projects/4169655/resources/437041/image-preview) -**Login test**: Visit `console.flashcat.cloud`, select SSO login, enter the login domain prefix from single sign-on configuration in the domain field. +**Login test**: Visit `console.flashcat.cloud`, select SSO login, and enter your organization's login domain in the domain field (configured on the **Platform Management → Organization → Organization Information → Organization Profile** page). You can also initiate single sign-on directly at `{domain}.sso.flashcat.cloud`. ![Test login](https://api.apifox.com/api/v1/projects/4169655/resources/437062/image-preview) @@ -105,7 +105,7 @@ Create user (must bind an email address): Login to Flashduty console and obtain the Redirect URL (needed in subsequent steps). -Path: **Access Control => Single Sign-On => Settings => OIDC Protocol => Flashduty Service Provider Info => Redirect URL** +Path: **Access Control => Single Sign-On => OIDC Protocol => Flashcat Service Provider Info => Redirect URL** ![Get Redirect URL](https://api.apifox.com/api/v1/projects/4169655/resources/437183/image-preview) diff --git a/en/on-call/integration/sso/openldap.mdx b/en/on-call/integration/sso/openldap.mdx index 118ec219..9e152bd2 100644 --- a/en/on-call/integration/sso/openldap.mdx +++ b/en/on-call/integration/sso/openldap.mdx @@ -27,8 +27,6 @@ This article assumes Docker and Docker Compose are already supported in your env ## Docker Compose Configuration ```yaml docker-compose.yml -version: '1' - networks: go-ldap-admin: driver: bridge @@ -84,13 +82,13 @@ Save the above configuration as `docker-compose.yml`, open a terminal in the dir ```bash -docker-compose up +docker compose up ``` ```bash -docker-compose up -d +docker compose up -d ``` @@ -98,13 +96,13 @@ docker-compose up -d **Check service status:** ```bash -docker-compose ps +docker compose ps ``` **Stop services:** ```bash -docker-compose down +docker compose down ``` ## Login to OpenLDAP @@ -136,4 +134,4 @@ Based on the OpenLDAP configuration above, the Flashduty integration information For the meaning and description of the above fields, refer to [Configure Single Sign-On](/en/platform/configure-sso). -After completing the configuration, click the **Connection Test** button at the bottom of the settings drawer to verify that Flashduty can successfully connect to the OpenLDAP server. Once the connection succeeds, click **Save**. +After completing the configuration, click **Test connection** below the LDAP form in the **Protocol & connection** section to verify that Flashduty can successfully connect to the OpenLDAP server. Once the connection succeeds, click **Save**. diff --git a/en/on-call/integration/webhooks/alert-webhook.mdx b/en/on-call/integration/webhooks/alert-webhook.mdx index 83482900..7fd7fb20 100644 --- a/en/on-call/integration/webhooks/alert-webhook.mdx +++ b/en/on-call/integration/webhooks/alert-webhook.mdx @@ -1,12 +1,12 @@ --- title: "Alert Webhook" -description: "Configure alert webhooks to send HTTP callbacks when Flashduty alerts are created, updated, merged, or closed." +description: "Configure alert webhooks to send HTTP callbacks when Flashduty alerts are created, updated, or merged." keywords: ["alert webhook", "HTTP callback", "event notification", "integration", "automation"] --- **Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/) -Configure alert Webhook. When specific operations occur on alerts (such as trigger or close), the system makes an HTTP callback to your configured address. The callback content includes the alert's latest key information, allowing integration with your custom tools. +Configure alert Webhook. When specific operations occur on alerts (such as trigger or update), the system makes an HTTP callback to your configured address. The callback content includes the alert's latest key information, allowing integration with your custom tools. @@ -21,10 +21,13 @@ The following event types are currently supported; more may be added in the futu | a_new | Integration pushes new event, triggering a new alert | | a_update | Integration pushes new event, merges into an alert, and updates alert info (severity, status, labels, description, etc.) | | a_merge | Merge alert into incident | -| a_close | Manually close alert (system event, automatically triggered when an alert is manually closed, not selectable in the UI) | + +Manually closing an alert does not currently trigger a Webhook callback. + + ## 2. Push Description ### Request Method @@ -61,11 +64,18 @@ email | string | Yes | Email address | Field | Type | Required | Description | | :--------------: | :-----------: | :--: | :----------------- | | alert_id | string | Yes | Alert ID | -| data_source_id | int64 | Yes | Integration ID | -| data_source_name | string | Yes | Integration name | -| data_source_type | string | Yes | Integration type | +| account_id | int64 | Yes | Account ID | +| integration_id | int64 | Yes | Integration ID | +| integration_name | string | Yes | Integration name | +| integration_type | string | Yes | Integration type | +| integration_ref_id | string | No | Integration reference ID | +| data_source_id | int64 | Yes | Integration ID, same as integration_id | +| data_source_name | string | Yes | Integration name, legacy field kept for compatibility (Deprecated), use integration_name instead | +| data_source_type | string | Yes | Integration type, legacy field kept for compatibility (Deprecated), use integration_type instead | +| data_source_ref_id | string | No | Integration reference ID, legacy field kept for compatibility (Deprecated), use integration_ref_id instead | | channel_id | int64 | Yes | Channel ID | | channel_name | string | Yes | Channel name | +| channel_status | string | No | Channel status, enum: enabled, disabled | | title | string | Yes | Alert title | | title_rule | string | No | Title generation rule | | description | string | No | Alert description | diff --git a/en/on-call/integration/webhooks/incident-webhook.mdx b/en/on-call/integration/webhooks/incident-webhook.mdx index e5d530d9..16eb3e92 100644 --- a/en/on-call/integration/webhooks/incident-webhook.mdx +++ b/en/on-call/integration/webhooks/incident-webhook.mdx @@ -18,7 +18,7 @@ The following event types are currently supported; more may be added in the futu | :----------: | :--------------- | | i_new | Create incident (auto or manual) | | i_assign | Assign incident (auto or manual) | -| i_a_rspd | Add responders | +| i_a_rspd | Add responders (currently only subscribable via API) | | i_snooze | Manually snooze incident | | i_wake | Cancel snooze | | i_ack | Manually acknowledge incident | @@ -36,10 +36,10 @@ The following event types are currently supported; more may be added in the futu | i_r_rsltn | Update incident resolution | | i_r_severity | Update incident severity | | i_r_field | Update incident custom field | -| i_wi_created | Create action or follow-up | -| i_wi_assignees | Update action or follow-up assignees | -| i_wi_completed | Complete action or follow-up | -| i_wi_converted | Convert action to follow-up | +| i_wi_created | Create action or follow-up (currently only subscribable via API) | +| i_wi_assignees | Update action or follow-up assignees (currently only subscribable via API) | +| i_wi_completed | Complete action or follow-up (currently only subscribable via API) | +| i_wi_converted | Convert action to follow-up (currently only subscribable via API) | @@ -89,6 +89,8 @@ acknowledged_at | int64 | No | Acknowledgment time | Field | Type | Required | Description | | :---------------: | :-----------------: | :--: | :----------------- | | incident_id | string | Yes | Incident ID | +| account_id | int64 | Yes | Account ID | +| account_name | string | Yes | Account name | | title | string | Yes | Incident title | | description | string | No | Incident description | | impact | string | No | Incident impact | @@ -110,12 +112,17 @@ acknowledged_at | int64 | No | Acknowledgment time | creator | [Person](#Person) | No | Creator info, only exists for manually created incidents | | closer | [Person](#Person) | No | Closer info, only exists for manually closed incidents | | responders | [][Responder](#Responder) | No | Responders list, only exists after incident is assigned. May be empty for i_new event | +| assigned_to | object | No | Assignment info, only exists after incident is assigned. Includes type (assignment method), escalate_rule_id (escalation rule ID), escalate_rule_name (escalation rule name), layer_idx (current escalation layer), assigned_at (assignment time, Unix seconds timestamp), etc. | | alert_cnt | int64 | No | Associated alert count | +| active_alert_cnt | int64 | No | Active associated alert count (alerts in Critical, Warning, or Info status) | +| integration_ids | []int64 | No | Integration IDs of the associated alerts | +| integration_types | []string | No | Integration types of the associated alerts | | num | string | Yes | Short incident identifier — the last 6 hex characters of the incident ObjectID, uppercased (e.g. `56E25B`). Displayed in the console UI. Can be passed to the incident info API as an alternative to `incident_id` (either field is accepted; not unique within an account — the most recently created match is returned) | | channel_id | int64 | No | Channel ID, 0 means not belonging to any channel | | channel_name | string | No | Channel name | | team_id | int64 | No | ID of the team that owns the channel; 0 when the channel has no owning team | | detail_url | string | Yes | Detail URL | +| links | []object | No | Link integrations associated with the channel. Each entry includes name, endpoint, and open_type (popup or tab) | | group_method | string | No | Grouping method, enum: n: no grouping, p: rule-based grouping, i: intelligent grouping | @@ -214,6 +221,7 @@ Enter the integration name and description for easy management. | Config Item | Description | | :--- | :--- | +| **Managing Team** | Select the team that manages this integration; only team members can edit the integration configuration | | **Endpoint** | HTTP/HTTPS address to receive callbacks, must start with `http://` or `https://` | | **TLS Verification** | Enabled by default. When disabled, TLS certificate verification of the target server is skipped; suitable for test environments or self-signed certificates | | **Headers** | Custom request headers in Key-Value format; multiple headers supported | diff --git a/en/on-call/integration/webhooks/servicedesk-plus-sync.mdx b/en/on-call/integration/webhooks/servicedesk-plus-sync.mdx index ecf28fe5..f8625488 100644 --- a/en/on-call/integration/webhooks/servicedesk-plus-sync.mdx +++ b/en/on-call/integration/webhooks/servicedesk-plus-sync.mdx @@ -109,7 +109,7 @@ To sync ServiceDesk Plus requests to Flashduty, refer to this configuration item ``` # Private Deployment Version { - "suject":"${{request.subject}}", + "subject":"${{request.subject}}", "request_id":"${{request.id}}", "description":"${{request.description}}", "status":"${{request.status.name}}", diff --git a/en/on-call/quickstart/comparison.mdx b/en/on-call/quickstart/comparison.mdx index e08177a4..1be53091 100644 --- a/en/on-call/quickstart/comparison.mdx +++ b/en/on-call/quickstart/comparison.mdx @@ -184,7 +184,7 @@ Platform is the shared foundation underneath the four products above: how data g | **External Incident Submission** | ✅ Customers or partners can submit incidents **without logging in**, via a standalone page or API, with automatic escalation policy matching | Only supports email-to-incident, no structured form | Teams serving external customers can plug customer-reported issues directly into the handling process | | **Link Integration** | ✅ One-click jump to CMDB or internal systems by hostname and other labels | — | | | **Custom Webhooks (Outbound)** | Custom payload format, configurable retry conditions and automatic retries, signature-free verification, **full call-history tracing** (status codes, retry counts, request/response detail), subscribable by event type or source | Fixed payload format, fixed retry policy (3 retries, not configurable), no self-service call-history lookup | | -| **Open APIs** | ✅ 337 endpoints covering On-call, Monitors, RUM, AI SRE, and platform management | ✅ | Both provide rich APIs with detailed documentation | +| **Open APIs** | ✅ 330+ endpoints covering On-call, Monitors, RUM, AI SRE, and platform management | ✅ | Both provide rich APIs with detailed documentation | **Integration-on-demand commitment**: If a commercial or open-source tool you rely on isn't in our integration list yet, contact us — as long as you need it, we commit to fast turnaround support. @@ -229,9 +229,9 @@ Before reaching the team, alerts pass through routing, filtering, and transforma | Tool | Flashduty | PagerDuty | | --- | --- | --- | -| **[Open API](/en/openapi/api-catalog)** | 337 endpoints covering On-call, Monitors, RUM, AI SRE, and platform management, with bilingual docs | ✅ Full-featured REST API, mature documentation | +| **[Open API](/en/openapi/api-catalog)** | 330+ endpoints covering On-call, Monitors, RUM, AI SRE, and platform management, with bilingual docs | ✅ Full-featured REST API, mature documentation | | **[CLI](/en/developer/cli)** | 336 API operation commands + built-in Agent Skills, ready to hand directly to AI coding tools like Claude Code, Cursor, and Codex | No official CLI actively promoted: the community's most-used `pagerduty-cli` is an employee's personal project (officially not endorsed, and the author has announced it's archived); the official go-pagerduty library ships a limited `pd` command-line tool | -| **SDK** | [Go SDK](/en/developer/go-sdk): a go-github-style wrapper covering 337 API operations across 39 services | PagerDuty officially maintains go-pagerduty, python-pagerduty, and other client libraries | +| **SDK** | [Go SDK](/en/developer/go-sdk): a go-github-style wrapper covering 330+ API operations across 39 services | PagerDuty officially maintains go-pagerduty, python-pagerduty, and other client libraries | | **[Terraform Provider](/en/developer/terraform)** | 12 resource types + 13 data source types, managing collaboration spaces, escalation policies, schedules, and more as IaC | ✅ Official Terraform Provider, mature ecosystem | | **[MCP Server](/en/developer/mcp-server)** | 8 tool sets with 23 tools, deployable remotely, via Docker, or from source | ✅ Official MCP Server | diff --git a/en/on-call/quickstart/mobile-app.mdx b/en/on-call/quickstart/mobile-app.mdx new file mode 100644 index 00000000..0936cffa --- /dev/null +++ b/en/on-call/quickstart/mobile-app.mdx @@ -0,0 +1,175 @@ +--- +title: "Flashduty App (Mobile)" +sidebarTitle: "Mobile App" +description: "Use the Flashduty App and mobile H5 to receive alert notifications and handle incidents anywhere" +keywords: ["Flashduty App", "mobile", "mobile H5", "push notifications", "incident handling", "scan to sign in"] +--- + +Flashduty provides mobile capabilities across **iOS, Android, and mobile H5**. Wherever you are, you can receive incident notifications on your phone and perform all core handling actions — acknowledge, close, escalate, reassign, and more. + +## Download and Install + +--- + +For download and installation options (App Store, major Android app stores, QR-code package download), see [Personal Settings - Flashduty APP](/en/on-call/configuration/personal-settings#flashduty-app). + +Once installed, your first successful sign-in automatically binds the device to your account, and push notifications start working from then on. You can view and manage linked devices on the console's **Personal Center → Flashduty APP** page. + +## Sign-in Methods + +--- + + + + The App sign-in page offers two methods: + + - **Scan to sign in**: Tap **Scan to sign in** and scan the QR code shown on the console's **Personal Center → Flashduty APP** page. Signing in this way also completes device binding. On-premises environments are onboarded the same way — the App reads the service address from the QR code + - **Direct sign in**: Tap **Direct sign in** and complete account verification on the sign-in page opened inside the App. Verification code, password, and single sign-on (SSO) are supported. For on-premises deployments, use **Custom sign in domain** on the sign-in page to point at your own service address + + + When visiting the H5 console in a mobile browser, the following sign-in methods are supported: + + - **Code login**: Receive a verification code via phone or email + - **Password login**: Sign in with your account password + - **Single sign-on (SSO)**: Enter your enterprise domain or email to locate your organization's authentication method (including LDAP), then complete authentication with your identity provider + + + When you open a Flashduty notification link inside WeCom, Feishu/Lark, or DingTalk, the H5 page signs you in automatically through the platform's authorization mechanism — no need to re-enter account credentials; you land directly on the incident detail. + + + + +You can switch between 中文 and English anytime from the upper-right corner of the sign-in page. + + +## Incident Handling + +--- + +### Incident List and Filters + +The App home page is the incident list, split into two tabs: **Assigned to me** (with an incident-count badge) and **All**. Swipe left on an incident card to quickly **Acknowledge** or **Close** it. + +Tap the filter icon in the upper-right of the list to combine the following filters. Your filter choices are saved on the device: + +| Filter | Description | +| --- | --- | +| **Progress** | All / Open / Triggered / Processing / Closed (defaults to Open) | +| **Severity** | Critical / Warning / Info, multi-select | +| **Incident title / Incident ID** | Fuzzy search by keyword | +| **Related to me** | Show only incidents related to you | +| **People** | Filter by Creator, Responder, Ack'd by, or Closed by | +| **Channel** | Filter by the incident's channel | + +### Incident Detail and Actions + +Tap an incident to open its detail page, which has two tabs — **Overview** (title, severity, description, labels, custom fields, related alerts, war room entry, and more) and **Timeline** (handling history and comments) — with persistent actions at the bottom: + +| Action | Description | +| --- | --- | +| **Close** | Close the incident; a closed incident shows **Reopen** instead (a reopen reason is required) | +| **Acknowledge / Unacknowledge** | Acknowledge the incident to start working on it; undo if acknowledged by mistake | +| **More actions (⋮)** | Expand all supplementary actions, listed below | + +Available items under **More actions** adapt to the incident's state: + +| Action | Description | +| --- | --- | +| **Snooze** | Available for processing incidents; pauses escalation along the escalation rule | +| **Escalate** | Available when the incident was assigned via an enabled escalation rule; escalates it to the next level | +| **Reassign** | Available for incidents that are not closed; reassigns the incident to another person or schedule | +| **Quick silence** | Quickly create a silence rule based on the current incident | +| **AI summary** | Generate a summary of the incident handling process (Pro plan) | +| **War room** | Create war room, add stakeholders to war room, dissolve war room (Pro plan; requires an IM integration that supports war rooms) | +| **Jira and custom actions** | Custom actions such as Jira and ServiceNow configured by admins in integrations | + + +Consistent with the console: if an admin has configured a custom form for actions such as acknowledge or close, performing these actions in the App requires filling out the form first. + + +### Manually Create an Incident + +Tap the create button on the incident list page to manually create an incident: fill in the **incident title**, **severity**, and **description** (up to 200 characters), choose a **channel** and an **assignment type** (policy assignment or direct assignment to a person). Custom fields such as image upload are supported. Once created, the system immediately dispatches notifications via the selected method. + +## Push Notifications + +--- + +After you sign in, the current device is bound to your account automatically and starts receiving pushes. **Tapping a notification opens the corresponding incident detail page directly.** + + + + On iOS, Flashduty uses Apple's official **Critical Alerts** capability: notifications for Critical-severity incidents can break through silent and Do Not Disturb modes. + + Go to **Settings → Bypass do not disturb** in the App, or enable **Critical Alerts** in the system **Settings → Notifications → Flashduty**. + + + On Android, notifications are delivered through the Aliyun push channel, with two system notification channels created for incident notifications. Ringtone, vibration, and banner for each channel are managed separately in system notification settings (channel names appear in Chinese): + + | Notification channel | Description | + | --- | --- | + | **故障通知 (Incident notifications)** | The general channel, carrying Warning / Info severity incident notifications | + | **紧急通知 (Urgent notifications)** | Only Critical-severity incidents are routed to this channel — visible on the lock screen and able to bypass the system Do Not Disturb mode | + + Vendor push channels are adapted for Xiaomi and other Chinese manufacturers, so notifications still arrive even when the App is cleared from the background. + + + + +If pushes are not arriving, check in order: whether system notification permission is granted to Flashduty → whether your escalation rule includes the App push channel → (when the rule is set to "Follow Personal Preferences") whether Flashduty APP is selected in your personal notification preferences. See [Notification Channels](/en/on-call/configuration/notifications) for details. + + +## Useful Settings + +--- + +Tap the **settings icon** in the upper-right corner of the incident list page to open the settings page: + +| Setting | Description | +| --- | --- | +| **Notifications** | View notification permission status and jump to system notification settings | +| **Bypass do not disturb** (iOS) | Jump to system settings to enable Critical Alerts, so Critical incidents are not restricted by Do Not Disturb | +| **Sync contacts** | Create a Flashduty contact in your phone's address book and periodically sync voice-notification numbers into it, preventing voice alerts from being misidentified as spam. Only this contact is updated — no other address book information is read or stored | +| **Theme** | Follow system / Light / Dark | +| **Language** | 中文 / English | +| **Check for updates** | Check for a new app-store version; when your version is too old and no longer maintained, an immediate upgrade is required to continue using the App | + +## Mobile H5 + +--- + +**m.console.flashcat.cloud** is the web build from the same codebase as the App, with identical capabilities: + +- **Landing page for notification links**: incident-related links in SMS and IM messages (such as comment @mention notifications) open the incident detail page on H5 on mobile devices +- **Embedded in IM**: opened inside WeCom, Feishu/Lark, or DingTalk, it signs in automatically so you can handle incidents directly +- **Browser access**: visiting it directly in a mobile browser requires signing in first (verification code, password, or SSO) + +## Capability Boundaries + +--- + +The mobile side focuses on **receiving notifications and handling incidents**. The following configuration capabilities require the PC console: + +- Schedules, escalation rules, integration setup, and routing rules +- Notification templates, silence and grouping, and other noise-reduction configuration +- Personal notification preferences, contact binding, and other account settings + + +App push is offered only for the incident dispatch scenario. Collaboration notifications such as comment @mentions and work-item assignment do not offer App push — choose SMS, email, or IM under **Personal Center → Notification Preferences** in the PC console. + + +## Related Reading + +--- + + + + Learn all incident handling methods across console, IM, and voice + + + Configure App push and other notification channels + + + Download the App and manage linked devices + + diff --git a/en/on-call/statuspage/comparison.mdx b/en/on-call/statuspage/comparison.mdx index b31e8968..999f2911 100644 --- a/en/on-call/statuspage/comparison.mdx +++ b/en/on-call/statuspage/comparison.mdx @@ -68,7 +68,7 @@ Before evaluating specific products, there's a more fundamental question to answ | Feature | Flashduty | Atlassian Statuspage | | --- | --- | --- | | **Incident Publishing** | ✅ Create incidents, update timelines, notify subscribers | ✅ Supported | - | **Maintenance Events** | ✅ Schedule start/end times with auto-progression and manual override; **maintenance excluded from uptime calculation**, ideal for separating outages from planned maintenance | ❌ Not supported | + | **Maintenance Events** | ✅ Schedule start/end times with auto-progression and manual override; **maintenance excluded from uptime calculation**, ideal for separating outages from planned maintenance | ✅ Supports Scheduled Maintenance: start time and duration, automatic status progression, and subscriber reminders | | **Backfill Incidents** | ✅ Backfill incidents included in event history and availability statistics, with impact periods calculated from component status changes in the timeline -- **complete closed loop for historical records and availability tracking** | ✅ Supports backfill incidents, but with limited integration between backfill and availability statistics | | **Incident Templates** | ✅ Supported | ✅ Supported | | **Component Status Linking** | ✅ Supported | ✅ Supported | @@ -80,11 +80,11 @@ Before evaluating specific products, there's a more fundamental question to answ | **Full Subscription** | ✅ Supported | ✅ Supported | | **Component Subscription** | ✅ **Available in all editions** | Business and above only | | **Incident Subscription** | ✅ Subscribe to updates for a specific incident | ❌ Not supported | - | **Bulk Import/Export** | ✅ Admins can bulk import and export subscribers | ❌ Not supported | + | **Bulk Import/Export** | ✅ Admins can bulk import and export subscribers (import requires Pro; export requires Standard or above) | ✅ CSV import and JSON/CSV export | | **Self-service Management** | ✅ Subscribers manage their own scope or unsubscribe via management tokens | Limited self-service capabilities | - Flashduty offers finer-grained subscription management: full, component, and incident-level subscriptions all included, with no plan-tier restrictions. + Flashduty offers finer-grained subscription management: full, component, and incident-level subscriptions all included. @@ -189,17 +189,17 @@ See the [Service Level Agreement (SLA)](/en/compliance/service-sla) for full ava --- -Flashduty CLI supports one-click migration of components, sections, incident history, and email subscribers from Atlassian Statuspage, with `history.rss` and `history.atom` link format compatibility so existing RSS/Atom subscribers need no changes. +Flashduty CLI supports one-click migration of components, sections, incident history, and email subscribers from Atlassian Statuspage (migration requires the Pro plan), with `history.rss` and `history.atom` link format compatibility so existing RSS/Atom subscribers need no changes. - Use `flashduty statuspage migrate structure` to automatically import components, sections, historical incidents, and notification templates -- this step does not notify subscribers + Use `flashduty status-page migrate-structure` to automatically import components, sections, historical incidents, and notification templates -- this step does not notify subscribers Check the imported components, sections, and incident history in the Flashduty Console - Use `flashduty statuspage migrate email-subscribers` to import subscribers -- imported subscribers are immediately active + Use `flashduty status-page migrate-email-subscribers` to import subscribers -- imported subscribers are immediately active Point your custom domain CNAME to Flashduty, confirm everything works, and go live @@ -218,7 +218,7 @@ For detailed command flags and a complete migration walkthrough, see the migrati - Maintenance events, incident subscriptions, component display controls, bulk import/export, native IM notifications, and more **exclusive capabilities** -- with no plan-tier restrictions + Incident subscriptions, component display controls, maintenance excluded from uptime calculation, native IM notifications, and other **differentiated capabilities** Status page included in the On-call module, **no separate purchase needed**. Compared to Atlassian Statuspage's thousands of dollars per year in standalone fees, the additional cost is zero diff --git a/en/on-call/statuspage/get-started.mdx b/en/on-call/statuspage/get-started.mdx index 712df905..e9991674 100644 --- a/en/on-call/statuspage/get-started.mdx +++ b/en/on-call/statuspage/get-started.mdx @@ -42,7 +42,7 @@ Creating from scratch only establishes the status page entity and confirms its n | Field | Description | | --- | --- | | **Name** | Display name for the status page, usually your company, product, or service name | - | **URL slug** | Unique identifier used to build the status page URL; only lowercase letters, numbers, and hyphens are allowed | + | **URL slug** | Unique identifier used to build the status page URL; only lowercase letters, numbers, hyphens, and underscores are allowed | | **Type** | Choose **Public** or **Internal** | @@ -55,7 +55,13 @@ Creating from scratch only establishes the status page entity and confirms its n ## Migrate from Atlassian Statuspage -If you already use Atlassian Statuspage, you can use Flashduty CLI to migrate **components, sections, historical events, and email subscribers** to Flashduty Status Page. Migration is split into two independent steps: +If you already use Atlassian Statuspage, you can use Flashduty CLI to migrate **components, sections, historical events, and email subscribers** to Flashduty Status Page. + + +**Plan requirement**: migration (structure & history migration and email subscriber migration) requires the Flashduty **Pro** plan. + + +Migration is split into two independent steps: 1. **Migrate structure and history**: import components, sections, historical events, maintenance records, and notification templates. 2. **Migrate email subscribers**: import the subscriber list and subscription preferences. @@ -119,18 +125,15 @@ Migrate structure and history first, then migrate subscribers, and switch the do Run the following command to import Atlassian Statuspage components, sections, historical events, maintenance records, and notification templates. This step creates or reuses the target Flashduty status page but does not notify subscribers. ```bash - flashduty statuspage migrate structure \ - --from atlassian \ - --source-page-id \ + flashduty status-page migrate-structure \ --api-key "$ATLASSIAN_STATUSPAGE_API_KEY" ``` | Flag | Required | Description | | --- | --- | --- | - | `--from` | Yes | Migration source, currently only `atlassian` | - | `--source-page-id` | Yes | Atlassian Statuspage Page ID | + | `` | Yes | Atlassian Statuspage Page ID (positional argument; can also be passed via `--source-page-id`) | | `--api-key` | Yes | Atlassian Statuspage API Key | - | `--url-name` | No | URL name for the newly created Flashduty public status page | + | `--url-name` | No | URL name for the newly created Flashduty public status page; when omitted, the source page's URL name is reused | `--url-name` is honored **only when this run creates a new target status page.** If the same `--source-page-id` is already mapped to an existing Flashduty status page from a previous migration: @@ -149,15 +152,15 @@ Migrate structure and history first, then migrate subscribers, and switch the do Migration jobs run asynchronously, and the command returns immediately with a **Job ID**. Check progress with: ```bash - flashduty statuspage migrate status --job-id + flashduty status-page migration-status ``` - The migration imports `components`, `sections`, `history`, and `templates` in order. When the job completes, the output includes the Flashduty status page ID (`target-page-id`), which you need for subscriber migration. + The structure and history migration completes 5 steps in order: create (or reuse) the target status page → import sections → import components → import historical incidents (including maintenances) → import event templates. When the job completes, the output's `target_page_id` is the Flashduty status page ID, which you need for subscriber migration. To cancel a running migration job, run: ```bash - flashduty statuspage migrate cancel --job-id + flashduty status-page migration-cancel ``` @@ -165,11 +168,14 @@ Migrate structure and history first, then migrate subscribers, and switch the do Before proceeding, verify the imported data: ```bash - # View the new status page - flashduty statuspage list --id + # List status pages + flashduty status-page list - # View imported incidents - flashduty statuspage changes --page-id --type incident + # View the target status page details (including component and section IDs) + flashduty status-page info + + # View imported incidents (both --type and --status are required) + flashduty status-page change-list --type incident --status resolved ``` You can also log in to the [Flashduty console](https://console.flashcat.cloud) to visually inspect components, sections, and incident history. @@ -179,8 +185,7 @@ Migrate structure and history first, then migrate subscribers, and switch the do After confirming the structure and history are correctly imported, run the subscriber migration: ```bash - flashduty statuspage migrate email-subscribers \ - --from atlassian \ + flashduty status-page migrate-email-subscribers \ --source-page-id \ --target-page-id \ --api-key "$ATLASSIAN_STATUSPAGE_API_KEY" @@ -188,9 +193,8 @@ Migrate structure and history first, then migrate subscribers, and switch the do | Flag | Required | Description | | --- | --- | --- | - | `--from` | Yes | Migration source, `atlassian` | | `--source-page-id` | Yes | Atlassian Statuspage Page ID | - | `--target-page-id` | Yes | Flashduty status page ID returned by the structure and history migration | + | `--target-page-id` | Yes | Flashduty status page ID returned by the structure and history migration (`target_page_id`) | | `--api-key` | Yes | Atlassian Statuspage API Key | Imported subscribers become active immediately without email verification. Email addresses marked as quarantined on the Atlassian side are automatically skipped. Subscriber migration can safely be run multiple times, and existing subscribers will not be duplicated. @@ -210,30 +214,27 @@ Migrate structure and history first, then migrate subscribers, and switch the do export ATLASSIAN_STATUSPAGE_API_KEY="your_api_key_here" # 1. Migrate structure and history -flashduty statuspage migrate structure \ - --from atlassian \ - --source-page-id 0db0rq26tg1l \ +flashduty status-page migrate-structure 0db0rq26tg1l \ --api-key "$ATLASSIAN_STATUSPAGE_API_KEY" -# Output: Job ID: str_abc +# Returns a job_id (ULID format), e.g. 01KP0311872NVYFRRQ82FW0001 # 2. Poll until completed -flashduty statuspage migrate status --job-id str_abc -# Repeat until Status: completed -# Record the target-page-id from output +flashduty status-page migration-status 01KP0311872NVYFRRQ82FW0001 +# Repeat until status is completed +# Record the target_page_id from the output # 3. Verify imported content -flashduty statuspage list --id +flashduty status-page info # 4. Migrate email subscribers -flashduty statuspage migrate email-subscribers \ - --from atlassian \ +flashduty status-page migrate-email-subscribers \ --source-page-id 0db0rq26tg1l \ --target-page-id \ --api-key "$ATLASSIAN_STATUSPAGE_API_KEY" -# Output: Job ID: sub_xyz +# Returns the job_id of the subscriber migration job, e.g. 01KP04M3W5EZY0QHAJ2VB00002 # 5. Poll until completed -flashduty statuspage migrate status --job-id sub_xyz +flashduty status-page migration-status 01KP04M3W5EZY0QHAJ2VB00002 ``` --- diff --git a/en/on-call/statuspage/publish-events.mdx b/en/on-call/statuspage/publish-events.mdx index c280413b..0ac1f899 100644 --- a/en/on-call/statuspage/publish-events.mdx +++ b/en/on-call/statuspage/publish-events.mdx @@ -35,26 +35,34 @@ Components are marked **Under Maintenance** only during the maintenance's actual ## Publish an event - - In the status page management view, click **Publish Event** and choose either **Incident** or **Maintenance**. + + In the status page detail view, incidents and maintenance have their own independent entries: + + - **Publish an incident**: go to the **Incidents** page and click **New incident**; to backfill a historical incident, click **Retrospective incident** + - **Publish a maintenance**: go to the **Maintenance** page and click **Schedule maintenance** Configure the following fields: | Field | Description | | --- | --- | - | **Title** | Brief title for the event | - | **Description** | Detailed description of the event | - | **Status** | Initial status of the event | - | **Affected components** | Select components affected by this event and set an impact status for each | - | **Responders** | Assign team members involved in handling the event | + | **Incident name / Maintenance name** | Brief title for the event, displayed publicly on the status page (required) | + | **Current status** | Initial status of the event | + | **Message** | Detailed description of the event (required), shown on the status page to describe the event status | + | **Affected components** | Select components affected by this event and set an impact status for each (at least 1 required) | | **Notify subscribers** | Whether to send notifications to subscribers when publishing | + + When publishing a maintenance, you must also fill in the **Impact window** (planned start and end times), and the end time must be later than the start time. + + + The **Responders** field is only available via the API / CLI; the console publish form does not offer this option. + Every event requires at least one timeline update. The system automatically generates an initial update record based on the information you provide. - After confirming the details, click **Publish** to create the event. + After confirming the details, click **Publish incident** or **Publish maintenance** to create the event. @@ -85,7 +93,7 @@ When an event reaches a terminal status (Resolved for incidents, Completed for m ### Markdown formats supported in messages -The editor for event descriptions and timeline updates supports the following Markdown elements, which public status pages render in the same format: +The editor for event messages and timeline updates supports the following Markdown elements, which public status pages render in the same format: | Format | Syntax example | | --- | --- | @@ -116,7 +124,7 @@ Each timeline update can include: | --- | --- | | **Timestamp** | The actual time this update corresponds to | | **Status change** | Advance the event to its next lifecycle status (optional) | -| **Description** | Narrative text about the current progress | +| **Message** | Narrative text about the current progress (required) | | **Component status changes** | Adjust the service status of affected components (optional) | @@ -179,6 +187,10 @@ Retrospective events allow you to: Retrospective events are displayed on the status page in the same way as regular events and are included in event history and uptime calculations. + +When creating a retrospective incident, the timeline must contain at least one update in a status other than **Resolved**, so the incident's progression can be presented. + + If a retrospective event is created with a terminal status and no end time specified, the system automatically uses the timestamp of the last update as the end time. diff --git a/en/on-call/statuspage/subscriptions.mdx b/en/on-call/statuspage/subscriptions.mdx index 3cec6081..ec5828c4 100644 --- a/en/on-call/statuspage/subscriptions.mdx +++ b/en/on-call/statuspage/subscriptions.mdx @@ -93,12 +93,25 @@ When "All updates" is selected, component-level and event-level subscription set ## Administrator subscription management +### Subscription settings + +On the **Subscriptions** page of the status page settings, **Enable subscriptions** is a page-level master switch: it controls email subscriptions for public status pages and IM subscriptions for internal status pages. When it is off, the system does not push notifications to subscribers even if "Notify subscribers" is checked when publishing an event. + +Usage rules for subscription notifications: + +- **Email (public status pages)**: event notification emails count toward the Flashduty account's email quota. For Free plan accounts, event notification emails stop being sent once the quota is exceeded. For paid plan accounts, emails beyond the quota are billed separately, and notifications stop only when the account is in arrears. +- **IM (internal status pages)**: event notifications count toward the API call quota of the corresponding IM platform; when the IM platform's API quota is exceeded, notifications stop being sent. API call limits usually depend on the IM platform pricing plan your organization uses. + ### View subscribers -In the status page settings under **Subscription Management**, administrators can view the current subscriber list and filter by subscription method or component. The list supports pagination and displays each subscriber's email address (or user ID), subscription method, and subscribed components. +In the Subscriber List section of the **Subscriptions** page in the status page settings, administrators can view the current subscriber list and filter by component. The list supports pagination and displays each subscriber's email address (or user ID), subscription method, and subscribed components. ### Bulk import + +**Plan requirement**: bulk importing subscribers requires the Flashduty **Pro** plan. + + Administrators can bulk import subscribers, useful for migration scenarios or pre-configuring subscriptions for specific user groups. The following fields are required for import: | Field | Description | @@ -113,6 +126,10 @@ Subscriptions imported by administrators do not require email confirmation and t ### Export subscribers + +**Plan requirement**: exporting subscribers requires the Flashduty **Standard** plan or above. + + Administrators can export the subscriber list, including each subscriber's recipient address, subscription method, and subscribed components. --- diff --git a/en/on-call/statuspage/templates.mdx b/en/on-call/statuspage/templates.mdx index 0b4631be..a272a7a1 100644 --- a/en/on-call/statuspage/templates.mdx +++ b/en/on-call/statuspage/templates.mdx @@ -1,17 +1,17 @@ --- title: "Event templates" -description: "Learn how to use pre-defined templates and message templates to quickly publish status page events" +description: "Learn how to use complete status update and status description templates to quickly publish status page events" --- Manually filling in event details is time-consuming and prone to missing key information. Flashduty Status Pages provide **event templates** that let you quickly publish events using pre-set content, reducing repetitive work. -Status pages support two template types: **pre-defined templates** and **message templates**. +Status pages support two template types: **complete status updates** (pre-defined templates) and **status descriptions** (message templates). --- -## Pre-defined templates +## Complete status updates (pre-defined templates) -Pre-defined templates are used to quickly create events with complete initial information. Each pre-defined template contains the following fields: +Complete status update templates are used to quickly create events with complete initial information. Each complete status update template contains the following fields: | Field | Description | | --- | --- | @@ -22,19 +22,19 @@ Pre-defined templates are used to quickly create events with complete initial in ### Use cases -Pre-defined templates are ideal for foreseeable, recurring event scenarios. For example: +Complete status update templates are ideal for foreseeable, recurring event scenarios. For example: - **Routine maintenance**: Create a template titled "Scheduled System Maintenance" with status pre-set to Scheduled and standard maintenance notification wording in the description - **Known issues**: Create templates for common service degradation scenarios with pre-set titles and descriptions -### Manage pre-defined templates +### Manage complete status update templates - In the status page settings under the **Templates** tab, select **Pre-defined Templates** and click **Create Template**. Fill in the title, type, status, and description. + In the status page settings under the **Event Templates** tab, select **Complete status update** and click **Create Template**. Fill in the title, type, status, and description. - When publishing an event, select a pre-defined template. The system auto-fills the template fields, which you can then adjust as needed. + When publishing an event, select a complete status update template. The system auto-fills the template fields, which you can then adjust as needed. You can modify a template's title, description, and status at any time, or delete templates that are no longer needed. @@ -43,11 +43,11 @@ Pre-defined templates are ideal for foreseeable, recurring event scenarios. For --- -## Message templates +## Status descriptions (message templates) -Message templates are used to pre-set update messages for different event status stages. Unlike pre-defined templates which focus on event initialization, message templates focus on the notification wording used as events progress. +Status description templates are used to pre-set update messages for different event status stages. Unlike complete status update templates which focus on event initialization, status description templates focus on the notification wording used as events progress. -Each message template contains the following fields: +Each status description template contains the following fields: | Field | Description | | --- | --- | @@ -57,10 +57,10 @@ Each message template contains the following fields: ### Message mapping -Message templates provide pre-set text for each status in the event lifecycle: +Status description templates provide pre-set text for each status in the event lifecycle: - + | Status | Example pre-set message | | --- | --- | | **Investigating** | "We are investigating an issue affecting [service name]." | @@ -68,7 +68,7 @@ Message templates provide pre-set text for each status in the event lifecycle: | **Monitoring** | "A fix has been implemented and we are continuing to monitor." | | **Resolved** | "The issue has been resolved and service is operating normally." | - + | Status | Example pre-set message | | --- | --- | | **Scheduled** | "Planned maintenance will begin at [time]." | @@ -79,16 +79,16 @@ Message templates provide pre-set text for each status in the event lifecycle: ### Use cases -Message templates are ideal for standardizing event update wording, ensuring that different team members use consistent language when progressing events. +Status description templates are ideal for standardizing event update wording, ensuring that different team members use consistent language when progressing events. -### Manage message templates +### Manage status description templates - In the status page settings under the **Templates** tab, select **Message Templates** and click **Create Template**. Fill in the title, type, and message content for each status. + In the status page settings under the **Event Templates** tab, select **Status description** and click **Create Template**. Fill in the title, type, and message content for each status. - When adding a timeline update to an event, select a message template. The system auto-fills the message text based on the current event status. + When adding a timeline update to an event, select a status description template. The system auto-fills the message text based on the current event status. You can update a template's title, type, and message content at any time, or delete templates that are no longer needed. @@ -99,4 +99,4 @@ Message templates are ideal for standardizing event update wording, ensuring tha ## Template preference -You can configure a **default template type** in the status page settings. When publishing events, the corresponding template list will be shown by default. This preference does not prevent you from switching to other template types. +You can choose a **default template type** (**Status description** or **Complete status update**) at the top of the **Event Templates** tab in the status page settings. When publishing events, the corresponding template list will be shown by default. This preference does not prevent you from switching to other template types. diff --git a/en/openapi/api-catalog.mdx b/en/openapi/api-catalog.mdx index 64823d4a..8edc2243 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 **338** 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 **335** 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. All endpoint URLs use `https://api.flashcat.cloud` as the base, authenticated via APP Key through query string. @@ -269,7 +269,7 @@ All endpoint URLs use `https://api.flashcat.cloud` as the base, authenticated vi - + ### Alert rules @@ -285,7 +285,6 @@ All endpoint URLs use `https://api.flashcat.cloud` as the base, authenticated vi | POST | [`/monit/rule/import`](/en/api-reference/monitors/alert-rules/monit-rule-write-import) | Import alert rules | | POST | [`/monit/rule/export`](/en/api-reference/monitors/alert-rules/monit-rule-read-export) | Export alert rules | | POST | [`/monit/rule/move`](/en/api-reference/monitors/alert-rules/monit-rule-write-move) | Move alert rules to folder | -| POST | [`/monit/rule/status`](/en/api-reference/monitors/alert-rules/monit-rule-write-status) | Get rule trigger status under folder | | POST | [`/monit/rule/audits`](/en/api-reference/monitors/alert-rules/monit-rule-read-audits) | List rule change history | | POST | [`/monit/rule/audit/detail`](/en/api-reference/monitors/alert-rules/monit-rule-read-audit-detail) | Get rule audit snapshot | | POST | [`/monit/rule/dstypes`](/en/api-reference/monitors/alert-rules/monit-rule-read-dstypes) | List available datasource types | @@ -321,7 +320,6 @@ All endpoint URLs use `https://api.flashcat.cloud` as the base, authenticated vi | Method | Endpoint | Description | | :--- | :--- | :--- | | POST | [`/monit/query/data`](/en/api-reference/monitors/diagnostics/monit-read-query-data) | Query structured data | -| POST | [`/monit/query/rows`](/en/api-reference/monitors/diagnostics/monit-read-query-rows) | Query data source rows | | POST | [`/monit/query/diagnose`](/en/api-reference/monitors/diagnostics/monit-read-query-diagnose) | Diagnose data source | | POST | [`/monit/tools/catalog`](/en/api-reference/monitors/diagnostics/monit-read-tools-catalog) | List target tool catalog | | POST | [`/monit/tools/invoke`](/en/api-reference/monitors/diagnostics/monit-read-tools-invoke) | Invoke target tools | @@ -331,7 +329,6 @@ All endpoint URLs use `https://api.flashcat.cloud` as the base, authenticated vi | Method | Endpoint | Description | | :--- | :--- | :--- | -| POST | [`/monit/preview/sync`](/en/api-reference/monitors/monitor-utilities/monit-preview-sync) | Preview datasource query | ### Service map diff --git a/en/platform/configure-sso.mdx b/en/platform/configure-sso.mdx index 6f35e280..82a9a997 100644 --- a/en/platform/configure-sso.mdx +++ b/en/platform/configure-sso.mdx @@ -41,7 +41,7 @@ The egress IPs above apply only to Flashduty's **SaaS (public cloud) service**. | Stable User ID Field (`user_id`) | Optional. The unique user identifier attribute returned by the identity provider, used to recognize the same member; email or phone changes do not affect recognition. If left empty, members are matched by the email/phone fields below. Recommended value: `employee_id`; enter `name_id` to use the NameID (Subject) of the SAML assertion. See [Member Association](#member-association) below | | Create Account on Sign In | Enabled by default; when disabled, members must be invited before they can sign in | | SSO-only login (`force_sso`) | Enabled by default. When on, every member of this account can sign in only via SSO; password and verification-code sign-in are rejected. See [SSO-only login](#sso-only-login) below | -| Flashduty Service Provider Info | **Service Provider Metadata** and **Assertion Consumer Service URL** (assertion address for identity provider to call for single sign-on) | +| Flashcat Service Provider Info | **Service Provider Metadata** and **Assertion Consumer Service URL** (assertion address for identity provider to call for single sign-on) | ## Configuring OIDC Protocol @@ -60,7 +60,7 @@ The egress IPs above apply only to Flashduty's **SaaS (public cloud) service**. | Create Account on Sign In | Enabled by default; when disabled, members must be invited before they can sign in | | SSO-only login (`force_sso`) | Enabled by default. When on, every member of this account can sign in only via SSO; password and verification-code sign-in are rejected. See [SSO-only login](#sso-only-login) below | | Scopes | Specifies the information and functionality permissions the request can access, with support for customization. Defaults to `openid`, `profile`, `email`, `phone`; you can add custom scopes as tags | -| Flashduty Service Provider Info | **Redirect URL**: Identity provider callback address
**Supported Signing Algorithms**: RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512 (HS256 not supported) | +| Flashcat Service Provider Info | **Redirect URL**: Identity provider callback address
**Supported Signing Algorithms**: RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512 (HS256 not supported) | Scopes is a required field. The default values `openid`, `profile`, `email`, `phone` are the base permissions needed for OIDC to function properly. Removing these defaults may cause single sign-on to fail or prevent correct retrieval of user information. If you need to add custom scopes, add them while keeping the defaults intact. @@ -82,7 +82,7 @@ Scopes is a required field. The default values `openid`, `profile`, `email`, `ph | Stable User ID Field (`user_id`) | Optional. The unique user identifier used to recognize the same member; email or phone changes do not affect recognition. If left empty, members are matched by the email/phone fields below. Recommended value: `principal` (the CAS authenticated username); you can also map it to a returned attribute. See [Member Association](#member-association) below | | Create Account on Sign In | Enabled by default; when disabled, members must be invited before they can sign in | | SSO-only login (`force_sso`) | Enabled by default. When on, every member of this account can sign in only via SSO; password and verification-code sign-in are rejected. See [SSO-only login](#sso-only-login) below | -| Flashduty Service Provider Info | **Redirect URL**: Identity provider callback address | +| Flashcat Service Provider Info | **Redirect URL**: Identity provider callback address | ## Configuring LDAP Protocol @@ -114,7 +114,7 @@ Field mapping must be consistent with the identity provider configuration, other ### LDAP Connection Test -After configuring the LDAP connection information, you can click the **Connection Test** button at the bottom of the settings drawer to verify that Flashduty can successfully connect to your LDAP server. The system will attempt to establish a connection using the currently entered LDAP URL, BIND DN, and password, and return a success or failure result. +After configuring the LDAP connection information, you can click **Test connection** below the LDAP form in the **Protocol & connection** section to verify that Flashduty can successfully connect to your LDAP server. The system will attempt to establish a connection using the currently entered LDAP URL, BIND DN, and password, and return a success or failure result. We recommend running the connection test before saving the configuration to ensure connection parameters are correct, avoiding login failures due to misconfiguration. @@ -180,7 +180,7 @@ The `force_sso` option restricts every member of the account to signing in throu | Item | Behavior | | --- | --- | | Field name | `force_sso` | -| Default | **On** — the toggle in the settings drawer is pre-filled to enabled the first time SSO is configured | +| Default | **On** — the toggle on the SSO settings page is pre-filled to enabled the first time SSO is configured | | When enabled | Every member of the account can sign in only via SSO; password and verification-code sign-in are rejected by the backend | | When disabled | Members may sign in via SSO, password, or verification code | | Exemptions | **None.** The account owner and super-admins are also subject to this restriction — there is no bypass branch | diff --git a/integration-docs/src/doc-map.mjs b/integration-docs/src/doc-map.mjs index 39f2e9f7..5731bb1f 100644 --- a/integration-docs/src/doc-map.mjs +++ b/integration-docs/src/doc-map.mjs @@ -64,6 +64,8 @@ export const docMap = { AliyunPrometheus: `${alertBase}/aliyun-prometheus.mdx`, HttpPull: `${alertBase}/http-pull.mdx`, DbPull: `${alertBase}/db-pull.mdx`, + Emqx: `${alertBase}/emqx.mdx`, + Rizhiyi: `${alertBase}/rizhiyi.mdx`, CustomChange: `${integrationBase}/change-integration/custom-event.mdx`, Jira: { @@ -92,7 +94,5 @@ export const docMap = { export const optionalMissingKeys = [ // These keys are referenced defensively by fc-saas-web but were not present // in the old published knowledge-base package either. - 'Emqx', - 'Rizhiyi', 'Datadog' ]; diff --git a/zh/changelog/changelog.mdx b/zh/changelog/changelog.mdx index 8179ce2f..e2a20eed 100644 --- a/zh/changelog/changelog.mdx +++ b/zh/changelog/changelog.mdx @@ -210,6 +210,18 @@ AI SRE 向所有账户全量开放公测：无需申请，登录控制台即可 + + +### 故障评论 @提及 通知 + +在故障评论与故障复盘中 @提及成员，被提及人会实时收到通知，关键协作信息不再被淹没： + +- 在故障详情的评论区或复盘报告中输入 `@` 即可选择并提及成员，通知中附带评论内容、故障摘要与详情链接，点击可直达故障详情 +- 通知渠道按被提及人的个人偏好投递：支持短信、邮件与各类 IM 应用（钉钉、飞书、企业微信、Slack、Microsoft Teams），默认通过邮件通知 +- 在 **个人中心 → 通知偏好 → 协作与跟进 → 协作提及** 中修改接收方式；同一评论不会重复通知 + + + ### AI SRE 自治排障 Agent diff --git a/zh/developer/cli.mdx b/zh/developer/cli.mdx index e57bc764..6d46058c 100644 --- a/zh/developer/cli.mdx +++ b/zh/developer/cli.mdx @@ -474,12 +474,11 @@ FDUTY ### monit-query — 监控数据源查询 -直接探测监控后端数据源，无需经过告警规则层。`data` 子命令支持 9 种数据源类型（Prometheus、VictoriaLogs、Loki、MySQL、SLS、Elasticsearch、PostgreSQL、Oracle、ClickHouse）；`diagnose` 支持 `prometheus`（指标趋势）、`victorialogs`、`loki`（日志模式）；已弃用的 `rows` 支持 `prometheus`、`victorialogs`、`loki`、`mysql`。 +直接探测监控后端数据源，无需经过告警规则层。`data` 子命令支持 9 种数据源类型（Prometheus、VictoriaLogs、Loki、MySQL、SLS、Elasticsearch、PostgreSQL、Oracle、ClickHouse）；`diagnose` 支持 `prometheus`（指标趋势）、`victorialogs` 和 `loki`（日志模式）。 ```bash flashduty monit-query diagnose [flags] # 预聚合 RCA 分析（日志模式或指标趋势） -flashduty monit-query data [flags] # 结构化数据源查询（推荐） -flashduty monit-query rows [flags] # 原始数据直通查询（已弃用，请改用 data） +flashduty monit-query data [flags] # 结构化数据源查询 ``` `diagnose` 常用参数： diff --git a/zh/developer/go-sdk.mdx b/zh/developer/go-sdk.mdx index dde3ba57..3800145a 100644 --- a/zh/developer/go-sdk.mdx +++ b/zh/developer/go-sdk.mdx @@ -161,7 +161,6 @@ client, err := flashduty.NewClient("YOUR_APP_KEY", | `client.NotificationTemplates` | 通知模板 | | `client.Changes` | 变更 | | `client.Diagnostics` | 诊断 | -| `client.MonitorUtilities` | 监控数据源预览 | | `client.ServiceMap` | 服务拓扑（ServiceMap） | | `client.Analytics` | 分析 | | `client.A2aAgents` | A2A Agents | @@ -182,7 +181,7 @@ client, err := flashduty.NewClient("YOUR_APP_KEY", `client.Knowledge` 对应 `/safari/knowledge/*` 的 9 个 API 操作：知识包侧为 `PackReadGet`（获取账户知识包）、`PackReadList`（列出知识包）、`PackWriteEnsure`（确保知识包存在）、`PackWriteUpdate`（变更知识包作用域）、`PackWriteDelete`（删除知识包）；知识文件侧为 `FileReadGet`、`FileReadList`、`FileWritePut`（上传/覆盖）、`FileWriteDelete`。相关导出类型包括 `KnowledgePackItem`、`KnowledgeFileItem`、`KnowledgeWarning` 以及各 `Knowledge*Request` / `Knowledge*Response`。 -`client.Diagnostics`（诊断）提供数据源查询方法：`QueryData` 通过 `POST /monit/query/data` 执行同步查询，返回稳定的 `query_result.v1` 结构化结果（`format` 固定为 `query_result.v1`，`result.kind` 为 `frames` / `records` / `samples` 之一），该接口要求 monit-edge v0.65.0 及以上版本；`QueryRows`（`POST /monit/query/rows`）已弃用，返回历史压平的行结构，建议迁移到 `QueryData`；`QueryDiagnose`（`POST /monit/query/diagnose`）用于预聚合 RCA 分析（日志模式或指标趋势），最长运行 35 秒。 +`client.Diagnostics`（诊断）提供数据源查询方法：`QueryData` 通过 `POST /monit/query/data` 执行同步查询，返回稳定的 `query_result.v1` 结构化结果（`format` 固定为 `query_result.v1`，`result.kind` 为 `frames` / `records` / `samples` 之一），该接口要求 monit-edge v0.65.0 及以上版本；`QueryDiagnose`（`POST /monit/query/diagnose`）用于预聚合 RCA 分析（日志模式或指标趋势），最长运行 35 秒。 所有标识符、服务字段名与方法名均与生成代码保持一致。具体每个服务有哪些方法、请求与响应类型,请以 `services_gen.go` 与各服务文件,以及 [Open API 参考](/zh/openapi/introduction) 为准。 diff --git a/zh/on-call/analytics/insights.mdx b/zh/on-call/analytics/insights.mdx index 27502f73..a5179819 100644 --- a/zh/on-call/analytics/insights.mdx +++ b/zh/on-call/analytics/insights.mdx @@ -36,7 +36,7 @@ keywords: ["分析看板", "数据分析", "故障统计", "报表导出", "运 | 团队 | 选择需要查询的团队名称，支持多选，选中后会按选中的团队更新仪表盘中的数据 | | 协作空间 | 选择需要查询的协作空间名称，支持多选，选中后会按选中的协作空间更新仪表盘中的数据 | | 严重程度 | 选择需要查询的严重程度，支持多选，选中后会按选中的严重程度更新仪表盘中的数据 | -| 时间范围 | 选择需要查询的时间范围，支持按本周、最近两周、本月、上个月以及自定义时间的维度进行查询，但最多支持查询最近 **1 年** 的数据 | +| 时间范围 | 选择需要查询的时间范围，支持按本周、最近两周、本月、上个月以及自定义时间的维度进行查询，最长支持查询最近 **2 年（720 天）** 的数据（具体上限以您的订阅版本为准） | | 数据间隔 | 支持天、周、月的维度进行查询，默认按小时进行查询，但查询的时间范围大于 31 天时，无法以天的维度进行预览 | | 排序 | 团队、协作空间和个人维度的仪表盘可以选择倒排和正排，默认只显示 TOP 10 的数据，单独放大后可以展示更多 | @@ -108,9 +108,19 @@ keywords: ["分析看板", "数据分析", "故障统计", "报表导出", "运 -以 CSV 格式导出故障列表、团队、协作空间和个人维度数据。导出前可以在弹窗中选择需要的字段；故障列表的导出字段为**固定集合**（共 28 个）：故障ID、故障标题、严重程度、处理进度、协作空间ID、协作空间、团队ID、团队、触发时间、认领耗时、关闭耗时、关闭方式、响应投入、通知次数、中断次数、认领次数、分派次数、重新分派次数、升级次数、手动升级次数、自动升级次数、分派方式、处理人员、故障描述、故障标签、自定义字段、发起人ID、发起人姓名。开启 **提取 HTML 中的文本内容** 后，故障描述会以纯文本写入 CSV，便于在表格工具中阅读。 +以 CSV 格式导出故障列表、团队、协作空间和个人维度数据，单次最多导出 **10000** 条。导出前可以在弹窗中选择需要的字段；故障列表的导出提供 **42 个可选字段**（默认全选），按用途分组如下： -故障列表的导出字段不随页面展示的扩展字段变化：告警数量、活跃告警数量、告警事件、负责人、关闭人、屏蔽至、曾被收敛、新奇故障等扩展字段仅用于页面展示，不参与 CSV 导出。 +| 分组 | 字段 | +| :--- | :--- | +| 基本信息 | 故障ID、故障标题、严重程度、处理进度、故障描述、故障标签、自定义字段 | +| 归属 | 协作空间ID、协作空间、团队ID、团队 | +| 时间与效率 | 触发时间、认领耗时、关闭耗时、关闭方式、响应投入、时间段 | +| 通知与分派 | 通知次数、中断次数、认领次数、分派次数、重新分派次数、升级次数、手动升级次数、自动升级次数、分派方式、处理人员、分派方式原文、处理人员原文、分派策略 | +| 关联告警 | 告警数量、活跃告警数量、告警事件 | +| 相关人员 | 负责人ID、负责人、发起人ID、发起人、关闭人ID、关闭人 | +| 其他 | 屏蔽至、曾被收敛、新奇故障 | + +开启 **提取 HTML 中的文本内容** 后（默认开启），故障描述会以纯文本写入 CSV，便于在表格工具中阅读。 数据导出示意图 @@ -141,7 +151,7 @@ keywords: ["分析看板", "数据分析", "故障统计", "报表导出", "运 -目前分析看板中最多支持查询最近 1 年的数据（具体取决于您的订阅版本的数据保留周期），如果需要查询更久的数据，可以通过 [API 查询](/zh/api-reference/on-call/analytics/insight-incident-list)。 +目前分析看板中最多支持查询最近 **2 年（720 天）** 的数据（具体上限取决于您的订阅版本），如果需要查询更久的数据，可以通过 [API 查询](/zh/api-reference/on-call/analytics/insight-incident-list)。 diff --git a/zh/on-call/channel/create-edit.mdx b/zh/on-call/channel/create-edit.mdx index a143f956..a27a1d03 100644 --- a/zh/on-call/channel/create-edit.mdx +++ b/zh/on-call/channel/create-edit.mdx @@ -107,7 +107,7 @@ keywords: ["协作空间", "创建管理", "业务隔离", "团队协作", "告 空间创建后，进入详情页的 **配置** 页签完成以下配置。配置页签采用侧边栏菜单，按功能分组组织： - **集成数据**：专属集成、排除规则 -- **降噪处理**：告警聚合、抖动检测、静默策略、抑制策略 +- **降噪处理**：事件聚合、告警聚合、抖动检测、静默策略、抑制策略 - **通知分派**：分派策略 - **设置**：基础信息、高级配置 @@ -163,6 +163,7 @@ keywords: ["协作空间", "创建管理", "业务隔离", "团队协作", "告 | 能力 | 导航路径 | 说明 | | :--- | :--- | :--- | +| **事件聚合** | 降噪处理 → 事件聚合 | 控制相同 `alert_key` 的事件在聚合窗口内是否合入同一条告警 | | **告警聚合** | 降噪处理 → 告警聚合 | 将同一主机、同一服务的相似告警合并为一条故障 | | **抖动检测** | 降噪处理 → 抖动检测 | 自动识别并屏蔽短时间内反复震荡的告警 | | **静默策略** | 降噪处理 → 静默策略 | 在预定的维护窗口或特定时间段，临时屏蔽特定条件下的告警通知 | diff --git a/zh/on-call/channel/escalation-rule.mdx b/zh/on-call/channel/escalation-rule.mdx index 264ef640..cc6f52fd 100644 --- a/zh/on-call/channel/escalation-rule.mdx +++ b/zh/on-call/channel/escalation-rule.mdx @@ -68,7 +68,7 @@ src="https://download.flashcat.cloud/flashduty/video/escalate-rule.mp4" - 点对点发送给具体的分派对象，支持电话、短信、邮件、App 推送、IM 私聊（飞书/钉钉/企微）。 + 点对点发送给具体的分派对象，支持电话、短信、邮件、App 推送、IM 私聊（飞书/钉钉/企微/Slack/Microsoft Teams）。 - **遵循个人偏好（推荐）**：通知方式由成员在 [个人中心](/zh/on-call/configuration/personal-settings) 自行配置 - **遵循统一设置**：强制规定通知方式（如必须发送短信），覆盖成员的个人偏好 @@ -76,8 +76,8 @@ src="https://download.flashcat.cloud/flashduty/video/escalate-rule.mp4" 发送到即时通讯软件的群组中，支持 @ 提到相关人员。 - - **IM 应用群**：支持飞书、钉钉、企业微信、Slack、Microsoft Teams 群，需先完成 [IM 集成](/zh/on-call/integration/instant-messaging/lark) - - **群机器人**：支持飞书、钉钉、企业微信、Telegram、Zoom 等 Webhook 机器人。其中 Telegram 需要配置 Webhook 通知地址和群聊 ID（Chat Ids），Zoom 需要配置 Webhook 地址和 Verify Token，并支持开启 @ 提醒功能。详见 [通知渠道配置](/zh/on-call/configuration/notifications) + - **IM 应用群**：支持飞书、钉钉、企业微信、Slack、Microsoft Teams 群（其中企业微信仅存量配置可用，新建策略不可选），需先完成 [IM 集成](/zh/on-call/integration/instant-messaging/lark) + - **群机器人**：支持飞书、钉钉、企业微信、Slack、Telegram、Zoom 等 Webhook 机器人。其中 Telegram 需要配置 Webhook 通知地址和群聊 ID（Chat Ids），Zoom 需要配置 Webhook 地址和 Verify Token，并支持开启 @ 提醒功能。详见 [通知渠道配置](/zh/on-call/configuration/notifications) **不使用上述 IM 平台？** 您可以选择任意一种机器人类型，将 Webhook 地址填写为您自己的服务端 URL（系统不会校验域名），然后在服务端实现对应的消息协议即可。详见[常见问题](/zh/on-call/quickstart/faq#custom-bot-notifications)。 diff --git a/zh/on-call/channel/integrate-data.mdx b/zh/on-call/channel/integrate-data.mdx index 52d1fdac..f69a03b3 100644 --- a/zh/on-call/channel/integrate-data.mdx +++ b/zh/on-call/channel/integrate-data.mdx @@ -114,15 +114,16 @@ Flashduty On-call 提供两种告警接入方式： ## 频率限制 -为保证系统稳定性，每个集成的请求频率限制为： +为保证系统稳定性，网关对告警推送接口实施以下频率限制： -| 限制类型 | 限制值 | +| 限制维度 | 限制值 | | :--- | :--- | -| **QPS** | 100 次/秒 | -| **QPM** | 1000 次/分钟 | +| **单个 API** | 8000 次/秒（QPS） | +| **单个账户** | 2000 次/分钟 | +| **单个集成** | 2000 次/分钟 | -超出限制将返回 `429` 状态码，请等待后重试。如需扩大限制，请联系技术支持。 +超出任一维度的限制将返回 `429` 状态码，请等待后重试。如需扩大限制，请联系技术支持。 ## 常见问题 diff --git a/zh/on-call/channel/noise-reduction.mdx b/zh/on-call/channel/noise-reduction.mdx index 9fda9c55..84a54aa8 100644 --- a/zh/on-call/channel/noise-reduction.mdx +++ b/zh/on-call/channel/noise-reduction.mdx @@ -81,7 +81,7 @@ src="https://download.flashcat.cloud/flashduty/video/alert-aggr.mp4" ## 事件聚合 -进入 协作空间详情 → **降噪配置** → **事件聚合** 进行配置。 +进入 协作空间详情 → **降噪处理** → **事件聚合** 进行配置。 事件聚合控制「事件 → 告警」的合并行为：当上游监控系统持续推送相同 `alert_key` 的事件时，是否将这些事件合入同一条已有告警，还是为每个事件创建独立的告警。 @@ -94,7 +94,7 @@ src="https://download.flashcat.cloud/flashduty/video/alert-aggr.mp4" | 配置项 | 说明 | 默认值 | 取值范围 | | :--- | :--- | :--- | :--- | | **开启事件聚合** | 开启后，相同 `alert_key` 的事件在聚合窗口内将合入同一条告警；关闭后，每一条事件都会生成独立的告警 | 开启 | 开启 / 关闭 | -| **聚合窗口** | 从告警创建时间开始计时，到达该时长后的事件将创建新告警；仅在开启事件聚合时可配置 | 1440 分钟（24 小时） | 1–1440 分钟 | +| **聚合窗口** | 从告警创建时间开始计时，到达该时长后的事件将创建新告警；仅在开启事件聚合时可配置 | 1440 分钟（24 小时） | 1–1440 分钟；默认最大 24 小时，开通扩展后可达 7 天（需联系 Flashduty 团队） | `alert_key` 是用于告警关联和去重的标识字段，由上游集成上报或由集成规则自动生成。 @@ -109,7 +109,7 @@ src="https://download.flashcat.cloud/flashduty/video/alert-aggr.mp4" ## 告警聚合 -进入 协作空间详情 → **降噪配置** 进行配置。 +进入 协作空间详情 → **降噪处理** 进行配置。 告警聚合将多条相似告警合并为一条故障，统一分派和通知。当告警风暴来袭时，您只需处理一条故障，而非数百条重复通知。 @@ -217,7 +217,7 @@ Flashduty On-call 提供两种聚合模式： 当同一故障频繁触发与恢复时，系统将其标记为"抖动"状态，避免通知轰炸。 -进入 协作空间详情 → 降噪配置 → **抖动检测**： +进入 协作空间详情 → 降噪处理 → **抖动检测**： | 选项 | 行为 | | :-------- | :--------------- | @@ -226,7 +226,7 @@ Flashduty On-call 提供两种聚合模式： | **提醒后静默** | 标记抖动状态，首次提醒后不再通知 | - 新建协作空间默认开启抖动检测（仅提醒模式）。 + 新建协作空间默认开启抖动检测（**提醒后静默** 模式），默认参数为：观测窗口 60 分钟、状态变化 4 次、静默时长 120 分钟。 ### 可配置参数 @@ -254,7 +254,7 @@ src="https://download.flashcat.cloud/flashduty/video/silence.mp4" 在维护窗口或已知问题期间，静默规则可以屏蔽特定条件的告警通知。 -进入 协作空间详情 → 降噪配置 → **静默规则**。 +进入 协作空间详情 → 降噪处理 → **静默策略**。 ### 静默时间 @@ -340,12 +340,12 @@ src="https://download.flashcat.cloud/flashduty/video/inhibit.mp4" | 位置 | 路径 | 特点 | | :------- | :----------------------- | :------------ | -| **协作空间** | 协作空间详情 → 降噪配置 → **抑制规则** | 仅对当前协作空间的告警生效 | +| **协作空间** | 协作空间详情 → 降噪处理 → **抑制策略** | 仅对当前协作空间的告警生效 | | **告警集成** | 告警集成详情 → 告警处理 → **告警抑制** | 对通过该集成接入的告警生效 | ### 抑制条件 -当新告警满足条件，且 10 分钟内存在满足条件的 **活跃告警**（未被认领且未恢复的告警），且两者存在相同项时，新告警被抑制。 +当新告警满足条件，且 10 分钟内存在满足条件的 **活跃告警**（处于活跃状态、未恢复的告警即可作为抑制源，无论是否已被认领），且两者存在相同项时，新告警被抑制。 | 配置项 | 说明 | | :--------- | :------------------------------ | @@ -385,7 +385,7 @@ src="https://download.flashcat.cloud/flashduty/video/inhibit.mp4" 上限为 5000 条，主要为了保证控制台渲染性能。由于后台并发处理，实际可能略超此限制。 - 事件能否合入已有告警，由协作空间的 **事件聚合** 设置决定（控制「事件 → 告警」层级，默认开启、窗口 24 小时，可关闭或自定义为 1–1440 分钟）： + 事件能否合入已有告警，由协作空间的 **事件聚合** 设置决定（控制「事件 → 告警」层级，默认开启、窗口 24 小时，可关闭或自定义为 1–1440 分钟，开通扩展后可达 7 天）： - **事件聚合开启**：相同 `alert_key` 的事件在窗口内合入同一条告警；超出窗口后到达的事件将创建新告警 - **事件聚合关闭**：每一条事件都会创建独立的告警，不再合并 diff --git a/zh/on-call/configuration/custom-forms.mdx b/zh/on-call/configuration/custom-forms.mdx index 3372be9b..5f354a70 100644 --- a/zh/on-call/configuration/custom-forms.mdx +++ b/zh/on-call/configuration/custom-forms.mdx @@ -12,7 +12,7 @@ keywords: ["自定义表单", "故障创建", "故障认领", "故障关闭", " - 在控制台进入 **故障管理 → 自定义表单**，选择要配置的操作：**创建故障**、**认领故障** 或 **关闭故障**。 + 在控制台进入 **配置中心 → 自定义表单**，选择要配置的操作：**创建故障**、**认领故障** 或 **关闭故障**。 点击 **添加字段**，按需加入以下元素： @@ -41,6 +41,8 @@ keywords: ["自定义表单", "故障创建", "故障认领", "故障关闭", " 表单的显示和必填条件会在用户操作时重新计算。例如，你可以只在特定严重程度、特定标签或特定团队成员处理故障时要求填写某个字段。 +这些表单在 Flashduty App 中同样生效：创建、认领、关闭故障时 App 会弹出同一份表单，两端共用同一配置，显示条件、必填规则和图片上传等行为一致。 + 如果某个操作没有配置表单元素，或当前故障和用户不满足表单元素的显示条件，系统会直接执行原有的创建、认领或关闭流程，不会额外要求填写内容。 diff --git a/zh/on-call/configuration/notifications.mdx b/zh/on-call/configuration/notifications.mdx index bf852f52..c44bb8b4 100644 --- a/zh/on-call/configuration/notifications.mdx +++ b/zh/on-call/configuration/notifications.mdx @@ -44,7 +44,7 @@ Flashduty App 是 On-call 工程师最高效的移动办公工具。无论您身 - 前往 App Store 或安卓各大应用市场搜索"Flashduty"下载，或前往控制台个人中心扫描二维码下载 + 下载方式见 [个人设置 - Flashduty APP](/zh/on-call/configuration/personal-settings#flashduty-app) 打开 App 并使用您的 Flashduty 账户登录，或扫描控制台登录。登录后，当前设备将自动与您的账户绑定 @@ -61,6 +61,11 @@ Flashduty App 是 On-call 工程师最高效的移动办公工具。无论您身 1. 检查手机系统的通知权限是否已为 Flashduty App 开启 2. 确认在您的分派策略中，已将 App 推送设置为通知渠道之一 3. 如果设置了"遵循个人偏好"，需检查个人通知设置中是否勾选了 Flashduty App + 4. **Android 用户**：检查系统通知设置中的两个通知渠道是否都已开启——「故障通知」承载常规（Warning/Info）故障通知，「紧急通知」承载 Critical 级别故障通知（锁屏可见、可绕过免打扰），两个渠道在系统设置中分别管理，关闭其中一个会导致对应级别的通知不提醒 + + **点击推送通知会打开什么？** + + 点击通知会直接打开 App 内对应的故障详情页，可立即进行认领、关闭等处理操作。 @@ -381,6 +386,14 @@ Flashduty On-call 允许您为不同渠道定制个性化的通知消息。 例如，您可以配置：P1 级别的故障，首先通过 Flashduty App 和飞书应用通知主值班人员；如果 5 分钟内无人认领，则通过语音电话通知其主管。 + + + 在故障详情的评论区或故障复盘中输入 `@` 提及成员时，系统会向被提及人发送一条通知，内容包含评论摘要、故障信息与详情链接，点击可直达故障详情。 + + - **通知渠道**：按被提及人的个人偏好投递，支持 **短信、邮件与各类 IM 应用**（钉钉、飞书、企业微信、Slack、Microsoft Teams 的单聊），默认通过 **邮件** 通知；该场景不提供语音与 Flashduty App 推送 + - **偏好设置**：被提及人可在 **个人中心 → 通知偏好 → 协作与跟进 → 协作提及** 中修改接收方式 + - **防打扰**：同一评论不会重复通知 + ## 延伸阅读 diff --git a/zh/on-call/configuration/schedule.mdx b/zh/on-call/configuration/schedule.mdx index 3fda53f6..6c90f31c 100644 --- a/zh/on-call/configuration/schedule.mdx +++ b/zh/on-call/configuration/schedule.mdx @@ -44,6 +44,8 @@ Flashduty On-call 提供极具灵活性的值班编排能力，支持按天、 - **值班名称**：长度为 1~40 个字符，同一账户下不可重复 - **管理团队**：指定该值班表归属哪个团队管理，团队成员将获得该值班表的编辑权限 - **值班描述**：支持 Markdown 语法，该区域的内容可以在通知时携带，长度不超过 500 字符 + + 免费版最多可创建 1 个值班表，升级至标准版及以上后可创建多个。 为了避免忘记值班或交接，系统提供两种通知时机： @@ -86,19 +88,29 @@ Flashduty On-call 提供极具灵活性的值班编排能力，支持按天、 +## 删除值班表 + +--- + +您可以在值班管理列表或值班表详情页删除值班表，删除前系统会要求二次确认。 + + +如果值班表正被分派策略引用，删除按钮将置灰不可用，悬停可查看引用该值班表的分派策略清单（协作空间 → 规则名称）。请先前往对应协作空间解除引用，再执行删除，防止删除后无法收到新的故障通知。 + + ## 值班角色 --- -Flashduty 的值班角色不仅仅限于"主值班 / 备值班"，而是一种账户级资源：您可以在账户角色管理页面维护任意数量的命名角色（如"研发主值班"、"DBA 备值班"、"SRE 响应官"），并在配置值班表时将成员映射到对应角色。 +值班角色用于区分同一值班表中不同职责的值班人员（如"主值班"、"备值班"），是一种账户级资源： -- **账户级资源**：角色在账户层面统一管理，所有值班表共享同一角色库 -- **规则内按角色分组**：在值班规则中添加人员时，可将成员绑定到指定角色 ID，形成"角色 → 成员"的映射 +- **账户级共享**：角色在账户层面全局生效，所有值班表共享同一套角色 +- **规则内按角色分组**：在值班规则中添加人员时，可将成员绑定到指定角色，形成"角色 → 成员"的映射 - **分派策略按角色定向**：分派策略的通知对象支持 **所有值班人员**、**指定角色**（如仅通知主值班）或 **指定成员**，实现更细粒度的告警路由 - -如果您的团队只需要"主 / 备"两种角色，直接使用系统内置的主备角色即可，无需创建新的角色。 - + +默认情况下，每个账户仅有一个值班角色，添加值班人员时无需选择角色。如果您需要多个值班角色（如主备值班），请联系 Flashduty 技术支持开通；开通后，配置值班规则和临时调班时均可为成员选择角色。控制台暂不支持自助增删角色。 + ## 临时调班与请假 @@ -124,7 +136,7 @@ Flashduty 的值班角色不仅仅限于"主值班 / 备值班"，而是一种 - **开始时间** / **结束时间**：定义替班窗口，默认 `[今日 00:00, 次日 00:00]` - **替班人员**：在该窗口内替代原值班人员的成员 -临时调班不支持轮换周期、日期掩码、主备角色、分组等普通规则字段。 +临时调班不支持轮换周期、日期掩码、分组等普通规则字段。对于开通了多个值班角色的账户，临时调班同样可以为替班人员选择角色。 - **抢占语义**：临时调班在其时间窗口内**完全替换**所有普通值班规则（不论对方属于哪一层），而不是与之叠加。窗口结束后，原规则自动恢复生效 @@ -225,25 +237,13 @@ Flashduty 的值班角色不仅仅限于"主值班 / 备值班"，而是一种 在日历中点击任意时间段，可以查看当前值班人员，或创建临时调班。 -## 查看个人值班计划 +## 查看我的值班 --- -进入 **值班管理** → **个人值班计划**，你可以在统一视图中查看自己参与的所有值班表安排。 - -页面顶部展示你当前正在值班的值班表名称，点击可跳转到对应值班表详情。 - -你可以通过右上角的时间范围按钮切换查看区间： - -| 选项 | 说明 | -| :--- | :--- | -| **1 天** | 查看当天的值班安排 | -| **4 天** | 查看未来 4 天的值班安排 | -| **1 周** | 查看未来 1 周的值班安排 | -| **2 周** | 查看未来 2 周的值班安排（默认） | -| **1 月** | 查看未来 1 个月的值班安排 | +**值班管理** 列表页顶部内嵌「我的值班」区块，以周视图汇总展示你参与的值班安排：左侧列出本周有值班安排的值班表名称，右侧日历展示你在各值班表中的值班时段。 -使用左右箭头按钮可以翻页查看前后时间段的值班安排，点击 **今天** 按钮可快速回到当前时间。 +点击标题右侧的左右箭头可按周翻看此前或之后的值班安排，点击中间的圆点按钮可快速回到本周。 ## 延伸阅读 diff --git a/zh/on-call/configuration/service-calendar.mdx b/zh/on-call/configuration/service-calendar.mdx index 38909001..537fa195 100644 --- a/zh/on-call/configuration/service-calendar.mdx +++ b/zh/on-call/configuration/service-calendar.mdx @@ -29,17 +29,20 @@ keywords: ["服务日历", "工作日", "休息日", "节假日", "差异化处 --- -进入 故障管理 → 服务日历 → **新增日历**。 +进入 **配置中心 → 服务日历**，点击 **新增日历**。 | 配置项 | 说明 | | --- | --- | -| **日历名称** | 建议按业务维度命名，如「结算业务系统」 | +| **日历名称** | 必填，长度为 1~40 个字符，建议按业务维度命名，如「结算业务系统」 | +| **管理团队** | 必填。日历归属于该团队，团队成员将获得编辑该日历的权限 | | **日历描述** | 概述业务特性，便于团队成员快速了解 | -| **管理团队** | 配置后，团队成员拥有该日历的完整权限 | -| **关联节假日** | 建议关联国家节假日，自动获取假日安排，也可手动调整 | + + +每个账户默认最多可创建 5 个服务日历。如需创建更多，请联系 Flashduty 技术支持。 + -新建日历默认全部为工作日，关联节假日后会自动标记法定假日为休息日。 +新建日历默认全部为工作日。创建成功后进入日历详情页关联国家节假日，系统会自动将法定假日标记为休息日，您也可以手动调整。 ![服务日历](https://fcpub-1301667576.cos.ap-nanjing.myqcloud.com/flashduty/doc/rili.png) @@ -51,6 +54,7 @@ keywords: ["服务日历", "工作日", "休息日", "节假日", "差异化处 | 操作 | 说明 | | --- | --- | | **修改基础信息** | 日历名称、描述、管理团队 | +| **关联节假日** | 在日历详情页关联国家节假日日历，系统自动将法定假日标记为休息日，可随时调整或取消关联 | | **批量标记休息日** | 按星期几快速标记，如每周六、日为休息日 | | **单日调整** | 点击日期切换工作日/休息日状态 | diff --git a/zh/on-call/incident/alert-management.mdx b/zh/on-call/incident/alert-management.mdx index 5cc26323..a289ad70 100644 --- a/zh/on-call/incident/alert-management.mdx +++ b/zh/on-call/incident/alert-management.mdx @@ -34,7 +34,7 @@ keywords: ["告警管理", "告警列表", "告警详情", "聚合视图", "告 | 字段 | 取值 | 说明 | | :--- | :--- | :--- | -| **alert_severity**（严重程度） | Critical / Warning / Info | 告警创建时确定，**后续不再变化**；列表顶部的严重程度筛选也作用于此字段 | +| **alert_severity**（严重程度） | Critical / Warning / Info | 告警创建时确定；此后若有新事件合入该告警，严重程度会取历史级别与新事件级别中的最差值，即**只升不降**；列表顶部的严重程度筛选也作用于此字段 | | **alert_status**（告警状态） | Critical / Warning / Info / Ok | 反映告警当前的恢复状态，其中 **Ok 即表示已恢复**，其余取值均视为未恢复 | | **故障处理进度** | Triggered / Processing / Closed | 该列展示的并非告警自身的状态，而是告警所关联故障的处理进度 | diff --git a/zh/on-call/incident/escalate-dispatch-incident.mdx b/zh/on-call/incident/escalate-dispatch-incident.mdx index a79a4694..1ab7b44b 100644 --- a/zh/on-call/incident/escalate-dispatch-incident.mdx +++ b/zh/on-call/incident/escalate-dispatch-incident.mdx @@ -34,6 +34,10 @@ keywords: ["故障升级", "重新分派", "处理人", "故障分派", "升级 添加处理人界面 + +以上操作在 [Flashduty App](/zh/on-call/quickstart/mobile-app) 中同样可用：**重新分派** 和 **升级** 位于故障详情页的 **更多操作（⋮）** 中；**添加处理人** 位于故障详情页的 **处理人员** 区域。 + + ## 常见问题 diff --git a/zh/on-call/incident/external-submission.mdx b/zh/on-call/incident/external-submission.mdx new file mode 100644 index 00000000..1319c18d --- /dev/null +++ b/zh/on-call/incident/external-submission.mdx @@ -0,0 +1,75 @@ +--- +title: "外部故障提交" +description: "开启外部提报后，客户或合作伙伴无需登录 Flashduty，即可通过专属链接或 API 向协作空间提交故障，并自动进入分派与通知流程" +keywords: ["外部故障提交", "外部提报", "免登录提交", "故障工单", "客户报障"] +--- + +**版本要求**：此功能需要 On-call 专业版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/) + +外部故障提交允许外部人员（如您的客户或合作伙伴）在**无需登录** Flashduty 的情况下，通过一个独立页面或 API 提交故障。提交成功后，故障直接创建到对应的协作空间中，自动匹配分派策略并通知处理人员，适合把对客服务的报障入口接入统一的故障处置流程。 + +## 开启外部提报 + +进入 **协作空间详情 → 配置 → 设置 → 高级配置**，打开 **外部提报** 开关（创建协作空间的向导中也可以开启）。开启后系统会为该协作空间生成一条专属的外部提报链接，复制并分享给外部人员即可。 + + +- 外部提报链接是免登录提交入口，任何持有链接的人都可以提交故障，请仅分享给需要的对象 +- **关闭外部提报后，已分享的链接立即失效；再次开启会生成新的链接**，旧链接不可恢复 + + +## 提交页面 + +外部人员打开提报链接后，在独立页面填写并提交故障，全程无需登录： + +| 字段 | 必填 | 说明 | +| :--- | :--- | :--- | +| 故障标题 | 是 | 最长 500 字符 | +| 详细描述 | 是 | 支持 Markdown 格式，最长 10000 字符 | +| 附件或截图 | 否 | 最多上传 10 个文件，支持 JPEG、PNG、WebP、GIF、TIFF、BMP、ICO 格式，单个文件不超过 5 MB | +| 邮箱 | 是 | 提报人的联系方式，便于处理人员跟进时获取更多信息 | +| 公司 | 否 | 提报人所在公司名称 | + +提交前需完成人机验证（验证码）。提交成功后页面会展示成功提示；如果链接已被关闭或重新生成，页面会提示**链接无效**，提报人需要联系您的团队获取新链接。 + +## 提交后的处理 + +外部提交的故障会创建到链接所属的协作空间中，并带有以下特征： + +- **严重程度**：固定为 **Warning** +- **处理进度**：待处理，与告警自动触发的故障一致 +- **提报人信息**：邮箱和公司分别记录为故障的 `reporter_email`、`reporter_company` 标签，可在故障详情的标签区域查看 +- **自动分派**：故障创建后自动匹配协作空间下的分派策略并发出通知 + + +如果协作空间没有配置分派策略，外部提交的故障不会分派给任何人，也不会产生通知。开启外部提报前，请确保协作空间已配置有效的[分派策略](/zh/on-call/channel/escalation-rule)。 + + +## 通过 API 提交 + +除独立页面外，您还可以将提交能力集成到自己的系统中。外部提报链接形如 `https://<控制台域名>/incident/external-create/`，取其中的 `token`，以 `multipart/form-data` 方式调用： + +```bash +curl -X POST "https://<控制台域名>/api/incident/external-create?token=" \ + -F 'data={"title":"支付接口报错","description":"从 14:00 开始所有支付请求返回 500","reporter_email":"ops@example.com","reporter_company":"示例公司","captcha_verify_param":"<验证码校验参数>"}' \ + -F "images=@/path/to/screenshot.png" +``` + +| 部分 | 说明 | +| :--- | :--- | +| `data` | 必填，JSON 字符串。字段：`title`（必填，最长 500 字符）、`description`（必填，最长 10000 字符）、`reporter_email`（必填，最长 100 字符）、`reporter_company`（可选，最长 100 字符）、`captcha_verify_param`（SaaS 环境必填的人机验证码参数；私有化部署无需提供） | +| `images` | 可选，图片文件，可携带多个；单个文件不超过 5 MB，请求整体不超过 50 MB，超出的图片将被忽略，仅保留前 10 个 | + +调用成功返回创建的故障 ID： + +```json +{ + "data": { + "incident_id": "664f1b2c8f2a1c0012ab34cd" + } +} +``` + +## 延伸阅读 + +- [创建与配置协作空间](/zh/on-call/channel/create-edit)：外部提报开关所在的协作空间配置 +- [配置分派策略](/zh/on-call/channel/escalation-rule)：决定外部提交的故障通知给谁 diff --git a/zh/on-call/incident/handle-update-incident.mdx b/zh/on-call/incident/handle-update-incident.mdx index e1fb1afd..83f2d58e 100644 --- a/zh/on-call/incident/handle-update-incident.mdx +++ b/zh/on-call/incident/handle-update-incident.mdx @@ -77,6 +77,10 @@ keywords: ["故障处理", "故障更新", "认领故障", "关闭故障", "状 Flashduty On-call 推送的语音告警，在语音播报结束时，会提醒您 **一键认领请按 1**。点击按键 1，系统会以您的身份完成故障认领。 + + +在 [Flashduty App](/zh/on-call/quickstart/mobile-app) 中打开故障详情，点击底部 **认领** 按钮；也可以在故障列表的卡片上左滑，快捷完成认领。 + @@ -124,6 +128,10 @@ Flashduty On-call 推送的语音告警，在语音播报结束时，会提醒 故障消息卡片点击 **暂缓** 按钮，选择暂缓时长，完成。 + + +在 [Flashduty App](/zh/on-call/quickstart/mobile-app) 中打开故障详情，点击底部 **更多操作（⋮）** → **暂缓**，选择暂缓时长，完成。仅处理中的故障可暂缓。 + ## 关闭故障 @@ -139,6 +147,10 @@ Flashduty On-call 推送的语音告警，在语音播报结束时，会提醒 应用类消息主卡片，提供一个 **关闭** 按钮，点击卡片即可完成认领。如果您点击卡片没有任何反应，可能是您没有在应用内完成登录账户关联或其他原因。详情请参考[飞书集成指引](/zh/on-call/integration/instant-messaging/lark)。 + + +在 [Flashduty App](/zh/on-call/quickstart/mobile-app) 中打开故障详情，点击底部 **关闭** 按钮；也可以在故障列表的卡片上左滑，快捷关闭。已关闭的故障可在详情页点击 **重新打开** 并填写原因后恢复处理。 + diff --git a/zh/on-call/incident/search-view-incident.mdx b/zh/on-call/incident/search-view-incident.mdx index 63f64f81..4b3ab59f 100644 --- a/zh/on-call/incident/search-view-incident.mdx +++ b/zh/on-call/incident/search-view-incident.mdx @@ -18,8 +18,8 @@ Flashduty On-call 提供了两个入口查看故障列表。一个是协作空 | 2 | 我的协作空间 | 默认聚焦为全部协作空间，可切换为查看**我的协作空间**的故障 | | 3 | 处理进度 | 按照处理进度筛选故障，默认为 **全部** | | 4 | 时间筛选 | 支持相对时间和自定义区间筛选 | -| 5 | 键入检索 | 支持搜索故障 ID，如果分派人员切换为"分派给我"，则同时支持模糊匹配"故障标题" | -| 6 | 更多筛选 | 支持丰富的维度筛选，包括严重程度、协作空间、团队、标签或自定义字段等。其中**团队**筛选仅在全局故障管理入口下可见，按协作空间归属的团队过滤故障 | +| 5 | 键入检索 | 支持搜索故障标题、ID、标签和自定义字段。故障标题、标签、自定义字段更新后，查询结果可能存在短暂延迟 | +| 6 | 更多筛选 | 支持丰富的维度筛选，包括严重程度、处理人员、与我相关、发起人员、认领人员、关闭人员、暂缓状态、抖动收敛过、新奇故障、标签和自定义字段等。其中**协作空间**和**团队**筛选仅在全局故障管理入口下可见，团队按协作空间归属的团队过滤故障；**与我相关**匹配我作为发起人员、认领人员、关闭人员或处理人员的故障 | | 7 | 视图设置 | 支持丰富的渲染形式，包括引入 **自定义的展示属性**，甚至是聚合视图 | | 8 | 分页设置 | 分页和单页条数调整 | @@ -67,6 +67,18 @@ Flashduty On-call 提供各种维度的筛选能力，并给您足够多的灵 灵活常常意味着低性能，在 Flashduty On-call 也不例外，尽管我们已经做了很多性能优化的工作。我们永远建议，缩小您的时间查询区间，尽量通过 **分派给我**、**处理进度** 等条件缩小查询范围。 +### 保存筛选视图 + +您可以将筛选条上当前的筛选条件保存为命名的**筛选视图**，后续一键套用，适合高频使用的检索组合： + +- **保存视图**：配置好筛选条件后，将其保存为命名视图；视图名称不可重复，每人最多保存 **10** 个 +- **套用视图**：选择已保存的视图，即可将其筛选条件应用到当前列表 +- **管理视图**：已保存的视图支持**重命名**、**更新**（以当前筛选条件覆盖视图）和**删除** + + +筛选视图按用户保存，仅自己可见。视图保存除**时间范围**外的全部筛选条件，套用视图时时间范围保持当前选择不变。 + + ### 列表内容说明 每条故障除了标题和处理进度，还会展示两个关键计数： @@ -76,6 +88,21 @@ Flashduty On-call 提供各种维度的筛选能力，并给您足够多的灵 悬浮计数区域可展开详细提示，显示关联告警数、关联事件数和最后一次事件合入的相对时间。 +### 批量操作 + +在故障列表中勾选一个或多个故障后，可通过列表上方的操作栏执行批量操作： + +| 操作 | 说明 | +| :--- | :--- | +| **认领** | 批量认领选中的故障 | +| **暂缓** | 批量暂缓选中的故障，可选快捷时长预设（默认为 2 小时、4 小时、12 小时，可在下拉菜单中进入设置并配置 3 个预设时长）或自定义时长（支持小时或分钟，最长 30 天）；仅处理中的故障可暂缓，选中项包含其他状态的故障时按钮不可用 | +| **分派** | 将选中的故障批量分派给指定成员；已关闭的故障不支持分派，选中项包含已关闭故障时按钮不可用 | +| **关闭** | 批量关闭选中的故障 | +| **合并** | 将选中的多个故障合并为一个故障 | +| **AI 分析** | 将选中的故障作为上下文批量推送给 AI SRE Agent 进行分析。需要 AI SRE 模块开启且有相应权限；若选中的故障分属同一团队，会自动以该团队为会话范围 | + +除 **AI 分析** 外，以上批量操作均需具备故障更新权限。 + ### 自定义渲染 点击故障列表右上角的 **设置** 按钮，可以定制化展示内容和交互行为： @@ -257,7 +284,7 @@ Flashduty On-call 提供各种维度的筛选能力，并给您足够多的灵 - **影响**：受影响的关键资源，如服务、系统、环境、实例等 - **建议**：即时可执行的排查和修复操作（最多 3 条） -您可以选择不同的 AI 模型（默认为 DeepSeek V3，也可选择 DeepSeek R1 以获得深度思考和推理能力），并支持重新生成。生成的摘要可以实时流式输出，也可以保存为故障描述。 +AI 总结固定使用 DeepSeek V4 Pro（`deepseek-v4-pro`）模型生成，控制台不提供模型选择入口。生成的摘要支持实时流式输出，可以重新生成，也可以保存为故障描述。 AI 总结仅适用于由告警自动触发的故障，手动创建的故障不支持此功能。 diff --git a/zh/on-call/incident/what-is-incident.mdx b/zh/on-call/incident/what-is-incident.mdx index fe1706f7..4dae813b 100644 --- a/zh/on-call/incident/what-is-incident.mdx +++ b/zh/on-call/incident/what-is-incident.mdx @@ -22,7 +22,7 @@ keywords: ["故障", "告警", "事件", "故障状态", "故障管理"] 故障、告警和事件，均使用以上三种严重程度。**严重程度首字母大写**，您在使用 API 时需要特别注意。三者的严重程度生成规则如下： - **事件的严重程度**：不同集成来源（如 Zabbix 和夜莺）的告警事件有不同的严重程度枚举值，Flashduty On-call 会按照一定规则映射为以上三种标准严重程度。具体映射关系，请您参阅具体集成的接入文档，如需自定义严重程度，请参阅[告警处理](/zh/on-call/integration/alert-integration/alert-pipelines)。 -- **告警的严重程度**：等于所关联的事件中最高级别的严重程度。 +- **告警的严重程度**：等于所关联的事件中最高级别的严重程度。随着新事件持续合入，告警严重程度只会随之升级到最差级别，不会因合入低级别事件而降低。 - **故障的严重程度**：等于所关联的告警中最高级别的严重程度。 ### 处理进度 @@ -84,7 +84,7 @@ Flashduty On-call 提供了标签增强方案，用于自动化生成标签， - **自动触发**：Flashduty On-call 接收到集成上报的告警事件（如 Zabbix 通知），事件自动触发一条告警，告警自动触发一条故障 - **手动触发**：在 Flashduty On-call 控制台点击 **创建故障** 按钮，填写标题、描述、严重程度等信息，触发一条新故障 -- **外部提报**：开启外部提报功能后，外部人员可通过专属链接提交故障工单，无需登录 Flashduty 账号。详见[协作空间配置](/zh/on-call/channel/create-edit) +- **外部提报**：开启外部提报功能后，外部人员可通过专属链接提交故障工单，无需登录 Flashduty 账号。详见[外部故障提交](/zh/on-call/incident/external-submission) @@ -141,7 +141,7 @@ Flashduty On-call 支持专属集成和共享集成模式： Flashduty On-call 提供了一个自定义事件标准，允许您通过标准协议上报告警，适用于任何未适配的监控系统。详细文档请阅读[自定义告警事件](/zh/on-call/integration/alert-integration/alert-sources/standard-alert)。 -为了保证整个系统的稳定，Flashduty On-call 对每个集成的 API 上报实施频率限制（**100 次/秒**、**1000 次/分钟**），超出限制将返回 `429` 状态码，请等待后重试。详见[接入告警 - 频率限制](/zh/on-call/channel/integrate-data#频率限制)。 +为了保证整个系统的稳定，Flashduty On-call 对告警推送接口实施频率限制（单个 API **8000 次/秒**、单个账户 **2000 次/分钟**、单个集成 **2000 次/分钟**），超出限制将返回 `429` 状态码，请等待后重试。详见[接入告警 - 频率限制](/zh/on-call/channel/integrate-data#频率限制)。 diff --git a/zh/on-call/incident/work-items.mdx b/zh/on-call/incident/work-items.mdx index 60d5a230..9f5038a1 100644 --- a/zh/on-call/incident/work-items.mdx +++ b/zh/on-call/incident/work-items.mdx @@ -22,7 +22,7 @@ keywords: ["行动项", "跟进项", "工作项", "故障处理", "故障复盘" | **描述** | 否 | 补充需要执行的具体内容，最长 **65535** 字符 | | **负责人** | 否 | 支持搜索并从账户成员中多选，不限制人数 | -创建成功后，行动项会展示在面板中，并在故障时间线上记录一条"创建了行动项"事件。被指定为负责人的成员会收到一条个人通知，提醒其跟进处理（默认通过邮件发送，可在[个人设置](/zh/on-call/configuration/personal-settings)中调整通知渠道）。 +创建成功后，行动项会展示在面板中，并在故障时间线上记录一条"创建了行动项"事件。被指定为负责人的成员会收到一条个人通知，提醒其跟进处理（默认通过**邮件和应用内推送**发送，可在[个人设置](/zh/on-call/configuration/personal-settings)中调整通知渠道）。 ### 编辑与删除 diff --git a/zh/on-call/integration/alert-integration/alert-sources/emqx.mdx b/zh/on-call/integration/alert-integration/alert-sources/emqx.mdx new file mode 100644 index 00000000..993fa558 --- /dev/null +++ b/zh/on-call/integration/alert-integration/alert-sources/emqx.mdx @@ -0,0 +1,171 @@ +--- +title: "EMQX 告警集成" +description: "通过 Webhook 将 EMQX 的告警事件推送到 Flashduty，实现告警事件自动化降噪处理" +keywords: ["告警集成", "EMQX", "MQTT", "监控告警", "数据接入"] +--- + +
+ +## 在 Flashduty On-call +--- + +您可通过以下2种方式，获取一个集成推送地址，任选其一即可。 + +### 使用专属集成 + +当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。 + + + + + 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 + 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 + 3. 选择 **EMQX** 集成，点击 **保存**，生成卡片。 + 4. 点击生成的卡片，可以查看到 **推送地址**，复制备用，完成。 + + + + +### 使用共享集成 + +当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。 + + + + + 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 + 2. 选择 **EMQX** 集成： + - **集成名称**：为当前集成定义一个名称。 + 3. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 + 4. 点击 **保存** 后，复制当前页面的新生成的 **推送地址** 备用。 + 5. 完成。 + + + +
+ +## 在 EMQX +--- + +EMQX Cloud（托管服务）与自建 EMQX 的接入方式不同，请根据您的部署形态选择。 + +### EMQX Cloud（托管服务） + +EMQX Cloud 内置了 Flashduty 告警集成类型，配置步骤如下： + +
+ +1. 登录 EMQX Cloud 控制台，进入您的部署，选择 **告警 → 告警集成**（Alerts → Alert Integrations） +2. 在 Webhook 集成区域点击 **新建**，类型选择 **FlashDuty** +3. 将 Flashduty 集成的推送地址粘贴到 URL 输入框 +4. 点击 **确认** 保存，然后可以点击 **测试** 发送一条测试告警，验证 Flashduty 是否正常接收 + +
+ +配置完成后，EMQX Cloud 会在告警产生时以 POST 请求推送告警到推送地址，推送内容携带 `deployment_id`、`level`、`message`、`region` 四个标签。 + +### 自建 EMQX + +自建 EMQX 需要通过规则引擎将系统告警事件转发到推送地址。 + + +规则引擎自 EMQX 5.8.5 起支持 `$events/sys/alarm_activated`（告警激活）和 `$events/sys/alarm_deactivated`（告警解除）两个系统告警事件，请确保您的 EMQX 版本不低于 5.8.5。 + + + +EMQX Dashboard「监控 → 告警」页面提供的 Webhook 快捷配置推送的是 EMQX 原生告警格式，与 Flashduty 要求的事件格式不一致，请按以下步骤通过规则引擎自定义请求体。 + + +
+ +**步骤 1：创建告警触发规则** + +1. 登录 EMQX Dashboard，进入 **集成 → 规则**，点击 **新建规则** +2. 在 SQL 编辑器中输入以下语句，匹配系统告警激活事件： + + ```sql + SELECT + name, + message, + node + FROM + "$events/sys/alarm_activated" + ``` + +3. 在动作区域添加 **HTTP 服务器** 动作： + - 连接器 URL 填写 Flashduty 集成的推送地址（需携带 integration_key 参数） + - 请求方法选择 `POST` + - 请求体填写以下模板，将告警字段转换为 Flashduty 标准告警事件格式： + + ```json + { + "event_status": "Critical", + "alert_key": "emqx::${node}::${name}", + "title_rule": "EMQX 告警：${message}", + "description": "${message}", + "labels": { + "alarm_name": "${name}", + "node": "${node}" + } + } + ``` + + 模板中的 `${name}`、`${message}`、`${node}` 会被规则 SQL 输出的字段值替换。 + +4. 保存规则 + +**步骤 2：创建告警恢复规则** + +按照步骤 1 再创建一条规则，SQL 语句改为匹配告警解除事件： + +```sql +SELECT + name, + message, + node +FROM + "$events/sys/alarm_deactivated" +``` + +请求体模板与步骤 1 相同，但 `event_status` 固定填写为 `Ok`，以便告警解除时自动恢复 Flashduty 中对应的告警。 + +
+ +## 严重程度映射关系 +--- + +
+ +**EMQX Cloud（托管服务）**：EMQX Cloud 自动按以下关系映射告警等级： + +| EMQX Cloud 告警等级 | Flashduty | 状态 | +| --- | --- | --- | +| Critical | Critical | 严重 | +| Error / Warning | Warning | 警告 | +| Info | Info | 提醒 | + +**自建 EMQX**：告警等级由规则请求体模板中的 `event_status` 字段决定。上述示例中告警激活推送 `Critical`、告警解除推送 `Ok`，您可以在模板中将激活等级改为 `Warning` 或 `Info`。`event_status` 的合法取值为 `Critical`、`Warning`、`Info`、`Ok`。 + +
+ +## 常见问题 +--- + + + + +**在 Flashduty On-call** + +1. 查看集成是否展示了 **最新事件时间**？如果没有，代表 Flashduty 没有收到推送，请优先排查 EMQX 侧配置。 +2. 如果您使用的是 **共享集成**，优先确认您是否配置了 **路由规则**。不设置路由规则，系统会直接拒绝新的推送，因为没有协作空间可以承接您的告警。这种情况下，直接配置路由规则到您期望的空间即可。 + +**在 EMQX** + +1. 自建 EMQX：确认规则的请求体模板与上文示例一致，`event_status` 必须是 `Critical`、`Warning`、`Info`、`Ok` 之一，否则 Flashduty 会拒绝该请求。 +2. 在 EMQX Dashboard 的规则详情页查看规则的运行统计，确认动作执行成功、无失败计数。 +3. 确认 EMQX 节点可以访问外网 `api.flashcat.cloud` 域名。 + +如果以上步骤执行之后，仍然没有查询到问题根因，请 **携带请求响应中的 request_id** 联系我们。 + + + diff --git a/zh/on-call/integration/alert-integration/alert-sources/influxdata.mdx b/zh/on-call/integration/alert-integration/alert-sources/influxdata.mdx index d3e42a3d..c01af699 100644 --- a/zh/on-call/integration/alert-integration/alert-sources/influxdata.mdx +++ b/zh/on-call/integration/alert-integration/alert-sources/influxdata.mdx @@ -95,9 +95,9 @@ keywords: ["告警集成", "Influxdata 集成", "监控告警", "数据接入"]
-Influxdata 告警事件到快猫星云告警等级映射关系： +Influxdata 告警事件到 Flashduty 告警等级映射关系： -| Influxdata | 快猫星云 | 状态 | +| Influxdata | Flashduty | 状态 | | ---------- | -------- | ---- | | CRITICAL | Critical | 严重 | | WARNING | Warning | 警告 | diff --git a/zh/on-call/integration/alert-integration/alert-sources/lark-alert.mdx b/zh/on-call/integration/alert-integration/alert-sources/lark-alert.mdx index a99dd204..b2975c0f 100644 --- a/zh/on-call/integration/alert-integration/alert-sources/lark-alert.mdx +++ b/zh/on-call/integration/alert-integration/alert-sources/lark-alert.mdx @@ -38,7 +38,7 @@ keywords: ["告警集成", "飞书", "监控告警", "数据接入"] 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 2. 选择 **飞书告警** 集成： - **集成名称**：为当前集成定义一个名称。 - - **消息类型**：选择飞书告警消息类型，目前仅支持 Text、Markdown。 + - **消息类型**：选择飞书告警消息类型，目前仅支持文本（Text）、富文本（Post）。 - **推送模式**：选择飞书告警在何种情况下触发或恢复告警。 3. 复制当前页面的 **飞书告警集成地址** 备用。 4. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 @@ -72,7 +72,7 @@ keywords: ["告警集成", "飞书", "监控告警", "数据接入"] ### 注意事项 -- 飞书告警集成地址仅支持接收文本、富文本中 text 和 markdown 的消息类型，其他消息无法接收。 +- 飞书告警集成地址仅支持接收文本（text）和富文本（post）两种消息类型，其他类型的消息无法接收。 - 当飞书消息类型是Text 时，Flashduty On-call 会生成默认告警标题 “飞书告警”。 ## 严重程度映射关系 diff --git a/zh/on-call/integration/alert-integration/alert-sources/overview.mdx b/zh/on-call/integration/alert-integration/alert-sources/overview.mdx deleted file mode 100644 index 8a09f5db..00000000 --- a/zh/on-call/integration/alert-integration/alert-sources/overview.mdx +++ /dev/null @@ -1,230 +0,0 @@ ---- -title: "标准告警事件集成指引" -description: "通过标准协议推送自有系统告警事件到 Flashduty On-call，实现告警事件自动化降噪处理。" -keywords: ["告警集成", "标准告警事件集成指引", "监控告警", "数据接入"] ---- - -:::tips -Flashduty On-call 已经适配了大部分常用告警系统的 webhook 协议，对于这些系统您应该首先使用对应的集成，更加简单方便。本集成提供了一个标准的 HTTP 接口，需要您开发适配。好处是您可以推送任何你想进行oncall的告警事件。 -::: - -
- -## 操作步骤 ---- - -### 在 Flashduty On-call - -您可通过以下2种方式，获取一个集成推送地址，任选其一即可。 - -#### 使用专属集成 - -当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。 - - - - - 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 - 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 - 3. 选择 **标准告警事件** 集成，点击 **保存**，生成卡片。 - 4. 点击生成的卡片，可以查看到 **推送地址**，复制备用，完成。 - - - - -#### 使用共享集成 - -当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。 - - - - - 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 - 2. 选择 **标准告警事件** 集成： - - **集成名称**：为当前集成定义一个名称。 - 3. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 - 4. 点击 **保存** 后，复制当前页面的新生成的 **推送地址** 备用。 - 5. 完成。 - - - -
- - -## 一、请求描述 ---- - -### 请求方式 - -
- -POST, Content-Type:"application/json" - -
- -### 请求参数： - -
- -#### Headers: -字段|必含|类型|释义 -:-:|:-:|:-:|:--- -| Content-Type | 是 | string | 固定值：`application/json`。 - -#### Query Strings: -字段|必含|类型|释义 -:-:|:-:|:-:|:--- -| integration_key | 是 | string | 集成秘钥，用于访问控制。添加集成后获得。 - -#### Payload: - -字段|必含|类型|释义 -:-:|:-:|:-:|:--- -| title_rule | 是 | string | 告警标题，不超过`512`个字符，超出后将自动截断。

支持根据告警内容动态生成标题，生成规则请参考 [定制故障标题](https://docs.flashduty.com/zh/flashduty/customize-incident-attrs)。 -| event_status | 是 | string | 告警状态。

枚举值（`首字母大写`）：*Critical*：严重，*Warning*：警告，*Info*：提醒，*Ok*：恢复。

当指定为Ok时，意味着对告警进行自动恢复。 -| alert_key | 否 | string | 告警标识，用于对已经存在的告警进行更新或自动恢复。

您可以自定义此值，但不可超过`255`个字符。您也可以依赖系统自动生成，该值会在响应中返回。

如果您上报的是恢复事件，则此值必须存在。 -| description | 否 | string | 告警描述，不超过`2048`个字符，超出后将自动截断。 -| labels | 否 | map | 告警标签集合，key 为标签名称，value 为标签值：

1. 标签的 key 和 value 均为 string 类型，区分大小写。
2. 标签的 key 不要超过`128`个字符，遵循Prometheus标签命名规范。value 不超过`2048`个字符，超出后将自动截断。
3. 至多传入`50`个标签。`标签内容参考`[最佳实践](#最佳实践)。

示例："resource": "171.26.23.22", "check": "api latency > 500ms" -| images | 否 | [][image](#image) | 图片数组，可用于前端或飞书和钉钉应用通知的图片展示。系统根据 alt 进行合并覆盖，相同(包括空字符)的alt只保留一条 - -#### image 结构体 - -字段|必含|类型|释义 -:-:|:-:|:-:|:--- -| alt | 否 | string | 图片的替代文本, 长度限制 128 字符，超长截断。 -| src | 是 | string | 图片来源，值：http/https 开头的图片链接地址 或 [图片上传接口](/zh/openapi/api-catalog)返回的image_key，长度限制 256 字符，超长会被丢弃 -| href | 否 | string | 超链接引用路径，长度限制 256 字符，超长截断 - -
- -### 请求响应 - -字段名称|必选|类型|描述 -:-:|:-:|:-:|:--- -request_id|是|string|请求 ID，用于链路追踪 -error |否|[Error](#Error)|错误描述，仅当出现错误时返回 -data |否|[Data](#Data)| 上报信息 - - -Data: - -| 字段名称 | 必选 | 类型 | 描述 | -:-:|:-:|:-:|:--- -| alert_key| 否 | string | 告警标识，可依据此值上报恢复事件。如果您上报事件时，已经指定了 alert_key，则此值不变。否则，系统自动生成。 | - - -Error: - -| 字段名称 | 必选 | 类型 | 描述 | -:-:|:-:|:-:|:--- -| code | 是 | string | 错误码，枚举值参考 [Code](#Code) | -| message | 否 | string | 错误描述 | - - -Code: - -| 错误码 | HTTP Status | 描述 | -| :-:|:-:| ------------------ | -| InvalidParameter | 400 | 参数错误 | -| InvalidContentType | 400 | Conten-Type 不支持 | -| MethodNotAllowed | 400 | HTTP Method 不支持 | -| Unauthorized | 401 | 登录认证未通过 | -| AccessDenied | 403 | 权限认证未通过 | -| RequestTooFrequently | 429 | 请求过于频繁 | -| RouteNotFound | 404 | 请求 Method+Path 未匹配 | -| ResourceNotFound | 400 | 账户未购买资源，先前往费用中心线操作下单| -| NoLicense | 400 | 账户无充足订阅 License，先前往费用中心升级或购买订阅 -| InternalError | 500 | 内部或未知错误 | - - -### 二、请求示例 ---- - -请求： - -``` -curl -X POST '{api_host}/event/push/alert/standard?integration_key={integration_key}' \ --H 'Content-Type: application/json' \ --d '{ - "event_status": "Warning", - "title_rule": "cpu idle low than 20%", - "labels": { - "service": "engine", - "cluster":"nj", - "resource":"es.nj.01", - "check":"cpu.idle<20%", - "metric":"node_cpu_seconds_total" - } -}' -v - -``` - -成功响应： - -``` -{ - "request_id": "0ace00116215ab4ca0ec5244b8fc54b0", - "data": { - "alert_key": "9qJ798NJoXS4UMVB5SHsNj" - } -} -``` - -失败响应： - -``` -{ - "request_id": "0ace00116215abc0ba4e52449bd305b0", - "error": { - "code": "InvalidParameter", - "message": "integration_key is not a valid one" - } -} -``` - -## 三、最佳实践 ---- - -1. 当告警状态发生变更时，向 Flashduty发送事件 -2. 当告警恢复时，发送一个 status 为 Ok 的事件，来关闭告警。否则，告警将一直处于打开状态。如果您的告警系统没有恢复事件，建议您手动发送恢复事件 -3. 标签是事件的描述，应尽量丰富标签内容（发送时指定，或者通过配置 enrichment 规则来生成新的标签），比如： - - 告警的发生来源，如 host，cluster，check 或 metric 等 - - 告警的归属信息，如 team，owner 等 - - 告警的类别信息，如 class（api，db，net） - - -## 四、常见问题 ---- - - - - - #### 在 Flashduty On-call - - 1. 查看集成是否展示了 **最新事件时间**？如果没有，代表Flashduty没有收到推送，直接优先您的系统。 - 2. 如果您使用的是 **共享集成**，优先确认您是否配置了 **路由规则**。不设置路由规则，系统会直接拒绝新的推送，因为没有协作空间可以承接您的告警。这种情况下，直接配置路由规则到您期望的空间即可。 - - #### 在您的系统 - - 1. 确认您请求的地址，和集成详情中的地址完全一致。 - 2. 确认您的服务可以访问外网 api.flashcat.cloud 域名。如果不可以，您首先需要为 server 开通外网，或单独针对 Flashduty 的域名开通外网访问。 - 3. 打印 Flashduty 服务的响应结果，查看是否有明确信息。 - - 如果以上步骤执行之后，仍然没有查询到问题根因，请 **携带请求响应中的 request_id** 联系我们。 - - - - - - - - Flashduty On-call 使用2层降噪机制： - - 1. 首先对告警event进行去重检查，如果您推送的event和之前推送的event内容完全一致，则新的event将被直接丢弃。 - 2. 如果新的event的状态和描述和其对应的告警的上一条event的状态、标题、描述均一致，则新的event将被直接丢弃，同时更新归属告警属性。 - 3. 新的event可能由于匹配到排除、丢弃、抑制或静默规则，而被丢弃。 - 4. 当新的event触发了新告警，则系统会进入第二层降噪检查，判断新告警是否可以被合并到某个活跃的故障中，如果可以，则只会并入已有的故障，而不会产生新故障。 - - 更多内容请参考 [告警降噪](/zh/on-call/channel/noise-reduction)。 - - diff --git a/zh/on-call/integration/alert-integration/alert-sources/rizhiyi.mdx b/zh/on-call/integration/alert-integration/alert-sources/rizhiyi.mdx new file mode 100644 index 00000000..62bb337a --- /dev/null +++ b/zh/on-call/integration/alert-integration/alert-sources/rizhiyi.mdx @@ -0,0 +1,176 @@ +--- +title: "日志易告警集成" +description: "通过自定义告警插件将日志易告警事件推送到 Flashduty，实现告警事件自动化降噪处理" +keywords: ["告警集成", "日志易", "日志监控", "监控告警", "数据接入"] +--- + +
+ +## 在 Flashduty On-call +--- + +您可通过以下2种方式，获取一个集成推送地址，任选其一即可。 + +### 使用专属集成 + +当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。 + + + + + 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 + 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 + 3. 选择 **日志易** 集成，点击 **保存**，生成卡片。 + 4. 点击生成的卡片，可以查看到 **推送地址**，复制备用，完成。 + + + + +### 使用共享集成 + +当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。 + + + + + 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 + 2. 选择 **日志易** 集成： + - **集成名称**：为当前集成定义一个名称。 + 3. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 + 4. 点击 **保存** 后，复制当前页面的新生成的 **推送地址** 备用。 + 5. 完成。 + + + +
+ +## 在日志易 +--- + +日志易告警支持邮件、syslog、告警转发和自定义告警插件等通知方式。其中「告警转发」推送的 JSON 结构是日志易的固定格式，与 Flashduty 要求的事件格式不一致，因此请通过 **自定义告警插件**（Python 脚本）将告警转换为标准格式后推送到 Flashduty。 + +
+ +**步骤 1：编写告警插件脚本** + +新建一个 Python 文件（如 `FlashdutyWebhook.py`），内容如下，并将脚本开头的 `push_url` 替换为您的 Flashduty 集成推送地址： + +```python +# -*- coding: utf-8 -*- +import json + +import requests + +# Flashduty 集成推送地址，替换为控制台上「日志易」集成的推送地址 +push_url = "https://api.flashcat.cloud/event/push/alert/standard?integration_key=YOUR_INTEGRATION_KEY" + +# 前置 HTTP 代理，适用于日志易主机无法直连互联网的场景，不涉及则留空 +proxies = { + 'http': '', + 'https': '', +} + +# 日志易告警等级到 Flashduty 告警等级的映射 +LEVEL_MAP = { + "critical": "Critical", + "high": "Critical", + "mid": "Warning", + "low": "Info", + "info": "Info", +} + +META = { + "name": "FlashdutyWebhook", + "version": 1, + "alias": "Flashduty告警推送", + "configs": [] +} + + +def set_logger(reset_logger): + global logger + logger = reset_logger + + +def content(params, alert): + return alert.get("description", "") + + +def handle(params, alert): + level = alert.get("strategy", {}).get("trigger", {}).get("level", "low") + if alert.get("is_alert_recovery"): + event_status = "Ok" + else: + event_status = LEVEL_MAP.get(level, "Info") + event = { + "event_status": event_status, + "title_rule": alert.get("name", "日志易告警"), + "alert_key": "rizhiyi::" + alert.get("name", ""), + "description": alert.get("description", ""), + "labels": { + "alert_name": alert.get("name", ""), + "alert_level": level, + }, + } + resp = requests.post(push_url, json=event, timeout=10, proxies=proxies) + logger.info("push to flashduty, status: %s, resp: %s", resp.status_code, resp.text) + + +def execute_reply(params, alert): + handle(params, alert) + return "push to flashduty done" +``` + +**步骤 2：上传插件** + +进入日志易【监控】页面，在【其他】→【告警插件】中上传脚本文件。 + +**步骤 3：在监控项中引用插件** + +编辑需要对接 Flashduty 的监控项，在【添加告警方式】中选择刚上传的插件并保存。日志易还支持平台自身监控（Manager）和剧本（Soar）两类插件，编写方式与上述示例一致，可按需扩展。 + +
+ + +插件推送的事件需遵循 Flashduty 标准告警事件格式：`event_status` 必填（`Critical`、`Warning`、`Info`、`Ok` 之一），`title_rule` 为告警标题，`alert_key` 用于告警的更新与自动恢复，`labels` 为告警标签。完整字段说明请参考 [标准告警事件](/zh/on-call/integration/alert-integration/alert-sources/standard-alert)。 + + +## 严重程度映射关系 +--- + +
+ +日志易到 Flashduty 的告警等级映射由插件脚本中的 `LEVEL_MAP` 决定，上述示例的映射关系如下，您可以按需调整： + +| 日志易告警等级 | Flashduty | 状态 | +| --- | --- | --- | +| critical | Critical | 严重 | +| high | Critical | 严重 | +| mid | Warning | 警告 | +| low | Info | 提醒 | +| info | Info | 提醒 | +| 告警恢复（is_alert_recovery） | Ok | 恢复 | + +
+ +## 常见问题 +--- + + + + +**在 Flashduty On-call** + +1. 查看集成是否展示了 **最新事件时间**？如果没有，代表 Flashduty 没有收到推送，请优先排查日志易侧配置。 +2. 如果您使用的是 **共享集成**，优先确认您是否配置了 **路由规则**。不设置路由规则，系统会直接拒绝新的推送，因为没有协作空间可以承接您的告警。这种情况下，直接配置路由规则到您期望的空间即可。 + +**在日志易** + +1. 查看插件运行日志（默认位于 `/data/rizhiyi/logs/cruxee/plugins` 目录，文件名与上传时显示的名称一致），确认脚本执行无报错、推送请求返回成功。 +2. 确认脚本中的推送地址与 Flashduty 集成详情中的地址完全一致，且 `event_status` 取值为 `Critical`、`Warning`、`Info`、`Ok` 之一，否则 Flashduty 会拒绝该请求。 +3. 确认日志易主机可以访问外网 `api.flashcat.cloud` 域名，如无法直连，请在脚本的 `proxies` 中配置 HTTP 正向代理。 + +如果以上步骤执行之后，仍然没有查询到问题根因，请 **携带请求响应中的 request_id** 联系我们。 + + + diff --git a/zh/on-call/integration/alert-integration/alert-sources/wecom-alert.mdx b/zh/on-call/integration/alert-integration/alert-sources/wecom-alert.mdx index 5d0291d6..b455b5d8 100644 --- a/zh/on-call/integration/alert-integration/alert-sources/wecom-alert.mdx +++ b/zh/on-call/integration/alert-integration/alert-sources/wecom-alert.mdx @@ -38,7 +38,7 @@ keywords: ["告警集成", "企微", "监控告警", "数据接入"] 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 2. 选择 **企微告警** 集成： - **集成名称**：为当前集成定义一个名称。 - - **消息类型**：选择企微告警消息类型，目前仅支持 Text、Markdown。 + - **消息类型**：选择企微告警消息类型，目前仅支持文本（Text）、富文本（Post）。 - **推送模式**：选择企微告警在何种情况下触发或恢复告警。 3. 复制当前页面的 **企微告警集成地址** 备用。 4. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 diff --git a/zh/on-call/integration/alert-integration/alert-sources/zabbix.mdx b/zh/on-call/integration/alert-integration/alert-sources/zabbix.mdx index 09f9392a..c207c927 100644 --- a/zh/on-call/integration/alert-integration/alert-sources/zabbix.mdx +++ b/zh/on-call/integration/alert-integration/alert-sources/zabbix.mdx @@ -57,7 +57,7 @@ keywords: ["告警集成", "Zabbix集成", "监控告警", "数据接入"] ### 7.x 版本 -#### 步骤 1：定义快猫星云 media type +#### 步骤 1：定义 Flashduty media type
1. media type 是 Zabbix 中用于发送通知和告警的传输通道。进入终端，通过以下命令，下载完整配置 @@ -71,7 +71,7 @@ wget --header="Referer: https://console.flashcat.cloud" https://download.flashca - `URL`：webhook 推送请求地址，复制集成的推送地址即可 - `zabbix_url`：Zabbix 控制台地址，直接复制即可（如果您的页面配置了 tomcat/nginx 转发路径，请同时携带），系统会在路径后拼接 trigger_id 等参数来生成告警详情页面连接 - - `HTTPProxy`：如果您的 Zabbix Server 不能直接访问快猫星云服务，可以将该参数设置为一个代理地址 + - `HTTPProxy`：如果您的 Zabbix Server 不能直接访问 Flashduty 服务，可以将该参数设置为一个代理地址 drawing @@ -87,7 +87,7 @@ media type 必须关联至某个 user 才能发送事件。user 至少拥有对 1. 登录 Zabbix 控制台，选择 `Users > Users`，选择 Admin 用户，选择 media，选择 Add，进入编辑窗口： -- Type： 选择以上创建的快猫星云 media type +- Type： 选择以上创建的 Flashduty media type - Send To：填写 Flashduty - 其他配置使用默认配置，保持不变 @@ -112,7 +112,7 @@ media type 必须关联至某个 user 才能发送事件。user 至少拥有对 - 在 Operations 配置项，点击 Add 按钮，进入配置窗口 - Send to users：选择以上新建或配置的 user -- Send only to：选择快猫星云 media type +- Send only to：选择 Flashduty media type - 其他配置保持默认 - 点击 Add 按钮，完成该配置项配置 - 重复以上步骤，完成对 `Recovery operations` 和 `Update operations` 的配置 @@ -123,14 +123,14 @@ media type 必须关联至某个 user 才能发送事件。user 至少拥有对
-#### 步骤 4：发送事件到快猫星云 +#### 步骤 4：发送事件到 Flashduty
登录 Zabbix 控制台，选择 `Monitoring > Problems`，查看最新的告警列表。 1. 点击 Actions，弹窗内可以看到消息通知结果 -2. 找到快猫星云对应日志，如果 Status 为 `Sent`，代表通知成功。否则根据提示排查原因 +2. 找到 Flashduty 对应日志，如果 Status 为 `Sent`，代表通知成功。否则根据提示排查原因 drawing @@ -144,7 +144,7 @@ media type 必须关联至某个 user 才能发送事件。user 至少拥有对 ### 5.x~6.x 版本 -#### 步骤 1：定义快猫星云 media type +#### 步骤 1：定义 Flashduty media type
@@ -163,7 +163,7 @@ wget --header="Referer: https://console.flashcat.cloud" https://download.flashca - `URL`：webhook 推送请求地址，复制集成的推送地址即可 - `zabbix_url`：Zabbix 控制台地址，直接复制即可（如果您的页面配置了 tomcat/nginx 转发路径，请同时携带），系统会在路径后拼接 trigger_id 等参数来生成告警详情页面连接 - - `HTTPProxy`：如果您的 Zabbix Server 不能直接访问快猫星云服务，可以将该参数设置为一个代理地址 + - `HTTPProxy`：如果您的 Zabbix Server 不能直接访问 Flashduty 服务，可以将该参数设置为一个代理地址 drawing @@ -179,7 +179,7 @@ media type 必须关联至某个 user 才能发送事件。user 至少拥有对 1. 登录 Zabbix 控制台，选择 `Administration > Users`，选择 Admin 用户，选择 media，选择 Add，进入编辑窗口： -- Type： 选择以上创建的快猫星云 media type +- Type： 选择以上创建的 Flashduty media type - Send To：填写 N/A - 其他配置使用默认配置，保持不变 @@ -204,7 +204,7 @@ media type 必须关联至某个 user 才能发送事件。user 至少拥有对 - 在 Operations 配置项，点击 Add 按钮，进入配置窗口 - Send to users：选择以上新建或配置的 user -- Send only to：选择快猫星云 media type +- Send only to：选择 Flashduty media type - 其他配置保持默认 - 点击 Add 按钮，完成该配置项配置 - 重复以上步骤，完成对 `Recovery operations` 和 `Update operations` 的配置 @@ -214,14 +214,14 @@ media type 必须关联至某个 user 才能发送事件。user 至少拥有对
-#### 步骤 4：发送事件到快猫星云 +#### 步骤 4：发送事件到 Flashduty
登录 Zabbix 控制台，选择 `Monitoring > Problems`，查看最新的告警列表。 1. 点击 Actions，弹窗内可以看到消息通知结果 -2. 找到快猫星云对应日志，如果 Status 为 `Sent`，代表通知成功。否则根据提示排查原因 +2. 找到 Flashduty 对应日志，如果 Status 为 `Sent`，代表通知成功。否则根据提示排查原因 drawing @@ -234,7 +234,7 @@ media type 必须关联至某个 user 才能发送事件。user 至少拥有对 ### 3.x~4.x 版本 -#### 步骤 1：定义快猫星云 media type +#### 步骤 1：定义 Flashduty media type
@@ -246,7 +246,7 @@ media type 必须关联至某个 user 才能发送事件。user 至少拥有对 - `Flashduty webhook 推送请求地址`，复制集成的推送地址即可，保持在第三个参数 - `Zabbix 控制台地址`，直接复制即可（如果您的页面配置了 tomcat/nginx 转发路径，请同时携带），用于生成告警详情页面连接。如果没有空着即可，保持在第四个参数 - - `HTTPProxy`：如果您的 Zabbix Server 不能直接访问快猫星云服务，可以将该参数设置为一个代理地址。如果没有空着即可，保持在第五个参数 + - `HTTPProxy`：如果您的 Zabbix Server 不能直接访问 Flashduty 服务，可以将该参数设置为一个代理地址。如果没有空着即可，保持在第五个参数 drawing @@ -279,7 +279,7 @@ media type 必须关联至某个 user 才能发送事件。user 至少拥有对 1. 登录 Zabbix 控制台，选择 `Administration > Users`，选择 Admin 用户，选择 media，选择 Add，进入编辑窗口： - - Type： 选择以上创建的快猫星云 media type + - Type： 选择以上创建的 Flashduty media type - Send To：填写 N/A - 其他配置使用默认配置，保持不变 @@ -304,7 +304,7 @@ media type 必须关联至某个 user 才能发送事件。user 至少拥有对 - 在 Operations 配置项，点击 Add 按钮，进入配置窗口 - Send to users：选择以上新建或配置的 user - - Send only to：选择快猫星云 media type + - Send only to：选择 Flashduty media type - 其他配置保持默认 - 点击 Add 按钮，完成该配置项配置 - 重复以上步骤，完成对 `Recovery operations` 和 `Update operations` 的配置 @@ -327,14 +327,14 @@ media type 必须关联至某个 user 才能发送事件。user 至少拥有对
-#### 步骤 4：发送事件到快猫星云 +#### 步骤 4：发送事件到 Flashduty
登录 Zabbix 控制台，选择 Monitoring > Problems，查看最新的告警列表。 1. 点击 Actions，弹窗内可以看到消息通知结果 -2. 找到快猫星云对应日志，如果 Status 为 Sent，代表通知成功。否则根据提示排查原因 +2. 找到 Flashduty 对应日志，如果 Status 为 Sent，代表通知成功。否则根据提示排查原因 drawing @@ -347,9 +347,9 @@ media type 必须关联至某个 user 才能发送事件。user 至少拥有对
-Zabbix 到快猫星云告警等级映射关系： +Zabbix 到 Flashduty 告警等级映射关系： -| Zabbix | 快猫星云 | 状态 | +| Zabbix | Flashduty | 状态 | | -------------- | -------- | ---- | | Disaster | Critical | 严重 | | High | Critical | 严重 | diff --git a/zh/on-call/integration/alert-integration/label-enhancement.mdx b/zh/on-call/integration/alert-integration/label-enhancement.mdx index 995223e4..8abe7e8c 100644 --- a/zh/on-call/integration/alert-integration/label-enhancement.mdx +++ b/zh/on-call/integration/alert-integration/label-enhancement.mdx @@ -228,6 +228,10 @@ keywords: ["标签增强", "自动标签", "数据提取", "字段映射", "告 ## 映射数据管理 + +每个账户最多可创建 20 个映射表和 50 个映射服务（API），超出限制时创建将失败并提示数量超限。 + + ### 映射表数据管理 在映射表详情页面中，可以对映射表数据进行管理： diff --git a/zh/on-call/integration/alert-integration/routing-rules.mdx b/zh/on-call/integration/alert-integration/routing-rules.mdx index d493e426..dbc2db67 100644 --- a/zh/on-call/integration/alert-integration/routing-rules.mdx +++ b/zh/on-call/integration/alert-integration/routing-rules.mdx @@ -26,7 +26,7 @@ keywords: ["路由规则", "告警路由", "分发策略", "协作空间", "分 | **匹配条件** | 按标签、属性等条件筛选告警，支持精确、通配符、正则匹配 | | **路由模式** | 见下方详细说明 | | **流程控制** | **继续匹配**（默认）：命中后继续匹配后续规则；**停止匹配**：命中后不再匹配 | -| **默认路由** | 兜底规则，当所有规则都不匹配时生效 | +| **默认路由** | 兜底规则，当没有任何规则实际投递到协作空间时生效 | ### 路由模式 @@ -138,7 +138,7 @@ keywords: ["路由规则", "告警路由", "分发策略", "协作空间", "分 -不会。默认路由仅在所有路由规则均未命中时才生效。如果某条规则已命中（无论流程控制选择「继续」还是「停止」），默认路由都不会再触发。 +不会。默认路由与流程控制无关，仅在没有任何规则实际投递到协作空间时才生效：只要某条规则命中并实际投递了协作空间（无论流程控制选择「继续」还是「停止」），默认路由都不会再触发。需要注意，名称映射模式的规则即使命中，如果映射到的协作空间不存在、未能实际投递，默认路由仍会触发。 diff --git a/zh/on-call/integration/instant-messaging/lark.mdx b/zh/on-call/integration/instant-messaging/lark.mdx index 02b04e32..6c1e62a5 100644 --- a/zh/on-call/integration/instant-messaging/lark.mdx +++ b/zh/on-call/integration/instant-messaging/lark.mdx @@ -68,6 +68,8 @@ keywords: ["飞书", "Lark", "即时消息", "告警通知", "IM集成"] 回到 Flashduty On-call **集成中心** 页面，选择 即时消息 → **飞书**，在表单中填入 `名称` 以及上一步复制的 `App ID`、`App Secret`、`Verification Token` 和 `Encrypt Key` 后，点击 **保存** 完成创建。 +如果您使用的是 Lark（国际版），请同时开启 **是否为 Lark 版本** 开关，开启后系统将使用 Lark 国际版端点进行通信。Lark 开放平台的开发者后台入口为 [open.larksuite.com](https://open.larksuite.com)，上文创建应用、配置权限等步骤均在该站点完成。 + 创建成功后，您将在列表中看到已添加的飞书集成。点击其名称进入详情页面，即可查看 **网页配置** 地址、**重定向 URL** 和 **消息卡片请求网址**，这些信息将在后续步骤中使用。 ![2025-09-18-10-44-00](https://docs-cdn.flashcat.cloud/images/png/1e8ffb6c39f99ef12bd85ae49992ebad.png) @@ -85,10 +87,10 @@ keywords: ["飞书", "Lark", "即时消息", "告警通知", "IM集成"] ![2025-09-18-10-47-46](https://docs-cdn.flashcat.cloud/images/png/d91efc598bda17e1bfcb367aec47c779.png) -3. 前往 事件回调 → **事件配置** 页面，配置 `订阅方式`（内容为集成详情中的 **消息卡片请求网址**）。然后，添加以下两项事件： +3. 前往 事件回调 → **事件配置** 页面，配置 `订阅方式`（内容为集成详情中的 **消息卡片请求网址**）。然后，添加以下事件： -- `im.chat.disbanded_v1` - `im.message.receive_v1` +- `im.chat.disbanded_v1`（可选订阅，当前无消费逻辑） ![2025-09-18-11-06-05](https://docs-cdn.flashcat.cloud/images/png/71910d8af8d60b5f30baf009081646df.png) diff --git a/zh/on-call/integration/instant-messaging/slack.mdx b/zh/on-call/integration/instant-messaging/slack.mdx index 24c8cc33..df790068 100644 --- a/zh/on-call/integration/instant-messaging/slack.mdx +++ b/zh/on-call/integration/instant-messaging/slack.mdx @@ -19,25 +19,55 @@ keywords: ["Slack", "即时消息", "告警通知", "IM集成", "协作工具"] | 官方 scope 名称 | 用途 | | :--- | :--- | | `app_mentions:read` | 接收群聊中 @ 应用的消息，用于 AI SRE 对话入口 | -| `im:history` | 读取私聊历史消息，用于 AI SRE 上下文 | | `chat:write` | 发送基础通知、作战室消息和 AI SRE 回复 | | `chat:write.public` | 向应用尚未加入的公开频道发送通知和作战室消息 | +| `chat:write.customize` | 以自定义用户名和头像发送消息 | +| `commands` | 提供 `/fd` 斜杠命令 | | `channels:read` | 读取公开频道信息和频道列表 | | `channels:history` | 读取公开频道消息历史；AI SRE 上下文和 AI 生成复盘报告需要该权限 | +| `channels:join` | 允许应用加入公开频道 | +| `channels:manage` | 创建和管理公开频道，作战室功能必需 | | `groups:read` | 读取私有频道信息和频道列表 | | `groups:history` | 读取私有频道消息历史；AI SRE 上下文和 AI 生成复盘报告需要该权限 | -| `groups:write` | 创建和管理私有频道作战室 | -| `groups:write.invites` | 邀请成员加入私有频道作战室 | +| `groups:write` | 创建和管理私有频道作战室，并邀请成员加入 | +| `im:read` | 读取私聊会话列表 | +| `im:history` | 读取私聊历史消息，用于 AI SRE 上下文 | +| `im:write` | 发起私聊会话 | +| `mpim:read` | 读取多人私聊会话列表 | +| `mpim:history` | 读取多人私聊历史消息 | +| `mpim:write` | 发起多人私聊会话 | | `users:read` | 读取用户基础信息，用于用户关联、展示和邀请 | | `users:read.email` | 读取用户邮箱，用于用户关联 | +| `users.profile:read` | 读取用户资料 | +| `users:write` | 修改用户资料与状态 | +| `usergroups:read` | 读取用户组信息 | +| `usergroups:write` | 创建和管理用户组 | +| `team:read` | 读取工作区信息 | +| `reactions:read` | 读取消息表情反应，用于 AI SRE 处理状态确认 | | `reactions:write` | 添加或删除消息表情反应，用于 AI SRE 处理状态确认 | -| `files:read` | 读取消息中的文件，用于 AI SRE 上下文和附件处理 | +| `files:write` | 上传文件，用于发送复盘报告等附件 | ### User Token Scopes | 官方 scope 名称 | 用途 | | :--- | :--- | +| `identify` | 获取授权用户的基本身份信息 | | `channels:read` | 读取授权用户可见的公开频道，用于频道列表和分派策略配置 | +| `channels:write` | 管理授权用户所在的公开频道 | +| `groups:read` | 读取授权用户可见的私有频道 | +| `groups:write` | 管理授权用户所在的私有频道 | +| `im:read` | 读取授权用户的私聊会话 | +| `im:write` | 以授权用户身份发起私聊会话 | +| `mpim:read` | 读取授权用户的多人私聊会话 | +| `mpim:write` | 以授权用户身份发起多人私聊会话 | +| `chat:write` | 以授权用户身份发送消息 | +| `users:read` | 读取用户基础信息 | +| `users:read.email` | 读取用户邮箱，用于用户关联 | +| `users.profile:read` | 读取用户资料 | +| `reactions:read` | 读取消息表情反应 | +| `reactions:write` | 添加或删除消息表情反应 | + +以上清单与当前 OAuth 授权请求一致；如与 Slack 授权页面显示存在差异，以授权页实际请求为准。 如果您使用的是 Slack Incoming Webhook 方式的 Slack 机器人通知，而不是本页的 Slack App 集成，请在对应 Slack 应用中开启 Incoming Webhooks，并在 OAuth 流程中包含 `incoming-webhook` scope。 diff --git a/zh/on-call/integration/sso/keycloak.mdx b/zh/on-call/integration/sso/keycloak.mdx index ab38ce99..8f3326e7 100644 --- a/zh/on-call/integration/sso/keycloak.mdx +++ b/zh/on-call/integration/sso/keycloak.mdx @@ -19,7 +19,7 @@ Keycloak 是一个开源的身份和访问管理解决方案，提供了一套 登录 Flashduty 控制台，获取 ACS 地址（后续步骤会用到）。 -路径：**访问控制 => 单点登录 => 设置 => SAML2.0 协议 => Flashduty 服务提供商信息 => Assertion Consumer Service URL** +路径：**访问控制 => 单点登录 => SAML2.0 协议 => Flashcat 服务提供商信息 => Assertion Consumer Service URL** ![获取ACS地址](https://api.apifox.com/api/v1/projects/4169655/resources/437194/image-preview) @@ -94,7 +94,7 @@ Keycloak 是一个开源的身份和访问管理解决方案，提供了一套 ![创建用户](https://api.apifox.com/api/v1/projects/4169655/resources/437041/image-preview) -**登录测试**：访问 `console.flashcat.cloud`，选择 SSO 登录，在域名处填写单点登录配置中的登录域名前缀。 +**登录测试**：访问 `console.flashcat.cloud`，选择 SSO 登录，在域名处填写组织的登录域名（在 **平台管理 → 组织 → 组织信息 → 组织资料** 页面配置）；也可以直接访问 `{域名}.sso.flashcat.cloud` 发起单点登录。 ![测试登录](https://api.apifox.com/api/v1/projects/4169655/resources/437062/image-preview) @@ -106,7 +106,7 @@ Keycloak 是一个开源的身份和访问管理解决方案，提供了一套 登录 Flashduty 控制台，获取 Redirect URL（后续步骤会用到）。 -路径：**访问控制 => 单点登录 => 设置 => OIDC 协议 => Flashduty 服务提供商信息 => Redirect URL** +路径：**访问控制 => 单点登录 => OIDC 协议 => Flashcat 服务提供商信息 => Redirect URL** ![获取Redirect URL](https://api.apifox.com/api/v1/projects/4169655/resources/437183/image-preview) diff --git a/zh/on-call/integration/sso/openldap.mdx b/zh/on-call/integration/sso/openldap.mdx index 27cf587b..b97f83fb 100644 --- a/zh/on-call/integration/sso/openldap.mdx +++ b/zh/on-call/integration/sso/openldap.mdx @@ -28,8 +28,6 @@ OpenLDAP 是一个开源的 LDAP 实现，由于其开源和灵活性，成为 ## Docker Compose 配置 ```yaml docker-compose.yml -version: '1' - networks: go-ldap-admin: driver: bridge @@ -85,13 +83,13 @@ services: ```bash -docker-compose up +docker compose up ``` ```bash -docker-compose up -d +docker compose up -d ``` @@ -99,13 +97,13 @@ docker-compose up -d **查看服务状态：** ```bash -docker-compose ps +docker compose ps ``` **停止服务：** ```bash -docker-compose down +docker compose down ``` ## 登录 OpenLDAP @@ -137,4 +135,4 @@ docker-compose down 上述字段的含义与描述请参考 [配置单点登录](/zh/platform/configure-sso)。 -配置完成后，点击设置抽屉底部的 **连接检测** 按钮，验证 Flashduty 能否成功连接到 OpenLDAP 服务器。连接成功后再点击 **保存**。 +配置完成后，在 **协议与连接** 分区的 LDAP 表单下方点击 **连接检测**，验证 Flashduty 能否成功连接到 OpenLDAP 服务器。连接成功后再点击 **保存**。 diff --git a/zh/on-call/integration/webhooks/alert-webhook.mdx b/zh/on-call/integration/webhooks/alert-webhook.mdx index cd496ddd..79f69f50 100644 --- a/zh/on-call/integration/webhooks/alert-webhook.mdx +++ b/zh/on-call/integration/webhooks/alert-webhook.mdx @@ -6,7 +6,7 @@ keywords: ["告警Webhook", "HTTP回调", "事件通知", "系统集成", "自 **版本要求**：此功能需要 On-call 标准版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/) -配置告警 Webhook，当告警发生特定操作（如触发、关闭）时，系统通过 HTTP 回调您配置的地址。回调内容将包含告警最新关键信息，您可以与自研工具进行集成。 +配置告警 Webhook，当告警发生特定操作（如触发、更新）时，系统通过 HTTP 回调您配置的地址。回调内容将包含告警最新关键信息，您可以与自研工具进行集成。 @@ -21,10 +21,13 @@ keywords: ["告警Webhook", "HTTP回调", "事件通知", "系统集成", "自 | a_new | 集成推送新事件，触发一条新告警 | | a_update | 集成推送新事件，合并到一条告警，并更新告警信息（严重程度、状态、labels、描述等） | | a_merge | 合并告警至故障 | -| a_close | 手动关闭告警（系统事件，当告警被手动关闭时由系统自动触发，无法在 UI 中勾选） |
+ +手动关闭告警当前不会触发 Webhook 回调。 + + ## 二、推送描述 ### 请求方式 @@ -61,11 +64,18 @@ email | string | 是 | 邮件地址 | 字段 | 类型 | 必含 | 释义| | :--------------: | :-----------: | :--: | :----------------- | | alert_id | string | 是 | 告警 ID| -| data_source_id | int64 | 是 | 集成 ID| -| data_source_name | string | 是 | 集成名称| -| data_source_type | string | 是 | 集成类型| +| account_id | int64 | 是 | 账户 ID| +| integration_id | int64 | 是 | 集成 ID| +| integration_name | string | 是 | 集成名称| +| integration_type | string | 是 | 集成类型| +| integration_ref_id | string | 否 | 集成引用 ID| +| data_source_id | int64 | 是 | 集成 ID，同 integration_id| +| data_source_name | string | 是 | 集成名称，兼容保留字段（Deprecated），请使用 integration_name| +| data_source_type | string | 是 | 集成类型，兼容保留字段（Deprecated），请使用 integration_type| +| data_source_ref_id | string | 否 | 集成引用 ID，兼容保留字段（Deprecated），请使用 integration_ref_id| | channel_id | int64 | 是 | 协作空间 ID| | channel_name | string | 是 | 协作空间名称| +| channel_status | string | 否 | 协作空间状态，枚举值：enabled，disabled| | title | string | 是 | 告警标题| | title_rule | string | 否 | 标题生成规则| | description | string | 否 | 告警描述| diff --git a/zh/on-call/integration/webhooks/custom-actions.mdx b/zh/on-call/integration/webhooks/custom-actions.mdx index 7e7580b4..147c87dd 100644 --- a/zh/on-call/integration/webhooks/custom-actions.mdx +++ b/zh/on-call/integration/webhooks/custom-actions.mdx @@ -11,9 +11,10 @@ keywords: ["自定义操作", "HTTP回调", "事件通知", "系统集成", "自 1. 登录 Flashduty 控制台，进入【集成中心-Webhook】 2. 点击添加 自定义操作 集成 3. 配置 操作名称，此名称将以按钮的形式体现在故障详情中 -4. 配置 协作空间，可以配置多个，但每个协作空间至多添加三个 自定义操作 -5. 配置 Endpoint、自定义 Headers -6. 保存，完成 +4. 配置 管理团队（可选），只有该团队成员可以编辑此集成配置 +5. 配置 协作空间，可以配置多个，但每个协作空间至多添加五个 自定义操作 +6. 配置 Endpoint、自定义 Headers +7. 保存，完成 ## 二、推送描述 diff --git a/zh/on-call/integration/webhooks/incident-webhook.mdx b/zh/on-call/integration/webhooks/incident-webhook.mdx index 1ea62801..8ec2ba43 100644 --- a/zh/on-call/integration/webhooks/incident-webhook.mdx +++ b/zh/on-call/integration/webhooks/incident-webhook.mdx @@ -18,7 +18,7 @@ keywords: ["故障Webhook", "HTTP回调", "事件通知", "系统集成", "自 | :----------: | :--------------- | | i_new | 创建故障（自动或手动创建）| | i_assign | 分派故障（自动或手动分派）| -| i_a_rspd | 添加处理人 | +| i_a_rspd | 添加处理人（暂仅支持通过 API 订阅） | | i_snooze | 手动暂缓故障 | | i_wake | 取消暂缓故障 | | i_ack | 手动认领故障 | @@ -36,10 +36,10 @@ keywords: ["故障Webhook", "HTTP回调", "事件通知", "系统集成", "自 | i_r_rsltn | 更新故障解决办法 | | i_r_severity | 更新故障严重程度 | | i_r_field | 更新故障自定义字段 | -| i_wi_created | 创建行动项或跟进项 | -| i_wi_assignees | 更新行动项或跟进项负责人 | -| i_wi_completed | 完成行动项或跟进项 | -| i_wi_converted | 将行动项转换为跟进项 | +| i_wi_created | 创建行动项或跟进项（暂仅支持通过 API 订阅） | +| i_wi_assignees | 更新行动项或跟进项负责人（暂仅支持通过 API 订阅） | +| i_wi_completed | 完成行动项或跟进项（暂仅支持通过 API 订阅） | +| i_wi_converted | 将行动项转换为跟进项（暂仅支持通过 API 订阅） |
@@ -89,6 +89,8 @@ acknowledged_at | int64| 否 | 认领时间 | 字段 | 类型 | 必含 | 释义 | | :---------------: | :-----------------: | :--: | :----------------- | | incident_id | string | 是 | 故障 ID | +| account_id | int64 | 是 | 账户 ID | +| account_name | string | 是 | 账户名称 | | title | string | 是 | 故障标题 | | description | string | 否 | 故障描述 | | impact | string | 否 | 故障影响 | @@ -110,12 +112,17 @@ acknowledged_at | int64| 否 | 认领时间 | creator | [Person](#Person) | 否 | 创建人员信息，仅手动创建故障时存在 | | closer | [Person](#Person) | 否 | 关闭人员信息，仅手动关闭故障时存在 | | responders | [][Responder](#Responder) | 否 | 处理人员信息列表，仅故障被分派后存在。对于i_new事件，此值可能为空 | +| assigned_to | object | 否 | 分派信息，仅故障被分派后存在。包含 type（分派方式）、escalate_rule_id（分派策略 ID）、escalate_rule_name（分派策略名称）、layer_idx（当前分派层级）、assigned_at（分派时间，Unix 秒时间戳）等 | | alert_cnt | int64 | 否 | 关联告警个数 | +| active_alert_cnt | int64 | 否 | 活跃关联告警个数（告警状态为 Critical、Warning、Info） | +| integration_ids | []int64 | 否 | 关联告警来源的集成 ID 列表 | +| integration_types | []string | 否 | 关联告警来源的集成类型列表 | | num | string | 是 | 故障短标识，取故障 ObjectID 最后 6 位十六进制并大写，例如 `56E25B`，在控制台界面中显示。可作为查询故障详情 API 的替代参数（与 `incident_id` 二选一），同一账号下不唯一，查询时返回最新创建的匹配记录 | | channel_id | int64 | 否 | 协作空间ID，为0代表不属于任何空间 | | channel_name | string | 否 | 协作空间名称 | | team_id | int64 | 否 | 协作空间所属团队 ID，无归属团队时为 0 | | detail_url | string | 是 | 详情地址 | +| links | []object | 否 | 协作空间关联的链接集成列表，包含 name（名称）、endpoint（跳转地址）、open_type（打开方式：popup 或 tab） | | group_method | string | 否 | 聚合方式，枚举值：n：不聚合，p：按规则聚合，i：智能聚合 | @@ -214,6 +221,7 @@ curl -X POST 'https://example.com/incident/webhook?a=a' \ | 配置项 | 说明 | | :--- | :--- | +| **管理团队** | 选择管理该集成的团队，只有团队成员可以编辑此集成配置 | | **Endpoint** | 接收回调的 HTTP/HTTPS 地址，必须以 `http://` 或 `https://` 开头 | | **TLS 验证** | 默认启用。关闭后将跳过目标服务器的 TLS 证书验证，适用于测试环境或自签名证书场景 | | **Headers** | 自定义请求头，以 Key-Value 形式添加，支持添加多个 | diff --git a/zh/on-call/integration/webhooks/servicedesk-plus-sync.mdx b/zh/on-call/integration/webhooks/servicedesk-plus-sync.mdx index b813ef5e..34e738f9 100644 --- a/zh/on-call/integration/webhooks/servicedesk-plus-sync.mdx +++ b/zh/on-call/integration/webhooks/servicedesk-plus-sync.mdx @@ -110,7 +110,7 @@ keywords: ["ServiceDesk Plus", "工单同步", "Webhook", "ITSM", "故障关联" ``` # 私有化版本 { - "suject":"${{request.subject}}", + "subject":"${{request.subject}}", "request_id":"${{request.id}}", "description":"${{request.description}}", "status":"${{request.status.name}}", diff --git a/zh/on-call/quickstart/comparison.mdx b/zh/on-call/quickstart/comparison.mdx index 61c1e776..c12ed53a 100644 --- a/zh/on-call/quickstart/comparison.mdx +++ b/zh/on-call/quickstart/comparison.mdx @@ -184,7 +184,7 @@ PagerDuty AIOps 在超大规模事件关联场景上打磨多年，能力成熟 | **外部故障提交** | ✅ 客户或合作伙伴**免登录**通过独立页面或 API 提交故障，自动匹配分派策略 | 仅支持邮件转 incident，无结构化表单 | 对外提供服务的团队可直接把客户报障接入处置流程 | | **Link 集成** | ✅ 按 hostname 等标签一键跳转 CMDB 或内部系统 | — | | | **自定义 Webhook（出站）** | 自定义 Payload 格式、重试条件与自动重试、免密验证，**完整调用历史追溯**（状态码、重试次数、请求响应详情），可按事件类型或来源订阅 | Payload 格式固定，重试策略固定（3 次不可配置），无自助调用历史查询 | | -| **Open APIs** | ✅ 337 个接口，覆盖 On-call、Monitors、RUM、AI SRE 与平台管理 | ✅ | 两者均提供丰富的 API 和详细文档 | +| **Open APIs** | ✅ 330+ 个接口，覆盖 On-call、Monitors、RUM、AI SRE 与平台管理 | ✅ | 两者均提供丰富的 API 和详细文档 | **集成按需支持承诺**：如果您常用的商业软件或开源服务尚未在集成列表中，请联系我们——只要您需要，我们承诺快速支持。 @@ -229,9 +229,9 @@ PagerDuty AIOps 在超大规模事件关联场景上打磨多年，能力成熟 | 工具 | Flashduty | PagerDuty | | --- | --- | --- | -| **[Open API](/zh/openapi/api-catalog)** | 337 个接口，覆盖 On-call、Monitors、RUM、AI SRE 与平台管理，双语文档 | ✅ REST API 完善，文档成熟 | +| **[Open API](/zh/openapi/api-catalog)** | 330+ 个接口，覆盖 On-call、Monitors、RUM、AI SRE 与平台管理，双语文档 | ✅ REST API 完善，文档成熟 | | **[CLI](/zh/developer/cli)** | 336 个 API 操作命令 + 内置 Agent Skills，可直接配给 Claude Code、Cursor、Codex 等 AI 编程工具 | 无官方力推的完整 CLI：社区最常用的 `pagerduty-cli` 为员工个人项目（官方声明不背书、作者已宣布归档），官方 go-pagerduty 库附带功能有限的 `pd` 命令行小工具 | -| **SDK** | [Go SDK](/zh/developer/go-sdk)：go-github 风格封装，覆盖 337 个 API 操作、39 个服务 | 官方维护 go-pagerduty、python-pagerduty 等客户端库 | +| **SDK** | [Go SDK](/zh/developer/go-sdk)：go-github 风格封装，覆盖 330+ 个 API 操作、39 个服务 | 官方维护 go-pagerduty、python-pagerduty 等客户端库 | | **[Terraform Provider](/zh/developer/terraform)** | 12 类资源 + 13 类数据源，IaC 管理协作空间、分派策略、值班表等 | ✅ 官方 Terraform Provider，生态成熟 | | **[MCP Server](/zh/developer/mcp-server)** | 8 个工具集 23 个工具，支持远程、Docker、源码三种部署 | ✅ 官方 MCP Server | diff --git a/zh/on-call/quickstart/mobile-app.mdx b/zh/on-call/quickstart/mobile-app.mdx new file mode 100644 index 00000000..f9d342a6 --- /dev/null +++ b/zh/on-call/quickstart/mobile-app.mdx @@ -0,0 +1,175 @@ +--- +title: "Flashduty App 移动端" +sidebarTitle: "移动 App" +description: "使用 Flashduty App 与移动 H5 随时随地接收告警通知、处理故障" +keywords: ["Flashduty App", "移动端", "移动 H5", "推送通知", "故障处理", "扫码登录"] +--- + +Flashduty 提供覆盖 **iOS、Android 和移动 H5** 的移动端能力。无论您身在何处，都可以在手机上接收故障通知，并完成认领、关闭、升级、转派等全部核心处理操作。 + +## 下载与安装 + +--- + +下载与安装方式（App Store、各大安卓应用市场、扫码下载安装包）请参见 [个人设置 - Flashduty APP](/zh/on-call/configuration/personal-settings#flashduty-app)。 + +安装完成后，首次登录成功即会自动完成设备与账户的关联，此后即可接收 App 推送。您可以在控制台 **个人中心 → Flashduty APP** 页面查看和管理已关联的设备。 + +## 登录方式 + +--- + + + + App 登录页提供两种方式： + + - **扫码登录**：点击 **扫码登录**，扫描控制台 **个人中心 → Flashduty APP** 页面上的二维码，登录的同时完成设备关联。私有化部署环境同样通过扫码接入，App 会自动识别二维码中的服务地址 + - **直接登录**：点击 **直接登录**，在 App 内打开的登录页中完成账户验证，支持手机验证码、密码或单点登录（SSO）。私有化部署可使用登录页的 **自定义登录域名** 指向您的服务地址 + + + 在手机浏览器访问 H5 控制台时，支持以下登录方式： + + - **验证码登录**：通过手机号或邮箱接收验证码登录 + - **密码登录**：使用账户密码登录 + - **单点登录（SSO）**：输入企业域名或邮箱定位到您所在企业的认证方式（含 LDAP），跳转到企业身份提供方完成认证 + + + 在企业微信、飞书、钉钉内打开 Flashduty 的通知链接时，H5 页面会通过对应平台的授权机制自动完成登录，无需重复输入账户信息，直接进入故障详情。 + + + + +登录页右上角可随时切换中文 / English。 + + +## 故障处理 + +--- + +### 故障列表与筛选 + +App 首页即故障列表，分为 **分派给我**（带故障数量角标）和 **全部** 两个页签。在列表卡片上左滑，可以快捷 **认领** 或 **关闭** 故障。 + +点击列表右上角的筛选图标，可以按以下条件组合过滤，筛选条件会保存在本机： + +| 筛选项 | 说明 | +| --- | --- | +| **处理进度** | 全部 / 未关闭 / 待处理 / 处理中 / 已关闭（默认仅显示未关闭） | +| **严重程度** | Critical / Warning / Info，可多选 | +| **故障标题 / 故障 ID** | 输入关键字模糊搜索 | +| **与我相关** | 仅看与您相关的故障 | +| **人员** | 按发起人员、处理人员、认领人员、关闭人员筛选 | +| **协作空间** | 按故障所属协作空间筛选 | + +### 故障详情与操作 + +点击故障进入详情页，包含 **故障详情**（标题、严重程度、描述、标签、自定义字段、关联告警、作战室入口等）和 **时间线**（处理过程与评论记录）两个页签，页面底部提供常驻操作： + +| 操作 | 说明 | +| --- | --- | +| **关闭** | 关闭故障；已关闭的故障显示为 **重新打开**（需填写重开原因） | +| **认领 / 取消认领** | 认领故障开始处理，误认领可取消 | +| **更多操作（⋮）** | 展开全部补充操作，见下表 | + +**更多操作** 中的可用项随故障状态动态呈现： + +| 操作 | 说明 | +| --- | --- | +| **暂缓** | 仅处理中故障可用，暂停故障按分派策略继续升级 | +| **升级** | 仅按分派策略分派且策略启用中的故障可用，将故障升级到下一环节 | +| **重新分派** | 未关闭的故障可用，将故障转派给其他人员或值班表 | +| **快速静默** | 基于当前故障快速创建静默规则 | +| **AI 总结** | 生成故障处理过程摘要（专业版） | +| **作战室** | 创建作战室、添加关注人员进入作战室、解散作战室（专业版，需启用支持作战室的 IM 集成） | +| **Jira 与自定义操作** | 管理员在集成中配置的 Jira、ServiceNow 等自定义动作 | + + +与控制台一致：如果管理员为认领、关闭等操作配置了自定义表单，在 App 上执行这些操作时同样需要先填写表单。 + + +### 手动创建故障 + +在故障列表页点击创建按钮，即可手动创建故障：填写 **故障标题**、**严重程度**、**故障描述**（不超过 200 字），选择 **协作空间** 和 **分派方式**（策略分派或直接分派给个人），并支持上传图片等自定义字段。创建成功后系统立即按所选方式发起分派通知。 + +## 推送通知 + +--- + +App 登录成功后，当前设备会自动与账户绑定并接收推送。**点击通知可直接打开对应的故障详情页**。 + + + + iOS 端基于 Apple 官方的 **关键警报（Critical Alerts）** 能力：Critical 级别的故障通知可以穿透静音和勿扰模式强提醒。 + + 前往 App 内 **设置 → 绕过勿扰模式**，或系统 **设置 → 通知 → Flashduty** 中开启 **关键警报**。 + + + Android 端通过阿里云推送通道触达，并为故障通知建立了两个系统通知渠道，可在系统通知设置中分别管理铃声、震动与横幅： + + | 通知渠道 | 说明 | + | --- | --- | + | **故障通知** | 常规渠道，承载 Warning / Info 级别的故障通知 | + | **紧急通知** | 仅 Critical 级别故障路由至此渠道，锁屏可见，且可绕过系统免打扰模式 | + + 小米等国产机型已适配厂商推送通道，App 在后台被清理时也能收到通知。 + + + + +收不到推送时，请按顺序检查：手机系统的通知权限是否已为 Flashduty 开启 → 分派策略是否包含 App 推送渠道 →（策略为"遵循个人偏好"时）个人通知偏好中是否勾选了 Flashduty APP。详见 [通知渠道](/zh/on-call/configuration/notifications)。 + + +## 实用设置 + +--- + +在故障列表页点击右上角 **设置图标** 进入设置页： + +| 设置项 | 说明 | +| --- | --- | +| **消息通知** | 查看通知权限状态，一键跳转系统通知设置 | +| **绕过勿扰模式**（iOS） | 跳转系统设置开启关键警报，Critical 故障不受勿扰模式限制 | +| **同步联系人** | 在手机通讯录中创建 Flashduty 联系人并定期同步语音通知号码，避免语音告警被误拦截；仅更新该联系人，不获取或存储其他通讯录信息 | +| **主题** | 跟随系统 / 浅色 / 深色 | +| **语言** | 中文 / English | +| **检测更新** | 检查应用商店新版本；当版本过低不再维护时，需要立即升级才能继续使用 | + +## 移动 H5 + +--- + +**m.console.flashcat.cloud** 是与 App 同一代码库构建的 Web 端，能力与 App 一致： + +- **通知链接的落地页**：短信、IM 中的故障相关链接（如评论 @提及 通知）会在移动端打开 H5 的故障详情页 +- **IM 内嵌使用**：在企业微信、飞书、钉钉内打开时自动免登，可直接处理故障 +- **浏览器访问**：在手机浏览器直接访问时需要先完成登录（验证码、密码或 SSO） + +## 能力边界 + +--- + +移动端聚焦 **接收通知与处理故障**。以下配置类能力需要前往 PC 控制台完成： + +- 值班排班、分派策略、集成接入与路由规则 +- 通知模板、静默与聚合等降噪配置 +- 个人通知偏好、联系方式绑定等账户设置 + + +App 推送仅用于故障分派场景；评论 @提及、工作项指派等协作类通知不提供 App 推送，可在 PC 控制台 **个人中心 → 通知偏好** 中选择短信、邮件或 IM 接收。 + + +## 延伸阅读 + +--- + + + + 了解控制台、IM、语音等全部故障处理方式 + + + 配置 App 推送与其他通知渠道 + + + 下载 App、管理已关联设备 + + diff --git a/zh/on-call/statuspage/comparison.mdx b/zh/on-call/statuspage/comparison.mdx index 909d0289..28714e29 100644 --- a/zh/on-call/statuspage/comparison.mdx +++ b/zh/on-call/statuspage/comparison.mdx @@ -69,7 +69,7 @@ Flashduty 状态页和 Atlassian Statuspage 是市场上两款主流的状态页 | 功能项 | Flashduty | Atlassian Statuspage | | --- | --- | --- | | **事件发布** | ✅ 创建事件、更新时间线、通知订阅者 | ✅ 支持 | - | **维护事件** | ✅ 可设置计划开始和结束时间，自动推进状态，允许手动覆盖；**维护不计入 uptime 损耗**，适合区分故障与计划维护 | ❌ 不支持 | + | **维护事件** | ✅ 可设置计划开始和结束时间，自动推进状态，允许手动覆盖；**维护不计入 uptime 损耗**，适合区分故障与计划维护 | ✅ 支持 Scheduled Maintenance：可设定开始时间与时长，支持自动推进状态与订阅者提醒 | | **回溯事件** | ✅ 回溯事件纳入事件历史和可用性统计，通过时间线中的组件状态变更计算影响时段，**历史补录和可用性统计闭环** | ✅ 支持 backfill incident，但回溯与可用性统计的整合程度有限 | | **事件模板** | ✅ 支持 | ✅ 支持 | | **组件状态联动** | ✅ 支持 | ✅ 支持 | @@ -81,11 +81,11 @@ Flashduty 状态页和 Atlassian Statuspage 是市场上两款主流的状态页 | **全量订阅** | ✅ 支持 | ✅ 支持 | | **组件订阅** | ✅ **所有版本均支持** | 仅 Business 及以上套餐 | | **事件订阅** | ✅ 订阅者可订阅特定事件的后续更新 | ❌ 不支持 | - | **批量导入/导出** | ✅ 管理员可批量导入、导出订阅者 | ❌ 不支持 | + | **批量导入/导出** | ✅ 管理员可批量导入、导出订阅者（导入需专业版，导出需标准版及以上） | ✅ 支持 CSV 导入与 JSON/CSV 导出 | | **自助管理** | ✅ 订阅者通过管理令牌自助调整订阅范围或退订 | 有限的自助能力 | - Flashduty 在订阅管理上的粒度更细：全量、组件、事件三级订阅全覆盖，且不受套餐限制。 + Flashduty 在订阅管理上的粒度更细：全量、组件、事件三级订阅全覆盖。 @@ -190,17 +190,17 @@ Flashduty 状态页的额外成本为零——它是 On-call 订阅的内置能 --- -Flashduty CLI 支持将 Atlassian Statuspage 的组件、分组、历史事件和邮件订阅者一键迁移到 Flashduty 状态页，同时兼容 `history.rss` 和 `history.atom` 链接格式，现有 RSS/Atom 订阅者无需修改订阅地址。 +Flashduty CLI 支持将 Atlassian Statuspage 的组件、分组、历史事件和邮件订阅者一键迁移到 Flashduty 状态页（迁移功能需专业版），同时兼容 `history.rss` 和 `history.atom` 链接格式，现有 RSS/Atom 订阅者无需修改订阅地址。 - 使用 `flashduty statuspage migrate structure` 命令自动导入组件、分组、历史事件和通知模板，此步骤不会通知订阅者 + 使用 `flashduty status-page migrate-structure` 命令自动导入组件、分组、历史事件和通知模板，此步骤不会通知订阅者 在 Flashduty 控制台检查导入的组件、分组和历史事件是否完整 - 使用 `flashduty statuspage migrate email-subscribers` 命令导入订阅者，订阅者导入后即为活跃状态 + 使用 `flashduty status-page migrate-email-subscribers` 命令导入订阅者，订阅者导入后即为活跃状态 将自定义域名 CNAME 指向 Flashduty，确认一切正常后正式上线 @@ -219,7 +219,7 @@ Flashduty CLI 支持将 Atlassian Statuspage 的组件、分组、历史事件 - 维护事件、事件订阅、组件展示控制、批量导入导出、原生 IM 通知等**独有能力**，且不受套餐限制 + 事件订阅、组件展示控制、维护不计入可用性统计、原生 IM 通知等**差异化能力** 状态页包含在 On-call 模块中，**无需单独采购**。相比 Atlassian Statuspage 每年数千美元的独立费用，额外成本为零 diff --git a/zh/on-call/statuspage/get-started.mdx b/zh/on-call/statuspage/get-started.mdx index 192b90ce..331d4a47 100644 --- a/zh/on-call/statuspage/get-started.mdx +++ b/zh/on-call/statuspage/get-started.mdx @@ -42,7 +42,7 @@ keywords: ["状态页接入", "状态页入门", "Atlassian Statuspage 迁移", | 字段 | 说明 | | --- | --- | | **名称** | 状态页的显示名称，通常使用公司名、产品名或服务名 | - | **URL 标识** | 用于生成状态页访问地址的唯一标识，仅允许小写字母、数字和连字符 | + | **URL 标识** | 用于生成状态页访问地址的唯一标识，仅允许小写字母、数字、连字符和下划线 | | **类型** | 选择 **公开** 或 **内部** | @@ -55,7 +55,13 @@ keywords: ["状态页接入", "状态页入门", "Atlassian Statuspage 迁移", ## 从 Atlassian Statuspage 迁移 -如果你已经在使用 Atlassian Statuspage，可以使用 Flashduty CLI 将**组件、分组、历史事件和邮件订阅者**迁移到 Flashduty 状态页。迁移分为两个独立步骤： +如果你已经在使用 Atlassian Statuspage，可以使用 Flashduty CLI 将**组件、分组、历史事件和邮件订阅者**迁移到 Flashduty 状态页。 + + +**版本要求**：迁移功能（结构与历史迁移、邮件订阅者迁移）需要 Flashduty **专业版**。 + + +迁移分为两个独立步骤： 1. **迁移结构与历史**：导入组件、分组、历史事件、维护记录和通知模板。 2. **迁移邮件订阅者**：导入订阅者列表及其订阅偏好。 @@ -119,18 +125,15 @@ export ATLASSIAN_STATUSPAGE_API_KEY="your_api_key_here" 执行以下命令导入 Atlassian Statuspage 的组件、分组、历史事件、维护记录和通知模板。此步骤会创建或复用 Flashduty 目标状态页，但不会通知订阅者。 ```bash - flashduty statuspage migrate structure \ - --from atlassian \ - --source-page-id \ + flashduty status-page migrate-structure \ --api-key "$ATLASSIAN_STATUSPAGE_API_KEY" ``` | 参数 | 必填 | 说明 | | --- | --- | --- | - | `--from` | 是 | 迁移来源，目前仅支持 `atlassian` | - | `--source-page-id` | 是 | Atlassian Statuspage 的 Page ID | + | `` | 是 | Atlassian Statuspage 的 Page ID（位置参数，也可用 `--source-page-id` 传入） | | `--api-key` | 是 | Atlassian Statuspage 的 API Key | - | `--url-name` | 否 | 新创建的 Flashduty 公开状态页的 URL 名称 | + | `--url-name` | 否 | 新创建的 Flashduty 公开状态页的 URL 名称；省略时复用源页面的 URL 名称 | `--url-name` 仅在本次迁移**创建新的目标状态页**时生效。如果同一个 `--source-page-id` 已经在历史迁移中映射到一个已存在的目标状态页： @@ -149,15 +152,15 @@ export ATLASSIAN_STATUSPAGE_API_KEY="your_api_key_here" 迁移任务为异步执行，命令会立即返回一个 **Job ID**。使用以下命令查询进度： ```bash - flashduty statuspage migrate status --job-id + flashduty status-page migration-status ``` - 迁移会依次导入 `components`、`sections`、`history` 和 `templates`。任务完成后，输出中会包含 Flashduty 状态页 ID（`target-page-id`），后续迁移订阅者时需要使用。 + 结构与历史迁移会依次完成 5 个步骤：创建（或复用）目标状态页 → 导入分组（sections）→ 导入组件（components）→ 导入历史事件（incidents，含维护记录）→ 导入事件模板（templates）。任务完成后，输出中的 `target_page_id` 即为 Flashduty 状态页 ID，后续迁移订阅者时需要使用。 如果需要取消正在运行的迁移任务，执行： ```bash - flashduty statuspage migrate cancel --job-id + flashduty status-page migration-cancel ``` @@ -165,11 +168,14 @@ export ATLASSIAN_STATUSPAGE_API_KEY="your_api_key_here" 在进行下一步之前，建议检查导入的内容： ```bash - # 查看新状态页信息 - flashduty statuspage list --id + # 查看状态页列表 + flashduty status-page list - # 查看导入的事件 - flashduty statuspage changes --page-id --type incident + # 查看目标状态页详情（含组件与分组 ID） + flashduty status-page info + + # 查看导入的故障事件（--type 与 --status 均为必填） + flashduty status-page change-list --type incident --status resolved ``` 你也可以登录 [Flashduty 控制台](https://console.flashcat.cloud)，在状态页管理界面中检查组件、分组和历史事件是否完整。 @@ -179,8 +185,7 @@ export ATLASSIAN_STATUSPAGE_API_KEY="your_api_key_here" 确认结构和历史导入正确后，执行订阅者迁移： ```bash - flashduty statuspage migrate email-subscribers \ - --from atlassian \ + flashduty status-page migrate-email-subscribers \ --source-page-id \ --target-page-id \ --api-key "$ATLASSIAN_STATUSPAGE_API_KEY" @@ -188,9 +193,8 @@ export ATLASSIAN_STATUSPAGE_API_KEY="your_api_key_here" | 参数 | 必填 | 说明 | | --- | --- | --- | - | `--from` | 是 | 迁移来源，`atlassian` | | `--source-page-id` | 是 | Atlassian Statuspage 的 Page ID | - | `--target-page-id` | 是 | 结构与历史迁移完成后输出的 Flashduty 状态页 ID | + | `--target-page-id` | 是 | 结构与历史迁移完成后输出的 Flashduty 状态页 ID（`target_page_id`） | | `--api-key` | 是 | Atlassian Statuspage 的 API Key | 导入的订阅者会直接变为活跃状态，无需邮件验证。已在 Atlassian 端被标记为隔离（quarantined）的邮箱地址会被自动跳过。订阅者迁移可以安全地多次执行，已存在的订阅者不会被重复导入。 @@ -210,30 +214,27 @@ export ATLASSIAN_STATUSPAGE_API_KEY="your_api_key_here" export ATLASSIAN_STATUSPAGE_API_KEY="your_api_key_here" # 1. 迁移结构与历史 -flashduty statuspage migrate structure \ - --from atlassian \ - --source-page-id 0db0rq26tg1l \ +flashduty status-page migrate-structure 0db0rq26tg1l \ --api-key "$ATLASSIAN_STATUSPAGE_API_KEY" -# 输出: Job ID: str_abc +# 返回 job_id（ULID 格式），例如 01KP0311872NVYFRRQ82FW0001 # 2. 查询进度，等待完成 -flashduty statuspage migrate status --job-id str_abc -# 重复执行直到 Status: completed -# 记录输出中的 target-page-id +flashduty status-page migration-status 01KP0311872NVYFRRQ82FW0001 +# 重复执行直到 status 为 completed +# 记录输出中的 target_page_id # 3. 验证导入结果 -flashduty statuspage list --id +flashduty status-page info # 4. 迁移邮件订阅者 -flashduty statuspage migrate email-subscribers \ - --from atlassian \ +flashduty status-page migrate-email-subscribers \ --source-page-id 0db0rq26tg1l \ --target-page-id \ --api-key "$ATLASSIAN_STATUSPAGE_API_KEY" -# 输出: Job ID: sub_xyz +# 返回订阅者迁移任务的 job_id，例如 01KP04M3W5EZY0QHAJ2VB00002 # 5. 查询进度，等待完成 -flashduty statuspage migrate status --job-id sub_xyz +flashduty status-page migration-status 01KP04M3W5EZY0QHAJ2VB00002 ``` --- diff --git a/zh/on-call/statuspage/publish-events.mdx b/zh/on-call/statuspage/publish-events.mdx index 708d9468..734f5237 100644 --- a/zh/on-call/statuspage/publish-events.mdx +++ b/zh/on-call/statuspage/publish-events.mdx @@ -13,10 +13,10 @@ description: "了解如何在状态页中发布故障和维护事件，管理事 | 状态 | 说明 | | --- | --- | -| **调查中**（Investigating） | 团队已知悉问题，正在调查根因 | -| **已确认**（Identified） | 问题根因已确认，正在制定修复方案 | +| **排查中**（Investigating） | 团队已知悉问题，正在调查根因 | +| **已定位**（Identified） | 问题根因已确认，正在制定修复方案 | | **监控中**（Monitoring） | 修复措施已实施，正在监控恢复情况 | -| **已解决**（Resolved） | 问题已完全修复，服务恢复正常 | +| **已恢复**（Resolved） | 问题已完全修复，服务恢复正常 | ### 维护（Maintenance） @@ -24,7 +24,7 @@ description: "了解如何在状态页中发布故障和维护事件，管理事 | 状态 | 说明 | | --- | --- | -| **已计划**（Scheduled） | 维护已安排，尚未开始 | +| **已排期**（Scheduled） | 维护已安排，尚未开始 | | **进行中**（Ongoing） | 维护正在进行 | | **已完成**（Completed） | 维护已结束 | @@ -35,26 +35,34 @@ description: "了解如何在状态页中发布故障和维护事件，管理事 ## 发布事件 - - 在状态页管理页面中，点击 **发布事件**，选择事件类型为 **故障** 或 **维护**。 + + 在状态页详情中，故障与维护有各自独立的发布入口： + + - **发布故障**：进入 **故障** 页，点击 **新的故障**；如需补录历史故障，点击 **回溯故障** + - **发布维护**：进入 **维护** 页，点击 **计划维护** 配置以下字段： | 字段 | 说明 | | --- | --- | - | **标题** | 事件的简要标题 | - | **描述** | 事件的详细说明 | - | **状态** | 事件的初始状态 | - | **受影响组件** | 选择受此事件影响的组件，并为每个组件设定影响状态 | - | **响应人员** | 指定参与处理的团队成员 | + | **故障名称 / 维护名称** | 事件的简要标题，将在状态页上公开显示（必填） | + | **当前状态** | 事件的初始状态 | + | **消息** | 事件的详细说明（必填），展示在状态页上用于描述事件状态 | + | **受影响组件** | 选择受此事件影响的组件，并为每个组件设定影响状态（至少选择 1 个） | | **通知订阅者** | 是否在发布时向订阅者发送通知 | + + 发布维护时还必须填写 **影响时段**（计划开始与结束时间），且结束时间必须晚于开始时间。 + + + **响应人员**（responders）字段仅支持通过 API / CLI 设置，控制台发布表单中不提供该选项。 + 每个事件至少包含一条时间线更新。系统会根据你填写的信息自动生成初始更新记录。 - 确认信息后，点击 **发布** 完成事件创建。 + 确认信息后，点击 **发布故障** 或 **发布维护** 完成事件创建。 @@ -80,12 +88,12 @@ description: "了解如何在状态页中发布故障和维护事件，管理事 -当事件进入终止状态（故障的"已解决"或维护的"已完成"）时，所有受影响组件必须恢复为"运行正常"状态。 +当事件进入终止状态（故障的"已恢复"或维护的"已完成"）时，所有受影响组件必须恢复为"运行正常"状态。 ### 消息支持的 Markdown 格式 -事件描述与时间线更新的编辑器支持以下 Markdown 元素，公开状态页会按相同格式渲染： +事件消息与时间线更新的编辑器支持以下 Markdown 元素，公开状态页会按相同格式渲染： | 格式 | 语法示例 | | --- | --- | @@ -116,7 +124,7 @@ description: "了解如何在状态页中发布故障和维护事件，管理事 | --- | --- | | **时间戳** | 该更新对应的实际发生时间 | | **状态变更** | 将事件推进到下一个生命周期状态（可选） | -| **描述** | 当前进展的说明文字 | +| **消息** | 当前进展的说明文字（必填） | | **组件状态变更** | 调整受影响组件的服务状态（可选） | @@ -133,7 +141,7 @@ description: "了解如何在状态页中发布故障和维护事件，管理事 将事件状态更新为终止状态即可关闭事件： -- 故障：更新状态为 **已解决**（Resolved） +- 故障：更新状态为 **已恢复**（Resolved） - 维护：更新状态为 **已完成**（Completed） 关闭事件时，系统会自动记录关闭时间。所有受影响组件此时必须为"运行正常"状态。 @@ -148,7 +156,7 @@ description: "了解如何在状态页中发布故障和维护事件，管理事 对于维护事件，你可以设置**计划开始时间**和**计划结束时间**，并启用**按计划自动更新**功能。系统将在指定时间自动推进维护状态： -- **计划开始时间**到达时：自动将状态从"已计划"更新为"进行中" +- **计划开始时间**到达时：自动将状态从"已排期"更新为"进行中" - **计划结束时间**到达时：自动将状态从"进行中"更新为"已完成" @@ -179,6 +187,10 @@ description: "了解如何在状态页中发布故障和维护事件，管理事 回溯事件与普通事件在状态页上的展示方式完全一致，且会纳入事件历史和服务可用性统计。 + +创建回溯故障时，时间线中至少需要一条非「已恢复」状态的更新，用于呈现故障的演进过程。 + + 如果回溯事件创建时即为终止状态，且未指定结束时间，系统会自动将最后一条更新的时间戳作为结束时间。 diff --git a/zh/on-call/statuspage/subscriptions.mdx b/zh/on-call/statuspage/subscriptions.mdx index 4f6d5f49..a0f321cb 100644 --- a/zh/on-call/statuspage/subscriptions.mdx +++ b/zh/on-call/statuspage/subscriptions.mdx @@ -93,12 +93,25 @@ Feed 仅对**公开状态页**开放。对内部状态页或不存在的状态 ## 管理员管理订阅 +### 订阅设置 + +在状态页设置的 **订阅** 页中，**启用订阅** 是页面级总开关：公开状态页控制邮件订阅，内部状态页控制 IM 订阅。关闭后，即使发布事件时勾选了「通知订阅者」，系统也不会向订阅者推送通知。 + +订阅通知的用量规则： + +- **邮件（公开状态页）**：事件通知邮件计入 Flashduty 账户的邮件用量。免费版账户的邮件用量超出限额后，事件通知邮件将暂停发送；付费版账户超出限额的邮件将单独计费，仅当账户欠费时暂停发送。 +- **IM（内部状态页）**：事件通知计入对应 IM 平台的 API 调用用量，超出 IM 平台的限额时通知将暂停发送。API 调用限额通常与你的组织使用的 IM 平台定价方案有关。 + ### 查看订阅者 -在状态页设置的 **订阅管理** 中，管理员可以查看当前订阅者列表，并按订阅方式或组件进行筛选。列表支持分页浏览，展示每位订阅者的邮件地址（或用户 ID）、订阅方式和订阅的组件。 +在状态页设置的 **订阅** 页的「订阅者列表」区块中，管理员可以查看当前订阅者列表，并可按组件进行筛选。列表支持分页浏览，展示每位订阅者的邮件地址（或用户 ID）、订阅方式和订阅的组件。 ### 批量导入 + +**版本要求**：批量导入订阅者需要 Flashduty **专业版**。 + + 管理员可以批量导入订阅者，适用于迁移场景或需要为特定用户群体预先设置订阅的情况。导入时需提供： | 字段 | 说明 | @@ -113,6 +126,10 @@ Feed 仅对**公开状态页**开放。对内部状态页或不存在的状态 ### 导出订阅者 + +**版本要求**：导出订阅者需要 Flashduty **标准版**及以上。 + + 管理员可以导出订阅者列表，包括每位订阅者的接收地址、订阅方式、订阅的组件等信息。 --- diff --git a/zh/on-call/statuspage/templates.mdx b/zh/on-call/statuspage/templates.mdx index 6cb51721..1409479b 100644 --- a/zh/on-call/statuspage/templates.mdx +++ b/zh/on-call/statuspage/templates.mdx @@ -1,17 +1,17 @@ --- title: "事件模板" -description: "了解如何使用预定义模板和消息模板快速发布状态页事件" +description: "了解如何使用完整状态更新和状态描述模板快速发布状态页事件" --- 手动填写事件信息耗时且容易遗漏关键内容。Flashduty 状态页提供**事件模板**功能，让你通过预设的内容快速发布事件，减少重复操作。 -状态页支持两种模板类型：**预定义模板**和**消息模板**。 +状态页支持两种模板类型：**完整状态更新**（预定义模板）和**状态描述**（消息模板）。 --- -## 预定义模板 +## 完整状态更新（预定义模板） -预定义模板（PreDefined Template）用于快速创建包含完整初始信息的事件。每个预定义模板包含以下字段： +完整状态更新（PreDefined Template）用于快速创建包含完整初始信息的事件。每个完整状态更新模板包含以下字段： | 字段 | 说明 | | --- | --- | @@ -22,19 +22,19 @@ description: "了解如何使用预定义模板和消息模板快速发布状态 ### 使用场景 -预定义模板适用于可预见的、重复发生的事件场景。例如： +完整状态更新模板适用于可预见的、重复发生的事件场景。例如： -- **定期维护**：创建一个标题为"例行系统维护"的模板，预设状态为"已计划"，描述中包含标准的维护通知措辞 +- **定期维护**：创建一个标题为"例行系统维护"的模板，预设状态为"已排期"，描述中包含标准的维护通知措辞 - **已知问题**：为常见的服务降级场景创建模板，预设标题和描述 -### 管理预定义模板 +### 管理完整状态更新模板 - 在状态页设置的 **模板** 页签中，选择 **预定义模板**，点击 **创建模板**，填写标题、类型、状态和描述。 + 在状态页设置的 **事件模板** 页签中，选择 **完整状态更新**，点击 **创建模板**，填写标题、类型、状态和描述。 - 在发布事件时，选择一个预定义模板。系统会自动填充模板中的字段，你可以在此基础上进行调整。 + 在发布事件时，选择一个完整状态更新模板。系统会自动填充模板中的字段，你可以在此基础上进行调整。 你可以随时修改模板的标题、描述和状态，或删除不再使用的模板。 @@ -43,11 +43,11 @@ description: "了解如何使用预定义模板和消息模板快速发布状态 --- -## 消息模板 +## 状态描述（消息模板） -消息模板（Message Template）用于在事件的不同状态阶段预设更新消息。与预定义模板关注"事件初始化"不同，消息模板关注的是"事件推进过程中的通知措辞"。 +状态描述（Message Template）用于在事件的不同状态阶段预设更新消息。与完整状态更新关注"事件初始化"不同，状态描述关注的是"事件推进过程中的通知措辞"。 -每个消息模板包含以下字段： +每个状态描述模板包含以下字段： | 字段 | 说明 | | --- | --- | @@ -57,21 +57,21 @@ description: "了解如何使用预定义模板和消息模板快速发布状态 ### 消息映射 -消息模板为事件生命周期中的每个状态提供预设文本： +状态描述模板为事件生命周期中的每个状态提供预设文本： - + | 状态 | 预设消息示例 | | --- | --- | - | **调查中** | "我们正在调查影响 [服务名称] 的问题。" | - | **已确认** | "问题已被确认，团队正在积极处理。" | + | **排查中** | "我们正在调查影响 [服务名称] 的问题。" | + | **已定位** | "问题已被确认，团队正在积极处理。" | | **监控中** | "修复方案已实施，我们正在持续监控。" | - | **已解决** | "问题已解决，服务恢复正常运行。" | + | **已恢复** | "问题已解决，服务恢复正常运行。" | - + | 状态 | 预设消息示例 | | --- | --- | - | **已计划** | "计划维护将于 [时间] 开始。" | + | **已排期** | "计划维护将于 [时间] 开始。" | | **进行中** | "维护正在进行中，部分服务可能受到影响。" | | **已完成** | "维护已完成，所有服务恢复正常。" | @@ -79,16 +79,16 @@ description: "了解如何使用预定义模板和消息模板快速发布状态 ### 使用场景 -消息模板适用于需要标准化事件更新措辞的场景，确保不同团队成员在推进事件时使用一致的语言风格。 +状态描述模板适用于需要标准化事件更新措辞的场景，确保不同团队成员在推进事件时使用一致的语言风格。 -### 管理消息模板 +### 管理状态描述模板 - 在状态页设置的 **模板** 页签中，选择 **消息模板**，点击 **创建模板**，填写标题、类型和各状态对应的消息内容。 + 在状态页设置的 **事件模板** 页签中，选择 **状态描述**，点击 **创建模板**，填写标题、类型和各状态对应的消息内容。 - 在添加事件时间线更新时，选择一个消息模板。系统会根据当前的事件状态自动填充对应的消息文本。 + 在添加事件时间线更新时，选择一个状态描述模板。系统会根据当前的事件状态自动填充对应的消息文本。 你可以随时更新模板的标题、类型和消息内容，或删除不再使用的模板。 @@ -99,4 +99,4 @@ description: "了解如何使用预定义模板和消息模板快速发布状态 ## 模板偏好设置 -你可以在状态页设置中配置**默认模板类型**，发布事件时将优先展示对应类型的模板列表。此偏好设置不影响你切换到其他类型的模板。 +你可以在状态页设置的 **事件模板** 页签顶部选择默认模板类型（**状态描述** 或 **完整状态更新**），发布事件时将优先展示对应类型的模板列表。此偏好设置不影响你切换到其他类型的模板。 diff --git a/zh/openapi/api-catalog.mdx b/zh/openapi/api-catalog.mdx index 8b121c6d..d230b7b6 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 提供 **338** 个接口，覆盖 On-call、Monitors、RUM、AI SRE 和平台五个主要模块。所有接口使用统一认证方式和请求规范。详情参见[快速开始](/zh/openapi/introduction)。 +Flashduty Open API 提供 **335** 个接口，覆盖 On-call、Monitors、RUM、AI SRE 和平台五个主要模块。所有接口使用统一认证方式和请求规范。详情参见[快速开始](/zh/openapi/introduction)。 所有接口 URL 均以 `https://api.flashcat.cloud` 为 base，通过 query string 中的 APP Key 认证。 @@ -269,7 +269,7 @@ Flashduty Open API 提供 **338** 个接口，覆盖 On-call、Monitors、RUM、 - + ### 告警规则 @@ -285,7 +285,6 @@ Flashduty Open API 提供 **338** 个接口，覆盖 On-call、Monitors、RUM、 | POST | [`/monit/rule/import`](/zh/api-reference/monitors/alert-rules/monit-rule-write-import) | 导入告警规则 | | POST | [`/monit/rule/export`](/zh/api-reference/monitors/alert-rules/monit-rule-read-export) | 导出告警规则 | | POST | [`/monit/rule/move`](/zh/api-reference/monitors/alert-rules/monit-rule-write-move) | 移动告警规则到文件夹 | -| POST | [`/monit/rule/status`](/zh/api-reference/monitors/alert-rules/monit-rule-write-status) | 查看文件夹下规则触发状态 | | POST | [`/monit/rule/audits`](/zh/api-reference/monitors/alert-rules/monit-rule-read-audits) | 查询规则变更历史 | | POST | [`/monit/rule/audit/detail`](/zh/api-reference/monitors/alert-rules/monit-rule-read-audit-detail) | 查看规则审计快照 | | POST | [`/monit/rule/dstypes`](/zh/api-reference/monitors/alert-rules/monit-rule-read-dstypes) | 查询可用的数据源类型 | @@ -321,7 +320,6 @@ Flashduty Open API 提供 **338** 个接口，覆盖 On-call、Monitors、RUM、 | 方法 | 接口 | 描述 | | :--- | :--- | :--- | | POST | [`/monit/query/data`](/zh/api-reference/monitors/diagnostics/monit-read-query-data) | 查询结构化数据 | -| POST | [`/monit/query/rows`](/zh/api-reference/monitors/diagnostics/monit-read-query-rows) | 查询数据源原始行 | | POST | [`/monit/query/diagnose`](/zh/api-reference/monitors/diagnostics/monit-read-query-diagnose) | 数据源诊断 | | POST | [`/monit/tools/catalog`](/zh/api-reference/monitors/diagnostics/monit-read-tools-catalog) | 查询监控对象工具能力清单 | | POST | [`/monit/tools/invoke`](/zh/api-reference/monitors/diagnostics/monit-read-tools-invoke) | 调用监控对象工具 | @@ -331,7 +329,6 @@ Flashduty Open API 提供 **338** 个接口，覆盖 On-call、Monitors、RUM、 | 方法 | 接口 | 描述 | | :--- | :--- | :--- | -| POST | [`/monit/preview/sync`](/zh/api-reference/monitors/monitor-utilities/monit-preview-sync) | 同步预览数据源查询 | ### 服务拓扑 diff --git a/zh/platform/configure-sso.mdx b/zh/platform/configure-sso.mdx index 1c65fd15..7ce72e2a 100644 --- a/zh/platform/configure-sso.mdx +++ b/zh/platform/configure-sso.mdx @@ -42,7 +42,7 @@ Flashduty 支持 SAML2.0、OIDC、CAS 和 LDAP（仅私有化版本）协议的 | 稳定用户 ID 字段（`user_id`） | 可选。身份提供商返回的用户唯一标识属性，用于识别同一成员，邮箱或手机号变更不影响识别；留空时按下方邮箱/手机号字段匹配成员。建议值为 `employee_id`；填写 `name_id` 时取 SAML 断言中的 NameID（Subject）。详见下文 [成员关联方式](#成员关联方式) | | 登录即创建账号 | 默认开启，关闭后需要先邀请成员才可登录 | | 成员仅支持 SSO 登录（`force_sso`） | 默认开启。开启后，账户内所有成员仅能通过 SSO 登录，密码与验证码登录将被拒绝。详见下文 [强制 SSO 登录](#强制-sso-登录) | -| Flashduty 服务提供商信息 | **Service Provider Metadata** 和 **Assertion Consumer Service URL**（断言地址，用于身份提供商调用进行单点登录） | +| Flashcat 服务提供商信息 | **Service Provider Metadata** 和 **Assertion Consumer Service URL**（断言地址，用于身份提供商调用进行单点登录） | ## 配置 OIDC 协议 @@ -61,7 +61,7 @@ Flashduty 支持 SAML2.0、OIDC、CAS 和 LDAP（仅私有化版本）协议的 | 登录即创建账号 | 默认开启，关闭后需要先邀请成员才可登录 | | 成员仅支持 SSO 登录（`force_sso`） | 默认开启。开启后，账户内所有成员仅能通过 SSO 登录，密码与验证码登录将被拒绝。详见下文 [强制 SSO 登录](#强制-sso-登录) | | Scopes | 指定请求可访问的信息和功能权限，支持自定义。默认值为 `openid`、`profile`、`email`、`phone`，支持以标签形式添加自定义 Scope | -| Flashduty 服务提供商信息 | **Redirect URL**：身份提供商回调地址
**支持签名算法**：RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512（不支持 HS256） | +| Flashcat 服务提供商信息 | **Redirect URL**：身份提供商回调地址
**支持签名算法**：RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512（不支持 HS256） | Scopes 为必填字段。默认值 `openid`、`profile`、`email`、`phone` 是 OIDC 协议正常工作所需的基础权限。删除这些默认值可能导致单点登录失败或无法正确获取用户信息。如需添加自定义 Scope，建议在保留默认值的基础上追加。 @@ -83,7 +83,7 @@ Scopes 为必填字段。默认值 `openid`、`profile`、`email`、`phone` 是 | 稳定用户 ID 字段（`user_id`） | 可选。用于识别同一成员的用户唯一标识，邮箱或手机号变更不影响识别；留空时按下方邮箱/手机号字段匹配成员。建议值为 `principal`（即 CAS 认证用户名），也可配置为 CAS 返回的某个属性。详见下文 [成员关联方式](#成员关联方式) | | 登录即创建账号 | 默认开启，关闭后需要先邀请成员才可登录 | | 成员仅支持 SSO 登录（`force_sso`） | 默认开启。开启后，账户内所有成员仅能通过 SSO 登录，密码与验证码登录将被拒绝。详见下文 [强制 SSO 登录](#强制-sso-登录) | -| Flashduty 服务提供商信息 | **Redirect URL**：身份提供商回调地址 | +| Flashcat 服务提供商信息 | **Redirect URL**：身份提供商回调地址 | ## 配置 LDAP 协议 @@ -115,7 +115,7 @@ LDAP 单点登录仅**私有化版本**支持。 ### LDAP 连接检测 -配置 LDAP 连接信息后，你可以点击设置抽屉底部的 **连接检测** 按钮，验证 Flashduty 能否成功连接到你的 LDAP 服务器。系统会使用当前填写的 LDAP 链接、BIND DN 和密码尝试建立连接，并返回连接成功或失败的结果。 +配置 LDAP 连接信息后，你可以在 **协议与连接** 分区的 LDAP 表单下方点击 **连接检测**，验证 Flashduty 能否成功连接到你的 LDAP 服务器。系统会使用当前填写的 LDAP 链接、BIND DN 和密码尝试建立连接，并返回连接成功或失败的结果。 建议在保存配置前先执行连接检测，确保连接参数正确无误，避免因配置错误导致成员无法通过 LDAP 登录。 @@ -181,7 +181,7 @@ LDAP 单点登录仅**私有化版本**支持。 | 项 | 行为 | | --- | --- | | 字段名 | `force_sso` | -| 默认值 | **开启**——首次配置 SSO 时，设置抽屉中的该开关预置为开启状态 | +| 默认值 | **开启**——首次配置 SSO 时，单点登录设置页中的该开关预置为开启状态 | | 开启后 | 该账户的所有成员只能通过 SSO 登录，密码登录和验证码登录均会被服务端拒绝 | | 关闭后 | 允许成员同时使用 SSO 登录、密码登录与验证码登录 | | 例外 | **无**。账户主体（Owner）与超级管理员也受该限制约束，不存在豁免分支 |