# Flow API

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

You can create, read, update, execute, and delete Flows programmatically, and manage their executions.

> **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 and executions requires the **Member** role. Every write operation, execution, and deletion 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.

> **Note: Trigger type values**
>
> The API identifies trigger types by these values: `Schedule`, `Operation` (Operation Completed), `PartitionScan` (Anomalous Table or File Detected), `Anomaly` (Anomaly Detected), `AnomalyStatusChange` (Anomaly Status Changed), and `Manual`.

> **Note**
>
> The action payloads and the notification-specific endpoints (tokens, specifications, and test notifications) are documented on the [Actions API](https://userguide.qualytics.io/flows/actions/api/) page.

---

## Error Responses

| Status Code | Description |
| --- | --- |
| `400 Bad Request` | The request conflicts with the execution's state, such as aborting an execution that has already completed. |
| `401 Unauthorized` | Missing or invalid API token. |
| `403 Forbidden` | The user does not have the required role, lacks the **Editor** team permission on a datastore the Flow relates to, or the Flow is deactivated and cannot be executed. |
| `404 Not Found` | No Flow or execution exists with the specified ID, or the request refers to a datastore that does not exist. |
| `422 Unprocessable Entity` | Invalid request body, such as an unknown trigger type, an invalid timezone, a Flow without actions, or an inconsistent action chain. |

> **Example: Error response examples**
>
> **404 Not Found**:
>
> ```json
> { "detail": "Flow id: 999 not found" }
> ```
>
> **400 Bad Request** (aborting a finished execution):
>
> ```json
> { "detail": "Flow execution id: 1001 has already completed with result: success" }
> ```
>
> **422 Unprocessable Entity** (validation errors return a list of issues):
>
> ```json
> {
>   "detail": [
>     {
>       "type": "value_error",
>       "loc": ["body", "timezone"],
>       "msg": "Value error, Invalid timezone: 'America/NewYork'. Must be a valid IANA timezone (e.g. 'America/New_York').",
>       "input": "America/NewYork"
>     }
>   ]
> }
> ```

---

## List Flows

Returns a paginated list of Flows, sorted by creation date with the most recently created first.

**Endpoint**: `GET /flows`

**Permission**: Member role or above

| Query Parameter | Type | Description |
| --- | --- | --- |
| `id` | `integer` | Return the Flow with this ID. |
| `name` | `string` | Return Flows with this exact name. |
| `search` | `string` | Match a piece of the name or the ID. |
| `datastore` | `list of integers` | Only Flows related to these datastore IDs, including Flows that reach every datastore. |
| `datastore_named_only` | `boolean` | With `datastore`, match only Flows that name one of the datastores, in the trigger's datastore filter or in an action. A Flow that reaches every datastore is left out unless it also names one of them, for example in an operation action. |
| `trigger_type` | `list of strings` | Only Flows with these trigger types. |
| `tag` | `list of strings` | Only Flows whose trigger filters on any of these tag names. |
| `created_by` | `list of integers` | Only Flows created by any of these user IDs. |
| `recipient` | `list of strings` | Only Flows with an Email action that notifies any of these recipients. An email address matches the Flows that send to it, whether it belongs to a picked user, a member of a picked team, or a typed address, ignoring case; a partial address matches nothing. `team:<id>` matches the Flows that pick that team. Inside `filters`, `recipient` takes `in`, `not_in`, and `all_of`. |
| `only_deactivated` | `boolean` | `true` returns only deactivated Flows; `false` returns only active Flows. Leave it out to list both. |
| `filters` | `string` (JSON) | Narrows the list by one or more filters, written as a JSON object. See [Filtering Lists](https://userguide.qualytics.io/flows/flow/api/#filtering-lists). |
| `sort_created`, `sort_name`, `sort_last_triggered` | `asc` / `desc` | Sort by creation date, name, or last triggered time. |

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/flows?search=scan&sort_created=desc" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response** (abbreviated; each item carries the full Flow):
>
> ```json
> {
>   "items": [
>     {
>       "id": 42,
>       "name": "Notify on scan failures",
>       "description": "Sends an in-app notification when a scan fails",
>       "deactivated": false,
>       "trigger_type": "Operation",
>       "filter_operation_type": ["Scan"],
>       "filter_operation_result": "failure",
>       "last_triggered": "2026-09-07T14:03:22Z",
>       "user_can_manage": true
>     }
>   ],
>   "total": 1,
>   "page": 1,
>   "size": 50
> }
> ```

### Filtering Lists

`GET /api/flows` and `GET /api/flows/executions` accept a `filters` parameter: a JSON object with one entry per filter, saying how that filter's values should match.

```bash
curl -G "https://your-instance.qualytics.io/api/flows" \
  --data-urlencode 'filters={"trigger_type":{"not_in":["Manual"]}}' \
  -H "Authorization: Bearer YOUR_TOKEN"
```

This returns the Flows whose trigger isn't Manual.

| Key | Returns |
| --- | --- |
| `in` | The items that match at least one of the values. |
| `not_in` | The items that match none of the values. |
| `all_of` | The items that match every value, on filters an item can have several of, such as tags. |
| `empty` | The items with no value (`true`) or at least one (`false`), on filters an item can lack. |

- Different filters combine with AND, and so do keys on the same filter.
- `empty` can't be combined with other keys on the same filter.
- A filter sent both as its own parameter and inside `filters` returns a `422`. Put all of that filter's conditions in `filters`.
- `in`, `not_in` and `all_of` each take between 1 and 20 values.
- A filter or key the endpoint doesn't accept returns a `422` that names it. The [API docs](https://userguide.qualytics.io/api/docs) list what each endpoint accepts.

---

## Get a Flow

Returns the details of one Flow, including its trigger configuration and actions.

**Endpoint**: `GET /flows/{id}`

**Permission**: Member role or above

| Parameter | Type | Description |
| --- | --- | --- |
| `id` | `integer` | The Flow ID. |

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/flows/42" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response** (abbreviated):
>
> ```json
> {
>   "id": 42,
>   "name": "Notify on scan failures",
>   "description": "Sends an in-app notification when a scan fails",
>   "deactivated": false,
>   "trigger_type": "Operation",
>   "crontab": null,
>   "timezone": null,
>   "next_trigger": null,
>   "filter_datastores": [{ "id": 7, "name": "Payments DB" }],
>   "filter_operation_type": ["Scan"],
>   "filter_operation_result": "failure",
>   "actions": [
>     {
>       "id": 310,
>       "type": "notification",
>       "notification_type": "InApp",
>       "tokenized_message": "Scan on {{datastore_name}} finished: {{operation_result}}"
>     }
>   ],
>   "last_triggered": "2026-09-07T14:03:22Z"
> }
> ```

---

## Create a Flow

Creates a new Flow with its trigger configuration and its actions. A Flow needs at least one action.

**Endpoint**: `POST /flows`

**Permission**: Member role or above, plus the **Editor** team permission on every datastore the Flow relates to (Admins are exempt)

**Request Body** (main fields):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | The Flow's name, up to 255 characters. |
| `description` | `string` | No | The Flow's description. |
| `trigger_type` | `string` | Yes | One of the trigger type values above. |
| `crontab` | `string` | No | The cron expression. Required for the `Schedule` trigger. |
| `timezone` | `string` | No | IANA timezone name for the schedule (defaults to UTC). |
| `filter_datastores` | `list of integers` | No | Datastore IDs the trigger is filtered to. On an event trigger, leaving it empty fires on events from every datastore, which needs the **Editor** team permission on all of them. With `filter_operators.filter_datastores` set to `not_in`, the Flow runs for every datastore except these, including datastores added later, which also needs the **Editor** team permission on all of them. It is not part of `filter_match`. An ID that does not exist returns `404`. |
| `filter_operation_type` | `list of strings` | No | Operation types (`Sync`, `Profile`, `Scan`) for the `Operation` trigger. |
| `filter_operation_result` | `string` | No | `success` or `failure` for the `Operation` trigger. |
| `tags` | `list of strings` | No | Tags of the triggering asset. By default the asset must have all of them; see `filter_operators.tags`. Leave it empty with `empty` or `not_empty`. |
| `check_rule_types` | `list of strings` | No | Check rule types for the anomaly triggers. |
| `impact_level_threshold` | `string` | No | Anomaly impact level (`low`, `medium`, `high`, or `critical`) for the `Anomaly` and `AnomalyStatusChange` triggers. By default, anomalies at or above this level start the Flow. To compare differently, set `filter_operators.impact_level_threshold` to `gte` (at least), `lte` (at most), or `eq` (exactly). |
| `weight_threshold` | `integer` | No | **Deprecated**: use `impact_level_threshold`. Used only when `impact_level_threshold` is left out, and then saved as a level with the same comparison. With `gte`, a minimum of `0` or `1` is saved as `low`, `2` to `7` as `medium`, `8` to `14` as `high`, and `15` or more as `critical`. With `lte` or `eq`, it is saved as `low`. The number is not compared with anomalies. |
| `filter_anomaly_status` | `list of strings` | No | Target statuses for the `AnomalyStatusChange` trigger. |
| `filter_match` | `string` | No | `all` (the default) starts the Flow only when every trigger filter matches, `any` when at least one does. Empty filters are ignored, except `tags` with the `empty` or `not_empty` operator, which take no tags and still count. `filter_datastores` always applies. |
| `filter_operators` | `object` | No | The operator of each trigger filter, by field name. A filter left out uses its default. `tags`: `all_of` (the default), `in`, `not_in`, `empty`, or `not_empty`. `filter_datastores`, `filter_operation_type`, `check_rule_types`, and `filter_anomaly_status`: `in` (the default) or `not_in`. `filter_operation_result`: `in` (the default, the result is this value) or `not_in` (any other result). `impact_level_threshold`: `gte` (the default), `lte`, or `eq`. |
| `deactivated` | `boolean` | No | Create the Flow deactivated (defaults to `false`). |
| `actions` | `list of objects` | Yes | The action chain, with at least one action. Each action carries a `uuid` you generate and a `type` (`operation`, `notification`, `anomaly`, `create_ticket`, `ticket_status_update`) plus type-specific fields. A request with `actions` left out, `null`, or empty returns `422` and creates nothing. |

> **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.

> **Example: Example request and response**
>
> **Request** (an Operation-triggered Flow with one in-app notification):
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/flows" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "Notify on scan failures",
>     "description": "Sends an in-app notification when a scan fails",
>     "trigger_type": "Operation",
>     "filter_datastores": [7],
>     "filter_operation_type": ["Scan"],
>     "filter_operation_result": "failure",
>     "actions": [
>       {
>         "uuid": "3f8c1e42-9d77-4b6a-8f21-5c0a7b6d1e44",
>         "type": "notification",
>         "notification_type": "InApp",
>         "tokenized_message": "{{operation_type}} on {{datastore_name}}: {{operation_result}}",
>         "parameters": {}
>       }
>     ]
>   }'
> ```
>
> **Response** (abbreviated):
>
> ```json
> {
>   "id": 42,
>   "name": "Notify on scan failures",
>   "trigger_type": "Operation",
>   "deactivated": false,
>   "actions": [
>     { "id": 108, "uuid": "3f8c1e42-9d77-4b6a-8f21-5c0a7b6d1e44", "type": "notification" }
>   ],
>   "last_triggered": null
> }
> ```
>
> **422 Unprocessable Entity** (no actions; the ID in the message belongs to a Flow that is never saved):
>
> ```json
> { "detail": "Invalid schema provided for flow '42' due to missing actions. Please add at least one action to the flow." }
> ```

---

## Update a Flow

Replaces a Flow's configuration. The body has to describe the Flow in full, so fetch it with [Get a Flow](https://userguide.qualytics.io/flows/flow/api/#get-a-flow), change what you need, and send the whole thing back.

**Endpoint**: `PUT /flows/{id}`

**Permission**: Member role or above, plus the **Editor** team permission on every datastore the Flow relates to (Admins are exempt)

The body accepts the same fields as [Create a Flow](https://userguide.qualytics.io/flows/flow/api/#create-a-flow), and `name` and `trigger_type` are required. Leave `actions` out, or send it as `null`, to keep the stored actions. When you send `actions`, each action is matched by its `uuid`: send an existing action with both its `uuid` and its `id` to keep or edit it, send a new `uuid` without an `id` to add one, and leave an action out to delete it. A flow must keep at least one action, so `"actions": []` returns `422` with the missing actions message. Changing `trigger_type` needs the `actions` list too, or the request returns `422`: "Actions are required when the trigger type changes, so they can be checked against the new trigger."

> **Warning: Send every value you want to keep**
>
> This is not a partial update. Trigger settings left out of the body are cleared, including `description`, `crontab`, `timezone`, `filter_operation_type`, `filter_operation_result`, `check_rule_types`, `weight_threshold`, and `filter_anomaly_status`. Leaving out `deactivated` reactivates a deactivated Flow, and an `actions` list you send replaces the stored one in full. Only `filter_datastores`, `tags`, `filter_match`, and `filter_operators` keep their stored values when omitted or sent as null. `impact_level_threshold` keeps its value when omitted, but sending `impact_level_threshold: null` clears the impact filter. A `filter_operators` object you send replaces the stored one, so any filter it leaves out goes back to its default operator.
>
> On a Flow whose `trigger_type` is `Schedule`, a body without `crontab` is rejected with `422` and the message `crontab is required when trigger_type is Schedule`.

> **Example: Rename a Flow without losing its configuration**
>
> **Step 1**: read the Flow as it stands.
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/flows/42" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Step 2**: send the whole configuration back with the new name.
>
> ```bash
> curl -X PUT "https://your-instance.qualytics.io/api/flows/42" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "Notify on scan failures (payments)",
>     "trigger_type": "Operation",
>     "description": "Alerts the data team when a payments scan fails",
>     "deactivated": false,
>     "filter_datastores": [1],
>     "filter_operation_type": ["scan"],
>     "filter_operation_result": "failure",
>     "actions": [
>       {
>         "id": 108,
>         "uuid": "3f8c1e42-9d77-4b6a-8f21-5c0a7b6d1e44",
>         "type": "notification",
>         "notification_type": "InApp",
>         "tokenized_message": "{{operation_type}} on {{datastore_name}}: {{operation_result}}",
>         "parameters": {}
>       }
>     ]
>   }'
> ```
>
> **Response** (abbreviated):
>
> ```json
> {
>   "id": 42,
>   "name": "Notify on scan failures (payments)",
>   "trigger_type": "Operation",
>   "description": "Alerts the data team when a payments scan fails"
> }
> ```

---

## Activate or Deactivate Flows

Sets one Flow's deactivated state, or updates it for several Flows at once. A deactivated Flow keeps its configuration but does not start on its trigger.

**Endpoints**: `PATCH /flows/{id}/deactivated` (single) and `PATCH /flows/deactivation` (bulk)

**Permission**: Member role or above, plus the **Editor** team permission on every datastore the Flow relates to (Admins are exempt)

The bulk request is all or nothing. If any Flow in the list cannot be changed, the request fails and none of the Flows changes, including Flows listed before the one that failed. A Flow that does not exist, or that you cannot see, returns `404 Not Found` with `"Flow id: 99 not found"`; a Flow you cannot manage returns `403 Forbidden`. Remove or fix that item and send the whole list again.

> **Example: Deactivate one Flow**
>
> **Request**:
>
> ```bash
> curl -X PATCH "https://your-instance.qualytics.io/api/flows/42/deactivated" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{ "deactivated": true }'
> ```
>
> **Response** (abbreviated):
>
> ```json
> { "id": 42, "name": "Notify on scan failures", "deactivated": true }
> ```

> **Example: Activate two Flows in bulk**
>
> **Request**:
>
> ```bash
> curl -X PATCH "https://your-instance.qualytics.io/api/flows/deactivation" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '[
>     { "id": 42, "deactivated": false },
>     { "id": 43, "deactivated": false }
>   ]'
> ```
>
> **Response**: the list of updated Flows.

---

## Execute a Flow

Runs a Flow and returns the new execution, created in the `running` state. This is the same endpoint the platform's scheduler calls for scheduled Flows.

**Endpoint**: `POST /flows/{id}/execute`

**Permission**: Member role or above, plus the **Editor** team permission on every datastore the Flow relates to (Admins are exempt)

A deactivated Flow cannot be executed; the request returns `403 Forbidden` with `"Flow id: 42 is deactivated"`.

> **Example: Example request and response**
>
> **Request** (no body required):
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/flows/42/execute" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response** (abbreviated):
>
> ```json
> {
>   "id": 1001,
>   "flow": { "id": 42, "name": "Notify on scan failures", "user_can_manage": true },
>   "trigger_type": "Operation",
>   "start_time": "2026-09-08T12:00:00Z",
>   "end_time": null,
>   "result": "running",
>   "action_executions": []
> }
> ```

---

## Delete a Flow

Deletes a Flow, its execution history, and its schedules. Operations the Flow triggered remain, but their link to the Flow is removed.

**Endpoint**: `DELETE /flows/{id}`

**Permission**: Member role or above, plus the **Editor** team permission on every datastore the Flow relates to (Admins are exempt)

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X DELETE "https://your-instance.qualytics.io/api/flows/42" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response**: `204 No Content`

---

## Get a Flow's Change History

Returns a paginated change log with every version of the Flow and the user who made each change.

**Endpoint**: `GET /flows/{id}/history`

**Permission**: Member role or above

> **Example: Example request**
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/flows/42/history" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```

