> ## Documentation Index > Fetch the complete documentation index at: https://test-8ad8522e-feat-ai-sre.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Update escalation rule > Update an existing escalation rule configuration. ## Restrictions | Aspect | Value | | ----------- | ------------------------------------------------------------- | | Rate limits | **1,000 requests/minute**; **50 requests/second** per account | | Permissions | **Channels Manage** (`on-call`) | ## OpenAPI ````yaml /api-reference/on-call.openapi.en.json post /channel/escalate/rule/update openapi: 3.1.0 info: title: Flashduty Open API description: >- Public HTTP API for the Flashduty incident management platform — incidents, notification templates, channels, schedules, monitors, RUM, and platform administration. Every operation is authenticated with an `app_key` query parameter issued from the Flashduty console under Account → APP Keys. Responses follow a uniform envelope: `{ request_id, data }` on success, `{ request_id, error }` on failure. version: 1.0.0 servers: - url: https://api.flashcat.cloud description: Flashduty Open API security: - AppKeyAuth: [] tags: - name: On-call/Incidents description: '' - name: On-call/Channels description: '' - name: On-call/Alerts description: >- Search, inspect, and act on alerts. Manage card views and alert processing pipelines. - name: On-call/Integrations description: '' - name: On-call/IM integrations description: IM integration queries, such as which integrations have war room enabled. - name: On-call/Schedules description: '' - name: On-call/Licenses description: '' - name: On-call/Calendars description: '' - name: On-call/Notification templates description: '' - name: On-call/Alert enrichment description: Custom fields, enrichment rules, and data mapping (schema, data, API). - name: On-call/Analytics description: '' - name: On-call/Status pages description: '' - name: On-call/Changes description: '' paths: /channel/escalate/rule/update: post: tags: - On-call/Channels summary: Update escalation rule description: Update an existing escalation rule configuration. operationId: channelEscalateRuleUpdate requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateEscalationRuleRequest' example: channel_id: 1001 rule_id: 6621b23f4a2c5e0012ab34d0 template_id: 6621b23f4a2c5e0012ab34d1 rule_name: Default escalation layers: - target: person_ids: - 42 by: critical: - voice warning: - sms responses: '200': description: Success content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: $ref: '#/components/schemas/EmptyResponse' example: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 data: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/ServerError' components: schemas: UpdateEscalationRuleRequest: type: object description: Parameters for updating an escalation rule. required: - channel_id - rule_id - template_id - rule_name - layers properties: channel_id: type: integer format: int64 description: Owning channel ID; obtain it from `POST /channel/list`. rule_id: type: string pattern: ^[0-9a-fA-F]{24}$ description: Escalation rule ID (MongoDB ObjectID). priority: type: - integer - 'null' description: Evaluation priority. Lower runs first. aggr_window: type: integer description: Delay window in seconds. 0 disables delay. template_id: type: string pattern: ^[0-9a-fA-F]{24}$ description: Notification template ID (MongoDB ObjectID). rule_name: type: string minLength: 1 maxLength: 39 description: Rule name, 1 to 39 characters. description: type: string maxLength: 500 description: Rule description, up to 500 characters. layers: type: array items: $ref: '#/components/schemas/EscalateLayer' description: Escalation levels in order. At least one level is required. time_filters: type: array items: $ref: '#/components/schemas/TimeFilter' description: Optional recurring time windows during which the rule applies. filters: $ref: '#/components/schemas/FilterGroup' description: >- Incident-level match conditions (OR-of-AND tree): the rule is matched against the incident the alert was grouped into, not against the alert itself. Omit or leave empty to apply the rule to all incidents in the channel. SuccessEnvelope: type: object description: >- Success response envelope. On every 2xx response, `request_id` identifies the call (also mirrored in the `Flashcat-Request-Id` header) and `data` holds the endpoint-specific payload. Failure responses use a different shape — see `ErrorResponse`. properties: request_id: type: string description: >- Unique ID for this request. Mirrored in the Flashcat-Request-Id response header. Include it when reporting issues. example: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 data: description: Endpoint-specific payload. See each operation's 200 response schema. required: - request_id - data EmptyResponse: type: object description: 'Empty response body. The server returns `data: null` on success.' properties: {} EscalateLayer: type: object required: - target properties: max_times: type: integer minimum: 0 maximum: 6 description: Max repeat notifications within the level. notify_step: type: number format: float minimum: 0.5 maximum: 120 description: Repeat interval in minutes. target: $ref: '#/components/schemas/EscalateTarget' escalate_window: type: integer minimum: 0 maximum: 720 description: Wait before moving to the next level, in minutes. force_escalate: type: boolean description: When true, always escalate regardless of acknowledgement. TimeFilter: type: object description: >- Recurring time window. `start`/`end` use 24-hour `HH:MM` format; `repeat` lists ISO-style weekday indices (0=Sunday … 6=Saturday). properties: start: type: string description: Start of the window in `HH:MM`. end: type: string description: End of the window in `HH:MM`. repeat: type: array items: type: integer minimum: 0 maximum: 6 description: Days of the week this window repeats on. Empty means every day. cal_id: type: string description: >- Optional calendar ID; restricts the window to days matching the calendar. is_off: type: boolean description: When true, match days marked as days-off in the calendar. FilterGroup: $ref: '#/components/schemas/OrFilterGroup' ErrorResponse: type: object description: Response envelope for errors. `error` is required; `data` is absent. properties: request_id: type: string example: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 description: >- Unique trace ID of this request; include it when reporting issues so logs can be located. error: $ref: '#/components/schemas/DutyError' required: - request_id - error EscalateTarget: type: object description: >- Notification target. At least one of `person_ids`, `team_ids`, `schedule_to_role_ids`, or `emails` must be set, together with either `by` or `webhooks`. properties: person_ids: type: array items: type: integer format: int64 description: Member IDs to notify directly. team_ids: type: array items: type: integer format: int64 description: Team IDs to notify. schedule_to_role_ids: type: object additionalProperties: type: array items: type: integer format: int64 description: Map of schedule ID to the role IDs on that schedule to notify. emails: type: array items: type: string format: email description: Email addresses to notify (push-only scenarios). by: type: object description: >- Per-severity personal notification channels. Required unless `webhooks` is provided. properties: follow_preference: type: boolean description: >- When true, use each responder's personal preference instead of the lists below. critical: type: array items: type: string description: >- Notify channels used for Critical severity. Personal channels: `sms`, `voice`, `email`, `push`; IM group-chat channels: `feishu_app:`, `dingtalk_app:`, `wecom_app:`, `slack_app:`, `teams_app:`. warning: type: array items: type: string description: >- Notify channels used for Warning severity. Values as for `critical`. info: type: array items: type: string description: >- Notify channels used for Info severity. Values as for `critical`. webhooks: type: array description: Group chat / webhook targets. Required unless `by` is provided. items: type: object required: - type - settings properties: type: type: string description: >- Webhook type, one of `feishu`, `feishu_app`, `dingtalk`, `dingtalk_app`, `wecom`, `slack`, `slack_app`, `teams_app`, `telegram`, `zoom`. settings: type: object additionalProperties: true description: Type-specific settings (chat IDs, URLs, etc.). OrFilterGroup: type: array description: >- OR-of-AND filter tree. Outer array is a list of AND groups; the condition passes if **any** AND group matches. Within each AND group, **all** conditions must match. items: type: array description: AND group — all conditions in this array must match. items: $ref: '#/components/schemas/FilterCondition' DutyError: type: object description: >- Error payload inside the response envelope. Present only on non-2xx responses. properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: >- Human-readable error message, localized by the caller's Accept-Language. May contain field names, IDs, or other context from the failing request. example: The specified parameter template_id is not valid. required: - code - message FilterCondition: type: object required: - key - oper - vals properties: key: type: string description: >- Field name to filter on. Use plain names for built-in alert fields (e.g. `alert_severity`, `alert_key`, `check`, `resource`, `service`, `cluster`) or the `labels.` prefix for custom alert labels (e.g. `labels.env`, `labels.region`). oper: type: string enum: - IN - NOTIN description: >- Filter operator. `IN` — value must match one of `vals`; `NOTIN` — value must not match any of `vals`. Supports regex patterns wrapped in `/pattern/`. vals: type: array items: type: string description: >- List of values to match against. Each entry is a plain string or a `/regex/` pattern. ErrorCode: type: string description: >- Flashduty error code enum. Every failed API response sets `error.code` to one of these stable wire strings. HTTP status is informational — the authoritative signal is the enum value. | Code | HTTP | Meaning | |---|---|---| | `OK` | 200 | Reserved — not returned on real errors. | | `InvalidParameter` | 400 | A required parameter is missing or failed validation. | | `BadRequest` | 400 | Generic 400 used when no more specific code fits. | | `InvalidContentType` | 400 | The `Content-Type` header is not `application/json`. | | `ResourceNotFound` | 400 | The referenced resource does not exist. Note: returned as HTTP 400, not 404 (historical choice). | | `NoLicense` | 400 | The feature is license-gated and no active license was found. | | `ReferenceExist` | 400 | Deletion blocked — other entities still reference this resource. | | `Unauthorized` | 401 | `app_key` is missing, invalid, or expired. | | `BalanceNotEnough` | 402 | Billing-gated operation with insufficient account balance. | | `AccessDenied` | 403 | Authenticated but lacking the permission required for this operation. | | `RouteNotFound` | 404 | The request URL path is not a known route. | | `MethodNotAllowed` | 405 | The HTTP method is not allowed on this otherwise-known path. | | `UndonedOrderExist` | 409 | An outstanding billing order blocks this new one. Wait and retry. | | `RequestLocked` | 423 | Operation temporarily locked due to repeated failures. | | `EntityTooLarge` | 413 | Request body exceeds the configured max size. | | `RequestTooFrequently` | 429 | Rate limit hit — API-global, per-account, or per-integration. | | `RequestVerifyRequired` | 428 | Second-factor verification required but not supplied. | | `DangerousOperation` | 428 | High-risk operation requires MFA verification. | | `InternalError` | 500 | Unhandled server-side error. Include `request_id` in the bug report. | | `ServiceUnavailable` | 503 | A backend dependency is unavailable. Try again later. | enum: - OK - InvalidParameter - BadRequest - InvalidContentType - ResourceNotFound - NoLicense - ReferenceExist - Unauthorized - BalanceNotEnough - AccessDenied - RouteNotFound - MethodNotAllowed - UndonedOrderExist - RequestLocked - EntityTooLarge - RequestTooFrequently - RequestVerifyRequired - DangerousOperation - InternalError - ServiceUnavailable x-enumDescriptions: OK: Reserved — not returned on real errors. InvalidParameter: A required parameter is missing or failed validation. BadRequest: Generic 400 used when no more specific code fits. InvalidContentType: The `Content-Type` header is not `application/json`. ResourceNotFound: >- The referenced resource does not exist. Note: returned as HTTP 400, not 404 (historical choice). NoLicense: The feature is license-gated and no active license was found. ReferenceExist: Deletion blocked — other entities still reference this resource. Unauthorized: '`app_key` is missing, invalid, or expired.' BalanceNotEnough: Billing-gated operation with insufficient account balance. AccessDenied: Authenticated but lacking the permission required for this operation. RouteNotFound: The request URL path is not a known route. MethodNotAllowed: The HTTP method is not allowed on this otherwise-known path. UndonedOrderExist: An outstanding billing order blocks this new one. Wait and retry. RequestLocked: Operation temporarily locked due to repeated failures. EntityTooLarge: Request body exceeds the configured max size. RequestTooFrequently: Rate limit hit — API-global, per-account, or per-integration. RequestVerifyRequired: Second-factor verification required but not supplied. DangerousOperation: High-risk operation requires MFA verification. InternalError: Unhandled server-side error. Include `request_id` in the bug report. ServiceUnavailable: A backend dependency is unavailable. Try again later. example: InvalidParameter responses: BadRequest: description: Invalid request — usually a missing or malformed parameter. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingParameter: value: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 error: code: InvalidParameter message: The specified parameter is not valid. Unauthorized: description: Missing or invalid app_key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingAppKey: value: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 error: code: Unauthorized message: You are unauthorized. TooManyRequests: description: >- Rate limit hit. Either the global API limit, a per-account limit, or a per-integration limit. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: value: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 error: code: RequestTooFrequently message: Request too frequently. ServerError: description: Unexpected server-side error. Include the request_id when reporting. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal: value: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 error: code: InternalError message: >- We encountered an internal error, and it has been reported. Please try again later. securitySchemes: AppKeyAuth: type: apiKey in: query name: app_key description: >- App key issued from the Flashduty console under Account → APP Keys. Required on every public API call. Keep it secret — it grants the same access as the owning account. ````