> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashcat.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速入门

> Flashduty Open API 快速入门指南

Open API 用于通过 HTTP 接口主动调用 Flashduty，查询和管理故障、协作空间、值班表等实体数据。使用 API 与您登录 [Flashduty 控制台](https://console.flashcat.cloud) 后进行页面操作本质上是相同的。

<Tip>
  **不确定是否需要 Open API？** Flashduty 提供多种数据交互方式：

  * **Open API**（本文档）— 您主动调用 Flashduty，查询或操作数据。查看 [API 总览](/zh/openapi/api-catalog) 了解全部接口。
  * **标准告警事件** — 将自研监控系统的告警推送到 Flashduty，触发故障处理流程。详见\[自定义告警事件]\(/zh/on-call/integration/alert-integration/alert-sources/standard alert)。
  * **自定义变更事件** — 推送变更事件关联故障，辅助根因分析。详见[自定义变更事件](/zh/on-call/integration/change-integration/custom-event)。
  * **Webhook 推送** — Flashduty 主动向您的系统推送故障/告警事件通知。详见[故障 Webhook](/zh/on-call/integration/webhooks/incident-webhook) 和[告警 Webhook](/zh/on-call/integration/webhooks/alert-webhook)。
  * **自定义操作** — 在故障详情页触发外部操作。详见[自定义操作](/zh/on-call/integration/webhooks/custom-actions)。
</Tip>

***

## 请求规范

### 请求地址

所有 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

<Steps>
  <Step title="登录控制台">
    登录 [Flashduty 控制台](https://console.flashcat.cloud)
  </Step>

  <Step title="创建 APP Key">
    进入 **账户设置 → APP Key** 页面，输入名称，点击添加按钮完成创建
  </Step>
</Steps>

<Warning>
  每一个 APP Key 都代表一个独立用户，拥有该用户的全部操作权限，请妥善保存，避免泄露。
</Warning>

### 使用示例

将 APP Key 作为 query string 参数传入：

```bash theme={null}
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_id` | string |  ✅  | 请求 ID，用于链路追踪        |
| `error`      | object |     | 错误描述，仅当出现错误时返回      |
| `data`       | any    |     | 数据内容，具体格式参考各 API 定义 |

### 响应示例

<Tabs>
  <Tab title="成功响应">
    ```json theme={null}
    {
      "request_id": "abc123456",
      "data": {
        "id": "user_001",
        "name": "example"
      }
    }
    ```
  </Tab>

  <Tab title="错误响应">
    ```json theme={null}
    {
      "request_id": "abc123456",
      "error": {
        "code": "InvalidParameter",
        "message": "参数 name 不能为空"
      }
    }
    ```
  </Tab>
</Tabs>

### Error 对象结构

| 字段        | 类型     |  必选 | 描述                      |
| --------- | ------ | :-: | ----------------------- |
| `code`    | string |  ✅  | 错误码，详见下方[错误码列表](#错误码列表) |
| `message` | string |     | 错误描述                    |

***

## 使用限制

### 频率限制

为保证服务稳定性，API 对请求频率有一定限制。当请求过于频繁时，将返回 `429` 状态码和 `RequestTooFrequently` 错误。

<Warning>
  请合理控制请求频率，避免在短时间内发送大量请求。建议实现重试机制，在收到 429 错误时进行指数退避重试。
</Warning>

### 权限限制

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

### 错误码列表

| 错误码                    | HTTP Status | 描述                                      |
| ---------------------- | :---------: | --------------------------------------- |
| `InvalidParameter`     |     400     | 参数错误，请检查请求参数是否正确                        |
| `InvalidContentType`   |     400     | Content-Type 不支持，请使用 `application/json` |
| `MethodNotAllowed`     |     400     | HTTP Method 不支持                         |
| `Unauthorized`         |     401     | 登录认证未通过，请检查 APP Key 是否正确                |
| `AccessDenied`         |     403     | 权限认证未通过，当前用户无此操作权限                      |
| `RouteNotFound`        |     404     | 请求 Method + Path 未匹配，请检查 API 地址         |
| `RequestTooFrequently` |     429     | 请求过于频繁，请稍后重试                            |
| `ResourceNotFound`     |     400     | 账户未购买资源，请前往费用中心下单                       |
| `NoLicense`            |     400     | 账户无充足订阅 License，请前往费用中心升级或购买订阅          |
| `InternalError`        |     500     | 内部或未知错误，请联系技术支持                         |

***

## 错误处理建议

<AccordionGroup>
  <Accordion title="400 参数错误">
    **可能原因**：

    * 缺少必填参数
    * 参数格式不正确
    * Content-Type 未设置为 `application/json`

    **解决方案**：
    检查请求参数和 Headers 设置，参考 API 文档确认参数要求。
  </Accordion>

  <Accordion title="401 认证失败">
    **可能原因**：

    * APP Key 未提供
    * APP Key 不正确或已失效

    **解决方案**：

    1. 确认请求 URL 中包含 `app_key` 参数
    2. 前往控制台检查 APP Key 是否有效
  </Accordion>

  <Accordion title="403 权限不足">
    **可能原因**：

    * 当前用户无权执行此操作
    * APP Key 对应用户权限不足

    **解决方案**：
    联系账户管理员提升权限，或使用具有相应权限的 APP Key。
  </Accordion>

  <Accordion title="429 请求过频">
    **可能原因**：

    * 短时间内发送了过多请求

    **解决方案**：

    1. 降低请求频率
    2. 实现指数退避重试机制
    3. 合并多个请求（如使用批量接口）
  </Accordion>

  <Accordion title="500 内部错误">
    **可能原因**：

    * 服务端内部异常

    **解决方案**：

    1. 稍后重试
    2. 如持续出现，请联系技术支持并提供 `request_id`
  </Accordion>
</AccordionGroup>

***

## 最佳实践

<CardGroup cols={2}>
  <Card title="实现重试机制" icon="rotate">
    对于网络错误和 5xx 错误，建议实现指数退避重试，初始间隔 1 秒，最大重试 3 次。
  </Card>

  <Card title="记录 request_id" icon="clipboard-list">
    保存每次请求返回的 `request_id`，便于问题排查和技术支持。
  </Card>

  <Card title="保护 APP Key" icon="shield-check">
    不要在客户端代码中硬编码 APP Key，建议通过环境变量或配置中心管理。
  </Card>

  <Card title="定期轮换密钥" icon="key">
    定期更换 APP Key，及时删除不再使用的密钥，降低泄露风险。
  </Card>
</CardGroup>