Folders

Folders are used to organize test cases within a project. Use our REST API to manage folders by retrieving details, creating new folders, updating existing folders, deleting folders, and moving folders within a project.

Note: All API endpoints are secured using Role-Based Access Control (RBAC). Ensure that your account has the necessary permissions to retrieve or modify data.

Get folder details

GET /api/v2/projects/{project-id}/folders/{folder-id}

Invoking this API will fetch detailed information about a folder within a project associated with your username and access key. Provide both the project identifier and the folder identifier.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
https://test-management.browserstack.com/api/v2/projects/PR-2223/folders/54

project-id^* String

A unique string identifier for the project.
folder-id^* Integer

A unique numeric identifier of the folder.

Response attributes `200 OK` `json`

Response

{
  "success": true,
  "folder": {
    "id": 54,
    "name": "Login",
    "description": "Test cases for the login flow",
    "parent_id": 25,
    "cases_count": 12,
    "sub_folders_count": 2,
    "created_at": "2025-03-10T09:15:22.000Z",
    "updated_at": "2025-06-02T14:40:05.000Z",
    "links": {
      "sub_folders": "/api/v2/projects/PR-2223/folders/54/sub-folders"
    },
    "urls": {
      "self": "https://test-management.browserstack.com/projects/1234/folder/54/test-cases"
    }
  }
}

success Boolean

API call is executed successfully.
folder Object

Details of the folder.

▶ SHOW VALUES
- id Integer
  
  A unique numeric identifier for the folder.
- name String
  
  Name of the folder.
- description String
  
  Description of the folder. Empty if the folder has no description.
- parent_id Integer
  
  Identifier of the parent folder, or null if the folder is at the root level.
- cases_count Integer
  
  Number of test cases directly inside the folder. The count excludes test cases in sub-folders.
- sub_folders_count Integer
  
  Number of direct sub-folders within the folder.
- created_at String
  
  Timestamp when the folder was created, in ISO 8601 format.
- updated_at String
  
  Timestamp when the folder was last updated, in ISO 8601 format.
- attachments Array
  
  List of attachments on the folder. Returned only when the folder has attachments.
- links Object
  
  Related API endpoints for the folder.
  
  ▶ SHOW VALUES
  - sub_folders String
    
    API endpoint to retrieve the sub-folders of the folder.
- urls Object
  
  Web app URLs for the folder.
  
  ▶ SHOW VALUES
  - self String
    
    Web app URL that opens the folder’s test cases in BrowserStack Test Management.

Get list of folders in a project

GET /api/v2/projects/{project-id}/folders

Use this API to list the root-level folders in a project. To call this API, you need the identifier of the project, such as PR-2223.

The response does not include sub-folders. To list the sub-folders of a folder, send a request to the URL in the folder’s links.sub_folders field.

This list is paginated. For more information, see Pagination.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
"https://test-management.browserstack.com/api/v2/projects/PR-2223/folders?p=1&page_size=30"

project-id^* String

Identifier of the project. For example, PR-2223.
p Integer

Page number to retrieve, used as a query parameter. Defaults to 1.
page_size Integer

Number of folders per page, used as a query parameter. Defaults to 30. The maximum is 300.
updated_after String

Fetch folders updated after this timestamp, used as a query parameter. Use the format YYYY-MM-DDTHH:MM:SS.SSSZ.
updated_before String

Fetch folders updated before this timestamp, used as a query parameter. Use the format YYYY-MM-DDTHH:MM:SS.SSSZ.

Response attributes `200 OK` `json`

Response

