跳转到主要内容
Open API 用于通过 HTTP 接口主动调用 Flashduty，查询和管理故障、协作空间、值班表等实体数据。使用 API 与您登录 Flashduty 控制台 后进行页面操作本质上是相同的。
不确定是否需要 Open API？ Flashduty 提供多种数据交互方式：
  • Open API（本文档）— 您主动调用 Flashduty，查询或操作数据。查看 API 总览 了解全部接口。
  • 标准告警事件 — 将自研监控系统的告警推送到 Flashduty，触发故障处理流程。详见[自定义告警事件](/zh/on-call/integration/alert-integration/alert-sources/standard alert)。
  • 自定义变更事件 — 推送变更事件关联故障，辅助根因分析。详见自定义变更事件。
  • Webhook 推送 — Flashduty 主动向您的系统推送故障/告警事件通知。详见故障 Webhook 和告警 Webhook。
  • 自定义操作 — 在故障详情页触发外部操作。详见自定义操作。

​
请求规范

​
请求地址

所有 API 只接受 HTTPS 协议进行访问，且只有一个 Endpoint： 
https://api.flashcat.cloud

​
Headers

大部分请求使用 POST 方法，并使用 JSON Payload 传参。请确保设置正确的 Content-Type： 
Content-Type: application/json

​
字符编码

所有 API 均使用 UTF-8 编码。

​
认证方式

所有 Open API 使用 APP Key 进行鉴权。

​
获取 APP Key

1

登录控制台

登录 Flashduty 控制台
2

创建 APP Key

进入 账户设置 → APP Key 页面，输入名称，点击添加按钮完成创建
每一个 APP Key 都代表一个独立用户，拥有该用户的全部操作权限，请妥善保存，避免泄露。

​
使用示例

将 APP Key 作为 query string 参数传入： 
curl -X POST 'https://api.flashcat.cloud/your/api/path?app_key=YOUR_APP_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"param": "value"}'

​
响应结构

所有请求响应均为 JSON 格式，遵循统一结构：
字段类型必选描述
request_idstring✅请求 ID，用于链路追踪
errorobject错误描述，仅当出现错误时返回
dataany数据内容，具体格式参考各 API 定义

​
响应示例

{
  "request_id": "abc123456",
  "data": {
    "id": "user_001",
    "name": "example"
  }
}

​
Error 对象结构

字段类型必选描述
codestring✅错误码，详见下方错误码列表
messagestring错误描述

​
使用限制

​
频率限制

为保证服务稳定性，API 对请求频率有一定限制。当请求过于频繁时，将返回 429 状态码和 RequestTooFrequently 错误。
请合理控制请求频率，避免在短时间内发送大量请求。建议实现重试机制，在收到 429 错误时进行指数退避重试。

​
权限限制

  • 每个 APP Key 继承其创建者的全部权限
  • 操作超出权限范围时，将返回 403 状态码和 AccessDenied 错误
  • 建议为不同用途创建独立的 APP Key，遵循最小权限原则

​
错误码列表

错误码HTTP Status描述
InvalidParameter400参数错误，请检查请求参数是否正确
InvalidContentType400Content-Type 不支持，请使用 application/json
MethodNotAllowed400HTTP Method 不支持
Unauthorized401登录认证未通过，请检查 APP Key 是否正确
AccessDenied403权限认证未通过，当前用户无此操作权限
RouteNotFound404请求 Method + Path 未匹配，请检查 API 地址
RequestTooFrequently429请求过于频繁，请稍后重试
ResourceNotFound400账户未购买资源，请前往费用中心下单
NoLicense400账户无充足订阅 License，请前往费用中心升级或购买订阅
InternalError500内部或未知错误，请联系技术支持

​
错误处理建议

可能原因：
  • 缺少必填参数
  • 参数格式不正确
  • Content-Type 未设置为 application/json
解决方案： 检查请求参数和 Headers 设置，参考 API 文档确认参数要求。
可能原因：
  • APP Key 未提供
  • APP Key 不正确或已失效
解决方案：
  1. 确认请求 URL 中包含 app_key 参数
  2. 前往控制台检查 APP Key 是否有效
可能原因：
  • 当前用户无权执行此操作
  • APP Key 对应用户权限不足
解决方案： 联系账户管理员提升权限，或使用具有相应权限的 APP Key。
可能原因：
  • 短时间内发送了过多请求
解决方案：
  1. 降低请求频率
  2. 实现指数退避重试机制
  3. 合并多个请求（如使用批量接口）
可能原因：
  • 服务端内部异常
解决方案：
  1. 稍后重试
  2. 如持续出现，请联系技术支持并提供 request_id

​
最佳实践

实现重试机制

对于网络错误和 5xx 错误，建议实现指数退避重试，初始间隔 1 秒，最大重试 3 次。

记录 request_id

保存每次请求返回的 request_id，便于问题排查和技术支持。

保护 APP Key

不要在客户端代码中硬编码 APP Key，建议通过环境变量或配置中心管理。

定期轮换密钥

定期更换 APP Key，及时删除不再使用的密钥，降低泄露风险。