> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/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** page, enter a name, and click the Add button to complete creation
  </Step>
</Steps>

<Warning>
  Each APP Key represents an independent user and has all the operational permissions of that user. Please keep it safe and avoid leakage.
</Warning>

### 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

* Each APP Key inherits all permissions from its creator
* When an operation exceeds permission scope, a `403` status code with `AccessDenied` error will be 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>