Boomerang
Boomerang Flow · API ReferenceWorkspace Management

Workspace Management

Verified against Flow 5.0.0-beta.39

View as Markdown
On this page
Name Method Endpoint
Create new workspace POST /api/v2/workspace
Delete Approver Groups DELETE /api/v2/workspace/{workspace}/approvers
Delete Workspace Parameter DELETE /api/v2/workspace/{workspace}/parameters/{name}
Delete Workspace DELETE /api/v2/workspace/{workspace}
Retrieve Default Workspace Quota GET /api/v2/workspace/quotas/default
Retrieve Workspace Roles GET /api/v2/workspace/roles
Get workspace GET /api/v2/workspace/{workspace}
Search for Workspaces GET /api/v2/workspace/query
Leave Workspace DELETE /api/v2/workspace/{workspace}/leave
Remove Workspace Members DELETE /api/v2/workspace/{workspace}/members
Reset Workspace Quota DELETE /api/v2/workspace/{workspace}/quotas
Patch or update a workspace PATCH /api/v2/workspace/{workspace}
Validate workspace name and check uniqueness. POST /api/v2/workspace/validate-name

Create new workspace

POST /api/v2/workspace

Requires the workspace/write permission, from a session, user, global token.

Request parameters

Name Type Required Description Notes Example

Request body

Schema Required
WorkspaceRequest true

Authorization

One of BearerAuth, x-access-token

Request headers

  • Content-Type: application/json
  • Accept: */*

Response

Workspace

Example request

curl -X POST "$FLOW_URL/api/v2/workspace" \
  -H "Authorization: Bearer $FLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Example request body

The request sends this as body.json:

{
  "name": "my-workspace",
  "displayName": "My workspace"
}

Delete Approver Groups

DELETE /api/v2/workspace/{workspace}/approvers

Requires the workspace/delete permission, from a session, user, key, global token.

Request parameters

Name Type Required Description Notes Example
workspace String true Workspace as owner reference.

Request body

Schema Required
List of String true

Authorization

One of BearerAuth, x-access-token

Request headers

  • Content-Type: application/json
  • Accept: Not defined

Response

No response body

Example request

curl -X DELETE "$FLOW_URL/api/v2/workspace/$WORKSPACE/approvers" \
  -H "Authorization: Bearer $FLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Example request body

The request sends this as body.json:

[
  "<approver group id>"
]

Delete Workspace Parameter

DELETE /api/v2/workspace/{workspace}/parameters/{name}

Requires the workspace/delete permission, from a session, user, key, global token.

Request parameters

Name Type Required Description Notes Example
workspace String true Workspace as owner reference.
name String true

Request body

This endpoint does not require a request body.

Authorization

One of BearerAuth, x-access-token

Request headers

  • Content-Type: Not defined
  • Accept: Not defined

Response

No response body

Example request

curl -X DELETE "$FLOW_URL/api/v2/workspace/$WORKSPACE/parameters/$PARAMETER" \
  -H "Authorization: Bearer $FLOW_TOKEN"

Delete Workspace

DELETE /api/v2/workspace/{workspace}

Requires the workspace/delete permission, from a session, user, key, global token.

Request parameters

Name Type Required Description Notes Example
workspace String true ID of Workspace

Request body

This endpoint does not require a request body.

Authorization

One of BearerAuth, x-access-token

Request headers

  • Content-Type: Not defined
  • Accept: Not defined

Response

No response body

Example request

curl -X DELETE "$FLOW_URL/api/v2/workspace/$WORKSPACE" \
  -H "Authorization: Bearer $FLOW_TOKEN"

Retrieve Default Workspace Quota

GET /api/v2/workspace/quotas/default

Requires the workspace/read permission, from a session, user, key, global token.

Request parameters

This endpoint does not need any parameter.

Request body

This endpoint does not require a request body.

Authorization

One of BearerAuth, x-access-token

Request headers

  • Content-Type: Not defined
  • Accept: */*

Response

Quotas

Example request

curl -X GET "$FLOW_URL/api/v2/workspace/quotas/default" \
  -H "Authorization: Bearer $FLOW_TOKEN"

Retrieve Workspace Roles

GET /api/v2/workspace/roles

Requires the workspace/read permission, from a session, user, key, global token.

Request parameters

This endpoint does not need any parameter.

Request body

This endpoint does not require a request body.

Authorization

One of BearerAuth, x-access-token

Request headers

  • Content-Type: Not defined
  • Accept: */*

Response

List of Role

Example request

curl -X GET "$FLOW_URL/api/v2/workspace/roles" \
  -H "Authorization: Bearer $FLOW_TOKEN"

Get workspace

GET /api/v2/workspace/{workspace}

Requires the workspace/read permission, from a session, user, key, global token.

Request parameters

Name Type Required Description Notes Example
workspace String true Workspace as owner reference. my-amazing-workspace

Request body

This endpoint does not require a request body.

Authorization

One of BearerAuth, x-access-token

Request headers

  • Content-Type: Not defined
  • Accept: */*

Response

Workspace

Example request

curl -X GET "$FLOW_URL/api/v2/workspace/$WORKSPACE" \
  -H "Authorization: Bearer $FLOW_TOKEN"

Example response

200 OK:

