From dff8e8d50600d7e838529350fed74868eb570736 Mon Sep 17 00:00:00 2001 From: Flashduty AI-SRE Date: Fri, 23 Oct 2026 08:11:08 +0000 Subject: [PATCH] =?UTF-8?q?docs(api-reference):=20daily=20api-review=20202?= =?UTF-8?q?6-10-23=20=E2=80=94=20incident=20labels,=20invite=20schedule=5F?= =?UTF-8?q?id,=20reorder=20example?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Baseline docs main fb164406 (2026-10-23T06:31:16Z); public surface re-verified against fc-pgy registry (385 auth=all rows, non /event/push/) and every implementation repo at origin/main. - on-call: POST /incident/create accepts `labels` (fc-event c85709d1f). - platform: POST /member/invite accepts `schedule_id` (fc-pgy f91ce88b). - on-call: POST /channel/escalate/rule/reorder gained the request example the lint gate requires; the operation became public in fc-pgy 67e776e8 (Auth jwt -> all). - docs.json: regenerate the bare-path redirect for /channel/escalate/rule/reorder, which was left stale when the page was added in #1126 (scripts/api_path_redirects.py --check failed on main before this commit). No operations added or removed (384 documented = 385 public rows minus the unresolved POST /channel/incident/daily-counts). --- api-reference/on-call.openapi.en.json | 18 ++++++++++++++++++ api-reference/on-call.openapi.zh.json | 18 ++++++++++++++++++ api-reference/openapi.en.json | 26 +++++++++++++++++++++++++- api-reference/openapi.zh.json | 26 +++++++++++++++++++++++++- api-reference/platform.openapi.en.json | 8 +++++++- api-reference/platform.openapi.zh.json | 8 +++++++- docs.json | 4 ++++ 7 files changed, 104 insertions(+), 4 deletions(-) diff --git a/api-reference/on-call.openapi.en.json b/api-reference/on-call.openapi.en.json index e03c5073..7a635b4a 100644 --- a/api-reference/on-call.openapi.en.json +++ b/api-reference/on-call.openapi.en.json @@ -135,6 +135,11 @@ "application/json": { "schema": { "$ref": "#/components/schemas/ReorderEscalationRulesRequest" + }, + "example": { + "channel_id": 1001, + "drag_rule_id": "6621b23f4a2c5e0012ab34d9", + "target_rule_id": "6621b23f4a2c5e0012ab34d0" } } } @@ -14616,6 +14621,11 @@ "person_ids": [ 2476444212131 ] + }, + "labels": { + "env": "production", + "service": "order-api", + "region": "cn-hangzhou" } } }, @@ -22469,6 +22479,14 @@ "fields": { "$ref": "#/components/schemas/CustomFieldValues", "description": "Custom field values keyed by field name. When a create form applies, only its visible fields are accepted." + }, + "labels": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "maxProperties": 50, + "description": "Labels to store on the created incident, up to 50 entries. Blank values are dropped, keys are normalized to `[a-zA-Z_][a-zA-Z0-9_]*` (other characters become `_`), and values are trimmed and truncated at 8 KiB." } } }, diff --git a/api-reference/on-call.openapi.zh.json b/api-reference/on-call.openapi.zh.json index f8772dc7..e28c866b 100644 --- a/api-reference/on-call.openapi.zh.json +++ b/api-reference/on-call.openapi.zh.json @@ -135,6 +135,11 @@ "application/json": { "schema": { "$ref": "#/components/schemas/ReorderEscalationRulesRequest" + }, + "example": { + "channel_id": 1001, + "drag_rule_id": "6621b23f4a2c5e0012ab34d9", + "target_rule_id": "6621b23f4a2c5e0012ab34d0" } } } @@ -14616,6 +14621,11 @@ "person_ids": [ 2476444212131 ] + }, + "labels": { + "env": "production", + "service": "order-api", + "region": "cn-hangzhou" } } }, @@ -22469,6 +22479,14 @@ "fields": { "$ref": "#/components/schemas/CustomFieldValues", "description": "以字段名为键的自定义字段值。创建表单生效时，只接受表单中可见的字段。" + }, + "labels": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "maxProperties": 50, + "description": "新建故障时写入的标签，最多 50 个。空值会被丢弃，key 会规范化为 `[a-zA-Z_][a-zA-Z0-9_]*`（其它字符替换为 `_`），value 会去掉首尾空白并截断到 8 KiB。" } } }, diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json index 82d5ccd5..bf4b338b 100644 --- a/api-reference/openapi.en.json +++ b/api-reference/openapi.en.json @@ -5965,6 +5965,14 @@ "fields": { "$ref": "#/components/schemas/CustomFieldValues", "description": "Custom field values keyed by field name. When a create form applies, only its visible fields are accepted." + }, + "labels": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "maxProperties": 50, + "description": "Labels to store on the created incident, up to 50 entries. Blank values are dropped, keys are normalized to `[a-zA-Z_][a-zA-Z0-9_]*` (other characters become `_`), and values are trimmed and truncated at 8 KiB." } } }, @@ -13220,6 +13228,11 @@ "ref_id": { "type": "string", "description": "External reference ID (for example an employee ID in an HR system), usable later as a lookup key in `POST /member/delete` and `POST /member/info/reset`." + }, + "schedule_id": { + "type": "integer", + "format": "uint64", + "description": "Schedule to add the member to once the invitation is accepted. The join runs as the caller, so they must be allowed to edit that schedule; a schedule that was deleted or has no joinable layer is skipped. Omit it to invite without a schedule." } } }, @@ -39944,6 +39957,11 @@ "application/json": { "schema": { "$ref": "#/components/schemas/ReorderEscalationRulesRequest" + }, + "example": { + "channel_id": 1001, + "drag_rule_id": "6621b23f4a2c5e0012ab34d9", + "target_rule_id": "6621b23f4a2c5e0012ab34d0" } } } @@ -44993,6 +45011,11 @@ "person_ids": [ 2476444212131 ] + }, + "labels": { + "env": "production", + "service": "order-api", + "region": "cn-hangzhou" } } }, @@ -50503,7 +50526,8 @@ "time_zone": "Asia/Shanghai", "role_ids": [ 6 - ] + ], + "schedule_id": 5789640530410 }, { "member_name": "Dave", diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json index 72408b41..4aca4055 100644 --- a/api-reference/openapi.zh.json +++ b/api-reference/openapi.zh.json @@ -5965,6 +5965,14 @@ "fields": { "$ref": "#/components/schemas/CustomFieldValues", "description": "以字段名为键的自定义字段值。创建表单生效时，只接受表单中可见的字段。" + }, + "labels": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "maxProperties": 50, + "description": "新建故障时写入的标签，最多 50 个。空值会被丢弃，key 会规范化为 `[a-zA-Z_][a-zA-Z0-9_]*`（其它字符替换为 `_`），value 会去掉首尾空白并截断到 8 KiB。" } } }, @@ -13220,6 +13228,11 @@ "ref_id": { "type": "string", "description": "外部引用 ID（如 HR 系统中的员工号），之后可在 `POST /member/delete`、`POST /member/info/reset` 中作为查找键。" + }, + "schedule_id": { + "type": "integer", + "format": "uint64", + "description": "接受邀请后要把该成员加入的值班排班 ID。加入动作以调用方身份执行，因此调用方必须有权编辑该排班；排班已被删除或没有可加入的层级时会跳过。不传表示邀请不带排班。" } } }, @@ -39944,6 +39957,11 @@ "application/json": { "schema": { "$ref": "#/components/schemas/ReorderEscalationRulesRequest" + }, + "example": { + "channel_id": 1001, + "drag_rule_id": "6621b23f4a2c5e0012ab34d9", + "target_rule_id": "6621b23f4a2c5e0012ab34d0" } } } @@ -44993,6 +45011,11 @@ "person_ids": [ 2476444212131 ] + }, + "labels": { + "env": "production", + "service": "order-api", + "region": "cn-hangzhou" } } }, @@ -50503,7 +50526,8 @@ "time_zone": "Asia/Shanghai", "role_ids": [ 6 - ] + ], + "schedule_id": 5789640530410 }, { "member_name": "Dave", diff --git a/api-reference/platform.openapi.en.json b/api-reference/platform.openapi.en.json index 50882774..0f8cc239 100644 --- a/api-reference/platform.openapi.en.json +++ b/api-reference/platform.openapi.en.json @@ -1001,7 +1001,8 @@ "time_zone": "Asia/Shanghai", "role_ids": [ 6 - ] + ], + "schedule_id": 5789640530410 }, { "member_name": "Dave", @@ -3023,6 +3024,11 @@ "ref_id": { "type": "string", "description": "External reference ID (for example an employee ID in an HR system), usable later as a lookup key in `POST /member/delete` and `POST /member/info/reset`." + }, + "schedule_id": { + "type": "integer", + "format": "uint64", + "description": "Schedule to add the member to once the invitation is accepted. The join runs as the caller, so they must be allowed to edit that schedule; a schedule that was deleted or has no joinable layer is skipped. Omit it to invite without a schedule." } } }, diff --git a/api-reference/platform.openapi.zh.json b/api-reference/platform.openapi.zh.json index f85e4b88..ae546a7a 100644 --- a/api-reference/platform.openapi.zh.json +++ b/api-reference/platform.openapi.zh.json @@ -1001,7 +1001,8 @@ "time_zone": "Asia/Shanghai", "role_ids": [ 6 - ] + ], + "schedule_id": 5789640530410 }, { "member_name": "Dave", @@ -3023,6 +3024,11 @@ "ref_id": { "type": "string", "description": "外部引用 ID（如 HR 系统中的员工号），之后可在 `POST /member/delete`、`POST /member/info/reset` 中作为查找键。" + }, + "schedule_id": { + "type": "integer", + "format": "uint64", + "description": "接受邀请后要把该成员加入的值班排班 ID。加入动作以调用方身份执行，因此调用方必须有权编辑该排班；排班已被删除或没有可加入的层级时会跳过。不传表示邀请不带排班。" } } }, diff --git a/docs.json b/docs.json index 6fa4dc9f..a77690c3 100644 --- a/docs.json +++ b/docs.json @@ -1639,6 +1639,10 @@ "source": "/channel/escalate/rule/list", "destination": "/zh/api-reference/on-call/channels/channel-escalate-rule-list" }, + { + "source": "/channel/escalate/rule/reorder", + "destination": "/zh/api-reference/on-call/channels/channel-escalate-rule-reorder" + }, { "source": "/channel/escalate/rule/update", "destination": "/zh/api-reference/on-call/channels/channel-escalate-rule-update"