> ## 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 enrichment rule results > Run unsaved enrichment 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. * `integration_id` must be an integration of the account, and the caller must be allowed to read it. * A `mapping` rule with `mapping_type` = `api` calls the account's mapping API with its stored headers, so the request also needs permission to edit the integration; without it the call fails. * `before` is the event as it arrived, `after` is the event after the rules; `steps` explains every rule — whether its conditions matched, why it was skipped, and which labels it added, removed or rewrote. * A firing event is rendered the way ingestion does after enrichment, so `[TPL]` labels, title and description in `after` are the final ones. * `if` keys must come from the alert or change event vocabulary (`title`, `description`, `labels.`, ...); other keys return `InvalidParameter`. ## OpenAPI ````yaml /api-reference/on-call.openapi.en.json post /enrichment/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: /enrichment/preview: post: tags: - On-call/Alert enrichment summary: Preview enrichment rule results description: Run unsaved enrichment rules over one event, the way ingestion would. operationId: enrichment-read-preview requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EnrichmentPreviewRequest' example: integration_id: 6113996590131 rules: - kind: extraction if: - key: labels.env oper: IN vals: - prod settings: source_field: labels.host result_label: service_name pattern: ^(?P[a-z0-9-]+)-\d+$ override: false event: title: CPU usage 94% on checkout-7 description: CPU usage above 90% for 5 minutes. event_status: Critical labels: env: prod host: checkout-7 check: cpu responses: '200': description: Success content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: $ref: '#/components/schemas/EnrichmentPreviewResponse' example: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 data: before: title: CPU usage 94% on checkout-7 labels: check: cpu env: prod host: checkout-7 after: title: CPU usage 94% on checkout-7 labels: check: cpu env: prod host: checkout-7 service_name: checkout steps: - index: 0 kind: extraction matched: true skipped_reason: '' detail: checkout added: service_name: checkout removed: null changed: null mapping_row: null '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: EnrichmentPreviewRequest: type: object description: Request body of `POST /enrichment/preview`. required: - integration_id - event properties: integration_id: type: integer format: int64 minimum: 1 description: >- Integration whose context the preview runs in. The rules you send are not saved. rules: type: array maxItems: 50 items: $ref: '#/components/schemas/EnrichRule' description: >- Enrichment rules to try, in order. At most 50. The integration's stored rules are 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 EnrichmentPreviewResponse: type: object description: Result of the enrichment preview. required: - before - after - steps properties: before: $ref: '#/components/schemas/EnrichmentPreviewEvent' description: The event as it arrived. after: $ref: '#/components/schemas/EnrichmentPreviewEvent' description: >- The event after the rules ran, with the `[TPL]` labels, title and description of a firing event rendered. steps: type: array items: $ref: '#/components/schemas/EnrichStep' description: One entry per rule, in the order they ran. EnrichRule: type: object required: - kind - settings description: >- An enrichment rule with an optional condition and type-specific settings. properties: kind: type: string enum: - extraction - composition - mapping - drop description: >- Rule type. | Value | Meaning | |---|---| | `extraction` | Extract a value from the alert's `title`, `description`, or a `labels.*` key via regex or GJson, and write it to a label. | | `composition` | Render a Go `text/template` against the event and write the result to a label. | | `mapping` | Look up labels from a mapping schema or an external mapping API. | | `drop` | Remove the listed labels from the alert. | if: type: - array - 'null' items: $ref: '#/components/schemas/EnrichFilter' description: >- Optional AND-filter list; the rule is skipped unless every filter matches. `null` when the rule has no condition. Filter keys come from the alert/change event vocabulary (e.g. `title`, `labels.severity`). settings: description: Rule-kind–specific settings. The shape depends on `kind`. discriminator: propertyName: kind mapping: extraction: '#/components/schemas/ErsExtraction' composition: '#/components/schemas/ErsComposition' mapping: '#/components/schemas/ErsMapping' drop: '#/components/schemas/ErsDrop' oneOf: - $ref: '#/components/schemas/ErsExtraction' - $ref: '#/components/schemas/ErsComposition' - $ref: '#/components/schemas/ErsMapping' - $ref: '#/components/schemas/ErsDrop' 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. EnrichmentPreviewEvent: type: object description: The event as the enrichment preview saw it. required: - title - labels properties: title: type: string description: Event title after the steps applied so far. labels: type: object additionalProperties: type: string description: Label set after the steps applied so far. EnrichStep: type: object description: What one enrichment rule did to the event. required: - index - kind - matched - skipped_reason - detail - added - removed - changed - mapping_row properties: index: type: integer description: Zero-based position of the rule in `rules`. kind: type: string enum: - extraction - composition - mapping - drop description: >- Rule type that ran. | Value | Meaning | |---|---| | `extraction` | Extract a value from the alert's `title`, `description` or a `labels.*` key and write it to a label. | | `composition` | Render a template against the event and write the result to a label. | | `mapping` | Look up labels from a mapping schema or an external mapping API. | | `drop` | Remove the listed labels from the alert. | matched: type: boolean description: >- Whether the rule's `if` conditions all matched. `false` means the rule changed nothing. skipped_reason: type: string description: >- Why the rule was skipped: `condition_not_met`, `regex_not_matched`, `source_label_missing`, `mapping_row_not_found`, `result_label_exists` or `error`. Empty when the rule ran. detail: type: string description: >- Rule-specific detail: the matched mapping row, the rendered value, or the error message when `skipped_reason` is `error`. added: type: - object - 'null' additionalProperties: type: string description: >- Labels the rule wrote that were not there before. `null` when it added none. removed: type: - array - 'null' items: type: string description: Labels the rule deleted. `null` when it removed none. changed: type: - object - 'null' additionalProperties: type: string description: >- Labels the rule rewrote, each as a `[old_value, new_value]` pair. `null` when it rewrote none. mapping_row: type: - object - 'null' additionalProperties: type: string description: >- The mapping row the rule matched. `null` for a rule that is not a mapping rule or matched no row. 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 EnrichFilter: type: object required: - key - oper - vals description: A single label filter condition. properties: key: type: string description: >- Event key to match on: `title`, `description`, `labels.` or another alert/change event key. A `labels.` key must use a valid label name. minLength: 1 oper: type: string enum: - IN - NOTIN description: >- Match operator. - `IN`: matches when the key's value matches any of `vals`. A key missing from the event never matches. - `NOTIN`: matches when the value matches none of `vals`. A key missing from the event always matches. vals: type: array items: type: string description: >- Values to match (at least one). Each value is one of: an exact string; `/regex/` for a regular expression; a wildcard pattern with `*` and `?`; `cidr:` (e.g. `cidr:203.0.113.0/24`) for an IP range; `num:lt:`, `num:le:`, `num:gt:` or `num:ge:` for a numeric comparison. minItems: 1 ErsExtraction: type: object title: extraction required: - source_field - result_label properties: source_field: type: string description: >- Source field to extract from. Must be `title`, `description`, or a label key prefixed with `labels.` (e.g. `labels.env`). result_label: type: string description: >- Destination label key the extracted value is written to. Must match `^[a-zA-Z_][a-zA-Z0-9_]*$`. pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$ pattern: type: string description: >- Regular expression (RE2) applied to the source value; may be wrapped in `/.../`. All capture groups are joined with a space and written to `result_label`. Nothing is written when the expression does not match, has no capture group, or the first group is empty. Exactly one of `pattern` and `g_json` must be set. g_json: type: string description: >- GJSON path (a leading `$.` is ignored) used when the source value is a JSON string, e.g. `host.name`. If the source value is not valid JSON the rule is skipped; if the path does not exist an empty string is written. Exactly one of `pattern` and `g_json` must be set. override: type: boolean description: >- When `false` (default) the rule is skipped if `result_label` already exists on the event; when `true` the existing value is overwritten. ErsComposition: type: object title: composition required: - result_label - template properties: result_label: type: string description: >- Destination label key the composed value is written to. Must match `^[a-zA-Z_][a-zA-Z0-9_]*$`. pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$ template: type: string maxLength: 500 description: >- Go `text/template` string (1–500 characters) rendered against the event struct — e.g. `{{.Title}}`, `{{.Description}}`, `{{.Labels.key}}`. Example: `{{.Labels.region}}-{{.Labels.env}}`. minLength: 1 override: type: boolean description: >- When `false` (default) the rule is skipped if `result_label` already exists on the event; when `true` the existing value is overwritten. ErsMapping: type: object title: mapping required: - result_labels properties: result_labels: type: array items: type: string pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$ description: >- Label keys to fill from the lookup result (at least one). For `schema` they are normally the schema's `result_labels`; for `api` they are sent to the API as `result_label_keys`. minItems: 1 mapping_type: type: string enum: - schema - api default: schema description: >- Lookup source. - `schema` (default): look up a row in the mapping schema `schema_id` using the event's values of the schema's `source_labels`; the rule does nothing if any source label is missing or no row matches. - `api`: call the mapping API `api_id` with the event; runs for alert events only. schema_id: type: string description: >- Mapping schema ID (MongoDB ObjectID hex). Required when `mapping_type` is `schema`. api_id: type: string description: >- Mapping API ID (MongoDB ObjectID hex). Required when `mapping_type` is `api`. override: type: boolean description: >- When `false` (default) the rule is skipped if every label in `result_labels` already exists, and otherwise only the missing labels are filled. When `true` all `result_labels` are overwritten with the lookup result. ErsDrop: type: object title: drop required: - drop_labels properties: drop_labels: type: array items: type: string description: >- Label names to remove from the event (at least one), given without the `labels.` prefix. minItems: 1 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.