Skip to main content
Open API lets you call Flashduty through 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 are served over HTTPS from a single endpoint:

Method and headers

Almost every operation is a POST with a JSON body, so set:
A few read operations use GET with query parameters (for example the status page reads and the Prometheus-compatible label query); each operation page shows its method. Send {} as the body of a POST that takes no parameters.

Character encoding

All requests and responses use UTF-8.

Response language

Error messages are localized. The language is taken, in order, from the locale query parameter, the lang query parameter, then the Accept-Language header, for example Accept-Language: en-US or zh-CN. Field names, enum values, and error codes are never translated.

Authentication

All Open APIs authenticate with an APP Key.

Obtaining an APP key

1

Sign in to console

Sign in to the Flashduty Console
2

Create APP Key

Hover over the avatar in the lower left, select APP Key in the Personal center column, enter a name, choose a permission scope, then click Add. See Personal settings.
  • 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. Do not hardcode it in client code; load it from an environment variable or a secret manager, and delete keys you no longer use.
You can edit an existing APP Key’s name and permission scope from the APP Key list.

What to do if an APP key is exposed

If an APP key may have been exposed (for example, committed to a public repository or shown in logs or screenshots), replace it:
1

Create a replacement key

In Personal center → APP Key, create a new APP key.
2

Switch your integrations

Move every integration, script, and configuration that uses the old key to the new key, and confirm the calls work.
3

Disable or delete the old key

Disable or delete the old key in the APP key list. Requests that use it then return 401 Unauthorized.

Passing the APP key

Pass the key as the app_key query parameter:
Or send it in the Fd-App-Key request header, which keeps the key out of URLs and access logs:
When both are present, the query parameter wins. A missing or invalid key returns 401 Unauthorized.
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 responses are JSON with the same envelope: Success returns HTTP 200. Failures return the HTTP status listed in the error code list, but branch on error.code, not on the status.

Response examples

Error object structure


Data conventions

  • Timestamps are Unix epoch integers. Most are in seconds; some (most AI SRE and RUM timestamps, incident feed entries, audit logs) are in milliseconds. Every time field states its unit in its description.
  • Enums are case-sensitive strings or integers; each field lists its allowed values and what they mean.
  • IDs are returned as integers or strings exactly as documented per field; send them back in the same type.
  • Lists are paginated; see About pagination.
  • Updates: each update operation states, per field, whether an omitted field keeps its current value or is cleared.

Limits and errors

Rate limits, permission checks, the full error code list, and retry advice are on Rate limits and errors. Each operation page also lists its own rate limits and required permission under Restrictions.