> ## 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. # Create escalation rule > Create an escalation rule defining who gets notified and when during an incident. ## 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/create 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/create: post: tags: - On-call/Channels summary: Create escalation rule description: >- Create an escalation rule defining who gets notified and when during an incident. operationId: channelEscalateRuleCreate requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateEscalationRuleRequest' example: channel_id: 3521074710131 rule_name: On-call escalation template_id: 6321aad26c12104586a88916 description: >- Notify primary on-call, then escalate to secondary after 30 minutes layers: - target: person_ids: - 3790925372131 by: follow_preference: true max_times: 3 notify_step: 10 escalate_window: 30 force_escalate: false responses: '200': description: Success content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: $ref: '#/components/schemas/RuleCreateResponse' example: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 data: rule_id: 69db2f72a0fe7db6448b1506 rule_name: Test escalation rule '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/ServerError' components: schemas: CreateEscalationRuleRequest: type: object description: Parameters for creating an escalation rule. required: - channel_id - template_id - rule_name - layers properties: channel_id: type: integer format: int64 description: Owning channel ID; obtain it from `POST /channel/list`. priority: type: - integer - 'null' minimum: 0 maximum: 200 description: Evaluation priority. Lower runs first. aggr_window: type: integer minimum: 0 maximum: 3600 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 description: Escalation levels in order. At least one level is required. items: 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: 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; obtain member IDs from `POST /member/list`. team_ids: type: array items: type: integer format: int64 description: >- Team IDs to notify; obtain team IDs from `POST /team/list`. 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.). 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. time_filters: type: array items: type: object description: >- Recurring time window. `start`/`end` use 24-hour `HH:MM` format; `repeat` uses 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 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. description: Optional recurring time windows during which the rule applies. filters: type: array 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. items: type: array items: type: object required: - key - oper - vals properties: key: type: string description: Field key (e.g. `alert_severity`, `labels.service`). oper: type: string enum: - IN - NOTIN description: Filter operator. vals: type: array items: type: string description: Values to match. 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 RuleCreateResponse: type: object required: - rule_id - rule_name properties: rule_id: type: string pattern: ^[0-9a-fA-F]{24}$ description: Newly created rule ID (MongoDB ObjectID). rule_name: type: string description: Rule name echoed back from the request. 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 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 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. ````