# ◉ Folder Endpoints

## Get all folders

 - [GET /projects/{project_id}/folders](https://testpad-api.redocly.app/openapi/folder-endpoints/paths/~1projects~1%7Bproject_id%7D~1folders/get.md): Retrieves the complete content tree of folders and scripts contained by the project, project_id.

By default, the returned tree of folders and scripts consists only of their names and IDs. Folder and script objects can be expanded with more details, such as progress statistics, test details and test runs details by using URL parameters as defined below.

For large projects, it is recommended to use the more specific endpoint Get a folder GET /projects/:p/folders/:f to retrieve the contents of just one folder rather than all folders in the project.

Takes Common URL Parameters for controlling the contents of contained objects.

Defaults for common parameters:
- subfolders=all
- scripts=terse
- tests=none
- fields=none
- runs=none
- results=none
- progress=none

## Create a folder

 - [POST /projects/{project_id}/folders](https://testpad-api.redocly.app/openapi/folder-endpoints/paths/~1projects~1%7Bproject_id%7D~1folders/post.md): Creates a new folder at the top level of the project project_id.

The new folder is supplied as a JSON object in the request body supplying only the name of the new folder.

Note: it is not possible to create a new folder together with a new script (or sub-folder) in the same request.
Instead, a first request must be made to create a new folder, and then subsequent requests can be used to populate it with content.

## Get a folder

 - [GET /projects/{project_id}/folders/{folder_id}](https://testpad-api.redocly.app/openapi/folder-endpoints/paths/~1projects~1%7Bproject_id%7D~1folders~1%7Bfolder_id%7D/get.md): Retrieves the basic information and contents of the folder specified by folder_id.

Folder IDs are strings that start with an 'f' followed by an integer. To find a folder ID in the app, click on a folder to open it and inspect the URL.

By default, the returned tree of folders and scripts consists only of their names and IDs. Folder and script objects can be expanded with more details, such as progress statistics, test details and test runs details by using URL parameters as defined below.

In particular, note that the subfolders URL parameter can be used to limit the response to just the folder requested, without also returning the contents of nested sub-folders.

Takes Common URL Parameters for controlling the contents of contained objects.

Defaults for common parameters:
- subfolders=all
- scripts=terse
- tests=none
- fields=none
- runs=none
- results=none
- progress=none

## Modify a folder

 - [PATCH /projects/{project_id}/folders/{folder_id}](https://testpad-api.redocly.app/openapi/folder-endpoints/paths/~1projects~1%7Bproject_id%7D~1folders~1%7Bfolder_id%7D/patch.md): Modifies the name of the folder folder_id in the project project_id.

To modify the contents of a folder, please see:
- Create a sub-folder POST /projects/:p/folders/:f/folders – for creating a new folder within a folder
- Create a script in a folder POST /projects/:p/folders/:f/scripts – for creating a script within a folder

### POST data
name string — The new name of the folder.

### Returns
JSON response payload containing:

folder object — Summary of the modified folder.  
context object — Project and folderPath context.

### Defaults for common parameters
(no common parameters are used).

## Create a sub-folder

 - [POST /projects/{project_id}/folders/{folder_id}/folders](https://testpad-api.redocly.app/openapi/folder-endpoints/paths/~1projects~1%7Bproject_id%7D~1folders~1%7Bfolder_id%7D~1folders/post.md): Creates a new sub-folder of the folder folder_id within the project project_id.

The new folder is supplied as a JSON object in the request body supplying only the name of the new folder.

Note, it is not possible to create a new folder and new script (or sub-folder) contents in the same request. Instead, a first request must be made to create a new folder, and then subsequent requests can be used to populate it with content.