ysyneu · Oct 17, 2026 · Oct 17, 2026 · Oct 17, 2026 · Oct 17, 2026
diff --git a/.github/workflows/openapi-lint.yml b/.github/workflows/openapi-lint.yml
@@ -1,9 +1,11 @@
 name: Lint OpenAPI specs
 
 # Quality gate for the public API reference. Fails on undocumented schema
-# properties, epoch time fields without Unix/timestamp wording, string enums
-# whose values are not explained in the description, and operations without
-# request/response examples. See scripts/lint_openapi.py for the rules.
+# properties, epoch time fields without Unix/timestamp wording, enums whose
+# values are not explained in the description, `required` entries that name
+# undeclared properties, operations without examples or a 403 response,
+# examples that do not match their schema, and over-long operation
+# descriptions. See scripts/lint_openapi.py for the rules.
 
 on:
   pull_request:

diff --git a/api-reference/monitors.openapi.en.json b/api-reference/monitors.openapi.en.json
diff --git a/api-reference/monitors.openapi.zh.json b/api-reference/monitors.openapi.zh.json
diff --git a/api-reference/on-call.openapi.en.json b/api-reference/on-call.openapi.en.json
diff --git a/api-reference/on-call.openapi.zh.json b/api-reference/on-call.openapi.zh.json
diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json
diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json
diff --git a/api-reference/platform.openapi.en.json b/api-reference/platform.openapi.en.json
diff --git a/api-reference/platform.openapi.zh.json b/api-reference/platform.openapi.zh.json
diff --git a/api-reference/rum.openapi.en.json b/api-reference/rum.openapi.en.json
diff --git a/api-reference/rum.openapi.zh.json b/api-reference/rum.openapi.zh.json
diff --git a/api-reference/safari.openapi.en.json b/api-reference/safari.openapi.en.json
diff --git a/api-reference/safari.openapi.zh.json b/api-reference/safari.openapi.zh.json
diff --git a/en/developer/go-sdk.mdx b/en/developer/go-sdk.mdx
@@ -325,7 +325,7 @@ for page := 0; page < 100; page++ {
 
 An unsuccessful call returned by the Flashduty API — whether the envelope carries an error or the HTTP status is non-2xx — returns `*ErrorResponse`. It has `Code`, `Message`, an optional `Reason`, and `RequestID` fields; when troubleshooting, give `RequestID` to the support team to pinpoint the request. `Reason` carries the server-supplied optional cause (the envelope's `DutyError` has the same field, JSON `reason`,omitempty); when non-empty it is also appended to the end of the error string, as `, reason X`.
 
-When the API returns 429, the error is promoted to `*RateLimitError`: it embeds `*ErrorResponse` (so `errors.As` for `*ErrorResponse` still matches) and additionally carries a `RetryAfter` hint. `Code` values match the Open API [error code list](/en/openapi/introduction#error-code-list).
+When the API returns 429, the error is promoted to `*RateLimitError`: it embeds `*ErrorResponse` (so `errors.As` for `*ErrorResponse` still matches) and additionally carries a `RetryAfter` hint. `Code` values match the Open API [error code list](/en/openapi/rate-limits#error-codes).
 
 <Note>
 For **generated endpoints**, if you receive a non-2xx response with a non-JSON body, the SDK returns a plain `error`, not `*ErrorResponse`. This indicates that a gateway, load balancer, proxy, or other intermediary produced the response, usually because the request exceeded an intermediary timeout. Retry the request or split a long-running batch into smaller batches, and do not assume that `errors.As(err, &apiErr)` matches this error.

diff --git a/en/openapi/api-catalog.mdx b/en/openapi/api-catalog.mdx
@@ -3,7 +3,7 @@ title: "API catalog"
 description: "Complete list of Flashduty Open API endpoints, organized by product module with links to detailed documentation"
 ---
 
-Flashduty Open API provides **365** endpoints covering five major modules: On-call, Monitors, RUM, AI SRE, and Platform. All endpoints use unified authentication and request specifications. See [Quick Start](/en/openapi/introduction) for details.
+Flashduty Open API provides **370** endpoints covering five major modules: On-call, Monitors, RUM, AI SRE, and Platform. All endpoints use unified authentication and request specifications. See [Quick Start](/en/openapi/introduction) for details.
 
 <Note>
 All endpoint URLs use `https://api.flashcat.cloud` as the base, authenticated through APP Key through query string.
@@ -282,7 +282,7 @@ The `/integration/*` management APIs cover public (account-level) integrations,
 
 </Accordion>
 
-<Accordion title="Monitors (41 endpoints)">
+<Accordion title="Monitors (46 endpoints)">
 
 ### Alert rules
 
@@ -358,6 +358,11 @@ Alert rule import and export are available in the console only (the YAML rule bu
 | Method | Endpoint | Description |
 | :--- | :--- | :--- |
 | POST | [`/monit/folder/list`](/en/api-reference/monitors/rule-folders/monit-folder-read-list) | List monitor folders |
+| POST | [`/monit/folder/health`](/en/api-reference/monitors/rule-folders/monit-folder-read-health) | Get monitor folder health |
+| POST | [`/monit/folder/create`](/en/api-reference/monitors/rule-folders/monit-folder-write-create) | Create monitor folder |
+| POST | [`/monit/folder/update`](/en/api-reference/monitors/rule-folders/monit-folder-write-update) | Update monitor folder |
+| POST | [`/monit/folder/move`](/en/api-reference/monitors/rule-folders/monit-folder-write-move) | Move monitor folder |
+| POST | [`/monit/folder/delete`](/en/api-reference/monitors/rule-folders/monit-folder-write-delete) | Delete monitor folder |
 
 </Accordion>
 

diff --git a/en/openapi/introduction.mdx b/en/openapi/introduction.mdx
@@ -21,29 +21,35 @@ Open API lets you call Flashduty through HTTP endpoints to query and manage enti
 
 ### Request URL
 
-All APIs only accept access through **HTTPS** protocol and have a single Endpoint:
+All APIs are served over **HTTPS** from a single endpoint:
 
 ```
 https://api.flashcat.cloud
 ```
 
-### Headers
+### Method and headers
 
-Most requests use the POST method with JSON Payload parameters. Please ensure the correct Content-Type is set:
+Almost every operation is a `POST` with a JSON body, so set:
 
 ```
 Content-Type: application/json
 ```
 
+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 APIs use **UTF-8** 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 use **APP Key** for authentication.
+All Open APIs authenticate with an **APP Key**.
 
 ### Obtaining an APP key
 
@@ -60,21 +66,32 @@ All Open APIs use **APP Key** for authentication.
 </Steps>
 
 <Warning>
-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.
+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.
 </Warning>
 
 You can edit an existing APP Key's name and permission scope from the APP Key list.
 
-### Usage example
+### Passing the APP key
 
-Pass the APP Key as a query string parameter:
+Pass the key as the `app_key` query parameter:
 
 ```bash
-curl -X POST 'https://api.flashcat.cloud/your/api/path?app_key=YOUR_APP_KEY' \
+curl -X POST 'https://api.flashcat.cloud/incident/list?app_key=YOUR_APP_KEY' \
   -H 'Content-Type: application/json' \
-  -d '{"param": "value"}'
+  -d '{"start_time": 1712000000, "end_time": 1712086400, "limit": 20}'
 ```
 
+Or send it in the `Fd-App-Key` request header, which keeps the key out of URLs and access logs:
+
+```bash
+curl -X POST 'https://api.flashcat.cloud/incident/list' \
+  -H 'Fd-App-Key: YOUR_APP_KEY' \
+  -H 'Content-Type: application/json' \
+  -d '{"start_time": 1712000000, "end_time": 1712086400, "limit": 20}'
+```
+
+When both are present, the query parameter wins. A missing or invalid key returns `401 Unauthorized`.
+
 <Note>
 Using Go? Use the official [Go SDK](/en/developer/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>
@@ -83,35 +100,37 @@ Using Go? Use the official [Go SDK](/en/developer/go-sdk) to call Flashduty —
 
 ## Response structure
 
-All request responses are in JSON format and follow a unified structure:
+All responses are JSON with the same envelope:
 
-| Field | Type | Required | Description |
+| Field | Type | Always present | 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 |
+| `request_id` | string | ✅ | Request ID, also returned in the `Flashcat-Request-Id` response header. Include it when contacting support. |
+| `data` | any | | Operation-specific payload, documented on each operation page. Operations with no payload return `{}` or omit `data` entirely, so do not rely on its presence. Absent on errors. |
+| `error` | object | | Present only when the request failed. |
+
+Success returns HTTP `200`. Failures return the HTTP status listed in the [error code list](/en/openapi/rate-limits#error-codes), but branch on `error.code`, not on the status.
 
 ### Response examples
 
 <Tabs>
   <Tab title="Success Response">
 ```json
 {
-  "request_id": "abc123456",
+  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
   "data": {
-    "id": "user_001",
-    "name": "example"
+    "team_id": 1467226103121,
+    "team_name": "SRE"
   }
 }
 ```
   </Tab>
   <Tab title="Error Response">
 ```json
 {
-  "request_id": "abc123456",
+  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
   "error": {
     "code": "InvalidParameter",
-    "message": "Parameter name cannot be empty"
+    "message": "The specified parameter team_name is not valid."
   }
 }
 ```
@@ -120,104 +139,23 @@ All request responses are in JSON format and follow a unified structure:
 
 ### Error object structure
 
-| Field | Type | Required | Description |
+| Field | Type | Always present | Description |
 | --- | --- | :---: | --- |
-| `code` | string | ✅ | Error code, see [Error Code List](#error-code-list) below |
-| `message` | string | | Error description |
+| `code` | string | ✅ | Stable error code, see the [error code list](/en/openapi/rate-limits#error-codes) |
+| `message` | string | ✅ | Human-readable description in the response language; may name the offending field. Do not parse it. |
 
 ---
 
-## 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
-
-- 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 |
-
----
+## Data conventions
 
-## 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 (for example, 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>
+- **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](/en/openapi/pagination).
+- **Updates**: each update operation states, per field, whether an omitted field keeps its current value or is cleared.
 
 ---
 
-## Best practices
+## Limits and errors
 
-- **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.
+Rate limits, permission checks, the full error code list, and retry advice are on [Rate limits and errors](/en/openapi/rate-limits). Each operation page also lists its own rate limits and required permission under **Restrictions**.