---

## List Executions

Returns a paginated list of Flow executions.

**Endpoint**: `GET /flows/executions`

**Permission**: Member role or above

| Query Parameter | Type | Description |
| --- | --- | --- |
| `flow` | `list of integers` | Only executions of these Flow IDs. |
| `search` | `string` | Match an execution ID. |
| `created` | `date` | Only executions created on this date. |
| `trigger_type` | `list of strings` | Only executions started by these trigger types. |
| `tag` | `list of strings` | Only executions of Flows whose trigger filtered on any of these tag names when the run started. Runs older than the Flow's saved history match by the Flow's current tags. |
| `result` | `list of strings` | `success`, `failure`, `aborted`, `queued`, or `running`. |
| `filters` | `string` (JSON) | Narrows the list by one or more filters, written as a JSON object. See [Filtering Lists](https://userguide.qualytics.io/flows/flow/api/#filtering-lists). |
| `sort_created`, `sort_duration` | `asc` / `desc` | Sort by creation date or duration. |

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/flows/executions?result=failure&sort_created=desc" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response** (abbreviated):
>
> ```json
> {
>   "items": [
>     {
>       "id": 1001,
>       "flow": { "id": 42, "name": "Notify on scan failures", "user_can_manage": true },
>       "trigger_type": "Operation",
>       "trigger_id": 8842,
>       "start_time": "2026-09-07T14:03:22Z",
>       "end_time": "2026-09-07T14:03:40Z",
>       "result": "failure",
>       "message": "One or more actions failed"
>     }
>   ],
>   "total": 1,
>   "page": 1,
>   "size": 50
> }
> ```

---

## Get an Execution

Returns the details of one Flow execution, including each action's execution and result.

**Endpoint**: `GET /flows/executions/{id}`

**Permission**: Member role or above

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/flows/executions/1001" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response** (abbreviated):
>
> ```json
> {
>   "id": 1001,
>   "flow": { "id": 42, "name": "Notify on scan failures" },
>   "trigger_type": "Operation",
>   "start_time": "2026-09-07T14:03:22Z",
>   "end_time": "2026-09-07T14:03:40Z",
>   "result": "success",
>   "action_executions": [
>     {
>       "action": { "id": 310, "type": "notification", "notification_type": "Slack" },
>       "result": "success",
>       "message": null
>     }
>   ]
> }
> ```

---

## Abort Executions

Aborts a running execution together with its action executions and any running operations they started. The bulk variant aborts several executions at once.

**Endpoints**: `POST /flows/executions/{id}/abort` (single) and `POST /flows/executions/abort` (bulk)

**Permission**: Member role or above, plus the **Editor** team permission on every datastore the execution's Flow relates to (Admins are exempt)

Aborting an execution that has already finished returns `400 Bad Request` naming its final result.

> **Example: Abort one execution**
>
> **Request** (no body required):
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/flows/executions/1001/abort" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response**: the aborted execution, with `"result": "aborted"`.

> **Example: Abort executions in bulk**
>
> **Request**:
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/flows/executions/abort" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '[ { "id": 1001 }, { "id": 1002 } ]'
> ```
>
> **Response**: the list of aborted executions.

---

## Delete Executions

Deletes an execution, or several at once by ID. Returns `204 No Content` on success.

**Endpoints**: `DELETE /flows/executions/{id}` (single) and `DELETE /flows/executions` (bulk)

**Permission**: Member role or above, plus the **Editor** team permission on every datastore the execution's Flow relates to (Admins are exempt)

> **Example: Delete executions in bulk**
>
> **Request**:
>
> ```bash
> curl -X DELETE "https://your-instance.qualytics.io/api/flows/executions" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '[ { "id": 1001 }, { "id": 1002 } ]'
> ```
>
> **Response**: `204 No Content`

*Last updated: November 13, 2026.*
