> ## Documentation Index
> Fetch the complete documentation index at: https://test-8ad8522e-feat-api-review-auto-fix.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Flashduty Open API quick start guide

Open API lets you call Flashduty via HTTP endpoints to query and manage entity data such as incidents, channels, and schedules. Using the API is essentially the same as logging into the [Flashduty Console](https://console.flashcat.cloud) and performing operations through the UI.

<Tip>
  **Not sure if you need Open API?** Flashduty offers multiple data interaction methods:

  * **Open API** (this guide) — You actively call Flashduty to query or operate on data. See the [API Catalog](/en/openapi/api-catalog) for all available endpoints.
  * **Standard Alert Events** — Push alerts from your custom monitoring system to Flashduty to trigger incident handling. See [Custom Alert Events](/en/on-call/integration/alert-integration/alert-sources/standard-alert).
  * **Custom Change Events** — Push change events to correlate with incidents for root cause analysis. See [Custom Change Events](/en/on-call/integration/change-integration/custom-event).
  * **Webhook Push** — Flashduty proactively pushes incident/alert event notifications to your system. See [Incident Webhook](/en/on-call/integration/webhooks/incident-webhook) and [Alert Webhook](/en/on-call/integration/webhooks/alert-webhook).
  * **Custom Actions** — Trigger external operations from the incident detail page. See [Custom Actions](/en/on-call/integration/webhooks/custom-actions).
</Tip>

***

## Request Specifications

### Request URL

All APIs only accept access via **HTTPS** protocol and have a single Endpoint:

```
https://api.flashcat.cloud
```

### Headers

Most requests use the POST method with JSON Payload parameters. Please ensure the correct Content-Type is set:

```
Content-Type: application/json
```

### Character Encoding

All APIs use **UTF-8** encoding.

***

## Authentication

All Open APIs use **APP Key** for authentication.

### Obtaining an APP Key

<Steps>
  <Step title="Sign in to console">
    Sign in to the [Flashduty Console](https://console.flashcat.cloud)
  </Step>

  <Step title="Create APP Key">
    Go to **Account Settings → APP Key**, enter a name, choose a permission scope, then click Add.

    * **All permissions**: Does not add an API-scope restriction, but remains limited by the creator's current role permissions.
    * **Custom permissions**: Select at least one available API permission. The APP Key can call only APIs in the selected scope.
  </Step>
</Steps>

<Warning>
  An APP Key's effective access is constrained by both its permission scope and the creator's current role permissions. Store the full key securely as soon as it is created; it cannot be viewed again after you leave the creation page.
</Warning>

You can edit an existing APP Key's name and permission scope from the APP Key list.

### Usage Example

Pass the APP Key as a query string parameter:

```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"}'
```

<Note>
  Using Go? Use the official [Go SDK](/en/openapi/go-sdk) to call Flashduty — you get typed request parameters, response structs, and error codes out of the box, with no hand-written HTTP.
</Note>

***

## Response Structure

All request responses are in JSON format and follow a unified structure:

| Field        | Type   | Required | Description                                                    |
| ------------ | ------ | :------: | -------------------------------------------------------------- |
| `request_id` | string |     ✅    | Request ID for tracing                                         |
| `error`      | object |          | Error description, returned only when an error occurs          |
| `data`       | any    |          | Data content, refer to each API definition for specific format |

### Response Examples

<Tabs>
  <Tab title="Success Response">
    ```json theme={null}
    {
      "request_id": "abc123456",
      "data": {
        "id": "user_001",
        "name": "example"
      }
    }
    ```
  </Tab>

  <Tab title="Error Response">
    ```json theme={null}
    {
      "request_id": "abc123456",
      "error": {
        "code": "InvalidParameter",
        "message": "Parameter name cannot be empty"
      }
    }
    ```
  </Tab>
</Tabs>

### Error Object Structure

| Field     | Type   | Required | Description                                               |
| --------- | ------ | :------: | --------------------------------------------------------- |
| `code`    | string |     ✅    | Error code, see [Error Code List](#error-code-list) below |
| `message` | string |          | Error description                                         |

***

## Rate Limits

### Rate Limits

To ensure service stability, APIs have rate limits on request frequency. When requests are too frequent, a `429` status code with `RequestTooFrequently` error will be returned.

<Warning>
  Please control your request frequency reasonably and avoid sending a large number of requests in a short period. It is recommended to implement a retry mechanism with exponential backoff when receiving a 429 error.
</Warning>

### Permission Limits

* An APP Key with **All permissions** has no additional API-scope restriction, but remains limited by the creator's current role permissions
* **Custom permissions** requires at least one selected API permission; the APP Key can call only APIs in that selected scope
* When an operation exceeds either the APP Key scope or the creator's role permissions, a `403` status code with `AccessDenied` error is returned
* It is recommended to create separate APP Keys for different purposes, following the principle of least privilege

### Error Code List

| Error Code             | HTTP Status | Description                                                                                                                  |
| ---------------------- | :---------: | ---------------------------------------------------------------------------------------------------------------------------- |
| `InvalidParameter`     |     400     | Parameter error, please check if request parameters are correct                                                              |
| `InvalidContentType`   |     400     | Content-Type not supported, please use `application/json`                                                                    |
| `MethodNotAllowed`     |     400     | HTTP Method not supported                                                                                                    |
| `Unauthorized`         |     401     | Authentication failed, please check if the APP Key is correct                                                                |
| `AccessDenied`         |     403     | Permission denied, current user does not have permission for this operation                                                  |
| `RouteNotFound`        |     404     | Request Method + Path not matched, please check the API address                                                              |
| `RequestTooFrequently` |     429     | Request too frequent, please try again later                                                                                 |
| `ResourceNotFound`     |     400     | Account has not purchased resources, please go to the billing center to place an order                                       |
| `NoLicense`            |     400     | Account does not have sufficient subscription License, please go to the billing center to upgrade or purchase a subscription |
| `InternalError`        |     500     | Internal or unknown error, please contact technical support                                                                  |

***

## Error Handling Recommendations

<AccordionGroup>
  <Accordion title="400 Parameter Error">
    **Possible causes**:

    * Missing required parameters
    * Incorrect parameter format
    * Content-Type not set to `application/json`

    **Solution**:
    Check request parameters and Headers settings, refer to API documentation for parameter requirements.
  </Accordion>

  <Accordion title="401 Authentication Failed">
    **Possible causes**:

    * APP Key not provided
    * APP Key is incorrect or has expired

    **Solution**:

    1. Confirm that the request URL contains the `app_key` parameter
    2. Go to the console to check if the APP Key is valid
  </Accordion>

  <Accordion title="403 Permission Denied">
    **Possible causes**:

    * Current user does not have permission to perform this operation
    * The user corresponding to the APP Key has insufficient permissions

    **Solution**:
    Contact the account administrator to elevate permissions, or use an APP Key with the appropriate permissions.
  </Accordion>

  <Accordion title="429 Too Many Requests">
    **Possible causes**:

    * Too many requests sent in a short period

    **Solution**:

    1. Reduce request frequency
    2. Implement exponential backoff retry mechanism
    3. Combine multiple requests (e.g., use batch APIs)
  </Accordion>

  <Accordion title="500 Internal Error">
    **Possible causes**:

    * Server-side internal exception

    **Solution**:

    1. Retry later
    2. If the issue persists, contact technical support and provide the `request_id`
  </Accordion>
</AccordionGroup>

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Implement Retry Mechanism" icon="rotate">
    For network errors and 5xx errors, it is recommended to implement exponential backoff retry with an initial interval of 1 second and a maximum of 3 retries.
  </Card>

  <Card title="Record request_id" icon="clipboard-list">
    Save the `request_id` returned from each request to facilitate troubleshooting and technical support.
  </Card>

  <Card title="Protect APP Key" icon="shield-check">
    Do not hardcode APP Key in client code. It is recommended to manage it through environment variables or configuration centers.
  </Card>

  <Card title="Rotate Keys Regularly" icon="key">
    Regularly replace APP Keys and promptly delete keys that are no longer in use to reduce the risk of leakage.
  </Card>
</CardGroup>