Flow and Automation Management

BrinqaIQ can discover, launch, monitor, and control Brinqa flows and automations. This capability is available in two ways:

• BrinqaIQ Assistant (chat UI): ask in natural language to list, launch, or check the status of flows and automations. BrinqaIQ handles the orchestration in the conversation.
• MCP integration: the flow and automation tools let any MCP-compatible AI client wrap workflow-centric tasks into agent prompts without leaving the client. See MCP Integration for setup.

info

For background on what flows and automations are, see the Automation Overview.

API and MCP access

Flows are opt-in for API and MCP access: a flow is exposed only when its "API & MCP Access" toggle is enabled on the flow definition. Listing and fuzzy lookup omit a flow that is not enabled: flows.list, and the fuzzy name matching in flows.get and entities.launch, return only enabled flows, so a disabled flow does not show up when you browse or search. Referencing a disabled flow by its exact name or id is handled differently: flows.get and entities.launch return an actionable error explaining that the "API & MCP Access" toggle must be enabled on the flow definition, rather than a bare not-found, so a caller who already knows the exact identifier is told how to enable it instead of being left guessing. Non-management button flows are always accessible and need no toggle; management flows (Brinqa's built-in system Flows) follow the same opt-in toggle. Automations are not gated: all automations are discoverable and launchable.

How it works

BrinqaIQ groups workflow operations into four areas:

• Discovery: list and inspect the flows and automations available in your instance, and find the button flows that apply to a data model or record.
• Trigger and lifecycle: launch a flow or an automation, get the status of a running instance, resume a paused one, and cancel one that is no longer needed.
• Live instances: list the flow instances currently running, so you or an agent can pick a transactionId to act on without having tracked it from the original launch.
• Run history: read the per-step execution history of a run to see what each step did, how long it took, and why a run failed.

The trigger and lifecycle operations mirror the Flow and Automation Management API. MCP clients introspect each tool's input schema via the standard list_tools request, so no out-of-band schema reference is required.

Discover flows and automations

Before launching, an agent can list the flows and automations in your instance and inspect a single one in detail. The relevant tools are flows.list, flows.get, automations.list, and automations.get. flows.list and flows.get cover only the flows enabled for API and MCP access (see API and MCP access); automations.list and automations.get cover all automations.

Example agent prompt:

List the automations available in my Brinqa instance and tell me which one runs the nightly asset sync.

The agent calls automations.list, gets the available automations, and answers based on their titles and descriptions.

Discover button flows for a model or record

Button flows are flows categorized BUTTON_FLOW that always act on a selection of records of a data model: a set of records of the model, or one specific record. They are the on-demand actions Brinqa surfaces as buttons on records and search results in the product. Two read-only tools let an agent find which button flows apply and learn each one's launch inputs, following a discovery-then-act pattern. They are scoped to a data model, unlike flows.list (the tenant-wide catalog) and flows.get (a single flow's metadata). Launching a button flow is handled by the launch tools below; these two only read configuration.

List the button flows for a model or record

flows.buttonFlows lists the button flows available for a data model, or for one specific record when you provide a record id.

Parameter	Required	Type	Description
dataModelName	Yes	string	A known UDM data model name, for example Finding, Asset, or Vulnerability.
dataSetId	No	string	A record id that scopes the result to one record's button flows. Pass it as a quoted numeric string of 17 to 19 digits, for example "184726195308400123". Do not pass it as a JSON number: record ids exceed JSON number precision.

It returns each button flow's name, title, scope (DATA_MODEL or DATA_SET), and active. Only button flows the caller may launch are returned. active is true when the flow can be launched right now, and false when an instance is already running for the model or record context.

Example agent prompts:

What button flows can I run on Finding?

What actions are available on this vulnerability record?

Inspect a button flow's launch inputs

flows.buttonFlowFields returns the launch input fields of one button flow on a data model: what you fill in before launching it.

Parameter	Required	Type	Description
dataModelName	Yes	string	A known UDM data model name, for example Finding, Asset, or Vulnerability.
flowName	Yes	string	The flow name returned by flows.buttonFlows.

It returns flowName and fields, where each field is { name, title, type, required, options, defaultValue, relatedDataModel, multiple }. The options list gives the allowed values for a choice field. For a model-scoped flow the fields include a required query field: a BQL query selecting which records the flow runs against. A record-scoped flow acts on one specific record instead and has no query field.

