Request specifications
Request URL
All APIs are served over HTTPS from a single endpoint:Method and headers
Almost every operation is aPOST with a JSON body, so set:
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 thelocale 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.
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 theapp_key query parameter:
Fd-App-Key request header, which keeps the key out of URLs and access logs:
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
- Success Response
- Error Response
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.