Skip to main content

Folders

The folders namespace provides API methods for getting, adding, updating or deleting folders from a Testmo project. The following endpoints allow single and bulk operations

GET /projects/{project_id}/folders

Returns a list of folders from the specified project.

This method uses pagination so you might need to request additional pages to retrieve all folders.

project_id id required
ID of the project.
 

Request

Parameters
Schema

page integer
Number of page to return (default: first page).
 

per_page integer
Maximum number of folders to return (supported: 15, 25, 50, 100; default: 100).
 

sort string
Sort field for the list of folders (supported: repository_folders:display_order, repository_folders:name, repository_folders:id, repository_folders:depth; default: repository_folders:display_order).
 

order string
Sort order (supported: asc, desc; default: asc).
 

parent_id integer
Filter by parent folder ID.
 

name string
Filter by name (partial match).
 

expands string
Comma-separated list of expands to return.
  

{
  "page": {
      "type": "integer",
      "format": "int64",
      "description": "Number of page to return (default: first page)."
  },
  "per_page": {
      "type": "integer",
      "format": "int64",
      "enum": [15, 25, 50, 100],
      "description": "Maximum number of items to return per page (default: 100)."
  },
  "sort": {
      "type": "string",
      "enum": [
          "repository_folders:display_order",
          "repository_folders:name",
          "repository_folders:id",
          "repository_folders:depth"
      ],
      "default": "repository_folders:display_order",
      "description": "Sort field for the list of folders."
  },
  "order": {
      "type": "string",
      "enum": ["asc", "desc"],
      "default": "asc",
      "description": "Sort order (ascending or descending)."
  },
  "parent_id": {
      "type": "integer",
      "format": "int64",
      "description": "Return only folders with this parent ID."
  },
  "name": {
      "type": "string",
      "description": "Filter by name (partial match, case-insensitive)."
  },
  "expands": {
      "type": "string",
      "description": "Comma-separated list of expands to return (folders)."
  }
}

This method supports the following expands so you can automatically include additional information for referenced objects:

  • folders — expands the parent folder referenced by parent_id

Response

GET /api/v1/projects/1/folders

 
200 OK
{
    "page": 1,
    "prev_page": null,
    "next_page": 2,
    "last_page": 6,
    "per_page": 15,
    "total": 82,
    "result": [
        {
            "id": 1100,
            "project_id": 1,
            "repo_id": 1,
            "parent_id": null,
            "depth": 0,
            "name": "Authentication",
            "docs": null,
            "display_order": 82,
            "case_count": 14
        },
        {
            "id": 1097,
            "project_id": 1,
            "repo_id": 1,
            "parent_id": null,
            "depth": 0,
            "name": "Billing",
            "docs": "Billing and subscription test cases.",
            "display_order": 81,
            "case_count": 7
        },
        ..
    ]
}

The case_count field returns the total number of test cases in the folder and all of its sub-folders.

Examples

// Get all folders for a project
GET /api/v1/projects/1/folders

// Filter by parent folder ID (immediate children only)
GET /api/v1/projects/1/folders?parent_id=601

// Filter by name (partial match)
GET /api/v1/projects/1/folders?name=login

// Sort by name
GET /api/v1/projects/1/folders?sort=repository_folders:name&order=asc

// Include parent folder details
GET /api/v1/projects/1/folders?expands=folders

// Paginate through results
GET /api/v1/projects/1/folders?page=2&per_page=25

Status codes

200 401 403 404 429 (details)

POST /projects/{project_id}/folders

Creates one or more folders (maximum 100 per request).

project_id id required
ID of the project.
 

Request

Parameters
Schema

folders array required
Array of folder objects to create.
 

name string required
The name of the folder.
 

parent_id integer
A valid parent folder ID. If omitted, the folder is created at the root level.
 

docs string
Description or notes for the folder.
 

display_order integer
Display position of the folder in the UI list.
  

{
  "folders": {
      "type": "array",
      "description": "Array of folder objects to create (maximum 100).",
      "maxItems": 100,
      "items": {
          "type": "object",
          "properties": {
              "name": {
                  "type": "string",
                  "description": "Name of the folder (required)."
              },
              "parent_id": {
                  "type": "integer",
                  "format": "int64",
                  "nullable": true,
                  "description": "Parent folder ID. Omit to create at root level."
              },
              "docs": {
                  "type": "string",
                  "description": "Description or notes."
              },
              "display_order": {
                  "type": "integer",
                  "format": "int64",
                  "description": "Display position in the UI list."
              }
          },
          "required": ["name"]
      }
  }
}

Example

POST /api/v1/projects/1/folders
{
    "folders": [
        {
            "name": "Authentication",
            "parent_id": 1,
            "docs": "Test cases for the authentication flow."
        }
    ]
}
 
201 Created
{
    "result": [
        {
            "id": 1101,
            "project_id": 1,
            "repo_id": 1,
            "parent_id": 1,
            "depth": 1,
            "name": "Authentication",
            "docs": "Test cases for the authentication flow.",
            "display_order": 2,
            "case_count": 0
        }
    ]
}

Status codes

201 401 403 404 422 429 (details)

PATCH /projects/{project_id}/folders

Bulk updates up to 100 folders (minimum 1, maximum 100).

project_id id required
ID of the project.
 

Request

Parameters
Schema

ids array required
Array of folder IDs to update (minimum 1, maximum 100).
 

name string
The name to apply to the folders.
 

parent_id integer
Move all selected folders under this parent. Use null to move to root level.
 

docs string
Description or notes to apply to the folders.
 

display_order integer
Display position to apply to the folders.
  

{
  "ids": {
      "type": "array",
      "description": "Array of folder IDs to update (minimum 1, maximum 100).",
      "minItems": 1,
      "maxItems": 100,
      "items": { "type": "integer", "format": "int64" }
  },
  "name": {
      "type": "string",
      "description": "New name to apply to all selected folders."
  },
  "parent_id": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "description": "Move all selected folders under this parent. Use null to move to root."
  },
  "docs": {
      "type": "string",
      "description": "Description or notes to apply."
  },
  "display_order": {
      "type": "integer",
      "format": "int64",
      "description": "Display position to apply."
  }
}

Example

PATCH /api/v1/projects/1/folders
{
    "ids": [1101],
    "name": "Authentication",
    "parent_id": 2,
    "docs": "Test cases for the authentication flow. (Moved from Security folder)"
}
 
200 OK
{
    "result": [
        {
            "id": 1101,
            "project_id": 1,
            "repo_id": 1,
            "parent_id": 2,
            "depth": 1,
            "name": "Authentication",
            "docs": "Test cases for the authentication flow. (Moved from Security folder)",
            "display_order": 2,
            "case_count": 0
        }
    ]
}

Status codes

200 401 403 404 422 429 (details)

DELETE /projects/{project_id}/folders

Deletes up to 100 folders (minimum 1, maximum 100). Returns a 403 if a folder contains sub-folders or test cases.

project_id id required
ID of the project.
 

Request

Parameters
Schema

ids array required
Array of folder IDs to delete (minimum 1, maximum 100).
  

{
  "ids": {
      "type": "array",
      "description": "Array of folder IDs to delete (minimum 1, maximum 100).",
      "minItems": 1,
      "maxItems": 100,
      "items": { "type": "integer", "format": "int64" }
  }
}

Returns a 204 no content response.

Example

DELETE /api/v1/projects/1/folders
{
    "ids": [1101, 1102, 1103]
}
 
204 No Content

Status codes

204 401 403 404 422 429 (details)

Was this article helpful?