Folders
The folders endpoint allows you to retrieve the folder structure of test cases within a project.
List Project Folders
Returns a hierarchical list of all folders in the project. This endpoint is useful for getting folder IDs and understanding the test case organization structure.
Path Parameters
project_id
: The project identifier (can be either the project code or UUID)
Query Parameters
Parameter | Type | Description | Example |
---|---|---|---|
page | number | Current page number of results | page=1 |
limit | number | Maximum number of items per page | limit=10 |
sortField | string | Field to sort by. Allowed values: - id - project_id - title - pos - parent_id - created_at - updated_at | sortField=title |
sortOrder | string | Sort direction (requires sortField ).Allowed values: asc , desc | sortOrder=desc |
Example Request
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://company.qasphere.com/api/public/v0/project/BD/tcase/folders?page=1&limit=10&sortField=title&sortOrder=desc
Response
Status: 200 OK
{
total: number,
page: number,
limit: number,
data: Array<{
id: number // Unique identifier for the folder
title: string // Name of the folder
comment: string // Additional notes or description
pos: number // Position of the folder among its siblings
parentId: number // ID of the parent folder (0 for root folders)
projectId: string // ID of the project the folder belongs to
}>
}
Response Fields
Field | Type | Description |
---|---|---|
total | number | Total number of items available |
page | number | Current page number |
limit | number | Number of items per page |
data | Array<object> | Array of folder objects |
» id | number | Unique identifier for the folder |
» title | string | Name of the folder |
» comment | string | Additional notes or description |
» pos | number | Position of the folder among its siblings |
» parentId | number | ID of the parent folder (0 for root folders) |
» projectId | string | ID of the project the folder belongs to |
Example Response
{
"total": 12,
"page": 1,
"limit": 10,
"data": [
{
"id": 11866,
"parentId": 11844,
"title": "Welcome",
"comment": "",
"projectId": "1CGeNZsqU_BRPFrugwAVDs3",
"pos": 4
},
{
"id": 11855,
"parentId": 11844,
"title": "Today's menu",
"comment": "",
"projectId": "1CGeNZsqU_BRPFrugwAVDs3",
"pos": 3
}
]
}
Error Responses
Status Code | Description |
---|---|
401 | Invalid or missing API key |
403 | Insufficient permissions or suspended tenant |
404 | Project not found |
Use the folder IDs returned by this endpoint when creating or updating test runs to specify which folders should be included in the run.
Bulk Upsert Folders
Creates or updates multiple folders in a single request using folder path hierarchies. This endpoint automatically creates nested folder structures and updates existing folders' comments.
Path Parameters
project_id
: The project identifier (can be either the project code or UUID)
Request Body
{
folders: Array<{
path: string[] // Array of folder names representing the hierarchy
comment: string // Additional notes or description for the leaf folder
}>
}
Example Request
curl -X POST \
-H "Authorization: ApiKey your.api.key.here" \
-H "Content-Type: application/json" \
-d '{
"folders": [
{
"path": ["Frontend", "Components", "Navigation"],
"comment": "Tests for navigation components"
},
{
"path": ["Frontend", "Components", "Forms"],
"comment": "Form validation and interaction tests"
},
{
"path": ["Backend", "API", "Authentication"],
"comment": "Authentication endpoint tests"
}
]
}' \
https://company.qasphere.com/api/public/v0/project/BD/tcase/folder/bulk
Response
Status: 200 OK
{
"message": "Folders upserted"
}
Behavior
- Creates nested structure: Automatically creates all parent folders in the path if they don't exist
- Updates existing folders: If a folder path already exists, only the comment is updated
- Idempotent: Running the same request multiple times produces the same result
- Preserves hierarchy: Maintains proper parent-child relationships between folders
- Position assignment: New folders are positioned automatically within their parent
Example Folder Creation
Given the request above, the following folder structure would be created:
Frontend/
├── Components/
│ ├── Navigation/ (comment: "Tests for navigation components")
│ └── Forms/ (comment: "Form validation and interaction tests")
Backend/
└── API/
└── Authentication/ (comment: "Authentication endpoint tests")
Error Responses
Status Code | Description |
---|---|
400 | Invalid request body or folder path format |
401 | Invalid or missing API key |
403 | Insufficient permissions or suspended tenant |
404 | Project not found |
500 | Internal server error |
Validation Rules
- Each folder name in the path must be 1-255 characters long
- Folder names cannot contain forward slash (
/
) characters - Folder names cannot be empty strings
- The
path
array cannot be empty - folder comment should be in html format
This endpoint is particularly useful for:
- Setting up folder structures during project initialization
- Bulk importing test case organization from external systems
- Synchronizing folder structures across projects
The endpoint only updates the comment
field for existing folders. Other properties like position and parent relationships are preserved.