Skip to main content

Workbench Folders API

The Workbench Folders API lets you create and manage the same folders you see on the Action Flow dashboard - the structure customers use to organize their Action Flows. Use this API when you want to provision folders as part of an environment setup script, mirror an external taxonomy, or keep folders in sync with another system of record.

The API supports:

Authentication​

The Workbench Folders API requires a fine-grained API key. Each operation maps to a specific scope:

OperationRequired scope
List, getworkbench_folders:read
Createworkbench_folders:create
Renameworkbench_folders:update
Deleteworkbench_folders:delete

Legacy API keys (the events, workbench, or auth roles) are not accepted on these endpoints. If you currently use a legacy key, issue a fine-grained API key with the scopes above from the workbench. See API credentials for how to create one.

You can interact with the Workbench Folders API using Insomnia (follow the Insomnia instructions) or curl. When using curl, you'll need to set up your Authentication first.

Detailed specs and examples can be found in the Atomic API spec for the Workbench Folders endpoint.

Folder names​

Folder names follow the same rules as the workbench UI:

  • Between 1 and 255 characters.
  • Letters (uppercase or lowercase), digits, hyphens, underscores, and spaces only.
  • Folder names must be unique within their parent. A name can be reused at a different level of the tree, but two folders with the same parent cannot share a name.

Names that don't match these rules are rejected with 400. Duplicate names within the same parent are rejected with 409.

API endpoints​

List workbench folders​

Returns all Action Flow folders in the environment, sorted by name. Both root folders and sub-folders are included; the parent of a sub-folder is identified by its parentId.

curl -X GET "$ATOMIC_API/v1/$ENVIRONMENT_ID/workbench-folder" \
    --header "Authorization: Bearer $TOKEN" | jq
Sample response
{
  "data": [
    {
      "id": "fld_2nBrJUjz",
      "name": "Onboarding",
      "environmentId": "4dkLrv",
      "organisationId": "atomic-demo",
      "parentId": null,
      "created": "2026-04-29T22:00:00.000Z",
      "updated": "2026-04-29T22:00:00.000Z"
    },
    {
      "id": "fld_8aP1qLZ4",
      "name": "Welcome series",
      "environmentId": "4dkLrv",
      "organisationId": "atomic-demo",
      "parentId": "fld_2nBrJUjz",
      "created": "2026-04-29T22:05:00.000Z",
      "updated": "2026-04-29T22:05:00.000Z"
    }
  ]
}

Errors

  • 401: No permission to environment, or no auth token provided
  • 403: API key does not have the workbench_folders:read scope

Create a workbench folder​

Creates a new folder. To create a sub-folder, supply the parentId of an existing folder in the same environment. Omit parentId (or pass null or an empty string) to create a root-level folder.

# Create a root folder
PAYLOAD='{"name": "campaigns"}'

curl -X POST "$ATOMIC_API/v1/$ENVIRONMENT_ID/workbench-folder" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $TOKEN" \
    --data "$PAYLOAD" | jq
# Create a sub-folder
PAYLOAD='{"name": "q3-launch", "parentId": "fld_2nBrJUjz"}'

curl -X POST "$ATOMIC_API/v1/$ENVIRONMENT_ID/workbench-folder" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $TOKEN" \
    --data "$PAYLOAD" | jq

On success, the new folder is returned with a 201.

Sample response
{
  "data": {
    "id": "fld_8aP1qLZ4",
    "name": "q3-launch",
    "environmentId": "4dkLrv",
    "organisationId": "atomic-demo",
    "parentId": "fld_2nBrJUjz",
    "created": "2026-05-01T03:14:00.000Z",
    "updated": "2026-05-01T03:14:00.000Z"
  }
}

Errors

  • 400: Name fails validation, or parentId does not reference a folder in this environment
  • 401: No permission to environment, or no auth token provided
  • 403: API key does not have the workbench_folders:create scope
  • 409: A folder with this name already exists in the same parent

Get a workbench folder​

Returns a single folder by id.

curl -X GET "$ATOMIC_API/v1/$ENVIRONMENT_ID/workbench-folder/$FOLDER_ID" \
    --header "Authorization: Bearer $TOKEN" | jq

The response shape matches an entry in the list response.

Errors

  • 401: No permission to environment, or no auth token provided
  • 403: API key does not have the workbench_folders:read scope
  • 404: Folder not found in this environment

Rename a workbench folder​

Updates the name of an existing folder. Only name can be changed via this endpoint - to move a folder to a different parent, delete it and recreate it under the new parent (any Action Flows you had filed in the original folder will need to be re-filed).

PAYLOAD='{"name": "renamed-folder"}'

curl -X PUT "$ATOMIC_API/v1/$ENVIRONMENT_ID/workbench-folder/$FOLDER_ID" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $TOKEN" \
    --data "$PAYLOAD" | jq

On success, the updated folder is returned with a 200.

Errors

  • 400: Name fails validation
  • 401: No permission to environment, or no auth token provided
  • 403: API key does not have the workbench_folders:update scope
  • 404: Folder not found in this environment
  • 409: A folder with this name already exists in the same parent

Delete a workbench folder​

Deletes a folder. Returns 204 No Content on success.

curl -X DELETE "$ATOMIC_API/v1/$ENVIRONMENT_ID/workbench-folder/$FOLDER_ID" \
    --header "Authorization: Bearer $TOKEN"

A few things happen automatically when you delete a folder:

  • Action Flows are unfiled, not deleted. If any Action Flows were filed in the folder, the folder reference is cleared from those flows so they appear in Uncategorized in the workbench. The Action Flows themselves are untouched.
  • Sub-folders block the delete. If the folder contains sub-folders, the request fails with a 409 and a message asking you to delete the sub-folders first. This prevents accidentally orphaning a whole sub-tree. Delete from the leaves up.

Errors

  • 401: No permission to environment, or no auth token provided
  • 403: API key does not have the workbench_folders:delete scope
  • 404: Folder not found in this environment
  • 409: The folder contains sub-folders and cannot be deleted

More​

Last updated on