{
  "folders": [
    {
      "id": 1310,
      "name": "Login",
      "description": "Test cases for the login flow",
      "parent_id": null,
      "cases_count": 12,
      "sub_folders_count": 2,
      "created_at": "2025-03-10T09:15:22.000Z",
      "updated_at": "2025-06-02T14:40:05.000Z",
      "links": {
        "sub_folders": "/api/v2/projects/PR-2223/folders/1310/sub-folders"
      },
      "urls": {
        "self": "https://test-management.browserstack.com/projects/1234/folder/1310/test-cases"
      }
    },
    {
      "id": 1312,
      "name": "Checkout",
      "description": "",
      "parent_id": null,
      "cases_count": 0,
      "sub_folders_count": 0,
      "created_at": "2025-03-11T10:02:47.000Z",
      "updated_at": "2025-03-11T10:02:47.000Z",
      "links": {
        "sub_folders": "/api/v2/projects/PR-2223/folders/1312/sub-folders"
      },
      "urls": {
        "self": "https://test-management.browserstack.com/projects/1234/folder/1312/test-cases"
      }
    }
  ],
  "info": {
    "page": 1,
    "page_size": 30,
    "count": 2,
    "prev": null,
    "next": null
  },
  "link": {
    "folders": "/api/v2/projects/PR-2223/folders"
  }
}

folders Array

List of root-level folders in the project.

▶ SHOW VALUES
- id Integer
  
  A unique numeric identifier for the folder.
- name String
  
  Name of the folder.
- description String
  
  Description of the folder. Empty if the folder has no description.
- parent_id Integer
  
  Identifier of the parent folder, or null if the folder is at the root level.
- cases_count Integer
  
  Number of test cases directly inside the folder. The count excludes test cases in sub-folders.
- sub_folders_count Integer
  
  Number of direct sub-folders within the folder.
- created_at String
  
  Timestamp when the folder was created, in ISO 8601 format.
- updated_at String
  
  Timestamp when the folder was last updated, in ISO 8601 format.
- attachments Array
  
  List of attachments on the folder. Returned only when the folder has attachments.
- links Object
  
  Related API endpoints for the folder.
  
  ▶ SHOW VALUES
  - sub_folders String
    
    API endpoint to retrieve the sub-folders of the folder.
- urls Object
  
  Web app URLs for the folder.
  
  ▶ SHOW VALUES
  - self String
    
    Web app URL that opens the folder’s test cases in BrowserStack Test Management.
info Object

Pagination information.

▶ SHOW VALUES
- page Integer
  
  Current page number.
- page_size Integer
  
  Number of items per page.
- count Integer
  
  Total number of items.
- prev Integer
  
  Previous page number, or null on the first page.
- next Integer
  
  Next page number, or null on the last page.
link Object

Related API endpoints.

▶ SHOW VALUES
- folders String
  
  API endpoint to retrieve the root-level folders in the project.

Create a folder

POST /api/v2/projects/{project-id}/folders

Use this API to create a folder in a project. To call this API, you need the identifier of the project. To create the folder inside another folder, set parent_id to the identifier of that folder. If you set parent_id to null or leave it out, the API creates the folder at the root level.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST https://test-management.browserstack.com/api/v2/projects/PR-1/folders

project-id^* String

A unique string identifier for the project.

Request body

Request Body

{
  "folder": {
    "name": "Test Management login",
    "description": "This is the description of this folder",
    "parent_id": 1200
  }
}

name^* String

The name of the folder.
description String

A brief overview detailing the folder’s purpose.
parent_id Integer

Identifier of the parent folder. Set to null or omit it to create the folder at the root level.

Response attributes `200 OK` `json`

Response

{
  "success": true,
  "folder": {
    "id": 54,
    "name": "Login",
    "description": "Test cases for the login flow",
    "parent_id": 25,
    "cases_count": null,
    "sub_folders_count": null,
    "created_at": "2025-06-02T14:40:05.000Z",
    "updated_at": "2025-06-02T14:40:05.000Z",
    "links": {
      "sub_folders": "/api/v2/projects/PR-2223/folders/54/sub-folders"
    },
    "urls": {
      "self": "https://test-management.browserstack.com/projects/1234/folder/54/test-cases"
    }
  }
}

success Boolean

API call is executed successfully.
folder Object

Details of the created folder.

▶ SHOW VALUES
- id Integer
  
  A unique numeric identifier for the folder.
- name String
  
  Name of the folder.
- description String
  
  Description of the folder. Empty if the folder has no description.
