Dashboard Folders (Projects)

A dashboard folder is called a project in this API and in the underlying Perses document model. The Logz.io app calls the same object a folder.

Addressing

Folders are addressed by id, the UUID returned by create, list and search. A folder's name is not an address: passing one as projectId returns 404.

Every account has a root folder named ROOT_FOLDER, created automatically the first time you list folders or create a dashboard. Its id comes from Get all dashboards folders, like any other folder's.

Writing a folder

Create and update both take a complete Perses project document. The update replaces the stored document rather than merging into it, so send the full desired state. To change only the name, use Rename dashboard folder.

A body that isn't a complete Perses project document is rejected with 400 before anything is written, and the message names the field that failed.

Deleting a folder

Deleting a folder also deletes every dashboard inside it, and succeeds whether or not the folder is empty. The deletion is soft: the folder and its dashboards stop appearing in this API, and creating a folder with the same metadata.name restores a deleted one.

Status codes

Every successful call returns 200, including create and delete.

Get all dashboards folders

Returns every folder in the account, sorted by name. Each entry pairs the folder with its dashboards.

Create dashboards folder

Creates a folder from a Perses project document.

Get dashboard folder by ID

Returns one folder.

Update dashboard folder

Replaces the folder's Perses project document with the body you send.

Delete dashboard folder

Deletes a folder and every dashboard inside it. Deleting a folder that still has dashboards in it also succeeds - there is no 'folder is not empty' guard.

Rename dashboard folder

Renames a folder, leaving the rest of its document alone.

Search dashboard folders

Searches dashboards and returns them grouped by folder.