{
  "approverGroups": [],
  "creationDate": "2026-11-05T21:23:47.310Z",
  "displayName": "Example workspace",
  "externalRef": null,
  "id": "6aecf3e3755e5fc7e99bea30",
  "labels": {},
  "members": [
    {
      "email": "grace.hopper@flow.local",
      "id": "6aecf30e755e5fc7e99bea28",
      "name": "Grace Hopper",
      "role": "owner"
    }
  ],
  "name": "example-workspace",
  "parameters": [
    {
      "description": "The deploy service's API token.",
      "hiddenValue": true,
      "label": "Deploy token",
      "name": "deploy-token",
      "readOnly": false,
      "type": "password",
      "value": "*****"
    }
  ],
  "quotas": {
    "artifactRetentionDays": 30,
    "currentArtifactStorage": 145,
    "currentConcurrentRuns": 3,
    "currentRunAverageDuration": 54060,
    "currentRunTotalDuration": 1135265,
    "currentRuns": 21,
    "currentWorkflowCount": 18,
    "maxArtifactStorage": 5,
    "maxConcurrentRuns": 4,
    "maxWorkflowCount": 20,
    "maxWorkflowRunDuration": 30,
    "maxWorkflowRunMonthly": 100,
    "maxWorkspaceStorage": 2,
    "monthlyResetDate": "2026-12-01T00:00:00.000Z"
  },
  "status": "active",
  "type": null,
  "workflows": []
}

Search for Workspaces

GET /api/v2/workspace/query

Requires the workspace/read permission, from a session, user, key, global token.

Request parameters

Name Type Required Description Notes Example
limit Integer true Result Size 10
page Integer true Page Number Defaults to 0. 0
search String false Free-text search on Workspace name and displayName (prefix match, case-insensitive).
labels List of String false List of url encoded labels. For example Organization=Boomerang,customKey=test would be encoded as Organization%3DBoomerang,customKey%3Dtest)
statuses List of String false List of statuses to filter for. Defaults to all. active,inactive
workspaces List of String false List of Workspace names to filter for. my-amazing-workspace,boomerangs-return
externalRef String false The one workspace carrying this external reference.
order String false Ascending or Descending (default) order Defaults to DESC. Enum: [ASC, DESC] 0
sort String false The element to sort on Defaults to name. 0

Request body

This endpoint does not require a request body.

Authorization

One of BearerAuth, x-access-token

Request headers

  • Content-Type: Not defined
  • Accept: */*

Response

PageWorkspace

Example request

curl -X GET "$FLOW_URL/api/v2/workspace/query?limit=10&page=0" \
  -H "Authorization: Bearer $FLOW_TOKEN"

Leave Workspace

DELETE /api/v2/workspace/{workspace}/leave

Requires the workspace/read permission, from a user, session token.

Request parameters

Name Type Required Description Notes Example
workspace String true Workspace as owner reference.

Request body

This endpoint does not require a request body.

Authorization

One of BearerAuth, x-access-token

Request headers

  • Content-Type: Not defined
  • Accept: Not defined

Response

No response body

Example request

curl -X DELETE "$FLOW_URL/api/v2/workspace/$WORKSPACE/leave" \
  -H "Authorization: Bearer $FLOW_TOKEN"

Remove Workspace Members

DELETE /api/v2/workspace/{workspace}/members

Requires the workspace/delete permission, from a session, user, key, global token.

Request parameters

Name Type Required Description Notes Example
workspace String true Workspace as owner reference. my-amazing-workspace

Request body

Schema Required
List of WorkspaceMember true

Authorization

One of BearerAuth, x-access-token

Request headers

  • Content-Type: application/json
  • Accept: Not defined

Response

No response body

Example request

curl -X DELETE "$FLOW_URL/api/v2/workspace/$WORKSPACE/members" \
  -H "Authorization: Bearer $FLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Example request body

The request sends this as body.json:

[
  {
    "id": "<user id>"
  }
]

Reset Workspace Quota

DELETE /api/v2/workspace/{workspace}/quotas

Requires the workspace/delete permission, from a session, user, key, global token.

Request parameters

Name Type Required Description Notes Example
workspace String true Workspace as owner reference.

Request body

This endpoint does not require a request body.

Authorization

One of BearerAuth, x-access-token

Request headers

  • Content-Type: Not defined
  • Accept: Not defined

Response

No response body

Example request

curl -X DELETE "$FLOW_URL/api/v2/workspace/$WORKSPACE/quotas" \
  -H "Authorization: Bearer $FLOW_TOKEN"

Patch or update a workspace

PATCH /api/v2/workspace/{workspace}

Requires the workspace/write permission, from a session, user, key, global token.

Request parameters

Name Type Required Description Notes Example
workspace String true ID of Workspace

Request body

Schema Required
WorkspaceRequest true

Authorization

One of BearerAuth, x-access-token

Request headers

  • Content-Type: application/json
  • Accept: */*

Response

Workspace

Example request

curl -X PATCH "$FLOW_URL/api/v2/workspace/$WORKSPACE" \
  -H "Authorization: Bearer $FLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Example request body

The request sends this as body.json:

{
  "displayName": "Platform workspace"
}

Validate workspace name and check uniqueness.

POST /api/v2/workspace/validate-name

Requires the workspace/read permission, from a session, user, global token.

Request parameters

Name Type Required Description Notes Example

Request body

Schema Required
WorkspaceNameCheckRequest true

Authorization

One of BearerAuth, x-access-token

Request headers

  • Content-Type: application/json
  • Accept: */*

Response

Object

Example request

curl -X POST "$FLOW_URL/api/v2/workspace/validate-name" \
  -H "Authorization: Bearer $FLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Example request body

The request sends this as body.json:

{
  "name": "my-workspace"
}
Edit this page on GitHub →Found a problem? Open an issue
Docs and examples licensed under Apache 2.0