> ## Documentation Index > Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt > Use this file to discover all available pages before exploring further. # Preview alert pipeline processing > Run unsaved alert processing rules over one event, the way ingestion would. ## Restrictions | Aspect | Value | | - | - | | Rate limits | **1,000 requests/minute**; **50 requests/second** per account | | Permissions | **Channels Manage** (`on-call`) or **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) | ## Usage * Nothing is saved and no alert or event is created. * The integration's saved enrichment rules run first, then your `rules` in order, against the enriched event. * A recovery (`Ok`) event closes the alert without running the pipeline: `is_recovery` is `true` and every step comes back `not_executed` with detail `recovery_event`. * `dropped` and `inhibited` report which rule stopped the event: `alert_drop` discards it, `alert_inhibit` discards it while a matching source alert is active. Rules after that one are `not_executed`. * When no rule matches, `after` is the event as the notification templates render it, so the preview shows what the channel would deliver. ## OpenAPI ````yaml /api-reference/on-call.openapi.en.json post /alert/pipeline/preview 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 created in the Flashduty console under My → APP Key (or sent in the `Fd-App-Key` header). 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: /alert/pipeline/preview: post: tags: - On-call/Alerts summary: Preview alert pipeline processing description: >- Run unsaved alert processing rules over one event, the way ingestion would. operationId: alert-read-pipeline-preview requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AlertPipelinePreviewRequest' example: integration_id: 6113996590131 rules: - kind: severity_reset if: - key: labels.env oper: IN vals: - test settings: severity: Info - kind: alert_drop if: - key: title oper: IN vals: - /.*noise.*/ settings: {} event: title: Disk usage 95% on db-3 description: Root filesystem is 95% full on db-3. event_status: Warning labels: service: mysql env: prod host: db-3 responses: '200': description: Success content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: $ref: '#/components/schemas/AlertPipelinePreviewResponse' example: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 data: is_recovery: false before: title: Disk usage 95% on db-3 description: Root filesystem is 95% full on db-3. severity: Warning labels: service: mysql env: prod host: db-3 after: title: Disk usage 95% on db-3 description: Root filesystem is 95% full on db-3. severity: Warning labels: service: mysql env: prod host: db-3 dropped: false inhibited: false steps: - index: 0 kind: severity_reset result: not_matched detail: condition_not_met - index: 1 kind: alert_drop result: not_matched detail: condition_not_met '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/ServerError' components: schemas: AlertPipelinePreviewRequest: type: object description: Request body of `POST /alert/pipeline/preview`. required: - integration_id - event properties: integration_id: type: integer format: int64 minimum: 1 description: >- Integration whose saved enrichment runs first and whose pipeline context the preview uses. rules: type: array maxItems: 50 items: $ref: '#/components/schemas/AlertPipeline' description: >- Alert processing rules to try, in order. At most 50. The integration's stored pipeline is not used. event: $ref: '#/components/schemas/AlertEvent' description: The event to run the rules over. 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: >- Operation-specific payload, documented in each operation's 200 response. Operations without a payload return `{}` or omit `data` entirely. required: - request_id AlertPipelinePreviewResponse: type: object description: Result of the pipeline preview. required: - is_recovery - before - after - dropped - inhibited - steps properties: is_recovery: type: boolean description: >- `true` when the event is a recovery event: ingestion closes the alert without running the pipeline. before: $ref: '#/components/schemas/AlertPipelinePreviewEvent' description: The event as it arrived. after: $ref: '#/components/schemas/AlertPipelinePreviewEvent' description: >- The event as notification templates would render it once the rules ran. dropped: type: boolean description: '`true` when a rule dropped the event, so no alert would be created.' inhibited: type: boolean description: >- `true` when a rule inhibited the event because a matching source alert is active. steps: type: array items: $ref: '#/components/schemas/PipelineStep' description: One entry per rule, in the order they ran. AlertPipeline: type: object description: A single alert processing rule. properties: kind: type: string enum: - title_reset - description_reset - severity_reset - alert_drop - alert_inhibit description: >- Rule type. Rules run in array order; when the `if` condition matches, the event is processed according to `kind`. | Value | Meaning | |---|---| | `title_reset` | Rewrites the event title from the `settings.title` template. | | `description_reset` | Rewrites the event description from the `settings.description` template. | | `severity_reset` | Resets the event severity and status to `settings.severity` (`Critical`/`Warning`/`Info`). | | `alert_drop` | Discards the matching event outright; no alert is created. | | `alert_inhibit` | Discards the event (inhibition) when an active source alert matching `settings.source_filters` and correlated via `settings.equals` exists. | if: type: - array - 'null' items: $ref: '#/components/schemas/FilterCondition' description: >- AND-filter list — the rule applies only when every condition matches the incoming event. Keys: `severity` (aliases `alert_severity`, `event_severity`), `status`, `title`, `title_rule`, `description`, `alert_key`, `integration_id` (alias `data_source_id`), and `labels.`; other keys return `InvalidParameter`. `null` or omitted means the rule applies to all events. settings: type: object description: >- Kind-specific settings. Shape depends on `kind`: - `title_reset`: `{ "title": "" }` - `description_reset`: `{ "description": "" }` - `severity_reset`: `{ "severity": "Critical"|"Warning"|"Info" }` - `alert_drop`: `{}` (empty object) - `alert_inhibit`: `{ "equals": ["", ...], "source_filters": }` oneOf: - $ref: '#/components/schemas/ApTitleReset' - $ref: '#/components/schemas/ApDescriptionReset' - $ref: '#/components/schemas/ApSeverityReset' - $ref: '#/components/schemas/ApAlertDrop' - $ref: '#/components/schemas/ApAlertInhibit' required: - kind AlertEvent: type: object description: >- One raw alert event, in the shape the ingestion pipeline receives and stores. required: - event_status properties: title: type: string description: >- Event title. Required unless `title_rule` is set; the two are the source of the alert title. title_rule: type: string description: >- Title template such as `$service::$alertname`, built from `labels` when `title` is empty. description: type: string description: Event description, truncated to 2048 characters. alert_key: type: string description: >- Deduplication key that merges events into one alert. Empty is allowed: the preview mints a random key, so nothing is merged. event_status: type: string enum: - Critical - Warning - Info - Ok description: >- Event status. `Critical`, `Warning` and `Info` are firing events; `Ok` is a recovery. event_severity: type: string enum: - Critical - Warning - Info description: >- Severity carried by a firing event. The preview overwrites it with `event_status` for firing events. event_time: type: integer format: int64 description: >- Unix timestamp in seconds. The preview stamps the current time, so the value sent is ignored. labels: type: object additionalProperties: type: string description: >- Event labels. Up to 50 entries; keys are label names, values strings. images: type: array items: $ref: '#/components/schemas/AlertImage' description: Images attached to the event. AlertPipelinePreviewEvent: type: object description: The event as the pipeline preview saw it. required: - title - description - severity - labels properties: title: type: string description: Event title. description: type: string description: Event description. severity: type: string enum: - Critical - Warning - Info - Ok description: Severity the event carried at this point. labels: type: object additionalProperties: type: string description: Label set. PipelineStep: type: object description: What one alert processing rule did to the event. required: - index - kind - result - detail properties: index: type: integer description: Zero-based position of the rule in `rules`. kind: type: string enum: - title_reset - description_reset - severity_reset - alert_drop - alert_inhibit description: >- Rule type that ran. | Value | Meaning | |---|---| | `title_reset` | Rewrote the title from the rule's template. | | `description_reset` | Rewrote the description from the rule's template. | | `severity_reset` | Reset the severity and status to the rule's `severity`. | | `alert_drop` | Discarded the event; no alert is created. | | `alert_inhibit` | Discarded the event while a matching source alert is active. | result: type: string enum: - applied - not_matched - not_executed description: >- Outcome of the rule: `applied` (it changed the event or stopped the pipeline), `not_matched` (its `if` conditions did not all match), or `not_executed` (an earlier rule stopped the pipeline, or the event is a recovery). detail: type: string description: >- `condition_not_met`, `no_active_source_alert`, `inhibit_not_evaluated` or `recovery_event` for those outcomes; otherwise the resulting value or the error message. 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 FilterCondition: type: object required: - key - oper - vals properties: key: type: string description: >- Field to match. Which built-in keys are allowed depends on the rule type and is listed on the field that holds the conditions; any `labels.` key (for example `labels.env`) is always accepted. An unknown key returns `InvalidParameter`. When the alert or incident has no value for the key, `IN` does not match and `NOTIN` matches. oper: type: string enum: - IN - NOTIN description: >- Match operator, case-sensitive. `IN`: matches when the field value matches any entry in `vals`. `NOTIN`: matches when it matches none of them. vals: type: array items: type: string description: >- Values to compare, at least one. Each entry is matched as: an exact string; a wildcard pattern when it contains `*` or `?` (must match the whole value); a regular expression when wrapped in slashes, such as `/^db-/` (may match anywhere in the value); an IP range written `cidr:`, such as `cidr:203.0.113.0/24`; or a numeric comparison `num::` with `lt`, `le`, `gt` or `ge`, such as `num:gt:90`. ApTitleReset: type: object description: 'Settings for `title_reset`: replaces the event title using a title rule.' required: - title properties: title: type: string description: >- Title rule. A value starting with `[TPL]` is a Go template rendered against the event, e.g. `[TPL]{{.Labels.service}}`. Otherwise it is a `::`-separated list in which each `$name` part is replaced by the value of label `name` and other parts are kept as written. ApDescriptionReset: type: object description: >- Settings for `description_reset`: replaces the event description with a rendered template. required: - description properties: description: type: string description: >- Description template. Only a value starting with `[TPL]` takes effect: the rest is rendered as a Go template against the event and replaces the description. A value without the prefix leaves the description unchanged. ApSeverityReset: type: object description: >- Settings for `severity_reset`: sets the event severity, and its status, to a fixed value. required: - severity properties: severity: type: string enum: - Critical - Warning - Info description: >- Severity to set: `Critical`, `Warning` or `Info`. The event status is set to the same value. ApAlertDrop: type: object description: >- Settings for `alert_drop`: no fields; send `{}`. A matching event is discarded and no alert is created or updated. properties: {} ApAlertInhibit: type: object description: >- Settings for `alert_inhibit`: the current event is discarded when an active alert of the same integration, with a different `alert_key` and started within the 10 minutes before the event, matches `source_filters` and has the same value as the event for every `equals` key. required: - equals - source_filters properties: equals: type: array items: type: string description: >- Keys whose values must be equal on the source alert and the current event: `title`, `severity`, or `labels.`. An empty list, any other key, or a label missing on the event means the rule never inhibits. source_filters: type: array items: $ref: '#/components/schemas/FilterCondition' description: >- AND-conditions a source alert must meet. Allowed keys: `severity`, `title`, and `labels.`; other keys return `InvalidParameter`. AlertImage: type: object description: An image attachment on an alert or event. required: - src properties: href: type: string description: Optional link URL when the image is clicked. src: type: string description: >- Image source URL or internal image reference (starts with `img_` or `http`). alt: type: string description: >- Alternative text shown when the image cannot be displayed; empty when not set. 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 in the response language (`locale` / `lang` query parameter or `Accept-Language` header). May name the offending field; do not parse it. example: The specified parameter template_id is not valid. required: - code - message ErrorCode: type: string description: >- Error code. Every failed response sets `error.code` to one of these stable strings; branch on it rather than on the HTTP status. | Code | HTTP | Meaning | |---|---|---| | `OK` | 200 | Reserved; never returned on a failed request. | | `InvalidParameter` | 400 | A parameter is missing, has the wrong type, or failed validation; `message` usually names the field. | | `BadRequest` | 400 | The request breaks a business rule or conflicts with the current state of an object; `message` says which. | | `InvalidContentType` | 400 | The body is not sent as `application/json`. | | `ResourceNotFound` | 400 | The referenced object does not exist in this account or was deleted. Returned as HTTP 400, not 404. | | `NoLicense` | 400 | The account's plan does not include the feature, a plan quota is used up, the plan has expired, or credits are insufficient. | | `ReferenceExist` | 400 | The object is still referenced by other objects, so it cannot be deleted. | | `Unauthorized` | 401 | The APP Key is missing, invalid, or deleted. | | `BalanceNotEnough` | 402 | Console-only (billing); not returned by Open API operations. | | `AccessDenied` | 403 | The APP Key's permission scope or the creator's role does not allow this operation or object. | | `RouteNotFound` | 404 | No operation matches the HTTP method and path. | | `MethodNotAllowed` | 405 | The path exists but not for this HTTP method. | | `UndonedOrderExist` | 409 | Console-only (billing); not returned by Open API operations. | | `EntityTooLarge` | 413 | The request body exceeds the size limit. | | `RequestLocked` | 423 | Console-only (sign-in protection); not returned by Open API operations. | | `RequestVerifyRequired` | 428 | Console-only (verification code); not returned by Open API operations. | | `DangerousOperation` | 428 | Console-only (MFA for high-risk actions); not returned by Open API operations. | | `RequestTooFrequently` | 429 | A rate limit was hit; wait for the `Flashcat-Request-Rate-Limit-Delay` response header (seconds) before retrying. | | `InternalError` | 500 | Unexpected server error; retry with backoff and include `request_id` when reporting. | | `ServiceUnavailable` | 503 | A backend dependency is overloaded or unavailable; retry with backoff. | enum: - OK - InvalidParameter - BadRequest - InvalidContentType - ResourceNotFound - NoLicense - ReferenceExist - Unauthorized - BalanceNotEnough - AccessDenied - RouteNotFound - MethodNotAllowed - UndonedOrderExist - EntityTooLarge - RequestLocked - RequestVerifyRequired - DangerousOperation - RequestTooFrequently - InternalError - ServiceUnavailable x-enumDescriptions: OK: Reserved; never returned on a failed request. InvalidParameter: >- A parameter is missing, has the wrong type, or failed validation; `message` usually names the field. BadRequest: >- The request breaks a business rule or conflicts with the current state of an object; `message` says which. InvalidContentType: The body is not sent as `application/json`. ResourceNotFound: >- The referenced object does not exist in this account or was deleted. Returned as HTTP 400, not 404. NoLicense: >- The account's plan does not include the feature, a plan quota is used up, the plan has expired, or credits are insufficient. ReferenceExist: >- The object is still referenced by other objects, so it cannot be deleted. Unauthorized: The APP Key is missing, invalid, or deleted. BalanceNotEnough: Console-only (billing); not returned by Open API operations. AccessDenied: >- The APP Key's permission scope or the creator's role does not allow this operation or object. RouteNotFound: No operation matches the HTTP method and path. MethodNotAllowed: The path exists but not for this HTTP method. UndonedOrderExist: Console-only (billing); not returned by Open API operations. EntityTooLarge: The request body exceeds the size limit. RequestLocked: >- Console-only (sign-in protection); not returned by Open API operations. RequestVerifyRequired: Console-only (verification code); not returned by Open API operations. DangerousOperation: >- Console-only (MFA for high-risk actions); not returned by Open API operations. RequestTooFrequently: >- A rate limit was hit; wait for the `Flashcat-Request-Rate-Limit-Delay` response header (seconds) before retrying. InternalError: >- Unexpected server error; retry with backoff and include `request_id` when reporting. ServiceUnavailable: A backend dependency is overloaded or unavailable; retry with backoff. 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. Forbidden: description: >- The app_key is valid, but its permission scope or the creator's role does not allow this operation or object. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: noEditPermission: value: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 error: code: AccessDenied message: Access Denied. TooManyRequests: description: >- Rate limit hit. Wait for the number of seconds in `Flashcat-Request-Rate-Limit-Delay`, then retry. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: value: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 error: code: RequestTooFrequently message: Request too frequently. headers: Flashcat-Request-Rate-Limit-Delay: description: >- Seconds until the current rate-limit window resets. Absent when the request was rejected by the gateway's global protection limit. schema: type: integer minimum: 0 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 created in the Flashduty console under My → APP Key. Send it as the `app_key` query parameter or in the `Fd-App-Key` request header. Its effective access is the intersection of the key's permission scope and the creator's current role permissions. Keep it secret. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.