---
title: "Folders"
description: "The folders endpoints of the HTTP API."
---

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

# Folders

## GET /folders

List the folders the caller can see.

A folder with listed people or groups is visible only to them, to its creator and to Admins; every other folder is visible to everyone. Folders are sorted by title without regard to case, with General last. Each folder carries the caller's own `permissions` on it.

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | The visible folders. | `object` |
| `401` | Authentication is missing or invalid. | [`Error`](/docs/reference/api/schemas/#error) |
| `403` | The caller is not allowed to perform the request; a role that is too low is code `forbidden_role`. | [`Error`](/docs/reference/api/schemas/#error) |
| `500` | The server failed to handle the request. | [`Error`](/docs/reference/api/schemas/#error) |

## POST /folders

Create a folder.

Needs the Editor role. The title is trimmed, 1 to 100 characters with no control characters, and unique without regard to case. The caller becomes the folder's creator and manages it, whatever its permissions list.

### Request body

`application/json`, required.

| Field | Type | Description |
| --- | --- | --- |
| `title` (required) | `string` | Trimmed before it is stored; 1 to 100 characters with no control characters. |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `201` | The folder was created. | [`Folder`](/docs/reference/api/schemas/#folder) |
| `400` | The request is malformed or fails validation. | [`Error`](/docs/reference/api/schemas/#error) |
| `401` | Authentication is missing or invalid. | [`Error`](/docs/reference/api/schemas/#error) |
| `403` | The caller is not allowed to perform the request; a role that is too low is code `forbidden_role`. | [`Error`](/docs/reference/api/schemas/#error) |
| `409` | A folder with that title already exists (`folder_exists`), ignoring case. | [`Error`](/docs/reference/api/schemas/#error) |
| `413` | The request body exceeds the size limit. | [`Error`](/docs/reference/api/schemas/#error) |
| `500` | The server failed to handle the request. | [`Error`](/docs/reference/api/schemas/#error) |

## GET /folders/{id}

Get a folder.

A folder the caller cannot see answers 404, as if it did not exist.

### Parameters

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | path | `string` (uuid) |   |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | The folder. | [`Folder`](/docs/reference/api/schemas/#folder) |
| `400` | The request is malformed or fails validation. | [`Error`](/docs/reference/api/schemas/#error) |
| `401` | Authentication is missing or invalid. | [`Error`](/docs/reference/api/schemas/#error) |
| `403` | The caller is not allowed to perform the request; a role that is too low is code `forbidden_role`. | [`Error`](/docs/reference/api/schemas/#error) |
| `404` | The resource does not exist. | [`Error`](/docs/reference/api/schemas/#error) |
| `500` | The server failed to handle the request. | [`Error`](/docs/reference/api/schemas/#error) |

## PATCH /folders/{id}

Rename a folder.

Needs the Manage permission on the folder. The General folder cannot be renamed.

### Parameters

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | path | `string` (uuid) |   |

### Request body

`application/json`, required.

| Field | Type | Description |
| --- | --- | --- |
| `title` (required) | `string` | Trimmed before it is stored; 1 to 100 characters with no control characters. |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | The renamed folder. | [`Folder`](/docs/reference/api/schemas/#folder) |
| `400` | The request is malformed or fails validation. | [`Error`](/docs/reference/api/schemas/#error) |
| `401` | Authentication is missing or invalid. | [`Error`](/docs/reference/api/schemas/#error) |
| `403` | The caller is not allowed to perform the request; a role that is too low is code `forbidden_role`. | [`Error`](/docs/reference/api/schemas/#error) |
| `404` | The resource does not exist. | [`Error`](/docs/reference/api/schemas/#error) |
| `409` | Another folder has that title (`folder_exists`), or the folder is General (`general_folder`). | [`Error`](/docs/reference/api/schemas/#error) |
| `413` | The request body exceeds the size limit. | [`Error`](/docs/reference/api/schemas/#error) |
| `500` | The server failed to handle the request. | [`Error`](/docs/reference/api/schemas/#error) |

## DELETE /folders/{id}

Delete an empty folder.

Needs the Manage permission on the folder. The General folder cannot be deleted, and a folder that holds dashboards must be emptied first.

### Parameters

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | path | `string` (uuid) |   |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `204` | The folder and its permissions are deleted. |   |
| `400` | The request is malformed or fails validation. | [`Error`](/docs/reference/api/schemas/#error) |
| `401` | Authentication is missing or invalid. | [`Error`](/docs/reference/api/schemas/#error) |
| `403` | The caller is not allowed to perform the request; a role that is too low is code `forbidden_role`. | [`Error`](/docs/reference/api/schemas/#error) |
| `404` | The resource does not exist. | [`Error`](/docs/reference/api/schemas/#error) |
| `409` | The folder still holds dashboards (`folder_not_empty`), or it is General (`general_folder`). | [`Error`](/docs/reference/api/schemas/#error) |
| `500` | The server failed to handle the request. | [`Error`](/docs/reference/api/schemas/#error) |

## GET /folders/{id}/permissions

List who a folder is restricted to.

An empty list means the folder is open to everyone by instance role. Users come first by name, then groups by name.

### Parameters

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | path | `string` (uuid) |   |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | The folder's permission entries. | [`FolderPermissions`](/docs/reference/api/schemas/#folderpermissions) |
| `400` | The request is malformed or fails validation. | [`Error`](/docs/reference/api/schemas/#error) |
| `401` | Authentication is missing or invalid. | [`Error`](/docs/reference/api/schemas/#error) |
| `403` | The caller is not allowed to perform the request; a role that is too low is code `forbidden_role`. | [`Error`](/docs/reference/api/schemas/#error) |
| `404` | The resource does not exist. | [`Error`](/docs/reference/api/schemas/#error) |
| `500` | The server failed to handle the request. | [`Error`](/docs/reference/api/schemas/#error) |

## PUT /folders/{id}/permissions

Replace the people and groups a folder is restricted to.

Needs the Manage permission on the folder. The entries replace every existing row in one transaction. An empty `entries` list makes the folder open to everyone by instance role again. Each entry names exactly one of `user_id`, `email` (matched without regard to case against people who have signed in) and `group` (an OIDC group name, matched exactly), at most 50 entries and no repeated person or group. A person whose entries match the folder gets the higher of their instance role's level and the highest of those entries on the folder and its dashboards: an entry can lift a Viewer or Commenter (Edit lets them change and create dashboards there, Admin lets them manage the folder) and never lowers anyone. The General folder is never restricted.

### Parameters

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | path | `string` (uuid) |   |

### Request body

`application/json`, required.

| Field | Type | Description |
| --- | --- | --- |
| `entries` (required) | array of `object` | At most 50 items. |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | The folder's permission entries after the change. | [`FolderPermissions`](/docs/reference/api/schemas/#folderpermissions) |
| `400` | The request is malformed or fails validation. | [`Error`](/docs/reference/api/schemas/#error) |
| `401` | Authentication is missing or invalid. | [`Error`](/docs/reference/api/schemas/#error) |
| `403` | The caller is not allowed to perform the request; a role that is too low is code `forbidden_role`. | [`Error`](/docs/reference/api/schemas/#error) |
| `404` | The resource does not exist. | [`Error`](/docs/reference/api/schemas/#error) |
| `409` | The folder is General (`general_folder`). | [`Error`](/docs/reference/api/schemas/#error) |
| `413` | The request body exceeds the size limit. | [`Error`](/docs/reference/api/schemas/#error) |
| `422` | No signed-in person matches an entry (`unknown_user`), or an email belongs to more than one person. `email` is set when the entry was an email. | `object` |
| `500` | The server failed to handle the request. | [`Error`](/docs/reference/api/schemas/#error) |

Generated from [`api/openapi.yaml`](https://github.com/slashobserve/slashobserve/blob/bac0fe39/api/openapi.yaml) at `bac0fe39`. [Report a problem](https://github.com/slashobserve/slashobserve/issues/new).