请求规范
请求地址
所有 API 只接受 HTTPS 访问,且只有一个 Endpoint:请求方法与 Headers
绝大多数接口使用POST 方法、JSON 请求体,请设置:
GET 方法和 query 参数(例如状态页的查询接口、Prometheus 兼容的标签查询),以各接口页面标注的方法为准。不需要参数的 POST 接口请传 {}。
字符编码
请求与响应均使用 UTF-8 编码。响应语言
错误信息会按语言返回。语言依次取自 query 参数locale、query 参数 lang、请求头 Accept-Language,例如 Accept-Language: zh-CN 或 en-US。字段名、枚举值和错误码不会被翻译。
认证方式
所有 Open API 使用 APP Key 进行鉴权。获取 APP Key
1
登录控制台
2
创建 APP Key
将鼠标悬停在左下角头像上,在 个人中心 一列选择 APP Key,输入名称并选择权限范围后,点击添加按钮完成创建。详见个人设置。
- 全部权限:不额外限制接口范围,但仍受创建者当前角色权限约束。
- 自定义权限:从可选 API 权限点中至少选择一项;该 APP Key 只能调用选中的接口范围。
APP Key 泄露了怎么办
如果 APP Key 可能已泄露(例如被提交到公开代码仓库,或出现在日志、截图中),请按以下步骤处置:1
创建替代密钥
在 个人中心 → APP Key 中创建一个新的 APP Key。
2
切换集成
把使用旧密钥的集成、脚本和配置切换到新密钥,并确认调用正常。
3
禁用或删除旧密钥
在 APP Key 列表中禁用或删除旧密钥。之后使用旧密钥的请求返回
401 Unauthorized。传递 APP Key
通过 query 参数app_key 传入:
Fd-App-Key 中,避免密钥出现在 URL 和访问日志里:
401 Unauthorized。
使用 Go?推荐用官方 Go SDK 调用 Flashduty,直接获得类型化的请求参数、响应结构和错误码,无需手写 HTTP 请求。
响应结构
所有响应均为 JSON,遵循统一结构:
成功时 HTTP 状态码为
200。失败时返回错误码列表中对应的 HTTP 状态码,但请以 error.code 而不是状态码做判断。
响应示例
- 成功响应
- 错误响应
Error 对象结构
数据约定
- 时间戳均为 Unix 时间戳整数。大多数以秒为单位;部分(AI SRE 和 RUM 的大多数时间字段、故障动态、审计日志)以毫秒为单位。每个时间字段的描述都会写明单位。
- 枚举区分大小写,可能是字符串或整数;每个字段都会列出可选值及含义。
- ID 按各字段标注的类型(整数或字符串)返回,回传时请保持相同类型。
- 列表均分页返回,见关于分页。
- 更新接口会逐字段说明:不传某字段时是保留原值还是清空。