From 2c00f27061bd95ceaf4cdb3ef6b9b56321395e6b Mon Sep 17 00:00:00 2001 From: ysyneu Date: Thu, 22 Oct 2026 23:30:41 -0700 Subject: [PATCH] docs(api): document POST /channel/escalate/rule/reorder for reordering channel escalation rules --- api-reference/on-call.openapi.en.json | 95 +++++++++++++++++++++++++++ api-reference/on-call.openapi.zh.json | 95 +++++++++++++++++++++++++++ api-reference/openapi.en.json | 95 +++++++++++++++++++++++++++ api-reference/openapi.zh.json | 95 +++++++++++++++++++++++++++ docs.json | 6 +- en/openapi/api-catalog.mdx | 1 + zh/openapi/api-catalog.mdx | 1 + 7 files changed, 386 insertions(+), 2 deletions(-) diff --git a/api-reference/on-call.openapi.en.json b/api-reference/on-call.openapi.en.json index 6d2dbb96..e03c5073 100644 --- a/api-reference/on-call.openapi.en.json +++ b/api-reference/on-call.openapi.en.json @@ -71,6 +71,76 @@ } ], "paths": { + "/channel/escalate/rule/reorder": { + "post": { + "operationId": "channelEscalateRuleReorder", + "summary": "Reorder escalation rules", + "description": "Change the evaluation order of a channel's escalation rules by moving one rule into another rule's slot.", + "tags": [ + "On-call/Channels" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Rules are evaluated in ascending `priority`: the first enabled rule whose `time_filters` and `filters` match a new incident takes it, and later rules are skipped. This endpoint moves `drag_rule_id` into `target_rule_id`'s slot and renumbers the channel's rules from priority 0, changing that evaluation order.\n- Both `drag_rule_id` and `target_rule_id` must be rules of `channel_id`; otherwise `InvalidParameter`.\n- An unknown `channel_id` returns `InvalidParameter`.\n- Concurrent reorders of the same channel are rejected with `TooManyRequests`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.", + "href": "/en/api-reference/on-call/channels/channel-escalate-rule-reorder", + "metadata": { + "sidebarTitle": "Reorder escalation rules" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": {} + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReorderEscalationRulesRequest" + } + } + } + } + } + }, "/channel/inhibit/rule/delete": { "post": { "operationId": "channelInhibitRuleDelete", @@ -28354,6 +28424,31 @@ } } }, + "ReorderEscalationRulesRequest": { + "type": "object", + "required": [ + "channel_id", + "drag_rule_id", + "target_rule_id" + ], + "properties": { + "channel_id": { + "type": "integer", + "format": "int64", + "description": "Owning channel ID; obtain it from `POST /channel/list`." + }, + "drag_rule_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "ID of the rule being dragged (24-character hex), as returned in `rule_id` by the create or list endpoint." + }, + "target_rule_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "ID of the rule whose slot the dragged rule moves into (24-character hex)." + } + } + }, "ResetIncidentFieldRequest": { "type": "object", "description": "Parameters for updating a custom field value on an incident.", diff --git a/api-reference/on-call.openapi.zh.json b/api-reference/on-call.openapi.zh.json index 77d2e8c7..f8772dc7 100644 --- a/api-reference/on-call.openapi.zh.json +++ b/api-reference/on-call.openapi.zh.json @@ -71,6 +71,76 @@ } ], "paths": { + "/channel/escalate/rule/reorder": { + "post": { + "operationId": "channelEscalateRuleReorder", + "summary": "调整分派策略顺序", + "description": "通过将一条策略移动到另一条策略的位置，改变协作空间内分派策略的评估顺序。", + "tags": [ + "On-call/Channels" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 策略按 `priority` 升序评估：新故障由第一条满足 `time_filters` 和 `filters` 的启用中策略承接，后面的策略跳过。本接口将 `drag_rule_id` 移动到 `target_rule_id` 所在位置，并将协作空间内的策略从 0 开始重新编号，从而改变评估顺序。\n- `drag_rule_id` 和 `target_rule_id` 必须都属于 `channel_id`，否则返回 `InvalidParameter`。\n- `channel_id` 不存在时返回 `InvalidParameter`。\n- 同一协作空间的并发排序请求会被拒绝，返回 `TooManyRequests`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。", + "href": "/zh/api-reference/on-call/channels/channel-escalate-rule-reorder", + "metadata": { + "sidebarTitle": "调整分派策略顺序" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": {} + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReorderEscalationRulesRequest" + } + } + } + } + } + }, "/channel/inhibit/rule/delete": { "post": { "operationId": "channelInhibitRuleDelete", @@ -28354,6 +28424,31 @@ } } }, + "ReorderEscalationRulesRequest": { + "type": "object", + "required": [ + "channel_id", + "drag_rule_id", + "target_rule_id" + ], + "properties": { + "channel_id": { + "type": "integer", + "format": "int64", + "description": "所属协作空间 ID，可通过 `POST /channel/list` 获取。" + }, + "drag_rule_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "被拖拽移动的策略 ID（24 位十六进制），即策略创建或列表接口返回的 `rule_id`。" + }, + "target_rule_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "目标位置的策略 ID（24 位十六进制），被拖拽的策略移动到该策略所在的位置。" + } + } + }, "ResetIncidentFieldRequest": { "type": "object", "description": "更新故障自定义字段值的参数。", diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json index edddbcd4..82d5ccd5 100644 --- a/api-reference/openapi.en.json +++ b/api-reference/openapi.en.json @@ -7897,6 +7897,31 @@ }, "description": "loki.query parameters. `expr` is LogQL. `execution.kind` must be `instant` or `range`; `instant` keeps the full time context so `$__auto` ranges resolve. `limit` and `direction` only apply to raw-log results." }, + "ReorderEscalationRulesRequest": { + "type": "object", + "required": [ + "channel_id", + "drag_rule_id", + "target_rule_id" + ], + "properties": { + "channel_id": { + "type": "integer", + "format": "int64", + "description": "Owning channel ID; obtain it from `POST /channel/list`." + }, + "drag_rule_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "ID of the rule being dragged (24-character hex), as returned in `rule_id` by the create or list endpoint." + }, + "target_rule_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "ID of the rule whose slot the dragged rule moves into (24-character hex)." + } + } + }, "VictoriaLogsQueryParams": { "type": "object", "additionalProperties": true, @@ -39855,6 +39880,76 @@ } } }, + "/channel/escalate/rule/reorder": { + "post": { + "operationId": "channelEscalateRuleReorder", + "summary": "Reorder escalation rules", + "description": "Change the evaluation order of a channel's escalation rules by moving one rule into another rule's slot.", + "tags": [ + "On-call/Channels" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Rules are evaluated in ascending `priority`: the first enabled rule whose `time_filters` and `filters` match a new incident takes it, and later rules are skipped. This endpoint moves `drag_rule_id` into `target_rule_id`'s slot and renumbers the channel's rules from priority 0, changing that evaluation order.\n- Both `drag_rule_id` and `target_rule_id` must be rules of `channel_id`; otherwise `InvalidParameter`.\n- An unknown `channel_id` returns `InvalidParameter`.\n- Concurrent reorders of the same channel are rejected with `TooManyRequests`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.", + "href": "/en/api-reference/on-call/channels/channel-escalate-rule-reorder", + "metadata": { + "sidebarTitle": "Reorder escalation rules" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": {} + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReorderEscalationRulesRequest" + } + } + } + } + } + }, "/channel/escalate/rule/update": { "post": { "operationId": "channelEscalateRuleUpdate", diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json index 5e85fda4..72408b41 100644 --- a/api-reference/openapi.zh.json +++ b/api-reference/openapi.zh.json @@ -7897,6 +7897,31 @@ }, "description": "loki.query 参数。`expr` 为 LogQL。`execution.kind` 取 `instant` 或 `range`；`instant` 保留完整时间上下文以便 `$__auto` 范围解析。`limit` 和 `direction` 只作用于原始日志结果。" }, + "ReorderEscalationRulesRequest": { + "type": "object", + "required": [ + "channel_id", + "drag_rule_id", + "target_rule_id" + ], + "properties": { + "channel_id": { + "type": "integer", + "format": "int64", + "description": "所属协作空间 ID，可通过 `POST /channel/list` 获取。" + }, + "drag_rule_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "被拖拽移动的策略 ID（24 位十六进制），即策略创建或列表接口返回的 `rule_id`。" + }, + "target_rule_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "目标位置的策略 ID（24 位十六进制），被拖拽的策略移动到该策略所在的位置。" + } + } + }, "VictoriaLogsQueryParams": { "type": "object", "additionalProperties": true, @@ -39855,6 +39880,76 @@ } } }, + "/channel/escalate/rule/reorder": { + "post": { + "operationId": "channelEscalateRuleReorder", + "summary": "调整分派策略顺序", + "description": "通过将一条策略移动到另一条策略的位置，改变协作空间内分派策略的评估顺序。", + "tags": [ + "On-call/Channels" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 策略按 `priority` 升序评估：新故障由第一条满足 `time_filters` 和 `filters` 的启用中策略承接，后面的策略跳过。本接口将 `drag_rule_id` 移动到 `target_rule_id` 所在位置，并将协作空间内的策略从 0 开始重新编号，从而改变评估顺序。\n- `drag_rule_id` 和 `target_rule_id` 必须都属于 `channel_id`，否则返回 `InvalidParameter`。\n- `channel_id` 不存在时返回 `InvalidParameter`。\n- 同一协作空间的并发排序请求会被拒绝，返回 `TooManyRequests`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。", + "href": "/zh/api-reference/on-call/channels/channel-escalate-rule-reorder", + "metadata": { + "sidebarTitle": "调整分派策略顺序" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": {} + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReorderEscalationRulesRequest" + } + } + } + } + } + }, "/channel/escalate/rule/update": { "post": { "operationId": "channelEscalateRuleUpdate", diff --git a/docs.json b/docs.json index 288900ae..6fa4dc9f 100644 --- a/docs.json +++ b/docs.json @@ -4103,7 +4103,8 @@ "POST /channel/escalate/rule/update", "POST /channel/escalate/rule/delete", "POST /channel/escalate/rule/enable", - "POST /channel/escalate/rule/disable" + "POST /channel/escalate/rule/disable", + "POST /channel/escalate/rule/reorder" ] }, { @@ -5880,7 +5881,8 @@ "POST /channel/escalate/rule/update", "POST /channel/escalate/rule/delete", "POST /channel/escalate/rule/enable", - "POST /channel/escalate/rule/disable" + "POST /channel/escalate/rule/disable", + "POST /channel/escalate/rule/reorder" ] }, { diff --git a/en/openapi/api-catalog.mdx b/en/openapi/api-catalog.mdx index 87ff14de..bd5c061d 100644 --- a/en/openapi/api-catalog.mdx +++ b/en/openapi/api-catalog.mdx @@ -108,6 +108,7 @@ All endpoint URLs use `https://api.flashcat.cloud` as the base, authenticated th | POST | [`/channel/escalate/rule/delete`](/en/api-reference/on-call/channels/channel-escalate-rule-delete) | Delete escalation rule | | POST | [`/channel/escalate/rule/enable`](/en/api-reference/on-call/channels/channel-escalate-rule-enable) | Enable escalation rule | | POST | [`/channel/escalate/rule/disable`](/en/api-reference/on-call/channels/channel-escalate-rule-disable) | Disable escalation rule | +| POST | [`/channel/escalate/rule/reorder`](/en/api-reference/on-call/channels/channel-escalate-rule-reorder) | Reorder escalation rules | | POST | [`/route/info`](/en/api-reference/on-call/channels/route-info) | Get routing rule detail | | POST | [`/route/list`](/en/api-reference/on-call/channels/route-list) | List routing rules | | POST | [`/route/upsert`](/en/api-reference/on-call/channels/route-upsert) | Upsert routing rule | diff --git a/zh/openapi/api-catalog.mdx b/zh/openapi/api-catalog.mdx index 923aebf8..7b21b448 100644 --- a/zh/openapi/api-catalog.mdx +++ b/zh/openapi/api-catalog.mdx @@ -108,6 +108,7 @@ Flashduty Open API 提供 **383** 个接口，覆盖 On-call、Monitors、RUM、 | POST | [`/channel/escalate/rule/delete`](/zh/api-reference/on-call/channels/channel-escalate-rule-delete) | 删除分派策略 | | POST | [`/channel/escalate/rule/enable`](/zh/api-reference/on-call/channels/channel-escalate-rule-enable) | 启用分派策略 | | POST | [`/channel/escalate/rule/disable`](/zh/api-reference/on-call/channels/channel-escalate-rule-disable) | 禁用分派策略 | +| POST | [`/channel/escalate/rule/reorder`](/zh/api-reference/on-call/channels/channel-escalate-rule-reorder) | 调整分派策略顺序 | | POST | [`/route/info`](/zh/api-reference/on-call/channels/route-info) | 获取路由规则详情 | | POST | [`/route/list`](/zh/api-reference/on-call/channels/route-list) | 查询路由规则列表 | | POST | [`/route/upsert`](/zh/api-reference/on-call/channels/route-upsert) | 创建或更新路由规则 |