# Actions API

Source: https://userguide.qualytics.io/flows/actions/api/

You can configure every action category through the Flow API's `actions` list, and support notification actions with their specification, token, and test endpoints.

> **Tip**
>
> For complete API documentation, including request/response schemas, visit the [API docs](https://userguide.qualytics.io/api/docs).

All endpoints use the base URL of your Qualytics deployment (e.g., `https://your-instance.qualytics.io/api`) and require a Personal API Token. Reading Flows requires the **Member** role. Creating, updating, or deleting them (and the actions they contain) also requires the **Editor** team permission on every datastore the Flow relates to, which Admins are exempt from. See [Flow Permissions](https://userguide.qualytics.io/flows/flow/deep-dive/permissions/) for the full matrix.

---

## The Actions List

Actions are configured as part of a Flow's definition rather than created one by one: [Create a Flow](https://userguide.qualytics.io/flows/flow/api/#create-a-flow) and [Update a Flow](https://userguide.qualytics.io/flows/flow/api/#update-a-flow) accept the `actions` list, and [Get a Flow](https://userguide.qualytics.io/flows/flow/api/#get-a-flow) returns it. When Update a Flow includes `actions`, it replaces the whole list: any action left out of it is deleted, so send every action you want to keep. Leaving `actions` out, or sending `null`, keeps the stored actions. A flow must keep at least one action. Each entry carries a `type` field, a `uuid`, and a `parent_action_uuid` pointing at the node the action hangs from (the trigger when absent), plus fields specific to that type; pick the tab for your category. Two read-only endpoints complement the list: `GET /flows/actions/{id}` returns a single action and `GET /flows/actions/{id}/version` returns the version an execution ran with.

> **Tip: Building the actions list**
>
> Action payloads vary by type. The practical way to compose one is to build a similar Flow in the UI once, fetch it with `GET /flows/{id}`, and use its `actions` array as the template for your own requests.

**Tab: Operation**

Operation actions use `"type": "operation"` plus the configuration of the operation they run:

```json
{
  "name": "Nightly pipeline",
  "trigger_type": "Schedule",
  "actions": [
    {
      "type": "operation",
      "uuid": "3f8c1e42-9d77-4b6a-8f21-5c0a7b6d1e44",
      "schedule": {
        "type": "scan",
        "...": "the operation's own fields"
      }
    }
  ]
}
```

The operation's configuration goes inside the required `schedule` object, whose own `type` is `sync`, `profile`, `scan`, `export`, or `materialize`. The remaining fields are the same ones the matching operation accepts when you run it directly on a datastore.

**Tab: Global Export**

Global Export actions use the type `global_export`:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `asset_type` | `string` | Yes | What to export: `check_templates` or `user_permissions`. |
| `enrichment_datastore_id` | `integer` | Yes | The enrichment datastore the export is written to. Any other datastore is refused. |
| `asset_ids` | `list of integers` | No | `check_templates` only: the check templates to export. Omit it to export every template. Refused for `user_permissions`. |

```json
{
  "name": "Weekly access review",
  "trigger_type": "Schedule",
  "crontab": "0 6 * * 1",
  "actions": [
    {
      "type": "global_export",
      "uuid": "8b1d7c3e-2f4a-4e9b-9c61-0d5e7a2b4f10",
      "asset_type": "user_permissions",
      "enrichment_datastore_id": 42
    }
  ]
}
```

Saving, updating, deleting, activating or deactivating, or manually executing a Flow with a `user_permissions` export requires the **Admin** role; with a `check_templates` export, the **Manager** role. A request without that role is refused with `403`. See [Flow Permissions](https://userguide.qualytics.io/flows/flow/deep-dive/permissions/).

**Tab: Anomaly**

Archive and Delete anomaly actions use the type `anomaly`:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `anomaly_operation_type` | `string` | Yes | The cleanup to run, `archive` or `delete`. |
| `parameters` | `object` | Yes | The cleanup's parameters, such as the inactivity period. They vary by operation type. |
| `filter_datastore_ids` | `list of integers` | No | The datastores to include anomalies from. `GET /flows/{id}` returns them as `filter_datastores`, a list of objects. Leaving it empty acts on anomalies from every datastore, which needs the **Editor** team permission on all of them. |
| `filter_tag_names` | `list of strings` | No | The tags the anomalies must have. `GET /flows/{id}` returns them as `filter_tags`, a list of objects. |
| `filter_statuses` | `list of strings` | No | The anomaly statuses to include, such as `Active` or `Discarded`. |

**Tab: Notifications**

Notification actions use `"type": "notification"`, with `notification_type` picking the channel (`InApp`, `Email`, `Slack`, `Microsoft Teams`, or `PagerDuty`), `tokenized_message` carrying the message, and `parameters` holding the channel's settings. Three endpoints support them, described below.

### Get Notification Specifications

Returns the configuration properties of each notification channel, as the form specifications the platform itself uses.

**Endpoint**: `GET /flows/actions/notification/specifications`

**Permission**: Member role or above

Pick the channel for its configuration properties.

**Tab: In App**

In App has no entry in this response. The channel takes no configuration beyond the message, and its recipients follow the platform's own rules. See [Notifications](https://userguide.qualytics.io/flows/actions/deep-dive/notifications/).

**Tab: Email**

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `emails` | `string` | No | The typed recipient addresses, separated by `;` or `,`. Required when the action picks no users or teams. |
| `email_subject` | `string` | No | Subject line of the notification email. It accepts the same message tokens as the body. Left out, the trigger's own default subject is used. The rendered subject is collapsed to one line and shortened to 150 characters. |

Users and teams are picked on the action itself, next to `parameters`, not inside it:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `recipient_user_ids` | `list of integers` | No | The users the email is sent to, reached at their current address. Only active users of the Human type with an email address can be picked. Left out on an update, the stored users are kept; `[]` removes them. |
| `recipient_team_ids` | `list of integers` | No | The teams whose members the email is sent to, read when it is sent. Left out on an update, the stored teams are kept; `[]` removes them. |

A Flow returns each Email action with `recipient_users` and `recipient_teams`, the picked users and teams. A deactivated user stays in `recipient_users`, with `deleted_at` set, but is not emailed.

An Email action needs at least one recipient across the three. Publishing one is refused with a `422` when it has none (`Add at least one recipient.`), when an address is malformed (`Invalid email address`), or when a picked user or team can't be emailed, such as a service user, a deactivated user, or an id that doesn't exist (`Cannot email the user with id N.`, `Cannot email the team with id N.`).

**Tab: Slack**

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `channel` | `enum` | Yes | The Slack channel where notifications will be sent. The available channels are retrieved from your connected Slack workspace. |

**Tab: Microsoft Teams**

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `channel` | `enum` | Yes | The Microsoft Teams channel where notifications will be sent. The available channels are retrieved from your connected Teams workspace. |

**Tab: PagerDuty**

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `severity` | `enum` | No | Severity level (`info`, `warning`, `error`, or `critical`). Defaults to `info`. |
| `custom_details` | `object` | No | Key-value pairs for additional incident context. |
| `routing_key` | `string` (secret) | No | Override the default Routing Key to route to a different PagerDuty service. |

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/flows/actions/notification/specifications" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response** (abbreviated). The endpoint returns seven entries, one per configurable destination: Slack, Webhook, Microsoft Teams, Email, PagerDuty, HTTP Action, and n8n Workflow:
>
> ```json
> [
>   {
>     "display_name": "Email",
>     "type": "Email",
>     "properties": [
>       {
>         "field": "emails",
>         "map_to": "parameters",
>         "required": true,
>         "title": "Email Addresses",
>         "type": "string"
>       },
>       {
>         "field": "email_subject",
>         "map_to": "parameters",
>         "required": false,
>         "title": "Email Subject",
>         "type": "tokenized"
>       }
>     ]
>   }
> ]
> ```

### Get Notification Tokens

Returns the [message tokens](https://userguide.qualytics.io/flows/actions/deep-dive/message/#message-variables) available per trigger type, the same set for every channel.

**Endpoint**: `GET /flows/actions/notification/tokens`

**Permission**: Member role or above

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/flows/actions/notification/tokens" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response** (abbreviated):
>
> ```json
> [
>   {
>     "trigger_type": "Anomaly",
>     "valid_message_tokens": ["{{flow_name}}", "{{datastore_name}}", "{{container_name}}", "{{anomaly_message}}", "{{anomaly_type}}"],
>     "optional_message_tokens": ["{{anomaly_message}}", "{{check_description}}", "{{old_status}}"],
>     "default_message": "...",
>     "default_subject": "{{anomaly_type}} anomaly in {{container_name}} ({{datastore_name}})"
>   },
>   {
>     "trigger_type": "Operation",
>     "valid_message_tokens": ["{{flow_name}}", "{{datastore_name}}", "{{operation_type}}", "{{operation_result}}"],
>     "optional_message_tokens": ["{{operation_message}}"],
>     "default_message": "...",
>     "default_subject": "{{operation_result}}: {{operation_type}} operation on {{datastore_name}}"
>   }
> ]
> ```

`valid_message_tokens` lists what the trigger provides, `optional_message_tokens` the subset that can arrive empty and is offered as optional sections, and `default_subject` the subject an Email notification opens on. Pass `notification_type` to shape `default_message` for the channel it will be delivered to; left out, the full Markdown default is returned.

### Template Validation Errors

Creating or updating a Flow, which carries its actions, and testing a notification run the message and the Email subject through template validation; in the web app those are **Publish** and **Test Notification**. A refused template returns `422 Unprocessable Entity` with `detail` carrying the first problem and an `errors` array carrying every problem; one publish reports all refused actions at once.

```json
{
  "detail": "The message uses {{old_status}}, which this notification does not provide. A variable that is not provided is not filled in and reaches the recipient exactly as written.",
  "errors": [
    {
      "loc": ["actions", "6f1c2c1e-9d7a-4b0e-8a4f-2f7d1c9a0b11", "tokenized_message"],
      "msg": "The message uses {{old_status}}, which this notification does not provide. A variable that is not provided is not filled in and reaches the recipient exactly as written.",
      "type": "value_error.template"
    },
    {
      "loc": ["actions", "6f1c2c1e-9d7a-4b0e-8a4f-2f7d1c9a0b11", "parameters", "email_subject"],
      "msg": "The subject has a condition on {{ticket_number}}, which this notification does not provide. A condition can only check a variable this notification provides; otherwise its section would never be shown.",
      "type": "value_error.template"
    }
  ]
}
```

`loc` names the action by its `uuid` and then the field: `tokenized_message` for the message, `parameters` and `email_subject` for the subject. A malformed conditional, a variable missing its `{{` or its `}}`, and a variable with spaces inside its braces are reported the same way, with `msg` saying what is wrong and quoting the fragment, for example `The message has spaces inside the braces of {{ flow_name }}. A variable is only filled in when written without them, as {{flow_name}}; otherwise it reaches the recipient exactly as written.`

### Test Notification

Sends a test message with sample data to verify a notification's configuration before publishing.

**Endpoint**: `POST /flows/actions/notifications/test`

**Permission**: Member role or above

The body is a full notification action: `type` is always `notification`, the channel goes in `notification_type`, and both `uuid` and `parameters` are required. Pick the channel for its test request.

**Tab: In App**

In App notifications cannot be tested. The channel has no test path, so the endpoint answers without delivering anything, and the settings panel offers no test button. Publish the Flow and check the bell icon instead.

**Tab: Email**

> **Example: Example request**
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/flows/actions/notifications/test" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "uuid": "3f8c1e42-9d77-4b6a-8f21-5c0a7b6d1e44",
>     "type": "notification",
>     "notification_type": "Email",
>     "tokenized_message": "Test notification from {{flow_name}}",
>     "parameters": {
>       "emails": "user@example.com",
>       "email_subject": "Qualytics Test Alert"
>     }
>   }'
> ```
>
> **Response**: `200 OK` with a success confirmation.

**Tab: Slack**

> **Example: Example request**
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/flows/actions/notifications/test" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "uuid": "3f8c1e42-9d77-4b6a-8f21-5c0a7b6d1e44",
>     "type": "notification",
>     "notification_type": "Slack",
>     "tokenized_message": "Test notification from {{flow_name}}",
>     "parameters": {
>       "channel": "general"
>     }
>   }'
> ```
>
> **Response**: `200 OK` with a success confirmation.

**Tab: Microsoft Teams**

> **Example: Example request**
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/flows/actions/notifications/test" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "uuid": "3f8c1e42-9d77-4b6a-8f21-5c0a7b6d1e44",
>     "type": "notification",
>     "notification_type": "Microsoft Teams",
>     "tokenized_message": "Test notification from {{flow_name}}",
>     "parameters": {
>       "channel": "general"
>     }
>   }'
> ```
>
> **Response**: `200 OK` with a success confirmation.

**Tab: PagerDuty**

> **Example: Example request**
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/flows/actions/notifications/test" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "uuid": "3f8c1e42-9d77-4b6a-8f21-5c0a7b6d1e44",
>     "type": "notification",
>     "notification_type": "PagerDuty",
>     "tokenized_message": "Test notification from {{flow_name}}",
>     "parameters": {
>       "severity": "info"
>     }
>   }'
> ```
>
> **Response**: `200 OK` with a success confirmation.

> **Warning**
>
> Test notifications **will create an incident** in your PagerDuty service (unlike connection validation, which uses Change Events).

**Tab: Workflow**

Workflow actions (Webhook, HTTP Action, and n8n) share the notification shape, using `"type": "notification"`:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `notification_type` | `string` | Yes | The destination, `Webhook`, `HttpAction`, or `n8n`. |
| `parameters` | `object` | Yes | The destination's settings. The URL is `parameters.url` for Webhook and HTTP Action, and `parameters.webhook_url` for n8n, which also takes an optional `parameters.webhook_secret`. |
| `secret` | `string` | No | The token or password for the HTTP Action, where it is required. Webhook and n8n do not use it. |
| `auth_type` | `string` | No | The authorization scheme, `basic`, `digest`, or `bearer`. Required on the HTTP Action, unused by Webhook and n8n. |
| `tokenized_message` | `string` | No | A custom message, with [message tokens](https://userguide.qualytics.io/flows/actions/deep-dive/message/#message-variables) resolved from the event. |

**Tab: Ticketing**

Ticketing actions use the type values `create_ticket` and `ticket_status_update`:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ticketing_type` | `string` | Yes | The ticketing integration, `servicenow` or `jira`. |
| `ticket_metadata` | `object` | Yes | On `create_ticket` only. The ticket's creation data, such as title, description, and priority. |
| `target_ticket_status` | `string` | Yes | On `ticket_status_update` only. The status to set, such as `Resolved`, `Closed`, or `In Progress`. |

*Last updated: October 28, 2026.*
