Quick Start

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 and performing operations through the UI.

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 for all available endpoints.
Standard Alert Events — Push alerts from your custom monitoring system to Flashduty to trigger incident handling. See Custom Alert Events.
Custom Change Events — Push change events to correlate with incidents for root cause analysis. See Custom Change Events.
Webhook Push — Flashduty proactively pushes incident/alert event notifications to your system. See Incident Webhook and Alert Webhook.
Custom Actions — Trigger external operations from the incident detail page. See Custom Actions.

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

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.

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.

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:

curl -X POST 'https://api.flashcat.cloud/your/api/path?app_key=YOUR_APP_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"param": "value"}'

Using Go? Use the official Go SDK to call Flashduty — you get typed request parameters, response structs, and error codes out of the box, with no hand-written HTTP.

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

Success Response
Error Response

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

{
  "request_id": "abc123456",
  "error": {
    "code": "InvalidParameter",
    "message": "Parameter name cannot be empty"
  }
}

Error Object Structure

Field	Type	Required	Description
`code`	string	✅	Error code, see Error Code List below
`message`	string		Error description

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.

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.

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

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.

401 Authentication Failed

Possible causes:

APP Key not provided
APP Key is incorrect or has expired

Solution:

Confirm that the request URL contains the app_key parameter
Go to the console to check if the APP Key is valid

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.

429 Too Many Requests

Possible causes:

Too many requests sent in a short period

Solution:

Reduce request frequency
Implement exponential backoff retry mechanism
Combine multiple requests (e.g., use batch APIs)

500 Internal Error

Possible causes:

Server-side internal exception

Solution:

Retry later
If the issue persists, contact technical support and provide the request_id

Best Practices

Implement Retry Mechanism

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.

Record request_id

Save the request_id returned from each request to facilitate troubleshooting and technical support.

Protect APP Key

Do not hardcode APP Key in client code. It is recommended to manage it through environment variables or configuration centers.

Rotate Keys Regularly

Regularly replace APP Keys and promptly delete keys that are no longer in use to reduce the risk of leakage.

Developer Guide

On-call

Monitors

RUM

AI SRE

Platform

Request Specifications

Request URL

Headers

Character Encoding

Authentication

Obtaining an APP Key

Usage Example

Response Structure

Response Examples

Error Object Structure

Rate Limits

Rate Limits

Permission Limits

Error Code List

Error Handling Recommendations

Best Practices

Implement Retry Mechanism

Record request_id

Protect APP Key

Rotate Keys Regularly

​Request Specifications

​Request URL

​Headers

​Character Encoding

​Authentication

​Obtaining an APP Key

​Usage Example

​Response Structure

​Response Examples

​Error Object Structure

​Rate Limits

​Rate Limits

​Permission Limits

​Error Code List

​Error Handling Recommendations

​Best Practices

Implement Retry Mechanism

Record request_id

Protect APP Key

Rotate Keys Regularly

Request Specifications

Request URL

Headers

Character Encoding

Authentication

Obtaining an APP Key

Usage Example

Response Structure

Response Examples

Error Object Structure

Rate Limits

Rate Limits

Permission Limits

Error Code List

Error Handling Recommendations

Best Practices