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,       // Total number of items available
  page: number,        // Current page number
  limit: number,       // Number of items per page
  data: Array<{        // Array of folder objects
    id: number         //   Unique identifier for the folder
    title: string      //   Name of the folder
    comment: html      //   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?: html // Additional notes or description for the leaf folder.
  }>
}

Response

Status: 200 OK

{
  ids: Array<Array<number>> // Each array represents the full folder path hierarchy in the request as an array of folder IDs, from root to leaf
}

Details:

• The ids field is an array where each item corresponds to one input folder path.
• Each inner array contains folder IDs that map 1:1 to the specified folder path in the request.
  • For example, if your path is ["Frontend", "Components", "Navigation"], the result could be [12, 13, 14] where 12 is "Frontend", 13 is "Components", 14 is "Navigation".
• Newly created folders will always get new IDs; existing folders return their original IDs.
• The order of returned arrays matches the order of the input folders in the request.

Example Request

curl -X POST \
  -H "Authorization: ApiKey your.api.key.here" \
  -H "Content-Type: application/json" \
  -d '{
    "folders": [
      {
        "path": ["Frontend", "Components", "Navigation"],
        "comment": "<p>Tests for navigation components</p>"
      },
      {
        "path": ["Frontend", "Components", "Forms"],
        "comment": "<p>Form validation and interaction tests</p>"
      },
      {
        "path": ["Backend", "API", "Authentication"],
        "comment": "<p>Authentication endpoint tests</p>"
      }
    ]
  }' \
  https://company.qasphere.com/api/public/v0/project/BD/tcase/folder/bulk

Example Response

Status: 200 OK

{
  "ids": [
    [12, 13, 14],
    [12, 13, 15],
    [16, 17, 18]
  ]
}

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
• Automating test case creation

note

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