Skip to main content

Folders

The folders endpoint allows you to retrieve the folder structure of test cases within a project.

List Project Folders

GET/api/public/v0/project/{project_id}/tcase/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

ParameterTypeDescriptionExample
pagenumberCurrent page number of resultspage=1
limitnumberMaximum number of items per pagelimit=10
sortFieldstringField to sort by. Allowed values:
- id
- project_id
- title
- pos
- parent_id
- created_at
- updated_at
sortField=title
sortOrderstringSort 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

FieldTypeDescription
totalnumberTotal number of items available
pagenumberCurrent page number
limitnumberNumber of items per page
dataArray<object>Array of folder objects
» idnumberUnique identifier for the folder
» titlestringName of the folder
» commentstringAdditional notes or description
» posnumberPosition of the folder among its siblings
» parentIdnumberID of the parent folder (0 for root folders)
» projectIdstringID 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 CodeDescription
401Invalid or missing API key
403Insufficient permissions or suspended tenant
404Project not found
tip

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

POST/api/public/v0/project/{project_id}/tcase/folder/bulk

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 CodeDescription
400Invalid request body or folder path format
401Invalid or missing API key
403Insufficient permissions or suspended tenant
404Project not found
500Internal 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
tip

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
note

The endpoint only updates the comment field for existing folders. Other properties like position and parent relationships are preserved.