For a relationship field (type is ReferenceAttributeType), relatedDataModel names the data model the field points to, and the value you supply is the id of a record of that model (see Reference field values below). multiple is true when the field takes more than one value, so its value is an array.

Example agent prompts:

What inputs does the Create Ticket button flow need?

What do I have to fill in to run Create Ticket on Finding?

Discover the flow name with flows.buttonFlows first, then pass it to flows.buttonFlowFields.

Launch a button flow

entities.launch is the single launch tool. It launches a named flow or automation (through its nameOrId argument) and, with the buttonFlow argument, it also launches a button flow. There is no separate button-flow launch tool.

To launch a button flow, provide a buttonFlow object instead of nameOrId:

Field	Required	Type	Description
dataModelName	Yes	string	A known UDM data model name, for example Finding, Asset, or Vulnerability.
flowName	Yes	string	The button flow's internal name, as returned by flows.buttonFlows.
dataSetId	No	string	A single record id for a record-scoped launch: a quoted numeric string of 17 to 19 digits, for example "184726195308400123". Omit it for a model-wide launch.
inputs	No	object	The field values keyed by field name, as described by flows.buttonFlowFields. For a model-wide launch, inputs must include the required query field whose value is the BQL selecting the records to act on.

When buttonFlow is provided it takes precedence and nameOrId is ignored. The nameOrId path for launching a named flow or automation is unchanged.

Author the model-wide query value with bql.fromNaturalLanguage. Do not hand-write BQL.

entities.launch validates required inputs before it launches, on both the client and the server. A launch missing a required input (including the query selection on a model-wide launch) is rejected with an error, not silently dropped, so the agent can correct the inputs and try again. Pass dataSetId only for a record-scoped flow and omit it for a model-wide flow; the server rejects a mismatch (a dataSetId on a model-wide flow, or a record-scoped flow launched without one).

Reference field values

When a flow input is a relationship field, flows.buttonFlowFields reports its type as ReferenceAttributeType and names the target model in relatedDataModel. Supply the id of a record of that model as the field value, as a quoted numeric string. You do not construct an internal reference object; the server resolves the id into the full reference. When the field's multiple flag is true, supply an array of ids.

For example, a slaPolicy field whose relatedDataModel is SLADefinition takes the id of an SLADefinition record:

entities.launch {
  "buttonFlow": {
    "dataModelName": "Vulnerability",
    "flowName": "createTicket",
    "inputs": {
      "query": "<BQL from bql.fromNaturalLanguage>",
      "name": "Escalation ticket",
      "summary": "Escalating unresolved critical findings",
      "slaPolicy": "2059997699363495936"
    }
  }
}

Find a valid id by querying the related model. The id must resolve to a record of that model the caller can read; an id that does not, including one the caller cannot read, is rejected before the flow starts.

Some flows act on the records shown within a specific parent record (for example, removing vulnerabilities from one ticket). For these, flows.buttonFlowFields reports a required __MAIN_ID__ field whose relatedDataModel is the parent model: pass the id of that parent record in inputs. It goes alongside query, which selects the related records to act on, so the parent and the target selection are two different records.

On success the tool returns a transactionId. Pass it to automation.status to follow the run through completion, and to automation.resume or automation.cancel to control it.

The recommended workflow is discover then act: call flows.buttonFlows to find the applicable flows, flows.buttonFlowFields to learn the required inputs, then entities.launch with the buttonFlow object, then automation.status to monitor.

Confirm before launching

Launching a button flow is a write action that creates real work. There is no server-side confirmation gate for external MCP callers: the human-in-the-loop pick-and-confirm card runs only for the in-platform BrinqaIQ Assistant. For external MCP clients, entities.launch carries the destructiveHint annotation, and the MCP host (your client) is responsible for surfacing a confirmation to the user before the call runs. Confirm with the user before launching.

Example tool-call sequence

Run the Create Ticket button flow against a set of high-severity vulnerabilities. This flow needs the record selection (query), a text name and summary, and an slaPolicy relationship that points at an SLADefinition record.

1. flows.buttonFlows { "dataModelName": "Vulnerability" }
   → returns flows including { "name": "createTicket", "title": "Create Ticket", "scope": "DATA_MODEL", "active": true }

