Reference
Folders
The folders endpoints of the HTTP API.
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 |
403 |
The caller is not allowed to perform the request; a role that is too low is code forbidden_role. |
Error |
500 |
The server failed to handle the request. | 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 |
400 |
The request is malformed or fails validation. | Error |
401 |
Authentication is missing or invalid. | Error |
403 |
The caller is not allowed to perform the request; a role that is too low is code forbidden_role. |
Error |
409 |
A folder with that title already exists (folder_exists), ignoring case. |
Error |
413 |
The request body exceeds the size limit. | Error |
500 |
The server failed to handle the request. | 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 |
400 |
The request is malformed or fails validation. | Error |
401 |
Authentication is missing or invalid. | Error |
403 |
The caller is not allowed to perform the request; a role that is too low is code forbidden_role. |
Error |
404 |
The resource does not exist. | Error |
500 |
The server failed to handle the request. | 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 |
400 |
The request is malformed or fails validation. | Error |
401 |
Authentication is missing or invalid. | Error |
403 |
The caller is not allowed to perform the request; a role that is too low is code forbidden_role. |
Error |
404 |
The resource does not exist. | Error |
409 |
Another folder has that title (folder_exists), or the folder is General (general_folder). |
Error |
413 |
The request body exceeds the size limit. | Error |
500 |
The server failed to handle the request. | 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 |
401 |
Authentication is missing or invalid. | Error |
403 |
The caller is not allowed to perform the request; a role that is too low is code forbidden_role. |
Error |
404 |
The resource does not exist. | Error |
409 |
The folder still holds dashboards (folder_not_empty), or it is General (general_folder). |
Error |
500 |
The server failed to handle the request. | 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 |
400 |
The request is malformed or fails validation. | Error |
401 |
Authentication is missing or invalid. | Error |
403 |
The caller is not allowed to perform the request; a role that is too low is code forbidden_role. |
Error |
404 |
The resource does not exist. | Error |
500 |
The server failed to handle the request. | 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 |
400 |
The request is malformed or fails validation. | Error |
401 |
Authentication is missing or invalid. | Error |
403 |
The caller is not allowed to perform the request; a role that is too low is code forbidden_role. |
Error |
404 |
The resource does not exist. | Error |
409 |
The folder is General (general_folder). |
Error |
413 |
The request body exceeds the size limit. | 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 |
Generated from api/openapi.yaml at bac0fe39. Report a problem.