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.

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

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.

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 covers the token kinds and how to create them, and 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?.

Read an error

An error Flow raises is a RestErrorResponse:

{
  "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"
}

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

Get the full contract

These pages are generated from 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. A running service-core serves the same document at /api/docs/spec/api-v2, and Swagger UI at /api/docs/swagger-ui.

Routes

Actions

Artifacts

Audit

Insights

Integrations

Parameters

Profile

Schedules

System

Task Runs

Tasks

Token Management

Users

Webhooks and Events

Workflow Runs

Workflows

Workspace Management

Workspace Tasks

Models

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