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

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

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 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

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.