Version: v12

Flow and Automation Management API

The Flow and Automation Management API lets you drive Brinqa workflows from your own scripts or agents. You can launch a flow or an automation, poll its status, review its step-by-step execution history, resume it when it pauses for input, and cancel it if it is no longer needed.

A Flow is a series of steps with defined paths and transitions. An Automation runs a Flow against a dataset, with extra controls over when the Flow runs (manual, scheduled, or as part of orchestration). The API lets you launch either one. Once launched, both produce a transactionId that you use for status, history, resume, and cancel.

Authentication

The Flow and Automation Management API uses API tokens for authentication. See API Token Authentication for instructions on generating, using, and managing API tokens.

API and MCP access

Flows are not exposed to the API or to MCP unless they are opted in. A Flow becomes accessible when its "API & MCP Access" toggle is enabled on the flow definition. Button flows are always accessible and need no toggle, except management flows (Brinqa's built-in system Flows), which follow the same opt-in toggle as regular flows: they are not accessible until the "API & MCP Access" toggle is enabled on their definition. Enabling API access also enables MCP access, because MCP is a layer over the same API.

Endpoints

Operation	Method and path
List API-accessible flows	`GET /v1/api/automation/management/flows`
Get an API-accessible flow	`GET /v1/api/automation/management/flows/{nameOrId}`
Launch a flow	`POST /v1/api/automation/management/flow/{nameOrId}/launch`
Launch an automation	`POST /v1/api/automation/management/automation/{nameOrId}/launch`
Get instance status	`GET /v1/api/automation/management/{transactionId}`
Get instance history	`GET /v1/api/automation/history/{transactionId}`
Resume an instance	`PUT /v1/api/automation/management/{transactionId}/resume`
Cancel an instance	`DELETE /v1/api/automation/management/{transactionId}`

The status, history, resume, and cancel endpoints are type-agnostic. They act on any transactionId regardless of whether it came from a Flow launch or an Automation launch.

List API-accessible flows

Returns the Flows that are enabled for API and MCP access. A Flow is included when its "API & MCP Access" toggle is enabled, or when it is a button flow that is not a management flow (those are always accessible). Flows that are not enabled are omitted. Results are sorted by name and returned in pages of 25. Request each page in turn, increasing page, until nextPage is null.

GET /v1/api/automation/management/flows

Query parameters:

Parameter	Type	Required	Description
`page`	integer	No	Zero-based page number. Defaults to `0`. A negative value returns `400`.
`nameFilter`	string	No	Case-insensitive substring matched against each flow's name and title. Only matching flows are returned.

Headers:

Authorization: ApiKey <your-api-token>

Response: 200 OK

{
  "results": [
    {
      "name": "AssetTagging",
      "title": "Asset Tagging",
      "description": "Tags assets based on their attributes.",
      "active": true
    }
  ],
  "totalRows": 1,
  "page": 0,
  "pageSize": 25,
  "nextPage": null
}

Field	Type	Description
`results`	array	The flows on this page.
`results[].name`	string	The flow's internal name.
`results[].title`	string	The flow's display title.
`results[].description`	string	The flow's description.
`results[].active`	boolean	Whether the flow is active.
`totalRows`	number	Total number of accessible flows matching the filter across all pages.
`page`	number	The zero-based number of the returned page.
`pageSize`	number	The page size, always `25`.
`nextPage`	number	The next page number, or `null` on the last page.

Example:

curl 'https://<your-brinqa-instance>/v1/api/automation/management/flows?nameFilter=asset' \
  -H 'Authorization: ApiKey <your-api-token>'

note

Replace <your-brinqa-instance> with the URL of your Brinqa Platform and <your-api-token> with your API token.

Get an API-accessible flow

Returns the detail of one Flow that is enabled for API and MCP access, resolved by name or id.

GET /v1/api/automation/management/flows/{nameOrId}

Path parameters:

Parameter	Description
`nameOrId`	The name or id of the flow.

Headers:

Authorization: ApiKey <your-api-token>

Response: 200 OK

{
  "name": "AssetTagging",
  "title": "Asset Tagging",
  "description": "Tags assets based on their attributes.",
  "active": true,
  "triggerType": "manual",
  "lastStatus": "SUCCESS",
  "lastExecution": "2026-04-27T18:05:32Z",
  "lastSuccess": "2026-04-27T18:05:32Z",
  "lastFailed": null,
  "nextRun": null,
  "categories": ["Asset Management"],
  "dateCreated": "2026-01-14T09:12:00Z",
  "lastUpdated": "2026-04-20T11:30:45Z"
}

Field	Type	Description
`name`	string	The flow's internal name.
`title`	string	The flow's display title.
`description`	string	The flow's description.
`active`	boolean	Whether the flow is active.
`triggerType`	string	How the flow is triggered. One of `manual`, `cron`, `fixedInterval`, `event`, or `webhook`.
`lastStatus`	string	Status of the most recent execution. See Status values.
`lastExecution`	string	ISO 8601 timestamp of the most recent execution, or `null` if the flow has never run.
`lastSuccess`	string	ISO 8601 timestamp of the most recent successful execution, or `null`.
`lastFailed`	string	ISO 8601 timestamp of the most recent failed execution, or `null`.
`nextRun`	string	ISO 8601 timestamp of the next scheduled run, or `null` when the flow is not scheduled.
`categories`	array	The categories assigned to the flow.
`dateCreated`	string	ISO 8601 timestamp for when the flow was created.
`lastUpdated`	string	ISO 8601 timestamp for when the flow was last updated.

A Flow that exists but is not enabled for API and MCP access returns 403, not 404. The response explains that the Flow is not enabled and that the "API & MCP Access" toggle on the flow definition must be enabled. When the caller has permission to edit Flows, the message also includes a link to the flow editor. A name or id that matches no Flow returns 404.

Example:

curl 'https://<your-brinqa-instance>/v1/api/automation/management/flows/AssetTagging' \
  -H 'Authorization: ApiKey <your-api-token>'

note

Replace <your-brinqa-instance> with the URL of your Brinqa Platform and <your-api-token> with your API token.

Launch a flow

Launches a Flow by name or id with optional arguments. The Flow must be enabled for API and MCP access. Launching a Flow that is not enabled returns 403 with a message explaining that the "API & MCP Access" toggle on the flow definition must be enabled; when the caller has permission to edit Flows, the message also includes a link to the flow editor.

POST /v1/api/automation/management/flow/{nameOrId}/launch

Path parameters:

Parameter	Description
`nameOrId`	The name or id of the Flow to launch.

Headers:

Content-Type: application/json
Authorization: ApiKey <your-api-token>

Request body (optional):

{
  "arguments": {
    "assetId": "1847261953084"
  }
}

Field	Type	Required	Description
`arguments`	object	No	Key/value pairs passed into the Flow as launch arguments. The accepted keys depend on the Flow definition.
`transactionId`	string	No	A caller-supplied identifier for the new instance. Most clients omit this field and let the server generate one. Supply your own only if your integration needs to track the instance under an identifier from an external system.

Response: 201 Created

HTTP/2 201
Location: /v1/api/automation/management/<transactionId>

The Location header holds the URL of the new instance. Extract the transactionId from the last path segment to call the status, resume, and cancel endpoints.

Example:

curl -i -X POST 'https://<your-brinqa-instance>/v1/api/automation/management/flow/AssetTagging/launch' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: ApiKey <your-api-token>' \
  -d '{
    "arguments": { "assetId": "1847261953084" }
  }'

note

Replace <your-brinqa-instance> with the URL of your Brinqa Platform and <your-api-token> with your API token.

Launch an automation

Launches an Automation by name or id. Automations do not accept launch arguments.

POST /v1/api/automation/management/automation/{nameOrId}/launch

Path parameters:

Parameter	Description
`nameOrId`	The name or id of the Automation to launch.

Headers:

Authorization: ApiKey <your-api-token>

Request body: none.

Response: 201 Created

HTTP/2 201
Location: /v1/api/automation/management/<transactionId>

The transactionId is always server-generated for Automation launches.

Example:

curl -i -X POST 'https://<your-brinqa-instance>/v1/api/automation/management/automation/NightlyAssetSync/launch' \
  -H 'Authorization: ApiKey <your-api-token>'

Get instance status

Returns the current status of a running or completed instance. Works for any transactionId regardless of how the instance was launched.

GET /v1/api/automation/management/{transactionId}

Headers:

Authorization: ApiKey <your-api-token>

Response: 200 OK

{
  "name": "AssetTagging",
  "title": "Asset Tagging",
  "start": "2026-04-27T18:05:32Z",
  "end": null,
  "username": "jdoe@example.com",
  "status": "RUNNING"
}

Field	Type	Description
`name`	string	Name of the launched Flow or Automation.
`title`	string	Human-readable title of the Flow or Automation.
`start`	string	ISO 8601 timestamp for when the instance started.
`end`	string	ISO 8601 timestamp for when the instance reached a terminal status. `null` until the instance completes.
`username`	string	User the instance is running as.
`status`	string	Current lifecycle status. See Status values.

Status values

The status field reports where the instance is in its lifecycle.

Group	Value	Meaning
Active	`INIT`	The instance has been created and is initializing.
Active	`RUNNING`	The instance is executing normally.
Paused	`TIME_PAUSED`	Paused until a scheduled time interval elapses.
Paused	`EVENT_PAUSED`	Paused while waiting for an event.
Paused	`PAUSED`	Paused while waiting for a webhook.
Paused	`RETRY_PAUSED`	Paused after an error, waiting to retry.
Terminal	`SUCCESS`	Completed successfully.
Terminal	`PARTIAL_SUCCESS`	Completed successfully, with some failures skipped.
Terminal	`FAILED`	Completed with a failure.
Terminal	`CANCELED`	Canceled by user request.

Terminal statuses are final. Resume and cancel on an instance in a terminal status return 404.

Example:

curl 'https://<your-brinqa-instance>/v1/api/automation/management/9f3a4c10-2c47-4e11-9d7a-7b1f5b3a82e8' \
  -H 'Authorization: ApiKey <your-api-token>'

Get instance history

Returns the per-step execution history of an instance: every step it executed, with the step name, action type, status, start and end timestamps, and the error message of any failed step. Use it to diagnose why a run failed or to audit what it did. Works for any transactionId regardless of how the instance was launched.

Where Get instance status reports only the aggregate state of a run, this endpoint returns the full step list.

GET /v1/api/automation/history/{transactionId}

Query parameters:

Parameter	Type	Required	Description
`ascOrder`	boolean	No	When `true`, returns steps in ascending start-date (execution) order. Defaults to `false` (newest first).

Headers:

Authorization: ApiKey <your-api-token>

Response: 200 OK

[
  {
    "id": "1024",
    "stepName": "create-ticket",
    "stepTitle": "Create Ticket",
    "nextStep": null,
    "actionType": "CreateTicketAction",
    "flowStatus": "FAILED",
    "actionResult": {
      "actionStatus": "ERROR",
      "arguments": {},
      "results": {}
    },
    "start": "2026-07-06T18:04:11Z",
    "end": "2026-07-06T18:04:15Z",
    "errorMessage": "Connection to ticketing service refused",
    "subFlowTxId": null
  },
  {
    "id": "1023",
    "stepName": "find-findings",
    "stepTitle": "Find Findings",
    "nextStep": "create-ticket",
    "actionType": "SearchAction",
    "flowStatus": "RUNNING",
    "actionResult": {
      "actionStatus": "SUCCESS",
      "arguments": {},
      "results": {}
    },
    "start": "2026-07-06T18:04:08Z",
    "end": "2026-07-06T18:04:11Z",
    "errorMessage": null,
    "subFlowTxId": null
  }
]

Field	Type	Description
`id`	string	Unique ID of the step in the run history.
`stepName`	string	Internal name of the executed step.
`stepTitle`	string	Human-readable step title, with template variables resolved.
`nextStep`	string	Name of the step the flow transitioned to next. `null` on the final step.
`actionType`	string	Action class the step executed, for example `CreateTicketAction`.
`flowStatus`	string	Flow-level status after the step. See Status values.
`actionResult.actionStatus`	string	Step-level result. One of `SUCCESS`, `PARTIAL_SUCCESS`, `SKIPPED`, `ERROR`, `TIMEOUT`, `POLL`, `CANCEL`. Failed steps report `ERROR`; `FAILED` exists only at the flow level.
`start`	string	ISO 8601 timestamp at which the step started.
`end`	string	ISO 8601 timestamp at which the step ended. `null` while the step is executing.
`errorMessage`	string	Error message of a failed step. `null` on successful steps.
`subFlowTxId`	string	Transaction ID of the sub-flow launched by the step, if the step ran a sub-flow. Query this endpoint again with that ID to inspect the sub-flow's own history.

Example:

curl 'https://<your-brinqa-instance>/v1/api/automation/history/9f3a4c10-2c47-4e11-9d7a-7b1f5b3a82e8?ascOrder=true' \
  -H 'Authorization: ApiKey <your-api-token>'

Resume an instance

Resumes a paused instance, optionally injecting arguments into the wait step.

PUT /v1/api/automation/management/{transactionId}/resume

Headers:

Content-Type: application/json
Authorization: ApiKey <your-api-token>

Request body (optional):

{
  "arguments": {
    "approved": true
  }
}

Field	Type	Required	Description
`arguments`	object	No	Key/value pairs to inject into the paused wait step. The accepted keys depend on the step definition. Omit the body to resume with no arguments.

Response: 202 Accepted

The resume is accepted and the instance moves out of the waiting state to continue from the next step. Poll the status endpoint to track progress.

Example:

curl -X PUT 'https://<your-brinqa-instance>/v1/api/automation/management/9f3a4c10-2c47-4e11-9d7a-7b1f5b3a82e8/resume' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: ApiKey <your-api-token>' \
  -d '{
    "arguments": { "approved": true }
  }'

Cancel an instance

Cancels an active instance.

DELETE /v1/api/automation/management/{transactionId}

Headers:

Authorization: ApiKey <your-api-token>

Response: 202 Accepted when the instance was active and the cancel request was accepted. Returns 404 Not Found if the instance is not active (already completed, cancelled, or unknown).

Example:

curl -i -X DELETE 'https://<your-brinqa-instance>/v1/api/automation/management/9f3a4c10-2c47-4e11-9d7a-7b1f5b3a82e8' \
  -H 'Authorization: ApiKey <your-api-token>'

Error handling

HTTP Status	Meaning	Common cause
`201 Created`	Launch accepted.	Normal launch response. The `Location` header holds the new instance URL.
`200 OK`	Status returned.	Normal response from the status endpoint.
`202 Accepted`	Resume or cancel accepted.	The instance was active; the resume or cancel was issued. Poll the status endpoint to confirm.
`400 Bad Request`	Invalid request parameter.	The `page` query parameter on the flow list endpoint is negative.
`401 Unauthorized`	Authentication failed.	Missing, invalid, expired, or revoked API token.
`403 Forbidden`	The caller lacks permission, or the target Flow is not enabled for API and MCP access.	The token's user does not have access to the resource, or the Flow's "API & MCP Access" toggle is off. When it is off, enable the toggle on the flow definition; the response includes an editor link for callers who can edit flows.
`404 Not Found`	The Flow, Automation, or instance does not exist.	Wrong `nameOrId` or `transactionId`. Returned by cancel for any inactive instance.
`429 Too Many Requests`	Rate limit exceeded.	Too many requests in a short period. Wait and retry after the `Retry-After` interval.

Authentication​

API and MCP access​

Endpoints​

List API-accessible flows​

Get an API-accessible flow​

Launch a flow​

Launch an automation​

Get instance status​

Status values​

Get instance history​

Resume an instance​

Cancel an instance​

Error handling​

Authentication

API and MCP access

Endpoints

List API-accessible flows

Get an API-accessible flow

Launch a flow

Launch an automation

Get instance status

Status values

Get instance history

Resume an instance

Cancel an instance

Error handling