> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coralogix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

# 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`](../dashboard-service/overview#endpoints) on the Dashboard service. For user-facing folder concepts, see the [Custom Dashboards user guide](https://coralogix.com/docs/user-guides/custom-dashboards/getting-started/).

## Authentication and permissions

To use the Dashboard folders service API you need to [create a personal or team API key](https://coralogix.com/docs/user-guides/account-management/api-keys/api-keys/). 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.

| Presets    | Permission               | Description                                           |
| ---------- | ------------------------ | ----------------------------------------------------- |
| Dashboards | `team-dashboards:Read`   | Grants access to read team-dashboards                 |
|            | `team-dashboards:Update` | Required to create, update, or delete team-dashboards |

## Common error response codes

| Status Code                 | Description       |
| --------------------------- | ----------------- |
| `400 Bad Request`           | Response code 400 |
| `401 Unauthorized`          | Response code 401 |
| `500 Internal Server Error` | Response code 500 |

## Endpoints

| Method   | Path                                 | Summary                    |
| -------- | ------------------------------------ | -------------------------- |
| `GET`    | `/dashboards/folders/v1`             | List dashboard folders     |
| `POST`   | `/dashboards/folders/v1`             | Create a dashboard folder  |
| `PUT`    | `/dashboards/folders/v1`             | Replace a dashboard folder |
| `GET`    | `/dashboards/folders/v1/{folder_id}` | Get a dashboard folder     |
| `DELETE` | `/dashboards/folders/v1/{folder_id}` | Delete a dashboard folder  |

## Folder payload

The `DashboardFolder` message is small and flat:

| Field       | Type     | Notes                                                                   |
| ----------- | -------- | ----------------------------------------------------------------------- |
| `id`        | `string` | Unique identifier.                                                      |
| `name`      | `string` | Display name.                                                           |
| `parent_id` | `string` | Optional parent folder id. Omit (or leave null) for a top-level folder. |

## 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.