Skip to content

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.

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 requires the Manager role. See Flow Permissions for the full matrix.

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 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, or the Flow is deactivated and cannot be executed.
404 Not Found No Flow or execution exists with the specified ID.
422 Unprocessable Entity Invalid request body, such as an unknown trigger type, an invalid timezone, or an inconsistent action chain.
Error response examples

404 Not Found:

{ "detail": "Flow id: 999 not found" }

400 Bad Request (aborting a finished execution):

{ "detail": "Flow execution id: 1001 has already completed with result: success" }

422 Unprocessable Entity (validation errors return a list of issues):

{
  "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 filtered to these datastore IDs.
trigger_type list of strings Only Flows with these trigger types.
only_deactivated boolean Only deactivated Flows.
sort_created, sort_name, sort_last_triggered asc / desc Sort by creation date, name, or last triggered time.
Example request and response

Request:

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):

{
  "items": [
    {
      "id": 42,
      "name": "Notify on scan failures",
      "description": "Sends a Slack message 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
}

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 request and response

Request:

curl -X GET "https://your-instance.qualytics.io/api/flows/42" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (abbreviated):

{
  "id": 42,
  "name": "Notify on scan failures",
  "description": "Sends a Slack message 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": "Slack",
      "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, optionally, its actions.

Endpoint: POST /flows

Permission: Manager role or above

Request Body (main fields):

Field Type Required Description
name string The Flow's name, up to 255 characters.
description string The Flow's description.
trigger_type string One of the trigger type values above.
crontab string The cron expression. Required for the Schedule trigger.
timezone string IANA timezone name for the schedule (defaults to UTC).
filter_datastores list of integers Datastore IDs the trigger is filtered to.
filter_operation_type list of strings Operation types (Sync, Profile, Scan) for the Operation trigger.
filter_operation_result string success or failure for the Operation trigger.
tags list of strings Tags the triggering asset must all have.
check_rule_types list of strings Check rule types for the anomaly triggers.
weight_threshold integer Minimum anomaly severity for the Anomaly trigger.
filter_anomaly_status list of strings Target statuses for the AnomalyStatusChange trigger.
deactivated boolean Create the Flow deactivated (defaults to false).
actions list of objects The action chain. Each action carries a type (operation, notification, anomaly, create_ticket, ticket_status_update) plus type-specific fields.

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 request and response

Request (an Operation-triggered Flow, actions added later):

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 a Slack message when a scan fails",
    "trigger_type": "Operation",
    "filter_datastores": [7],
    "filter_operation_type": ["Scan"],
    "filter_operation_result": "failure"
  }'

Response (abbreviated):

{
  "id": 42,
  "name": "Notify on scan failures",
  "trigger_type": "Operation",
  "deactivated": false,
  "actions": null,
  "last_triggered": null
}

Update a Flow

Replaces a Flow's configuration. The body has to describe the Flow in full, so fetch it with Get a Flow, change what you need, and send the whole thing back.

Endpoint: PUT /flows/{id}

Permission: Manager role or above

The body accepts the same fields as Create a Flow, and name and trigger_type are required. 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.

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 the actions list has to be sent in full. Only filter_datastores and tags keep their stored values when omitted.

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.

Rename a Flow without losing its configuration

Step 1: read the Flow as it stands.

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.

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": "Slack",
        "tokenized_message": "{{operation_type}} on {{datastore_name}}: {{operation_result}}",
        "parameters": { "channel": "data-alerts" }
      }
    ]
  }'

Response (abbreviated):

{
  "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: Manager role or above

Deactivate one Flow

Request:

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):

{ "id": 42, "name": "Notify on scan failures", "deactivated": true }
Activate two Flows in bulk

Request:

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: Manager role or above

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

Example request and response

Request (no body required):

curl -X POST "https://your-instance.qualytics.io/api/flows/42/execute" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (abbreviated):

{
  "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: Manager role or above

Example request and response

Request:

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 request 
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.
result list of strings success, failure, aborted, queued, or running.
sort_created, sort_duration asc / desc Sort by creation date or duration.
Example request and response

Request:

curl -X GET "https://your-instance.qualytics.io/api/flows/executions?result=failure&sort_created=desc" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (abbreviated):

{
  "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 request and response

Request:

curl -X GET "https://your-instance.qualytics.io/api/flows/executions/1001" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (abbreviated):

{
  "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: Manager role or above

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

Abort one execution

Request (no body required):

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

Abort executions in bulk

Request:

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: Manager role or above

Delete executions in bulk

Request:

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