2. flows.buttonFlowFields { "dataModelName": "Vulnerability", "flowName": "createTicket" }
   → returns required fields: "query" (the record selection), "name" and "summary" (text),
     and "slaPolicy" (type "ReferenceAttributeType", relatedDataModel "SLADefinition")

3. bql.fromNaturalLanguage { "prompt": "vulnerabilities with severity Critical that are open" }
   → returns the BQL to use as the query value

4. // slaPolicy is a reference: get the id of the SLADefinition record to point at
   bql.fromNaturalLanguage { "prompt": "the SLA definition for critical remediation" }
   bql.execute { "bql": "<BQL from the previous call>" }
   → read the SLADefinition record id from the results (e.g. "2059997699363495936")

5. entities.launch {
        "buttonFlow": {
          "dataModelName": "Vulnerability",
          "flowName": "createTicket",
          "inputs": {
            "query": "<BQL returned by step 3>",
            "name": "Escalation ticket",
            "summary": "Escalating unresolved critical findings",
            "slaPolicy": "2059997699363495936"
          }
        }
      }
   → returns { "transactionId": "9f3a4c10-2c47-4e11-9d7a-7b1f5b3a82e8" }

6. automation.status { "transactionId": "9f3a4c10-2c47-4e11-9d7a-7b1f5b3a82e8" }
   → poll until the run completes

A record-scoped (DATA_SET) button flow is launched the same way, but with the single record's id in dataSetId and no query (the flow acts on that one record). Use a flow whose scope is DATA_SET, and supply whatever inputs flows.buttonFlowFields lists for it:

entities.launch {
  "buttonFlow": {
    "dataModelName": "Vulnerability",
    "flowName": "<a DATA_SET-scoped flow name from flows.buttonFlows>",
    "dataSetId": "184726195308400123",
    "inputs": { }
  }
}

Launch and monitor a workflow

Once the agent knows the right name, it can launch the workflow and monitor it through completion. The relevant tool is entities.launch (which returns a transactionId), then automation.status, automation.resume, and automation.cancel.

Example agent prompt:

Launch the NightlyAssetSync automation and tell me when it finishes. If it pauses for input, ask me before resuming.

The agent calls entities.launch with the automation's name, captures the returned transactionId, polls automation.status until the run completes or pauses, and surfaces the pause to you for confirmation before calling automation.resume.

To launch a button flow rather than a named flow or automation, see Launch a button flow.

Inspect and cancel a running instance

When an agent does not have the transactionId from a previous launch (for example, in a fresh conversation, or after a launch by another user), it can list all currently running flow instances first, then pick the right one to inspect, resume, or cancel. The relevant tool is flows.running. Each entry in the response includes a transactionId that you can pass to automation.status, automation.resume, or automation.cancel.

Example agent prompt:

Show me the flows currently running. Cancel any that have been running for more than an hour.

The agent calls flows.running, filters the response by start time, and calls automation.cancel for each match.

Inspect a flow run's step history

To diagnose what a run did, or why it failed, an agent can read the per-step execution history of a run by transactionId. The relevant tool is flows.history. It is read-only and non-destructive, and mirrors the Flow History REST API (GET /v1/api/automation/history/{txId}).

Parameter	Required	Type	Description
transactionId	Yes	string	The run to inspect. Chain it from automation.status, flows.running, or a launch response.
ascOrder	No	boolean	Return steps in ascending start-date (execution) order. Defaults to newest-first.

It returns every executed step with its stepName, actionType, flow status, start and end timestamps, and the errorMessage of any failed step. To diagnose a failure, look for a step whose actionResult.actionStatus is ERROR and read its errorMessage. When a step has a subFlowTxId, call flows.history again with that id to descend into the sub-flow's own history.

flows.history complements automation.status: automation.status reports only the aggregate state of a run, while flows.history returns the full step list. Use automation.status for a quick status check, and flows.history when you need step-by-step detail.

Example agent prompts:

Why did transaction 9f3a4c10-2c47-4e11-9d7a-7b1f5b3a82e8 fail?

Show me the steps of the last NightlyAssetSync run and how long each one took.

The agent obtains the transactionId from automation.status or flows.running, calls flows.history, and explains the run from the step statuses and error messages.