- parent_id Integer
  
  Identifier of the parent folder, or null if the folder is at the root level.
- cases_count Integer
  
  Number of test cases directly inside the folder. The count excludes test cases in sub-folders.
- sub_folders_count Integer
  
  Number of direct sub-folders within the folder.
- created_at String
  
  Timestamp when the folder was created, in ISO 8601 format.
- updated_at String
  
  Timestamp when the folder was last updated, in ISO 8601 format.
- attachments Array
  
  List of attachments on the folder. Returned only when the folder has attachments.
- links Object
  
  Related API endpoints for the folder.
  
  ▶ SHOW VALUES
  - sub_folders String
    
    API endpoint to retrieve the sub-folders of the folder.
- urls Object
  
  Web app URLs for the folder.
  
  ▶ SHOW VALUES
  - self String
    
    Web app URL that opens the folder’s test cases in BrowserStack Test Management.

Update a folder

PATCH /api/v2/projects/{project-id}/folders/{folder-id}

Invoking this API allows you to update details of an existing folder within a project. To update a folder, you need the id of the project and the id of the folder.

Note: The API supports partial updates. Send only the fields you want to change, such as name or description.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X PATCH https://test-management.browserstack.com/api/v2/projects/PR-2223/folders/54

project-id^* String

A unique string identifier for the project.
folder-id^* Integer

A unique numeric identifier of the folder.

Request body

Request Body

{
  "folder": {
    "name": "Test Management login",
    "description": "This is a description of this test folder."
  }
}

name String

The new name of the folder.
description String

The new description of the folder.

Response attributes `200 OK` `json`

Response

{
  "success": true,
  "folder": {
    "id": 54,
    "name": "Login",
    "description": "Test cases for the login flow",
    "parent_id": 25,
    "cases_count": 12,
    "sub_folders_count": 2,
    "created_at": "2025-03-10T09:15:22.000Z",
    "updated_at": "2025-06-02T14:40:05.000Z",
    "links": {
      "sub_folders": "/api/v2/projects/PR-2223/folders/54/sub-folders"
    },
    "urls": {
      "self": "https://test-management.browserstack.com/projects/1234/folder/54/test-cases"
    }
  }
}

success Boolean

API call is executed successfully.
folder Object

Details of the updated folder.

▶ SHOW VALUES
- id Integer
  
  A unique numeric identifier for the folder.
- name String
  
  Name of the folder.
- description String
  
  Description of the folder. Empty if the folder has no description.
- parent_id Integer
  
  Identifier of the parent folder, or null if the folder is at the root level.
- cases_count Integer
  
  Number of test cases directly inside the folder. The count excludes test cases in sub-folders.
- sub_folders_count Integer
  
  Number of direct sub-folders within the folder.
- created_at String
  
  Timestamp when the folder was created, in ISO 8601 format.
- updated_at String
  
  Timestamp when the folder was last updated, in ISO 8601 format.
- attachments Array
  
  List of attachments on the folder. Returned only when the folder has attachments.
- links Object
  
  Related API endpoints for the folder.
  
  ▶ SHOW VALUES
  - sub_folders String
    
    API endpoint to retrieve the sub-folders of the folder.
- urls Object
  
  Web app URLs for the folder.
  
  ▶ SHOW VALUES
  - self String
    
    Web app URL that opens the folder’s test cases in BrowserStack Test Management.

Delete a folder

DELETE /api/v2/projects/{project-id}/folders/{folder-id}

Invoking this API will delete a folder. You need the id of the folder which you want to delete.

Warning: Using the delete API call will permanently remove the folder and all the associated data including test cases. This action cannot be undone.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X DELETE https://test-management.browserstack.com/api/v2/projects/PR-2223/folders/54

project-id^* String

A unique string identifier for the project.
folder-id^* Integer

A unique numeric identifier of the folder.

Response attributes `200 OK` `json`

Response

{
    "success": true
}

success Boolean

API call is executed successfully.

Move a folder

POST /api/v2/projects/{project-id}/folders/{folder-id}/move

