Skip to main content

​
Dashboard folders service overview

The Dashboard folders service organizes dashboards into folders. Folders are flat by default but support a nested structure through parent_id references; a folder’s full path is exposed as a FolderPath (an ordered list of name segments). Use this service to list every folder the caller can see, fetch a single folder by id, and create / replace / delete folders. For attaching a dashboard to a folder, see POST /dashboards/dashboards/v1/{dashboard_id}/folder on the Dashboard service. For user-facing folder concepts, see the Custom Dashboards user guide.

​
Authentication and permissions

To use the Dashboard folders service API you need to create a personal or team API key. It’s recommended to use permission presets, as they are automatically updated with all relevant permissions. Alternatively, you can manually add the following individual permissions.

​
Common error response codes

​
Endpoints

​
Folder payload

The DashboardFolder message is small and flat:

​
Folder hierarchy (FolderPath)

Where the dashboard payload itself references a folder, you can supply either:
  • folder_id — an existing folder’s id, or
  • folder_path — a FolderPath with segments, an ordered list of folder names from the root down to the target folder. folder_id and folder_path are mutually exclusive.
A FolderPath is useful for declarative dashboard payloads where the destination folder may be created on the fly. The path is positional, not name-mangled — duplicates of a name at different depths are distinct paths.