Users can create folders in their workspaces to help organize their boards, dashboards, and workdocs.

Queries

Get folders

Required scope:workspaces:read
Returns an array containing metadata about one or a collection of folders
Can only be queried directly at the root; can't be nested within another query

query {
  folders(workspace_ids: [1234567890]) {
    id
    name
    children {
      id
      name
    }
  }
}

Arguments

Argument	Type	Description
ids	`[ID!]`	The specific folders to return.
limit	`Int`	The number of folders to get. The default is 25 and the maximum is 100.
page	`Int`	The page number to return. Starts at 1.
workspace_ids	`[ID]`	The unique identifiers of the specific workspaces to return. You can pass `[null]` to return folders in the Main Workspace.

Fields

Field	Type	Description
children	`[Board]!`	The folder's contents, excluding dashboards and subfolders.
color	`FolderColor`	The folder's color. See a full list of colors here.
created_at	`Date!`	The folder's creation date.
id	`ID!`	The folder's unique identifier.
name	`String!`	The folder's name.
owner_id	`ID`	The unique identifier of the folder's owner.
parent	`Folder`	The folder's parent folder.
sub_folders	`[Folder]!`	The folders inside of the parent folder.
workspace	`Workspace!`	The workspace that contains the folder.
app_feature_slug	`String`	The app feature slug associated with this folder (Folders 2.0). Only available in versions `2026-04` and later.

Mutations

Required scope:workspaces:write

Create folder

Creates a new folder in a workspace. Returns Folder.

mutation {
  create_folder(
    name: "New folder", 
    workspace_id: 1234567890
	) {
    id
  }
}

Arguments

Argument	Type	Description
color	`FolderColor`	The folder's color. See a full list of colors here.
name	`String!`	The folder's name.
parent_folder_id	`ID`	The ID of the folder you want to nest the new one under.
workspace_id	`ID`	The unique identifier of the workspace to create the new folder in.

Update folder

Updates a folder's color, name, or parent folder. Returns Folder.

mutation {
  update_folder(
    folder_id: 1234567890,
    name: "Updated folder name",
    account_product_id: 54321,
    position: {
      object_id: "15",
      object_type: Board,
      is_after: false
    }
  ) {
    id
    name
  }
}

Arguments

Argument	Type	Description	Enum Values
account_product_id	`ID`	The unique identifier of the product to move the folder to. You must also provide the relevant `workspace_id` within the updated product.
color	`FolderColor`	The folder's color. See a full list of colors here.
custom_icon	`FolderCustomIcon`	The folder's custom icon. See a full list of icons here .
folder_id	`ID!`	The folder's unique identifier.
font_weight	`FolderFontWeight`	The folder's font weight.	`FONT_WEIGHT_BOLD` `FONT_WEIGHT_LIGHT` `FONT_WEIGHT_NORMAL` `FONT_WEIGHT_VERY_LIGHT` `NULL`
name	`String`	The folder's name.
parent_folder_id	`ID`	The ID of the folder you want to nest the updated one under.
position	`DynamicPosition`	The folder's updated position in the left-side menu.
workspace_id	`ID`	The unique identifier of the workspace to move the folder to.

Delete folder

Deletes a folder and all its contents. Returns Folder.

mutation {
  delete_folder(
    folder_id: 1234567890
	) {
    id
  }
}

Arguments

Argument	Type	Description
folder_id	`ID!`	The folder's unique identifier.