> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/api-reference/platform-apis/dashboards/folders.md).

# Folders

## POST /folders

> Create a new folder.

```json
{"openapi":"3.0.2","info":{"title":"Dashboards Open API","version":"1.0.0"},"paths":{"/folders":{"post":{"tags":["folders"],"description":"Create a new folder.","operationId":"create_folder","parameters":[{"in":"query","name":"accountId","schema":{"type":"string"},"required":false}],"requestBody":{"description":"Create a new folder","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFolderRequestBody"}}}},"responses":{"200":{"description":"Returns the newly created folder's details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetFolderResponse"}}}},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"CreateFolderRequestBody":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"GetFolderResponse":{"type":"object","properties":{"resource":{"$ref":"#/components/schemas/Folder"}},"required":["resource"]},"Folder":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"child_count":{"type":"integer"},"sub_folders":{"type":"array","items":{"$ref":"#/components/schemas/Folder"}},"Children":{"type":"array","items":{"$ref":"#/components/schemas/FolderChildren"}},"name":{"type":"string"},"type":{"type":"string","enum":["ACCOUNT","SHARED","OOTB"]},"permission":{"type":"string","enum":["core_dashboards_view","core_dashboards_create","core_dashboards_delete","core_dashboards_edit"]}},"required":["id","name","sub_folders","type"]},"FolderChildren":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"integer"},"correlationId":{"type":"string"},"responseMessages":{"type":"string"}},"required":["code","error","responseMessages"]}}}}
```

## GET /folders/{folder\_id}

> Get a folder by ID.

```json
{"openapi":"3.0.2","info":{"title":"Dashboards Open API","version":"1.0.0"},"paths":{"/folders/{folder_id}":{"get":{"tags":["folders"],"description":"Get a folder by ID.","operationId":"get_folder","parameters":[{"in":"path","name":"folder_id","schema":{"type":"string"},"required":true},{"in":"query","name":"accountId","schema":{"type":"string"},"required":false}],"responses":{"200":{"description":"Returns the folder details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetFolderResponse"}}}},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"GetFolderResponse":{"type":"object","properties":{"resource":{"$ref":"#/components/schemas/Folder"}},"required":["resource"]},"Folder":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"child_count":{"type":"integer"},"sub_folders":{"type":"array","items":{"$ref":"#/components/schemas/Folder"}},"Children":{"type":"array","items":{"$ref":"#/components/schemas/FolderChildren"}},"name":{"type":"string"},"type":{"type":"string","enum":["ACCOUNT","SHARED","OOTB"]},"permission":{"type":"string","enum":["core_dashboards_view","core_dashboards_create","core_dashboards_delete","core_dashboards_edit"]}},"required":["id","name","sub_folders","type"]},"FolderChildren":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"integer"},"correlationId":{"type":"string"},"responseMessages":{"type":"string"}},"required":["code","error","responseMessages"]}}}}
```

## DELETE /folders/{folder\_id}

> Delete a folder along with any dashboards it contains.

```json
{"openapi":"3.0.2","info":{"title":"Dashboards Open API","version":"1.0.0"},"paths":{"/folders/{folder_id}":{"delete":{"tags":["folders"],"description":"Delete a folder along with any dashboards it contains.","operationId":"delete_folder","parameters":[{"in":"path","name":"folder_id","schema":{"type":"string"},"required":true},{"in":"query","name":"accountId","schema":{"type":"string"},"required":false}],"responses":{"200":{"description":"Returns the deleted folder.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetFolderResponse"}}}},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"GetFolderResponse":{"type":"object","properties":{"resource":{"$ref":"#/components/schemas/Folder"}},"required":["resource"]},"Folder":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"child_count":{"type":"integer"},"sub_folders":{"type":"array","items":{"$ref":"#/components/schemas/Folder"}},"Children":{"type":"array","items":{"$ref":"#/components/schemas/FolderChildren"}},"name":{"type":"string"},"type":{"type":"string","enum":["ACCOUNT","SHARED","OOTB"]},"permission":{"type":"string","enum":["core_dashboards_view","core_dashboards_create","core_dashboards_delete","core_dashboards_edit"]}},"required":["id","name","sub_folders","type"]},"FolderChildren":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"integer"},"correlationId":{"type":"string"},"responseMessages":{"type":"string"}},"required":["code","error","responseMessages"]}}}}
```

## PATCH /folders/{folder\_id}

> Update a folder's name.

```json
{"openapi":"3.0.2","info":{"title":"Dashboards Open API","version":"1.0.0"},"paths":{"/folders/{folder_id}":{"patch":{"tags":["folders"],"description":"Update a folder's name.","operationId":"update_folder","parameters":[{"in":"path","name":"folder_id","schema":{"type":"string"},"required":true},{"in":"query","name":"accountId","schema":{"type":"string"},"required":false}],"requestBody":{"description":"Change the name of a folder","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFolderRequestBody"}}}},"responses":{"200":{"description":"Returns the updated folder.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetFolderResponse"}}}},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"UpdateFolderRequestBody":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"GetFolderResponse":{"type":"object","properties":{"resource":{"$ref":"#/components/schemas/Folder"}},"required":["resource"]},"Folder":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"child_count":{"type":"integer"},"sub_folders":{"type":"array","items":{"$ref":"#/components/schemas/Folder"}},"Children":{"type":"array","items":{"$ref":"#/components/schemas/FolderChildren"}},"name":{"type":"string"},"type":{"type":"string","enum":["ACCOUNT","SHARED","OOTB"]},"permission":{"type":"string","enum":["core_dashboards_view","core_dashboards_create","core_dashboards_delete","core_dashboards_edit"]}},"required":["id","name","sub_folders","type"]},"FolderChildren":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"integer"},"correlationId":{"type":"string"},"responseMessages":{"type":"string"}},"required":["code","error","responseMessages"]}}}}
```
