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

1. Sign in to console

   Sign in to the Flashduty Console

2. Create APP Key

   Go to Account Settings → APP Key page, enter a name, and click the Add button to complete creation

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

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

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

Error Response

{
  "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

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

• 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

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:

1. Confirm that the request URL contains the app_key parameter
2. 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:

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

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

---

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.