# Overview

<!-- Generated from contracts/api-v2.yaml at 5.0.0-beta.39 by flow/apis/assets/templates/README.mustache. Edit the template, not this page: see CLAUDE.md. -->

# Overview

Flow exposes a REST API under `/api/v2`. This page covers what every route has in common: where the API is, how to authenticate, and how errors, paging, labels and YAML work. The route pages list each operation with its parameters, permission and response.

## Where is the API?

Every route is under `/api/v2` on service-core. A resource that a workspace owns is under `/api/v2/workspace/{workspace}/…`, where `{workspace}` is the workspace's name. Everything else is global.

```bash
curl -H "Authorization: Bearer $FLOW_TOKEN" \
  "$FLOW_URL/api/v2/workspace/my-workspace/workflowrun/query?statuses=failed&limit=20"
```

`/api/v2` only gains routes and fields within 5.x, so a client written against an earlier 5.x release keeps working against a later one. The [API changelog](https://www.useboomerang.io/docs/flow/main/apis/changelog) lists what changed from the v4 API. The health probe, `GET /health`, is outside `/api/v2` and needs no token.

## Try a route with curl

Each operation on the route pages ends with an example `curl` request. The request reads service-core's origin and your token from the shell, and each value in the path from a variable named after it:

```bash
export FLOW_URL=http://localhost:7700   # service-core's origin, without /api/v2
export FLOW_TOKEN=bfk_...               # a Flow token
export WORKSPACE=example-workspace      # a workspace name
export RUN_ID=6aed1feb739ea20d87d5b99e  # a workflow run ID
```

Where a route takes a JSON body, the request either sends `body.json`, shown under it as the example request body, or a body built from the request schema's required fields, with placeholder values to replace. Some operations also show an example response, captured from a running Flow and shortened.

## Authenticate

Every route needs a Flow token, except the five that Slack and GitHub call: the GitHub App callback and four Slack routes. Those verify the request themselves, and their **Authorization** section reads "No authorization required". Send the token in one of the ways below.

### BearerAuth

`Authorization: Bearer <token>`, an HTTP bearer token. Send a Flow token, such as a `bfk_` key token. Behind an authenticating proxy, Flow also accepts the proxy's JSON Web Token (JWT) here, which is the format the contract names: `JWT`.


### access_token

`?access_token=<token>`, a URL query parameter. A token in the URL, for webhook senders that cannot set a header. Only the routes whose **Authorization** section lists `access_token` accept it: `POST /api/v2/webhook`, `POST /api/v2/event`, and `GET` or `POST /api/v2/callback`.

> [!WARNING]
> A token in a URL is recorded by every proxy and access log it passes through. Prefer a header. If a sender can only use the URL, give it a `key` token with only the `webhook/action` permission on its workspace.


### x-access-token

`x-access-token: <token>`, an HTTP header. Send a Flow token here instead of in `Authorization`.


### Which token?

Each route's description names the permission it needs and the token kinds it accepts, for example "Requires the `workflowrun/read` permission, from a global, key, user, session token." [Machine tokens](https://www.useboomerang.io/docs/flow/main/hosting/machine-tokens) covers the token kinds and how to create them, and [Tokens](https://www.useboomerang.io/docs/flow/main/architecture/security#tokens) covers what each kind grants.

A request without a valid token is `401`, with a `WWW-Authenticate: Bearer` header. A `403` means the credential lacks the permission the route needs. With `flow.security.enabled=false`, Flow checks no token at all: see [What happens with security off?](https://www.useboomerang.io/docs/flow/main/architecture/security#what-happens-with-security-off).

## Read an error

An error Flow raises is a `RestErrorResponse`:

```json
{
  "timestamp": "2026-09-01T10:00:00.000+00:00",
  "code": 1001,
  "reason": "QUERY_INVALID_FILTERS",
  "message": "Invalid query filters(labels) have been provided.",
  "status": "400 BAD_REQUEST"
}
```

| Field | Holds |
| --- | --- |
| `timestamp` | When Flow raised the error |
| `code` | A number. Below 1000 it mirrors the HTTP status, except 101, which two user errors carry. Then 10xx is generic, 11xx workspace, 12xx workflow, 13xx workflow run, 14xx task, 15xx task run, 16xx action, 17xx schedule, 18xx parameter, 19xx integration and 20xx artifact. |
| `reason` | The error's name, such as `WORKFLOWRUN_INVALID_REFERENCE`. Key on `reason`, not `code`: four codes each carry two reasons. 101 is `USER_NOT_FOUND` or `USER_UNABLE_TO_DELETE`, 429 is `TOO_MANY_REQUESTS` or `WORKFLOW_TRIGGER_DISABLED`, 1405 is `TASK_INVALID_WORKFLOWREF` or `TASK_DELETE_IN_USE`, and 1802 is `PARAMS_NON_UNIQUE_REFERENCE` or `PARAMS_NON_UNIQUE_KEY`. |
| `message` | A readable explanation |
| `status` | The HTTP status, as its code and name |

The response also carries `cause`, which is `null` unless the operator sets `flow.error.include-cause=true`. The default is `false`.

- A resource in the path that doesn't exist, or that you can't reach, is `404`, with a reason such as `WORKSPACE_INVALID_REF` or `WORKFLOWRUN_INVALID_REFERENCE`.
- Blank, missing or unusable input is `400`, with a reason such as `WORKFLOW_INVALID_REQ`.
- `PERMISSION_DENIED` carries code 403 but answers HTTP 401.
- A missing permission is `403`: the credential lacks the permission the route needs.
- A framework error, such as a malformed body or an unsupported method, keeps Spring's problem-detail body instead of a `RestErrorResponse`.

## Page through a list

List routes, usually ending `/query`, take these query parameters:
- `page`, counted from 0;
- `limit`;
- `order`, `ASC` or `DESC`;
- `sort`, a field name, where the list is sortable.

They return a page: the matches in `content`, with `totalElements`, `totalPages`, `number` and `size`. On the run, task run, workflow, task, workspace, user and token lists, leaving out `limit` returns every match. The action and schedule lists default to 10.

The run, task run, action and token lists also take `fromDate` and `toDate`, in epoch milliseconds: `fromDate` is included and `toDate` is not. `statuses` and `phase` ignore case. A value that names no status or phase is `400 QUERY_INVALID_FILTERS`.

## Filter by label

`labels` keeps the items that carry every `key=value` pair you list. URL-encode each pair and separate the pairs with commas: `labels=Organization%3DBoomerang,customKey%3Dtest`. Each pair splits on its first `=`, so `a%3Db%3Dc` matches the value `b=c`. A pair without a key or a value is `400 QUERY_INVALID_FILTERS`.

Labels under `boomerang.io/` are Flow's own. Flow sets some, such as `boomerang.io/model` on an AI task run, and drops any that a client sends. `PATCH` on a workspace replaces its labels, and `PUT` on a workflow merges them unless you add `replace=true`.

## Send and receive YAML

The task routes, under `/api/v2/task` and `/api/v2/workspace/{workspace}/task`, also serve and accept a task as YAML. Send `Accept: application/x-yaml` to read YAML and `Content-Type: application/x-yaml` to write it. With no `Accept` header, Flow answers JSON.

The YAML is a Tekton Task. Its `boomerang.io/params` annotation carries each parameter's other fields, so a task you read and apply back unchanged stays as it was.

## Use a client library

`flow-sdk` is the public API as a Java library: `Flow.connect(url, token)`, then typed calls to submit, read, cancel and retry workflow runs, query runs and task runs by label, and read Insights. Each Flow release publishes it to GitHub Packages as `io.boomerang:flow-sdk`, at the release's version. Use the version of the Flow you run against. Reading GitHub Packages needs a GitHub token with `read:packages`. [Call Flow with flow-sdk](https://www.useboomerang.io/docs/flow/main/extend/embed-flow#call-flow-with-flow-sdk) has the dependency, an example and what the library covers.

Flow publishes no client for other languages. Generate one from the contract with a tool such as [OpenAPI Generator](https://openapi-generator.tech).

## Get the full contract

These pages are generated from [`contracts/api-v2.yaml`](https://github.com/boomerang-io/flow/blob/5.0.0-beta.39/contracts/api-v2.yaml) at `5.0.0-beta.39`, an OpenAPI 3.1.0 document. The rules every route follows are in [`specifications/api-contract.md`](https://github.com/boomerang-io/flow/blob/5.0.0-beta.39/specifications/api-contract.md). A running service-core serves the same document at `/api/docs/spec/api-v2`, and Swagger UI at `/api/docs/swagger-ui`.

## Routes


### Actions

| Route | Endpoint |
| ----- | -------- |
| [**Provide an update for an Action**](https://www.useboomerang.io/docs/flow/main/apis/ActionsRoute#provide-an-update-for-an-action) | `PUT /api/v2/workspace/{workspace}/action` |
| [**Retrieve a specific Action by Id**](https://www.useboomerang.io/docs/flow/main/apis/ActionsRoute#retrieve-a-specific-action-by-id) | `GET /api/v2/workspace/{workspace}/action/{actionId}` |
| [**Search for Actions**](https://www.useboomerang.io/docs/flow/main/apis/ActionsRoute#search-for-actions) | `GET /api/v2/workspace/{workspace}/action/query` |
| [**Get Actions Summary**](https://www.useboomerang.io/docs/flow/main/apis/ActionsRoute#get-actions-summary) | `GET /api/v2/workspace/{workspace}/action/summary` |

### Artifacts

| Route | Endpoint |
| ----- | -------- |
| [**Delete a workspace artifact, by id, and its file**](https://www.useboomerang.io/docs/flow/main/apis/ArtifactsRoute#delete-a-workspace-artifact-by-id-and-its-file) | `DELETE /api/v2/workspace/{workspace}/artifacts/{artifactId}` |
| [**Delete a run's artifact, by name, and its file**](https://www.useboomerang.io/docs/flow/main/apis/ArtifactsRoute#delete-a-runs-artifact-by-name-and-its-file) | `DELETE /api/v2/workspace/{workspace}/workflowrun/{workflowRunId}/artifacts/{name}` |
| [**Download an artifact's file**](https://www.useboomerang.io/docs/flow/main/apis/ArtifactsRoute#download-an-artifacts-file) | `GET /api/v2/workspace/{workspace}/workflowrun/{workflowRunId}/artifacts/{name}` |
| [**List a WorkflowRun's artifacts, expired ones included**](https://www.useboomerang.io/docs/flow/main/apis/ArtifactsRoute#list-a-workflowruns-artifacts-expired-ones-included) | `GET /api/v2/workspace/{workspace}/workflowrun/{workflowRunId}/artifacts` |
| [**List the workspace's artifacts, largest first**](https://www.useboomerang.io/docs/flow/main/apis/ArtifactsRoute#list-the-workspaces-artifacts-largest-first) | `GET /api/v2/workspace/{workspace}/artifacts` |

### Audit

| Route | Endpoint |
| ----- | -------- |
| [**Query the audit trail**](https://www.useboomerang.io/docs/flow/main/apis/AuditRoute#query-the-audit-trail) | `GET /api/v2/audit` |
| [**Count the audit trail by outcome**](https://www.useboomerang.io/docs/flow/main/apis/AuditRoute#count-the-audit-trail-by-outcome) | `GET /api/v2/audit/stats` |

### Insights

| Route | Endpoint |
| ----- | -------- |
| [**Summarise a workspace's runs over a period**](https://www.useboomerang.io/docs/flow/main/apis/InsightsRoute#summarise-a-workspaces-runs-over-a-period) | `GET /api/v2/workspace/{workspace}/insights` |
| [**Summarise runs across workspaces over a period**](https://www.useboomerang.io/docs/flow/main/apis/InsightsRoute#summarise-runs-across-workspaces-over-a-period) | `GET /api/v2/insights` |
| [**List task runs across workspaces**](https://www.useboomerang.io/docs/flow/main/apis/InsightsRoute#list-task-runs-across-workspaces) | `GET /api/v2/insights/taskruns` |
| [**Group a workspace's task runs over a period**](https://www.useboomerang.io/docs/flow/main/apis/InsightsRoute#group-a-workspaces-task-runs-over-a-period) | `GET /api/v2/workspace/{workspace}/insights/tasks` |
| [**Group task runs across workspaces over a period**](https://www.useboomerang.io/docs/flow/main/apis/InsightsRoute#group-task-runs-across-workspaces-over-a-period) | `GET /api/v2/insights/tasks` |
| [**Detail one workflow's runs over a period**](https://www.useboomerang.io/docs/flow/main/apis/InsightsRoute#detail-one-workflows-runs-over-a-period) | `GET /api/v2/workspace/{workspace}/insights/workflow/{workflow}` |

### Integrations

| Route | Endpoint |
| ----- | -------- |
| [**Retrieve the integrations and their status within a Workspace**](https://www.useboomerang.io/docs/flow/main/apis/IntegrationsRoute#retrieve-the-integrations-and-their-status-within-a-workspace) | `GET /api/v2/integration` |
| [**Receive the GitHub App installation setup callback**](https://www.useboomerang.io/docs/flow/main/apis/IntegrationsRoute#receive-the-github-app-installation-setup-callback) | `GET /api/v2/integration/github/callback` |
| [**Retrieve the installation ID and store against a workspace**](https://www.useboomerang.io/docs/flow/main/apis/IntegrationsRoute#retrieve-the-installation-id-and-store-against-a-workspace) | `GET /api/v2/integration/github/installation` |
| [**Unlinks the GitHub Installation ID from a Workspace**](https://www.useboomerang.io/docs/flow/main/apis/IntegrationsRoute#unlinks-the-github-installation-id-from-a-workspace) | `POST /api/v2/integration/github/unlink` |
| [**Install URL Redirect**](https://www.useboomerang.io/docs/flow/main/apis/IntegrationsRoute#install-url-redirect) | `GET /api/v2/integration/slack/install` |
| [**Receive Slack Oauth2 request**](https://www.useboomerang.io/docs/flow/main/apis/IntegrationsRoute#receive-slack-oauth2-request) | `GET /api/v2/integration/slack/auth` |
| [**Receive Slack Slash Commands**](https://www.useboomerang.io/docs/flow/main/apis/IntegrationsRoute#receive-slack-slash-commands) | `POST /api/v2/integration/slack/commands` |
| [**Receive Slack Events**](https://www.useboomerang.io/docs/flow/main/apis/IntegrationsRoute#receive-slack-events) | `POST /api/v2/integration/slack/events` |
| [**Receive Slack Interactivity**](https://www.useboomerang.io/docs/flow/main/apis/IntegrationsRoute#receive-slack-interactivity) | `POST /api/v2/integration/slack/interactivity` |
| [**Shares an integration's credentials with the Workspace's tasks as managed Workspace parameters, or stops sharing them: GitHub's installation token, Slack's bot token, or the values entered for a form integration such as Google or Microsoft**](https://www.useboomerang.io/docs/flow/main/apis/IntegrationsRoute#shares-an-integrations-credentials-with-the-workspaces-tasks-as-managed-workspace-parameters-or-stops-sharing-them-githubs-installation-token-slacks-bot-token-or-the-values-entered-for-a-form-integration-such-as-google-or-microsoft) | `POST /api/v2/integration/{integration}/share` |
| [**Disconnects the Slack installation from a Workspace**](https://www.useboomerang.io/docs/flow/main/apis/IntegrationsRoute#disconnects-the-slack-installation-from-a-workspace) | `POST /api/v2/integration/slack/unlink` |

### Parameters

| Route | Endpoint |
| ----- | -------- |
| [**Create a global Param**](https://www.useboomerang.io/docs/flow/main/apis/ParametersRoute#create-a-global-param) | `POST /api/v2/parameters` |
| [**Delete a global Param**](https://www.useboomerang.io/docs/flow/main/apis/ParametersRoute#delete-a-global-param) | `DELETE /api/v2/parameters/{name}` |
| [**Get all global Params**](https://www.useboomerang.io/docs/flow/main/apis/ParametersRoute#get-all-global-params) | `GET /api/v2/parameters` |
| [**Update a global Param**](https://www.useboomerang.io/docs/flow/main/apis/ParametersRoute#update-a-global-param) | `PATCH /api/v2/parameters/{name}` |

### Profile

| Route | Endpoint |
| ----- | -------- |
| [**Get your Profile**](https://www.useboomerang.io/docs/flow/main/apis/ProfileRoute#get-your-profile) | `GET /api/v2/profile` |
| [**Patch your Profile**](https://www.useboomerang.io/docs/flow/main/apis/ProfileRoute#patch-your-profile) | `PATCH /api/v2/profile` |

### Schedules

| Route | Endpoint |
| ----- | -------- |
| [**Create a Schedule.**](https://www.useboomerang.io/docs/flow/main/apis/SchedulesRoute#create-a-schedule) | `POST /api/v2/workspace/{workspace}/schedule` |
| [**Delete a Schedule.**](https://www.useboomerang.io/docs/flow/main/apis/SchedulesRoute#delete-a-schedule) | `DELETE /api/v2/workspace/{workspace}/schedule/{scheduleId}` |
| [**Retrieve a Schedule.**](https://www.useboomerang.io/docs/flow/main/apis/SchedulesRoute#retrieve-a-schedule) | `GET /api/v2/workspace/{workspace}/schedule/{scheduleId}` |
| [**Retrieve Calendars for Schedules by Dates.**](https://www.useboomerang.io/docs/flow/main/apis/SchedulesRoute#retrieve-calendars-for-schedules-by-dates) | `GET /api/v2/workspace/{workspace}/schedule/calendars` |
| [**Search for Schedules**](https://www.useboomerang.io/docs/flow/main/apis/SchedulesRoute#search-for-schedules) | `GET /api/v2/workspace/{workspace}/schedule/query` |
| [**Apply a Schedule.**](https://www.useboomerang.io/docs/flow/main/apis/SchedulesRoute#apply-a-schedule) | `PUT /api/v2/workspace/{workspace}/schedule` |
| [**Validate a Schedules CRON.**](https://www.useboomerang.io/docs/flow/main/apis/SchedulesRoute#validate-a-schedules-cron) | `GET /api/v2/workspace/{workspace}/schedule/validate-cron` |

### System

| Route | Endpoint |
| ----- | -------- |
| [**Retrieve Boomerang Flow Settings**](https://www.useboomerang.io/docs/flow/main/apis/SystemRoute#retrieve-boomerang-flow-settings) | `GET /api/v2/settings` |
| [**Retrieve feature flags.**](https://www.useboomerang.io/docs/flow/main/apis/SystemRoute#retrieve-feature-flags) | `GET /api/v2/features` |
| [**Retrieve this instances context, features, and navigation.**](https://www.useboomerang.io/docs/flow/main/apis/SystemRoute#retrieve-this-instances-context-features-and-navigation) | `GET /api/v2/context` |
| [**Retrieve navigation.**](https://www.useboomerang.io/docs/flow/main/apis/SystemRoute#retrieve-navigation) | `GET /api/v2/navigation` |
| [**Update Boomerang Flow Settings**](https://www.useboomerang.io/docs/flow/main/apis/SystemRoute#update-boomerang-flow-settings) | `PATCH /api/v2/settings` |
| [**List outbox rows, dead ones by default.**](https://www.useboomerang.io/docs/flow/main/apis/SystemRoute#list-outbox-rows-dead-ones-by-default) | `GET /api/v2/system/outbox` |
| [**Register and activate an installation of Flow**](https://www.useboomerang.io/docs/flow/main/apis/SystemRoute#register-and-activate-an-installation-of-flow) | `PUT /api/v2/activate` |
| [**Replay outbox rows**](https://www.useboomerang.io/docs/flow/main/apis/SystemRoute#replay-outbox-rows) | `PUT /api/v2/system/outbox/replay` |

### Task Runs

| Route | Endpoint |
| ----- | -------- |
| [**Search for TaskRuns across WorkflowRuns**](https://www.useboomerang.io/docs/flow/main/apis/TaskRunsRoute#search-for-taskruns-across-workflowruns) | `GET /api/v2/workspace/{workspace}/taskrun/query` |
| [**Retrieve a TaskRuns log from a specific WorkflowRun.**](https://www.useboomerang.io/docs/flow/main/apis/TaskRunsRoute#retrieve-a-taskruns-log-from-a-specific-workflowrun) | `GET /api/v2/taskrun/{taskRunId}/log` |

### Tasks

| Route | Endpoint |
| ----- | -------- |
| [**Update, replace, or create a global task using Tekton Task YAML**](https://www.useboomerang.io/docs/flow/main/apis/TasksRoute#update-replace-or-create-a-global-task-using-tekton-task-yaml) | `PUT /api/v2/task/{name}` |
| [**Create a new Task using Tekton Task YAML**](https://www.useboomerang.io/docs/flow/main/apis/TasksRoute#create-a-new-task-using-tekton-task-yaml) | `POST /api/v2/task` |
| [**Delete a Task**](https://www.useboomerang.io/docs/flow/main/apis/TasksRoute#delete-a-task) | `DELETE /api/v2/task/{name}` |
| [**Retrieve a global task as Tekton Task YAML. If no version specified, the latest version is returned.**](https://www.useboomerang.io/docs/flow/main/apis/TasksRoute#retrieve-a-global-task-as-tekton-task-yaml-if-no-version-specified-the-latest-version-is-returned) | `GET /api/v2/task/{name}` |
| [**Retrieve a global task's changelog**](https://www.useboomerang.io/docs/flow/main/apis/TasksRoute#retrieve-a-global-tasks-changelog) | `GET /api/v2/task/{name}/changelog` |
| [**Search for Task. If workspaces are provided it will query the workspaces. If no workspaces are provided it will query Global Task Templates**](https://www.useboomerang.io/docs/flow/main/apis/TasksRoute#search-for-task-if-workspaces-are-provided-it-will-query-the-workspaces-if-no-workspaces-are-provided-it-will-query-global-task-templates) | `GET /api/v2/task/query` |
| [**Validate a global task's Tekton Task YAML**](https://www.useboomerang.io/docs/flow/main/apis/TasksRoute#validate-a-global-tasks-tekton-task-yaml) | `POST /api/v2/task/validate` |

### Token Management

| Route | Endpoint |
| ----- | -------- |
| [**Create Token**](https://www.useboomerang.io/docs/flow/main/apis/TokenManagementRoute#create-token) | `POST /api/v2/token` |
| [**Delete Token**](https://www.useboomerang.io/docs/flow/main/apis/TokenManagementRoute#delete-token) | `DELETE /api/v2/token/{id}` |
| [**Retrieve the permission catalog for building a Token**](https://www.useboomerang.io/docs/flow/main/apis/TokenManagementRoute#retrieve-the-permission-catalog-for-building-a-token) | `GET /api/v2/token/catalog` |
| [**Search for Tokens**](https://www.useboomerang.io/docs/flow/main/apis/TokenManagementRoute#search-for-tokens) | `GET /api/v2/token/query` |

### Users

| Route | Endpoint |
| ----- | -------- |
| [**Update a Boomerang Flow Users details**](https://www.useboomerang.io/docs/flow/main/apis/UsersRoute#update-a-boomerang-flow-users-details) | `PATCH /api/v2/user/{userId}` |
| [**Delete a Boomerang Flow user**](https://www.useboomerang.io/docs/flow/main/apis/UsersRoute#delete-a-boomerang-flow-user) | `DELETE /api/v2/user/{userId}` |
| [**Get a Users details**](https://www.useboomerang.io/docs/flow/main/apis/UsersRoute#get-a-users-details) | `GET /api/v2/user/{userId}` |
| [**Get a Users Workspace memberships**](https://www.useboomerang.io/docs/flow/main/apis/UsersRoute#get-a-users-workspace-memberships) | `GET /api/v2/user/{userId}/workspaces` |
| [**Search for Users**](https://www.useboomerang.io/docs/flow/main/apis/UsersRoute#search-for-users) | `GET /api/v2/user/query` |

### Webhooks and Events

| Route | Endpoint |
| ----- | -------- |
| [**Accept CloudEvent**](https://www.useboomerang.io/docs/flow/main/apis/WebhooksAndEventsRoute#accept-cloudevent) | `POST /api/v2/event` |
| [**Accept Wait for Event Callbcak**](https://www.useboomerang.io/docs/flow/main/apis/WebhooksAndEventsRoute#accept-wait-for-event-callbcak) | `GET /api/v2/callback` |
| [**Accept Wait for Event Callback with JSON Payload**](https://www.useboomerang.io/docs/flow/main/apis/WebhooksAndEventsRoute#accept-wait-for-event-callback-with-json-payload) | `POST /api/v2/callback` |
| [**Accept Webhook payloads from various sources.**](https://www.useboomerang.io/docs/flow/main/apis/WebhooksAndEventsRoute#accept-webhook-payloads-from-various-sources) | `POST /api/v2/webhook` |

### Workflow Runs

| Route | Endpoint |
| ----- | -------- |
| [**Cancel a WorkflowRun**](https://www.useboomerang.io/docs/flow/main/apis/WorkflowRunsRoute#cancel-a-workflowrun) | `DELETE /api/v2/workspace/{workspace}/workflowrun/{workflowRunId}/cancel` |
| [**Retrieve a summary of WorkflowRuns by Status.**](https://www.useboomerang.io/docs/flow/main/apis/WorkflowRunsRoute#retrieve-a-summary-of-workflowruns-by-status) | `GET /api/v2/workspace/{workspace}/workflowrun/count` |
| [**Retrieve a specific WorkflowRun.**](https://www.useboomerang.io/docs/flow/main/apis/WorkflowRunsRoute#retrieve-a-specific-workflowrun) | `GET /api/v2/workspace/{workspace}/workflowrun/{workflowRunId}` |
| [**Pause a running WorkflowRun**](https://www.useboomerang.io/docs/flow/main/apis/WorkflowRunsRoute#pause-a-running-workflowrun) | `PUT /api/v2/workspace/{workspace}/workflowrun/{workflowRunId}/pause` |
| [**Purge a WorkflowRun with everything it owns and its lineage: its retries, its child runs, their task runs, actions, artifacts and logs. A run in flight is cancelled first. Audit records stay.**](https://www.useboomerang.io/docs/flow/main/apis/WorkflowRunsRoute#purge-a-workflowrun-with-everything-it-owns-and-its-lineage-its-retries-its-child-runs-their-task-runs-actions-artifacts-and-logs-a-run-in-flight-is-cancelled-first-audit-records-stay) | `DELETE /api/v2/workspace/{workspace}/workflowrun/{workflowRunId}` |
| [**Purge the WorkflowRuns matching every label, oldest first, each with its lineage. One call takes a page of matches and reports how many remain; repeat until none.**](https://www.useboomerang.io/docs/flow/main/apis/WorkflowRunsRoute#purge-the-workflowruns-matching-every-label-oldest-first-each-with-its-lineage-one-call-takes-a-page-of-matches-and-reports-how-many-remain-repeat-until-none) | `DELETE /api/v2/workspace/{workspace}/workflowrun` |
| [**Search for WorkflowRuns**](https://www.useboomerang.io/docs/flow/main/apis/WorkflowRunsRoute#search-for-workflowruns) | `GET /api/v2/workspace/{workspace}/workflowrun/query` |
| [**Resume a paused WorkflowRun**](https://www.useboomerang.io/docs/flow/main/apis/WorkflowRunsRoute#resume-a-paused-workflowrun) | `PUT /api/v2/workspace/{workspace}/workflowrun/{workflowRunId}/resume` |
| [**Retry WorkflowRun execution.**](https://www.useboomerang.io/docs/flow/main/apis/WorkflowRunsRoute#retry-workflowrun-execution) | `PUT /api/v2/workspace/{workspace}/workflowrun/{workflowRunId}/retry` |
| [**Start WorkflowRun execution. The WorkflowRun has to already have been queued.**](https://www.useboomerang.io/docs/flow/main/apis/WorkflowRunsRoute#start-workflowrun-execution-the-workflowrun-has-to-already-have-been-queued) | `PUT /api/v2/workspace/{workspace}/workflowrun/{workflowRunId}/start` |

### Workflows

| Route | Endpoint |
| ----- | -------- |
| [**Update, replace, or create new, Workflow for Canvas**](https://www.useboomerang.io/docs/flow/main/apis/WorkflowsRoute#update-replace-or-create-new-workflow-for-canvas) | `PUT /api/v2/workspace/{workspace}/workflow/{name}/compose` |
| [**Update, replace, or create new, Workflow**](https://www.useboomerang.io/docs/flow/main/apis/WorkflowsRoute#update-replace-or-create-new-workflow) | `PUT /api/v2/workspace/{workspace}/workflow` |
| [**Convert workflow to compose model for UI Designer and detailed Activity screens.**](https://www.useboomerang.io/docs/flow/main/apis/WorkflowsRoute#convert-workflow-to-compose-model-for-ui-designer-and-detailed-activity-screens) | `GET /api/v2/workspace/{workspace}/workflow/{name}/compose` |
| [**Create a new workflow**](https://www.useboomerang.io/docs/flow/main/apis/WorkflowsRoute#create-a-new-workflow) | `POST /api/v2/workspace/{workspace}/workflow` |
| [**Delete a workflow**](https://www.useboomerang.io/docs/flow/main/apis/WorkflowsRoute#delete-a-workflow) | `DELETE /api/v2/workspace/{workspace}/workflow/{name}` |
| [**Duplicates the workflow.**](https://www.useboomerang.io/docs/flow/main/apis/WorkflowsRoute#duplicates-the-workflow) | `POST /api/v2/workspace/{workspace}/workflow/{name}/duplicate` |
| [**Export the Workflow as JSON.**](https://www.useboomerang.io/docs/flow/main/apis/WorkflowsRoute#export-the-workflow-as-json) | `GET /api/v2/workspace/{workspace}/workflow/{name}/export` |
| [**Retrieve the parameters.**](https://www.useboomerang.io/docs/flow/main/apis/WorkflowsRoute#retrieve-the-parameters) | `GET /api/v2/workspace/{workspace}/workflow/{name}/available-parameters` |
| [**Retrieve a workflow's changelog**](https://www.useboomerang.io/docs/flow/main/apis/WorkflowsRoute#retrieve-a-workflows-changelog) | `GET /api/v2/workspace/{workspace}/workflow/{name}/changelog` |
| [**Retrieve a Workflow**](https://www.useboomerang.io/docs/flow/main/apis/WorkflowsRoute#retrieve-a-workflow) | `GET /api/v2/workspace/{workspace}/workflow/{name}` |
| [**Change what a workflow is**](https://www.useboomerang.io/docs/flow/main/apis/WorkflowsRoute#change-what-a-workflow-is) | `PATCH /api/v2/workspace/{workspace}/workflow/{name}` |
| [**Search for Workflows**](https://www.useboomerang.io/docs/flow/main/apis/WorkflowsRoute#search-for-workflows) | `GET /api/v2/workspace/{workspace}/workflow/query` |
| [**Submit a Workflow to be run. Will queue the WorkflowRun ready for execution.**](https://www.useboomerang.io/docs/flow/main/apis/WorkflowsRoute#submit-a-workflow-to-be-run-will-queue-the-workflowrun-ready-for-execution) | `POST /api/v2/workspace/{workspace}/workflow/{name}/submit` |

### Workspace Management

| Route | Endpoint |
| ----- | -------- |
| [**Create new workspace**](https://www.useboomerang.io/docs/flow/main/apis/WorkspaceManagementRoute#create-new-workspace) | `POST /api/v2/workspace` |
| [**Delete Approver Groups**](https://www.useboomerang.io/docs/flow/main/apis/WorkspaceManagementRoute#delete-approver-groups) | `DELETE /api/v2/workspace/{workspace}/approvers` |
| [**Delete Workspace Parameter**](https://www.useboomerang.io/docs/flow/main/apis/WorkspaceManagementRoute#delete-workspace-parameter) | `DELETE /api/v2/workspace/{workspace}/parameters/{name}` |
| [**Delete Workspace**](https://www.useboomerang.io/docs/flow/main/apis/WorkspaceManagementRoute#delete-workspace) | `DELETE /api/v2/workspace/{workspace}` |
| [**Retrieve Default Workspace Quota**](https://www.useboomerang.io/docs/flow/main/apis/WorkspaceManagementRoute#retrieve-default-workspace-quota) | `GET /api/v2/workspace/quotas/default` |
| [**Retrieve Workspace Roles**](https://www.useboomerang.io/docs/flow/main/apis/WorkspaceManagementRoute#retrieve-workspace-roles) | `GET /api/v2/workspace/roles` |
| [**Get workspace**](https://www.useboomerang.io/docs/flow/main/apis/WorkspaceManagementRoute#get-workspace) | `GET /api/v2/workspace/{workspace}` |
| [**Search for Workspaces**](https://www.useboomerang.io/docs/flow/main/apis/WorkspaceManagementRoute#search-for-workspaces) | `GET /api/v2/workspace/query` |
| [**Leave Workspace**](https://www.useboomerang.io/docs/flow/main/apis/WorkspaceManagementRoute#leave-workspace) | `DELETE /api/v2/workspace/{workspace}/leave` |
| [**Remove Workspace Members**](https://www.useboomerang.io/docs/flow/main/apis/WorkspaceManagementRoute#remove-workspace-members) | `DELETE /api/v2/workspace/{workspace}/members` |
| [**Reset Workspace Quota**](https://www.useboomerang.io/docs/flow/main/apis/WorkspaceManagementRoute#reset-workspace-quota) | `DELETE /api/v2/workspace/{workspace}/quotas` |
| [**Patch or update a workspace**](https://www.useboomerang.io/docs/flow/main/apis/WorkspaceManagementRoute#patch-or-update-a-workspace) | `PATCH /api/v2/workspace/{workspace}` |
| [**Validate workspace name and check uniqueness.**](https://www.useboomerang.io/docs/flow/main/apis/WorkspaceManagementRoute#validate-workspace-name-and-check-uniqueness) | `POST /api/v2/workspace/validate-name` |

### Workspace Tasks

| Route | Endpoint |
| ----- | -------- |
| [**Update, replace, or create a workspace task using Tekton Task YAML**](https://www.useboomerang.io/docs/flow/main/apis/WorkspaceTasksRoute#update-replace-or-create-a-workspace-task-using-tekton-task-yaml) | `PUT /api/v2/workspace/{workspace}/task/{name}` |
| [**Create a new Task Template using Tekton Task YAML**](https://www.useboomerang.io/docs/flow/main/apis/WorkspaceTasksRoute#create-a-new-task-template-using-tekton-task-yaml) | `POST /api/v2/workspace/{workspace}/task` |
| [**Delete a Workspace Task**](https://www.useboomerang.io/docs/flow/main/apis/WorkspaceTasksRoute#delete-a-workspace-task) | `DELETE /api/v2/workspace/{workspace}/task/{name}` |
| [**Retrieve a workspace task as Tekton Task YAML. If no version specified, the latest version is returned.**](https://www.useboomerang.io/docs/flow/main/apis/WorkspaceTasksRoute#retrieve-a-workspace-task-as-tekton-task-yaml-if-no-version-specified-the-latest-version-is-returned) | `GET /api/v2/workspace/{workspace}/task/{name}` |
| [**Retrieve a workspace task's changelog**](https://www.useboomerang.io/docs/flow/main/apis/WorkspaceTasksRoute#retrieve-a-workspace-tasks-changelog) | `GET /api/v2/workspace/{workspace}/task/{name}/changelog` |
| [**Search for Tasks. If workspaces are provided it will query the workspaces. If no workspaces are provided it will query Global Task Templates**](https://www.useboomerang.io/docs/flow/main/apis/WorkspaceTasksRoute#search-for-tasks-if-workspaces-are-provided-it-will-query-the-workspaces-if-no-workspaces-are-provided-it-will-query-global-task-templates) | `GET /api/v2/workspace/{workspace}/task/query` |
| [**Validate a workspace task's Tekton Task YAML**](https://www.useboomerang.io/docs/flow/main/apis/WorkspaceTasksRoute#validate-a-workspace-tasks-tekton-task-yaml) | `POST /api/v2/workspace/{workspace}/task/validate` |


## Models

- [AbstractParam](https://www.useboomerang.io/docs/flow/main/apis/models/AbstractParam)
- [Action](https://www.useboomerang.io/docs/flow/main/apis/models/Action)
- [ActionRequest](https://www.useboomerang.io/docs/flow/main/apis/models/ActionRequest)
- [ActionSummary](https://www.useboomerang.io/docs/flow/main/apis/models/ActionSummary)
- [Actioner](https://www.useboomerang.io/docs/flow/main/apis/models/Actioner)
- [ApproverGroup](https://www.useboomerang.io/docs/flow/main/apis/models/ApproverGroup)
- [ApproverGroupRequest](https://www.useboomerang.io/docs/flow/main/apis/models/ApproverGroupRequest)
- [Artifact](https://www.useboomerang.io/docs/flow/main/apis/models/Artifact)
- [AuditEvent](https://www.useboomerang.io/docs/flow/main/apis/models/AuditEvent)
- [AuditStats](https://www.useboomerang.io/docs/flow/main/apis/models/AuditStats)
- [CanvasEdge](https://www.useboomerang.io/docs/flow/main/apis/models/CanvasEdge)
- [CanvasEdgeData](https://www.useboomerang.io/docs/flow/main/apis/models/CanvasEdgeData)
- [CanvasNode](https://www.useboomerang.io/docs/flow/main/apis/models/CanvasNode)
- [CanvasNodeData](https://www.useboomerang.io/docs/flow/main/apis/models/CanvasNodeData)
- [CanvasNodePosition](https://www.useboomerang.io/docs/flow/main/apis/models/CanvasNodePosition)
- [ChangeLog](https://www.useboomerang.io/docs/flow/main/apis/models/ChangeLog)
- [ChangeLogVersion](https://www.useboomerang.io/docs/flow/main/apis/models/ChangeLogVersion)
- [CronValidationResponse](https://www.useboomerang.io/docs/flow/main/apis/models/CronValidationResponse)
- [CurrentQuotas](https://www.useboomerang.io/docs/flow/main/apis/models/CurrentQuotas)
- [Day](https://www.useboomerang.io/docs/flow/main/apis/models/Day)
- [EventOutboxEntity](https://www.useboomerang.io/docs/flow/main/apis/models/EventOutboxEntity)
- [Failure](https://www.useboomerang.io/docs/flow/main/apis/models/Failure)
- [Features](https://www.useboomerang.io/docs/flow/main/apis/models/Features)
- [GHLinkRequest](https://www.useboomerang.io/docs/flow/main/apis/models/GHLinkRequest)
- [GHShareRequest](https://www.useboomerang.io/docs/flow/main/apis/models/GHShareRequest)
- [HeaderFeatures](https://www.useboomerang.io/docs/flow/main/apis/models/HeaderFeatures)
- [HeaderNavigation](https://www.useboomerang.io/docs/flow/main/apis/models/HeaderNavigation)
- [HeaderNavigationResponse](https://www.useboomerang.io/docs/flow/main/apis/models/HeaderNavigationResponse)
- [HeaderOption](https://www.useboomerang.io/docs/flow/main/apis/models/HeaderOption)
- [HeaderPlatform](https://www.useboomerang.io/docs/flow/main/apis/models/HeaderPlatform)
- [HeaderPlatformMessage](https://www.useboomerang.io/docs/flow/main/apis/models/HeaderPlatformMessage)
- [Integration](https://www.useboomerang.io/docs/flow/main/apis/models/Integration)
- [JsonNode](https://www.useboomerang.io/docs/flow/main/apis/models/JsonNode)
- [KeyValuePair](https://www.useboomerang.io/docs/flow/main/apis/models/KeyValuePair)
- [ModelUsage](https://www.useboomerang.io/docs/flow/main/apis/models/ModelUsage)
- [Navigation](https://www.useboomerang.io/docs/flow/main/apis/models/Navigation)
- [OneTimeCode](https://www.useboomerang.io/docs/flow/main/apis/models/OneTimeCode)
- [OutboxReplayResponse](https://www.useboomerang.io/docs/flow/main/apis/models/OutboxReplayResponse)
- [PageAction](https://www.useboomerang.io/docs/flow/main/apis/models/PageAction)
- [PageArtifact](https://www.useboomerang.io/docs/flow/main/apis/models/PageArtifact)
- [PageAuditEvent](https://www.useboomerang.io/docs/flow/main/apis/models/PageAuditEvent)
- [PageEventOutboxEntity](https://www.useboomerang.io/docs/flow/main/apis/models/PageEventOutboxEntity)
- [PageTaskRun](https://www.useboomerang.io/docs/flow/main/apis/models/PageTaskRun)
- [PageToken](https://www.useboomerang.io/docs/flow/main/apis/models/PageToken)
- [PageUser](https://www.useboomerang.io/docs/flow/main/apis/models/PageUser)
- [PageWorkflowRun](https://www.useboomerang.io/docs/flow/main/apis/models/PageWorkflowRun)
- [PageWorkflowSchedule](https://www.useboomerang.io/docs/flow/main/apis/models/PageWorkflowSchedule)
- [PageWorkspace](https://www.useboomerang.io/docs/flow/main/apis/models/PageWorkspace)
- [PageableObject](https://www.useboomerang.io/docs/flow/main/apis/models/PageableObject)
- [ParamSpec](https://www.useboomerang.io/docs/flow/main/apis/models/ParamSpec)
- [Quotas](https://www.useboomerang.io/docs/flow/main/apis/models/Quotas)
- [ResolvedPermissions](https://www.useboomerang.io/docs/flow/main/apis/models/ResolvedPermissions)
- [ResultSpec](https://www.useboomerang.io/docs/flow/main/apis/models/ResultSpec)
- [RetryBackoff](https://www.useboomerang.io/docs/flow/main/apis/models/RetryBackoff)
- [RetryFrom](https://www.useboomerang.io/docs/flow/main/apis/models/RetryFrom)
- [Role](https://www.useboomerang.io/docs/flow/main/apis/models/Role)
- [Routing](https://www.useboomerang.io/docs/flow/main/apis/models/Routing)
- [Row](https://www.useboomerang.io/docs/flow/main/apis/models/Row)
- [RunAttempt](https://www.useboomerang.io/docs/flow/main/apis/models/RunAttempt)
- [RunParam](https://www.useboomerang.io/docs/flow/main/apis/models/RunParam)
- [RunResult](https://www.useboomerang.io/docs/flow/main/apis/models/RunResult)
- [RunRetry](https://www.useboomerang.io/docs/flow/main/apis/models/RunRetry)
- [RunState](https://www.useboomerang.io/docs/flow/main/apis/models/RunState)
- [Setting](https://www.useboomerang.io/docs/flow/main/apis/models/Setting)
- [SettingConfig](https://www.useboomerang.io/docs/flow/main/apis/models/SettingConfig)
- [SlowTaskRun](https://www.useboomerang.io/docs/flow/main/apis/models/SlowTaskRun)
- [SortObject](https://www.useboomerang.io/docs/flow/main/apis/models/SortObject)
- [Step](https://www.useboomerang.io/docs/flow/main/apis/models/Step)
- [Task](https://www.useboomerang.io/docs/flow/main/apis/models/Task)
- [TaskEnvVar](https://www.useboomerang.io/docs/flow/main/apis/models/TaskEnvVar)
- [TaskResponsePage](https://www.useboomerang.io/docs/flow/main/apis/models/TaskResponsePage)
- [TaskRow](https://www.useboomerang.io/docs/flow/main/apis/models/TaskRow)
- [TaskRun](https://www.useboomerang.io/docs/flow/main/apis/models/TaskRun)
- [TaskRunRow](https://www.useboomerang.io/docs/flow/main/apis/models/TaskRunRow)
- [TaskRunSpec](https://www.useboomerang.io/docs/flow/main/apis/models/TaskRunSpec)
- [TaskSpec](https://www.useboomerang.io/docs/flow/main/apis/models/TaskSpec)
- [TektonMetadata](https://www.useboomerang.io/docs/flow/main/apis/models/TektonMetadata)
- [TektonSpec](https://www.useboomerang.io/docs/flow/main/apis/models/TektonSpec)
- [TektonTask](https://www.useboomerang.io/docs/flow/main/apis/models/TektonTask)
- [Token](https://www.useboomerang.io/docs/flow/main/apis/models/Token)
- [TokenCreateRequest](https://www.useboomerang.io/docs/flow/main/apis/models/TokenCreateRequest)
- [TokenCreateResponse](https://www.useboomerang.io/docs/flow/main/apis/models/TokenCreateResponse)
- [TokenPermissionCatalog](https://www.useboomerang.io/docs/flow/main/apis/models/TokenPermissionCatalog)
- [Totals](https://www.useboomerang.io/docs/flow/main/apis/models/Totals)
- [Trigger](https://www.useboomerang.io/docs/flow/main/apis/models/Trigger)
- [TriggerCondition](https://www.useboomerang.io/docs/flow/main/apis/models/TriggerCondition)
- [User](https://www.useboomerang.io/docs/flow/main/apis/models/User)
- [UserProfile](https://www.useboomerang.io/docs/flow/main/apis/models/UserProfile)
- [UserRequest](https://www.useboomerang.io/docs/flow/main/apis/models/UserRequest)
- [UserSettings](https://www.useboomerang.io/docs/flow/main/apis/models/UserSettings)
- [Workflow](https://www.useboomerang.io/docs/flow/main/apis/models/Workflow)
- [WorkflowCanvas](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowCanvas)
- [WorkflowConcurrency](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowConcurrency)
- [WorkflowPatch](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowPatch)
- [WorkflowResponsePage](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowResponsePage)
- [WorkflowRow](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowRow)
- [WorkflowRun](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowRun)
- [WorkflowRunCount](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowRunCount)
- [WorkflowRunInsightSummary](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowRunInsightSummary)
- [WorkflowRunInsightTaskRunPage](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowRunInsightTaskRunPage)
- [WorkflowRunInsightTasks](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowRunInsightTasks)
- [WorkflowRunInsightUsage](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowRunInsightUsage)
- [WorkflowRunInsightWorkflowDetail](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowRunInsightWorkflowDetail)
- [WorkflowRunPurge](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowRunPurge)
- [WorkflowRunRequest](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowRunRequest)
- [WorkflowRunRetryRequest](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowRunRetryRequest)
- [WorkflowSchedule](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowSchedule)
- [WorkflowScheduleCalendar](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowScheduleCalendar)
- [WorkflowSubmitRequest](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowSubmitRequest)
- [WorkflowSummary](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowSummary)
- [WorkflowTask](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowTask)
- [WorkflowTaskDependency](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowTaskDependency)
- [WorkflowTaskForeach](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowTaskForeach)
- [WorkflowTaskRetry](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowTaskRetry)
- [WorkflowTemplateRef](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowTemplateRef)
- [WorkflowTrigger](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowTrigger)
- [WorkflowWorkspace](https://www.useboomerang.io/docs/flow/main/apis/models/WorkflowWorkspace)
- [Workspace](https://www.useboomerang.io/docs/flow/main/apis/models/Workspace)
- [WorkspaceMember](https://www.useboomerang.io/docs/flow/main/apis/models/WorkspaceMember)
- [WorkspaceNameCheckRequest](https://www.useboomerang.io/docs/flow/main/apis/models/WorkspaceNameCheckRequest)
- [WorkspaceRequest](https://www.useboomerang.io/docs/flow/main/apis/models/WorkspaceRequest)
- [WorkspaceSummary](https://www.useboomerang.io/docs/flow/main/apis/models/WorkspaceSummary)
- [WorkspaceSummaryInsights](https://www.useboomerang.io/docs/flow/main/apis/models/WorkspaceSummaryInsights)