> ## Documentation Index > Fetch the complete documentation index at: https://test-8ad8522e-feat-ai-sre.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 获取故障时间线 > 获取指定故障的时间线动态，包括状态变更、评论和系统事件。 ## 限制说明 | 项目 | 说明 | | ---- | ------------------------------ | | 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** | | 权限要求 | **故障查看**（`on-call`） | ## 使用说明 * 对于 `i_comm` 条目，`detail.comment_type` 在读取时根据当前账户级评论类型定义解析，因此始终反映类型的最新名称和颜色。 ## OpenAPI ````yaml /api-reference/on-call.openapi.zh.json post /incident/feed openapi: 3.1.0 info: title: Flashduty 开放 API description: >- Flashduty 事件管理平台的公开 HTTP API —— 覆盖故障、通知模板、协作空间、值班排班、监控、RUM、以及平台管理。每次调用都需在 query 中携带 `app_key`，该 key 在 Flashduty 控制台 账户 → APP Key 中签发。所有响应使用统一结构：成功时为 `{ request_id, data }`，失败时为 `{ request_id, error }`。 version: 1.0.0 servers: - url: https://api.flashcat.cloud description: Flashduty Open API security: - AppKeyAuth: [] tags: - name: On-call/故障管理 description: '' - name: On-call/协作空间 description: '' - name: On-call/告警管理 description: 查询、查看和处理告警，管理卡片视图与告警处理规则。 - name: On-call/集成中心 description: '' - name: On-call/IM 集成 description: IM 集成相关查询，例如查看哪些集成开启了作战室。 - name: On-call/值班排班 description: '' - name: On-call/许可管理 description: '' - name: On-call/日历管理 description: '' - name: On-call/通知模板 description: '' - name: On-call/标签增强 description: 自定义字段、富化规则及数据映射（映射规则、映射数据、映射 API）管理。 - name: On-call/分析看板 description: '' - name: On-call/状态页 description: '' - name: On-call/变更管理 description: '' paths: /incident/feed: post: tags: - On-call/故障管理 summary: 获取故障时间线 description: 获取指定故障的时间线动态，包括状态变更、评论和系统事件。 operationId: incidentFeed requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ListIncidentFeedRequest' example: incident_id: 69da451ef77b1b51f40e83ee p: 1 limit: 20 responses: '200': description: 成功 content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: $ref: '#/components/schemas/ListIncidentFeedResponse' example: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 data: has_next_page: true items: - ref_id: 6a5f1e28807515413b384bce type: i_wi_created detail: work_item_id: wi_68MHnkWBiyjrh6uhkxUyiZ item_type: follow_up title: 'Follow-up: schedule database failover drill' status: open assignee_ids: - 3790925372131 - 4756301322131 post_mortem_id: 51d65cd9525c369379ba471b5512df63 account_id: 2451002751131 creator_id: 5329873302131 created_at: 1785495329402 updated_at: 1785495329402 - ref_id: 6a5f1e28807515413b384bce type: i_comm detail: comment: >- Root cause identified: connection pool exhaustion on the primary database. comment_type_id: 6a5895d672a064bc2d3ddfc2 comment_type: id: 6a5895d672a064bc2d3ddfc2 name: Key finding color: '#30A46C' account_id: 2451002751131 creator_id: 3790925372131 created_at: 1785496333926 updated_at: 1785496333926 - ref_id: 6a5f1e28807515413b384bce type: i_wi_completed detail: work_item_id: wi_68MHnkWBiyjrh6uhkxUyiZ item_type: follow_up title: 'Follow-up: schedule database failover drill' from_status: open to_status: done post_mortem_id: 51d65cd9525c369379ba471b5512df63 account_id: 2451002751131 creator_id: 3790925372131 created_at: 1785496384806 updated_at: 1785496384806 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/ServerError' components: schemas: ListIncidentFeedRequest: type: object description: 获取故障时间线的参数。 required: - incident_id properties: incident_id: type: string pattern: ^[0-9a-fA-F]{24}$ description: 故障 ID（MongoDB ObjectID）。 p: type: integer format: int64 minimum: 1 description: 页码，从 1 开始。 limit: type: integer format: int64 minimum: 1 maximum: 100 default: 20 description: 分页大小，最大 100。 asc: type: boolean description: true 为按时间升序。 types: type: array items: $ref: '#/components/schemas/IncidentFeedType' description: 可选类型过滤，仅返回指定类型的时间线条目。 SuccessEnvelope: type: object description: >- 成功响应结构。2xx 响应中 `request_id` 标识本次调用（同时出现在 `Flashcat-Request-Id` 响应头中），`data` 为接口业务 payload。失败响应使用不同结构，参见 `ErrorResponse`。 properties: request_id: type: string description: 本次请求的唯一 ID，也会在 Flashcat-Request-Id 响应头中返回。反馈问题时请一并附上。 example: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 data: description: 每个接口自己的业务 payload，详见各接口的 200 响应 schema。 required: - request_id - data ListIncidentFeedResponse: type: object description: 故障时间线分页结果。 required: - has_next_page - items properties: has_next_page: type: boolean description: 是否还有更多条目。 items: type: array items: $ref: '#/components/schemas/IncidentFeedItem' description: 当前页的时间线条目。 IncidentFeedType: type: string description: >- 故障时间线条目类型。每个值对应一个生命周期事件，其 `detail` 载荷结构由该字段决定。故障级事件前缀为 `i_`；向上冒泡到故障时间线的告警级事件前缀为 `a_`。 | 类型 | 含义 | |---|---| | `i_new` | 故障创建：系统自动或人工创建了新故障。 | | `i_assign` | 分派响应人：故障被分派给指定人员处理。 | | `i_a_rspd` | 添加响应人：有新的响应人被加入处理。 | | `i_notify` | 通过某个渠道在指定环节发送通知。 | | `i_storm` | 故障触发告警风暴阈值。 | | `i_snooze` | 暂停通知指定时长。 | | `i_wake` | 取消暂停并恢复通知。 | | `i_ack` | 确认故障：响应人确认已开始处理故障。 | | `i_unack` | 取消认领。 | | `i_comm` | 添加评论：响应人记录了处理进展或关键信息。 | | `i_rslv` | 解决故障：故障被标记为已解决。 | | `i_reopen` | 重新打开：已解决的故障被重新打开，可能问题复发。 | | `i_merge` | 合并故障：多个相关故障被合并为一个。 | | `i_r_title` | 标题更新。 | | `i_r_desc` | 描述更新。 | | `i_r_impact` | 影响范围更新。 | | `i_r_rc` | 根因更新。 | | `i_r_rsltn` | 解决方案更新。 | | `i_r_severity` | 严重等级变更：故障的严重程度被调整。 | | `i_r_field` | 自定义字段值更新。 | | `i_m_flapping` | 因抖动检测被静默。 | | `i_m_reply` | 评论静音回复标记。 | | `i_custom` | 执行动作：触发了自动化操作或脚本。 | | `i_wr_create` | 创建作战室：建立了即时通讯群组用于协作处理。 | | `i_wr_delete` | 删除作战室群组。 | | `i_auto_refresh` | 卡片自动刷新事件。 | | `i_wi_created` | 跟进事项创建：创建了行动项或后续行动。 | | `i_wi_updated` | 跟进事项更新：标题、描述、状态或优先级发生变化。 | | `i_wi_assignees` | 跟进事项负责人变更：负责人被更新。 | | `i_wi_completed` | 跟进事项完成：负责人将跟进事项标记为完成。 | | `i_wi_converted` | 跟进事项转化：行动项被转化为后续行动。 | | `i_wi_bound` | 跟进事项绑定：已转化的后续行动被绑定到故障复盘。 | | `i_wi_deleted` | 跟进事项删除：行动项或后续行动被软删除。 | | `a_merge` | 告警合并：一条告警被合并进已有故障。 | enum: - i_new - i_assign - i_a_rspd - i_notify - i_storm - i_snooze - i_wake - i_ack - i_unack - i_comm - i_rslv - i_reopen - i_merge - i_r_title - i_r_desc - i_r_impact - i_r_rc - i_r_rsltn - i_r_severity - i_r_field - i_m_flapping - i_m_reply - i_custom - i_wr_create - i_wr_delete - i_auto_refresh - i_wi_created - i_wi_updated - i_wi_assignees - i_wi_completed - i_wi_converted - i_wi_bound - i_wi_deleted - a_merge IncidentFeedItem: type: object description: 单条故障时间线条目。`detail` 字段由 `type` 决定具体结构，详见各 `FeedDetail*` 结构。 required: - ref_id - type - detail - account_id - creator_id - created_at - updated_at properties: ref_id: type: string pattern: ^[0-9a-fA-F]{24}$ description: 引用对象 ObjectID，根据 type 不同可能指向故障或告警。 type: $ref: '#/components/schemas/IncidentFeedType' detail: description: 由 `type` 决定的具体载荷；条目无结构化详情时为 `null`。 oneOf: - $ref: '#/components/schemas/FeedDetailIncidentNew' - $ref: '#/components/schemas/FeedDetailIncidentAssign' - $ref: '#/components/schemas/FeedDetailIncidentAddRspd' - $ref: '#/components/schemas/FeedDetailIncidentNotify' - $ref: '#/components/schemas/FeedDetailIncidentStorm' - $ref: '#/components/schemas/FeedDetailIncidentSnooze' - $ref: '#/components/schemas/FeedDetailIncidentWake' - $ref: '#/components/schemas/FeedDetailIncidentAck' - $ref: '#/components/schemas/FeedDetailIncidentUnack' - $ref: '#/components/schemas/FeedDetailIncidentComment' - $ref: '#/components/schemas/FeedDetailIncidentResolve' - $ref: '#/components/schemas/FeedDetailIncidentReopen' - $ref: '#/components/schemas/FeedDetailIncidentMerge' - $ref: '#/components/schemas/FeedDetailIncidentResetTitle' - $ref: '#/components/schemas/FeedDetailIncidentResetDescription' - $ref: '#/components/schemas/FeedDetailIncidentResetImpact' - $ref: '#/components/schemas/FeedDetailIncidentResetRootCause' - $ref: '#/components/schemas/FeedDetailIncidentResetResolution' - $ref: '#/components/schemas/FeedDetailIncidentResetSeverity' - $ref: '#/components/schemas/FeedDetailIncidentResetField' - $ref: '#/components/schemas/FeedDetailIncidentMuteByFlapping' - $ref: '#/components/schemas/FeedDetailIncidentMuteReply' - $ref: '#/components/schemas/FeedDetailIncidentCustomAction' - $ref: '#/components/schemas/FeedDetailIncidentWarRoomCreate' - $ref: '#/components/schemas/FeedDetailIncidentWarRoomDelete' - $ref: '#/components/schemas/FeedDetailIncidentAutoRefreshCard' - $ref: '#/components/schemas/FeedDetailWorkItemCreated' - $ref: '#/components/schemas/FeedDetailWorkItemUpdated' - $ref: '#/components/schemas/FeedDetailWorkItemAssigneesChanged' - $ref: '#/components/schemas/FeedDetailWorkItemCompleted' - $ref: '#/components/schemas/FeedDetailWorkItemConverted' - $ref: '#/components/schemas/FeedDetailWorkItemBound' - $ref: '#/components/schemas/FeedDetailWorkItemDeleted' - $ref: '#/components/schemas/FeedDetailAlertMerge' discriminator: propertyName: type mapping: i_new: $ref: '#/components/schemas/FeedDetailIncidentNew' i_assign: $ref: '#/components/schemas/FeedDetailIncidentAssign' i_a_rspd: $ref: '#/components/schemas/FeedDetailIncidentAddRspd' i_notify: $ref: '#/components/schemas/FeedDetailIncidentNotify' i_storm: $ref: '#/components/schemas/FeedDetailIncidentStorm' i_snooze: $ref: '#/components/schemas/FeedDetailIncidentSnooze' i_wake: $ref: '#/components/schemas/FeedDetailIncidentWake' i_ack: $ref: '#/components/schemas/FeedDetailIncidentAck' i_unack: $ref: '#/components/schemas/FeedDetailIncidentUnack' i_comm: $ref: '#/components/schemas/FeedDetailIncidentComment' i_rslv: $ref: '#/components/schemas/FeedDetailIncidentResolve' i_reopen: $ref: '#/components/schemas/FeedDetailIncidentReopen' i_merge: $ref: '#/components/schemas/FeedDetailIncidentMerge' i_r_title: $ref: '#/components/schemas/FeedDetailIncidentResetTitle' i_r_desc: $ref: '#/components/schemas/FeedDetailIncidentResetDescription' i_r_impact: $ref: '#/components/schemas/FeedDetailIncidentResetImpact' i_r_rc: $ref: '#/components/schemas/FeedDetailIncidentResetRootCause' i_r_rsltn: $ref: '#/components/schemas/FeedDetailIncidentResetResolution' i_r_severity: $ref: '#/components/schemas/FeedDetailIncidentResetSeverity' i_r_field: $ref: '#/components/schemas/FeedDetailIncidentResetField' i_m_flapping: $ref: '#/components/schemas/FeedDetailIncidentMuteByFlapping' i_m_reply: $ref: '#/components/schemas/FeedDetailIncidentMuteReply' i_custom: $ref: '#/components/schemas/FeedDetailIncidentCustomAction' i_wr_create: $ref: '#/components/schemas/FeedDetailIncidentWarRoomCreate' i_wr_delete: $ref: '#/components/schemas/FeedDetailIncidentWarRoomDelete' i_auto_refresh: $ref: '#/components/schemas/FeedDetailIncidentAutoRefreshCard' i_wi_created: $ref: '#/components/schemas/FeedDetailWorkItemCreated' i_wi_updated: $ref: '#/components/schemas/FeedDetailWorkItemUpdated' i_wi_assignees: $ref: '#/components/schemas/FeedDetailWorkItemAssigneesChanged' i_wi_completed: $ref: '#/components/schemas/FeedDetailWorkItemCompleted' i_wi_converted: $ref: '#/components/schemas/FeedDetailWorkItemConverted' i_wi_bound: $ref: '#/components/schemas/FeedDetailWorkItemBound' i_wi_deleted: $ref: '#/components/schemas/FeedDetailWorkItemDeleted' a_merge: $ref: '#/components/schemas/FeedDetailAlertMerge' account_id: type: integer format: int64 description: 账号 ID。 creator_id: type: integer format: int64 description: 操作人成员 ID，`0` 表示系统生成。 deleted_at: type: integer format: int64 description: 软删除时间戳（毫秒），未删除时为 0。 created_at: type: integer format: int64 description: 创建时间戳（毫秒）。 updated_at: type: integer format: int64 description: 最后更新时间戳（毫秒）。 ErrorResponse: type: object description: 错误响应结构。`error` 必填，`data` 不存在。 properties: request_id: type: string example: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 description: 本次请求的唯一追踪 ID（trace ID），反馈问题时请提供该值以便检索日志。 error: $ref: '#/components/schemas/DutyError' required: - request_id - error FeedDetailIncidentNew: type: object description: '`i_new` 的 detail 载荷。' properties: severity: $ref: '#/components/schemas/FeedSeverity' title: type: string description: 故障初始标题。 reporter_email: type: string description: 外部创建故障时的上报人邮箱。 title: i_new FeedDetailIncidentAssign: type: object description: '`i_assign` 的 detail 载荷。在 `AssignedTo` 基础上附加目标成员 ID 列表。' allOf: - $ref: '#/components/schemas/AssignedTo' - type: object properties: to: type: array items: type: integer format: int64 description: 被分派的成员 ID 列表。 title: i_assign FeedDetailIncidentAddRspd: type: object description: '`i_a_rspd` 的 detail 载荷。' properties: to: type: array items: type: integer format: int64 description: 新增为响应人的成员 ID 列表。 title: i_a_rspd FeedDetailIncidentNotify: type: object description: '`i_notify` 的 detail 载荷。' required: - layer_idx properties: rid: type: string description: 通知记录 ID。 msg_id: type: string description: 投递渠道返回的上游消息 ID。 fire_type: type: string enum: - fire - refire description: >- 首次触发或再次触发。`fire`：故障在该分派层级的首次通知；`refire`：故障一直未被处理时，按该层级的通知间隔对同一层级的再次催发，催发次数受层级配置的最大次数限制。 escalate_rule_name: type: string description: 分派策略名称。 escalate_rule_id: type: string pattern: ^[0-9a-fA-F]{24}$ description: 分派策略 ID（MongoDB ObjectID）。 layer_idx: type: integer description: 本次通知所处的环节索引。 by: type: string description: 投递渠道或方式标签。 persons: type: array items: $ref: '#/components/schemas/NotifyPerson' description: 个人投递记录。 chats: type: array items: $ref: '#/components/schemas/NotifyChat' description: 群聊投递记录。 robots: type: array items: $ref: '#/components/schemas/NotifyRobot' description: 机器人投递记录。 title: i_notify FeedDetailIncidentStorm: type: object description: '`i_storm` 的 detail 载荷。' properties: threshold: type: integer description: 触发的风暴阈值。 title: i_storm FeedDetailIncidentSnooze: type: object description: '`i_snooze` 的 detail 载荷。' properties: minutes: type: integer format: int64 description: 暂停时长（分钟）。 title: i_snooze FeedDetailIncidentWake: type: object description: '`i_wake` 的 detail 载荷。' properties: snoozedBefore: type: integer format: int64 description: 原本计划结束暂停的 Unix 时间戳。 title: i_wake FeedDetailIncidentAck: type: object description: '`i_ack` 的 detail 载荷。' properties: progress: type: string description: 认领时记录的处理进展。 comment: type: string description: 写入时间线评论的表单摘要。未提交认领表单摘要时省略。 images: type: array items: $ref: '#/components/schemas/Image' description: 认领表单提交的图片，仅写入时间线记录。未提交时省略。 title: i_ack FeedDetailIncidentUnack: type: object description: '`i_unack` 的 detail 载荷。' properties: progress: type: string description: 取消认领时记录的处理进展。 title: i_unack FeedDetailIncidentComment: type: object description: '`i_comm` 的 detail 载荷。' properties: comment: type: string description: 评论正文。 mute_reply: type: boolean description: 是否静音该评论的回复。 comment_type_id: type: string pattern: ^[0-9a-fA-F]{24}$ description: 附加到评论的账户级评论类型 ObjectID。 comment_type: $ref: '#/components/schemas/IncidentCommentTypeDisplay' title: i_comm FeedDetailIncidentResolve: type: object description: '`i_rslv` 的 detail 载荷。' required: - from properties: from: type: string enum: - voice - console - card - wcard - event - autorslv - autorefresh - escalation description: |- 触发恢复操作的来源。 | 值 | 含义 | |---|---| | `voice` | 语音电话按键操作。 | | `console` | 控制台（Web UI）操作。 | | `card` | IM 通知卡片按钮（钉钉/飞书/Slack/Teams）。 | | `wcard` | 企业微信通知卡片按钮。 | | `event` | 事件驱动：关联告警全部恢复 Ok 自动关闭，或外部 ITSM 系统同步的关闭。 | | `autorslv` | 自动恢复：超过协作空间配置的自动恢复时长无新告警，由系统关闭。 | | `autorefresh` | 卡片自动刷新（保留值，恢复动态中不会出现）。 | | `escalation` | 升级流程（保留值，恢复动态中不会出现）。 | comment: type: string description: 写入解决时间线评论的表单摘要。未提交解决表单摘要时省略。 images: type: array items: $ref: '#/components/schemas/Image' description: 解决表单提交的图片，仅写入时间线记录。未提交时省略。 title: i_rslv FeedDetailIncidentReopen: type: object description: '`i_reopen` 的 detail 载荷。' properties: reason: type: string description: 重新打开故障的原因。 title: i_reopen FeedDetailIncidentMerge: type: object description: '`i_merge` 的 detail 载荷。' properties: comment: type: string description: 合并时的评论。 source_incidents: type: array items: $ref: '#/components/schemas/IncidentShort' description: 被合并的源故障列表。 target_incident: $ref: '#/components/schemas/IncidentShort' owner_id: type: integer format: int64 description: 执行合并操作的成员 ID。 title: type: string description: 合并后的故障标题。 remove_source_incidents: type: boolean description: 合并后是否移除源故障。 source_responders: type: array items: type: integer format: int64 description: 从源故障继承的响应人成员 ID 列表。 title: i_merge FeedDetailIncidentResetTitle: type: object description: '`i_r_title` 的 detail 载荷。' properties: from: type: string description: 变更前的标题。 to: type: string description: 变更后的标题。 title: i_r_title FeedDetailIncidentResetDescription: type: object description: '`i_r_desc` 的 detail 载荷，无字段。' properties: {} additionalProperties: false title: i_r_desc FeedDetailIncidentResetImpact: type: object description: '`i_r_impact` 的 detail 载荷，无字段。' properties: {} additionalProperties: false title: i_r_impact FeedDetailIncidentResetRootCause: type: object description: '`i_r_rc` 的 detail 载荷，无字段。' properties: {} additionalProperties: false title: i_r_rc FeedDetailIncidentResetResolution: type: object description: '`i_r_rsltn` 的 detail 载荷，无字段。' properties: {} additionalProperties: false title: i_r_rsltn FeedDetailIncidentResetSeverity: type: object description: '`i_r_severity` 的 detail 载荷。' properties: from: $ref: '#/components/schemas/FeedSeverity' to: $ref: '#/components/schemas/FeedSeverity' title: i_r_severity FeedDetailIncidentResetField: type: object description: '`i_r_field` 的 detail 载荷。' required: - field_name properties: field_name: type: string description: 被更新的自定义字段名称。 to: description: 自定义字段的新值，类型取决于字段定义。 title: i_r_field FeedDetailIncidentMuteByFlapping: type: object description: '`i_m_flapping` 的 detail 载荷。' properties: max_changes: type: integer description: 窗口内允许的最大状态变化次数。 in_mins: type: integer description: 统计窗口长度（分钟）。 mute_mins: type: integer description: 触发抖动检测后的静音时长（分钟）。 title: i_m_flapping FeedDetailIncidentMuteReply: type: object description: '`i_m_reply` 的 detail 载荷，无字段。' properties: {} additionalProperties: false title: i_m_reply FeedDetailIncidentCustomAction: type: object description: '`i_custom` 的 detail 载荷。' properties: integration_id: type: integer format: int64 description: 执行动作的集成 ID。 integration_name: type: string description: 集成显示名称。 title: i_custom FeedDetailIncidentWarRoomCreate: type: object description: '`i_wr_create` 的 detail 载荷。' properties: integration_id: type: integer format: int64 description: 承载作战室群聊的集成 ID。 chat_id: type: string description: 群聊 ID。 chat_name: type: string description: 群聊显示名称。 plugin_type: type: string description: 聊天集成插件类型。 integration_name: type: string description: 集成显示名称。 share_link: type: string description: 作战室的可分享加入链接。 title: i_wr_create FeedDetailIncidentWarRoomDelete: type: object description: '`i_wr_delete` 的 detail 载荷。' properties: integration_id: type: integer format: int64 description: 承载作战室群聊的集成 ID。 chat_id: type: string description: 群聊 ID。 chat_name: type: string description: 群聊显示名称。 plugin_type: type: string description: 聊天集成插件类型。 integration_name: type: string description: 集成显示名称。 title: i_wr_delete FeedDetailIncidentAutoRefreshCard: type: object description: '`i_auto_refresh` 的 detail 载荷，无字段。' properties: {} additionalProperties: false title: i_auto_refresh FeedDetailWorkItemCreated: type: object description: '`i_wi_created` 的 detail 载荷。' properties: work_item_id: type: string description: 跟进事项 ID。 item_type: type: string enum: - action - follow_up description: >- 跟进事项类型。`action`：挂在故障上的处置行动事项，可直接转换为 `follow_up`；`follow_up`：挂在故障复盘（Post-mortem）上的改进事项，创建时要求故障已关联到该复盘。 title: type: string description: 跟进事项标题。 status: type: string description: 跟进事项状态标签（如 `open`、`done`）。 assignee_ids: type: array items: type: integer format: int64 description: 负责人成员 ID 列表。 post_mortem_id: type: string description: 跟进事项绑定的故障复盘 ID。 title: i_wi_created FeedDetailWorkItemUpdated: type: object description: '`i_wi_updated` 的 detail 载荷。仅发生变化的字段携带 `from_*`/`to_*` 值。' properties: work_item_id: type: string description: 跟进事项 ID。 item_type: type: string enum: - action - follow_up description: 跟进事项类型。`action`：挂在故障上的处置行动事项；`follow_up`：挂在故障复盘（Post-mortem）上的改进事项。 title: type: string description: 跟进事项标题。 from_title: type: string description: 更新前的标题。 from_status: type: string description: 更新前的状态标签。 to_status: type: string description: 更新后的状态标签。 from_priority: type: string description: 更新前的优先级标签。 to_priority: type: string description: 更新后的优先级标签。 from_description: type: string description: 更新前的描述。 to_description: type: string description: 更新后的描述。 title: i_wi_updated FeedDetailWorkItemAssigneesChanged: type: object description: '`i_wi_assignees` 的 detail 载荷。' properties: work_item_id: type: string description: 跟进事项 ID。 item_type: type: string enum: - action - follow_up description: 跟进事项类型。`action`：挂在故障上的处置行动事项；`follow_up`：挂在故障复盘（Post-mortem）上的改进事项。 title: type: string description: 跟进事项标题。 assignee_ids: type: array items: type: integer format: int64 description: 变更后的负责人成员 ID 列表。 added_assignee_ids: type: array items: type: integer format: int64 description: 新增为负责人的成员 ID。 removed_assignee_ids: type: array items: type: integer format: int64 description: 从负责人中移除的成员 ID。 title: i_wi_assignees FeedDetailWorkItemCompleted: type: object description: '`i_wi_completed` 的 detail 载荷。' properties: work_item_id: type: string description: 跟进事项 ID。 item_type: type: string enum: - action - follow_up description: 跟进事项类型。`action`：挂在故障上的处置行动事项；`follow_up`：挂在故障复盘（Post-mortem）上的改进事项。 title: type: string description: 跟进事项标题。 from_status: type: string description: 完成前的状态标签。 to_status: type: string description: 完成后的状态标签。 post_mortem_id: type: string description: 跟进事项绑定的故障复盘 ID。 title: i_wi_completed FeedDetailWorkItemConverted: type: object description: '`i_wi_converted` 的 detail 载荷。' properties: work_item_id: type: string description: 跟进事项 ID。 title: type: string description: 跟进事项标题。 from_type: type: string enum: - action - follow_up description: >- 转化前的事项类型。`action`：挂在故障上的处置行动事项；`follow_up`：挂在故障复盘（Post-mortem）上的改进事项。当前转换方向仅支持 `action` → `follow_up`，因此该事件中 `from_type` 恒为 `action`。 to_type: type: string enum: - action - follow_up description: >- 转化后的事项类型。`action`：挂在故障上的处置行动事项；`follow_up`：挂在故障复盘（Post-mortem）上的改进事项。当前转换方向仅支持 `action` → `follow_up`，因此该事件中 `to_type` 恒为 `follow_up`，且转换成功后会立即尝试绑定故障对应的复盘。 post_mortem_id: type: string description: 跟进事项绑定的故障复盘 ID。 status: type: string description: 转化后的事项状态标签。 title: i_wi_converted FeedDetailWorkItemBound: type: object description: '`i_wi_bound` 的 detail 载荷。' properties: work_item_id: type: string description: 跟进事项 ID。 item_type: type: string enum: - action - follow_up description: 跟进事项类型。`action`：挂在故障上的处置行动事项；`follow_up`：挂在故障复盘（Post-mortem）上的改进事项。 title: type: string description: 跟进事项标题。 post_mortem_id: type: string description: 跟进事项绑定的故障复盘 ID。 title: i_wi_bound FeedDetailWorkItemDeleted: type: object description: '`i_wi_deleted` 的 detail 载荷。' properties: work_item_id: type: string description: 跟进事项 ID。 item_type: type: string enum: - action - follow_up description: 跟进事项类型。`action`：挂在故障上的处置行动事项；`follow_up`：挂在故障复盘（Post-mortem）上的改进事项。 title: type: string description: 跟进事项标题。 post_mortem_id: type: string description: 跟进事项绑定的故障复盘 ID。 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: 目标故障被设置的新标题。未变更时不返回。 DutyError: type: object description: 响应结构中的错误 payload，仅在非 2xx 响应时出现。 properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: 用户可读的错误描述，语言会跟随调用方的 Accept-Language。可能包含字段名、ID 等请求上下文。 example: The specified parameter template_id is not valid. required: - code - message FeedSeverity: type: string enum: - Ok - Critical - Warning - Info description: 严重等级。 AssignedTo: type: object description: 故障分派目标。`person_ids` 与 `escalate_rule_id` 至少设置一项。 properties: person_ids: type: array items: type: integer format: int64 minItems: 1 maxItems: 100 description: 直接指派的成员 ID 列表。 escalate_rule_id: type: string pattern: ^[0-9a-fA-F]{24}$ description: 按分派策略指派时使用的策略 ID（MongoDB ObjectID）。 layer_idx: type: integer description: 当前环节索引。 type: type: string description: >- 指派类型：`assign` 直接指派、`reassign` 重新指派、`escalate` 分派策略驱动、`reopen` 重新打开时自动指派。 enum: - assign - reassign - escalate - reopen emails: type: array items: type: string format: email minItems: 1 maxItems: 100 description: 邮箱接收人列表，用于 ServiceNow 等外部系统。 notify: type: object description: 为本次指派覆盖通知渠道。 properties: follow_preference: type: - boolean - 'null' description: 为 false 时使用 `personal_channels`；为 true 或省略时跟随处理人员的个人偏好。 personal_channels: type: array items: type: string description: 使用的通知渠道（如 `voice`、`sms`、`email`）。 template_id: type: string pattern: ^[0-9a-fA-F]{24}$ description: 通知模板 ID（MongoDB ObjectID）。 escalate_rule_name: type: string description: 分派策略名称，由服务端填充。 assigned_at: type: integer format: int64 description: 指派发生的 Unix 时间戳（秒）。 id: type: string description: 服务端生成的指派 ID。 NotifyPerson: type: object description: 个人通知投递记录。 properties: person_id: type: integer format: int64 description: 接收人成员 ID。 failed_reason: type: string description: 投递失败原因。 sms_content: type: string description: 短信投递时发送的短信内容。 NotifyChat: type: object description: 群聊通知投递记录。 properties: data_source_id: type: integer format: int64 description: 发送通知所用的集成数据源 ID。 chat_id: type: string description: 群聊 ID。 chat_name: type: string description: 群聊显示名称。 failed_reason: type: string description: 投递失败原因。 NotifyRobot: type: object description: 机器人 webhook 通知投递记录。 properties: token: type: string description: 机器人 token 或标识。 alias: type: string description: 机器人别名。 failed_reason: type: string description: 投递失败原因。 Image: type: object description: 图片或附件引用。 required: - src properties: src: type: string description: 图片来源，可以是 `img_` 上传 token 或 `http(s)` URL。 href: type: string description: 可选的图片跳转链接。 alt: type: string description: 替代文本。 IncidentCommentTypeDisplay: type: object description: 账户级评论类型的解析后展示信息，读取时根据当前类型定义填充。 required: - id - name - color properties: id: type: string pattern: ^[0-9a-fA-F]{24}$ description: 评论类型 ID（MongoDB ObjectID）。 name: type: string maxLength: 40 description: 评论类型展示名称。 color: type: string pattern: ^#[0-9A-Fa-f]{6}$ description: 徽标颜色，#RRGGBB 格式。 IncidentShort: type: object description: 嵌入告警中的故障简要信息。 properties: incident_id: type: string description: 故障 ID（ObjectID 十六进制字符串）。 title: type: string description: 故障标题。 progress: type: string description: 故障处理进度——`Triggered`、`Processing`、`Closed` 之一。 AlertShort: type: object description: 告警简要引用。 properties: alert_id: type: string description: 告警 ID（ObjectID 十六进制字符串）。 pattern: ^[0-9a-fA-F]{24}$ title: type: string description: 告警标题，读取时解析填充。为空时不返回。 ErrorCode: type: string description: >- Flashduty 错误码枚举。每个失败响应的 `error.code` 都是下列稳定值之一，HTTP 状态码仅作参考。 | 错误码 | HTTP | 含义 | |---|---|---| | `OK` | 200 | 保留值，正常错误响应不会返回。 | | `InvalidParameter` | 400 | 必填参数缺失或未通过校验。 | | `BadRequest` | 400 | 通用的 400 错误，通常是请求本身不合法。 | | `InvalidContentType` | 400 | 请求头 `Content-Type` 不是 `application/json`。 | | `ResourceNotFound` | 400 | 目标资源不存在。注意 HTTP 状态码是 400 而非 404（历史设计）。 | | `NoLicense` | 400 | 功能需要有效授权，但未找到可用的 license。 | | `ReferenceExist` | 400 | 该资源仍被其他实体引用，无法删除。 | | `Unauthorized` | 401 | `app_key` 缺失、无效或已过期。 | | `BalanceNotEnough` | 402 | 账户余额不足，无法执行需要计费的操作。 | | `AccessDenied` | 403 | 身份认证通过，但 RBAC 权限不足以执行该操作。 | | `RouteNotFound` | 404 | 请求的 URL 路径不是已知路由。 | | `MethodNotAllowed` | 405 | 当前路径不接受所使用的 HTTP 方法。 | | `UndonedOrderExist` | 409 | 账户存在未完成的订单，请稍后重试。 | | `RequestLocked` | 423 | 因连续失败被临时锁定。 | | `EntityTooLarge` | 413 | 请求体超过允许的最大长度。 | | `RequestTooFrequently` | 429 | 命中限流（全局、账户级或集成级）。 | | `RequestVerifyRequired` | 428 | 操作需要二次验证码，但未提供。 | | `DangerousOperation` | 428 | 危险操作，需要进行 MFA 验证。 | | `InternalError` | 500 | 服务端未预期错误。反馈问题请附上 `request_id`。 | | `ServiceUnavailable` | 503 | 后端依赖不可用，请稍后重试。 | enum: - OK - InvalidParameter - BadRequest - InvalidContentType - ResourceNotFound - NoLicense - ReferenceExist - Unauthorized - BalanceNotEnough - AccessDenied - RouteNotFound - MethodNotAllowed - UndonedOrderExist - RequestLocked - EntityTooLarge - RequestTooFrequently - RequestVerifyRequired - DangerousOperation - InternalError - ServiceUnavailable x-enumDescriptions: OK: 保留值，正常错误响应不会返回。 InvalidParameter: 必填参数缺失或未通过校验。 BadRequest: 通用的 400 错误，通常是请求本身不合法。 InvalidContentType: 请求头 `Content-Type` 不是 `application/json`。 ResourceNotFound: 目标资源不存在。注意 HTTP 状态码是 400 而非 404（历史设计）。 NoLicense: 功能需要有效授权，但未找到可用的 license。 ReferenceExist: 该资源仍被其他实体引用，无法删除。 Unauthorized: '`app_key` 缺失、无效或已过期。' BalanceNotEnough: 账户余额不足，无法执行需要计费的操作。 AccessDenied: 身份认证通过，但 RBAC 权限不足以执行该操作。 RouteNotFound: 请求的 URL 路径不是已知路由。 MethodNotAllowed: 当前路径不接受所使用的 HTTP 方法。 UndonedOrderExist: 账户存在未完成的订单，请稍后重试。 RequestLocked: 因连续失败被临时锁定。 EntityTooLarge: 请求体超过允许的最大长度。 RequestTooFrequently: 命中限流（全局、账户级或集成级）。 RequestVerifyRequired: 操作需要二次验证码，但未提供。 DangerousOperation: 危险操作，需要进行 MFA 验证。 InternalError: 服务端未预期错误。反馈问题请附上 `request_id`。 ServiceUnavailable: 后端依赖不可用，请稍后重试。 example: InvalidParameter responses: BadRequest: description: 请求非法 — 通常是参数缺失或格式不正确。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingParameter: value: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 error: code: InvalidParameter message: The specified parameter is not valid. Unauthorized: description: app_key 缺失或无效。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingAppKey: value: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 error: code: Unauthorized message: You are unauthorized. TooManyRequests: description: 命中限流。可能是全局 API 限流、账户级限流或集成级限流。限流按账户聚合。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: value: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 error: code: RequestTooFrequently message: Request too frequently. ServerError: description: 服务端未预期错误。反馈问题时请携带 request_id。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal: value: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 error: code: InternalError message: >- We encountered an internal error, and it has been reported. Please try again later. securitySchemes: AppKeyAuth: type: apiKey in: query name: app_key description: >- 在 Flashduty 控制台 账户 → APP Key 中签发的 app_key。调用任何公开 API 时都必须携带。它等同于所属账户的身份凭证，请妥善保管。 ````