Use this API to move a folder and its sub-folders within the same project. To call this API, you need the identifiers of the project and the folder. Set parent_id to the identifier of a folder in the same project. To move the folder to the root level, set parent_id to null.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST https://test-management.browserstack.com/api/v2/projects/PR-2223/folders/54/move

project-id^* String

A unique string identifier for the project.
folder-id^* Integer

A unique numeric identifier of the folder.

Request body

Request Body

{
  "parent_id": 1200
}

parent_id^* Integer

Identifier of the destination folder in the same project. Set to null to move the folder to the root level.

Response attributes `200 OK` `json`

Response

{
  "success": true,
  "folder": {
    "id": 54,
    "name": "Login",
    "description": "Test cases for the login flow",
    "parent_id": 30,
    "cases_count": 12,
    "sub_folders_count": 2,
    "created_at": "2025-03-10T09:15:22.000Z",
    "updated_at": "2025-06-02T14:40:05.000Z",
    "links": {
      "sub_folders": "/api/v2/projects/PR-2223/folders/54/sub-folders"
    },
    "urls": {
      "self": "https://test-management.browserstack.com/projects/1234/folder/54/test-cases"
    }
  }
}

success Boolean

API call is executed successfully.
folder Object

Details of the moved folder.

▶ SHOW VALUES
- id Integer
  
  A unique numeric identifier for the folder.
- name String
  
  Name of the folder.
- description String
  
  Description of the folder. Empty if the folder has no description.
- parent_id Integer
  
  Identifier of the parent folder, or null if the folder is at the root level.
- cases_count Integer
  
  Number of test cases directly inside the folder. The count excludes test cases in sub-folders.
- sub_folders_count Integer
  
  Number of direct sub-folders within the folder.
- created_at String
  
  Timestamp when the folder was created, in ISO 8601 format.
- updated_at String
  
  Timestamp when the folder was last updated, in ISO 8601 format.
- attachments Array
  
  List of attachments on the folder. Returned only when the folder has attachments.
- links Object
  
  Related API endpoints for the folder.
  
  ▶ SHOW VALUES
  - sub_folders String
    
    API endpoint to retrieve the sub-folders of the folder.
- urls Object
  
  Web app URLs for the folder.
  
  ▶ SHOW VALUES
  - self String
    
    Web app URL that opens the folder’s test cases in BrowserStack Test Management.

Did this page help you?

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback

Folders

Get folder details

Request parameters

project-id* String

folder-id* Integer

Response attributes 200 OK json

success Boolean

folder Object

id Integer

name String

description String

parent_id Integer

cases_count Integer

sub_folders_count Integer

created_at String

updated_at String

attachments Array

links Object

sub_folders String

urls Object

self String

Get list of folders in a project

Request parameters

project-id* String

p Integer

page_size Integer

updated_after String

updated_before String

Response attributes 200 OK json

folders Array

id Integer

name String

description String

parent_id Integer

cases_count Integer

sub_folders_count Integer

created_at String

updated_at String

attachments Array

links Object

sub_folders String

urls Object

self String

info Object

page Integer

page_size Integer

count Integer

prev Integer

next Integer

link Object

folders String

Create a folder

Request parameters

project-id* String

Request body

name* String

description String

parent_id Integer

Response attributes 200 OK json

success Boolean

folder Object

id Integer

name String

description String

parent_id Integer

cases_count Integer

sub_folders_count Integer

created_at String

updated_at String

attachments Array

links Object

sub_folders String

urls Object

self String

Update a folder

Request parameters

project-id* String

folder-id* Integer

Request body

name String

project-id^* String

folder-id^* Integer

Response attributes `200 OK` `json`

project-id^* String

Response attributes `200 OK` `json`

project-id^* String

name^* String

Response attributes `200 OK` `json`

project-id^* String

folder-id^* Integer

Response attributes `200 OK` `json`

project-id^* String

folder-id^* Integer

Response attributes `200 OK` `json`

project-id^* String

folder-id^* Integer

parent_id^* Integer

Response attributes `200 OK` `json`