> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobileboost.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Folders

> Organise your test library into folders, and file tests into them

Folders group the tests in your library. They form a tree: every folder has a `parentId`, which is `null` at the top level, and a folder can hold both tests and other folders.

A folder is a **label on a test, not a container that owns it**. A test belongs to exactly one folder (or none), and deleting a folder never deletes a test.

<Note>
  Folders apply to the MobileBoost Platform test library. On a QA Studio organisation these endpoints answer `400`, and `folderId` is refused on `POST`/`PATCH /tests`.
</Note>

All requests below authenticate with your `mb_live_` API key passed as a Bearer token in the `Authorization` header.

## See the tree

`GET /tests/folders` returns every folder with its full path and how many tests are in it, counting subfolders, so one call is enough to find the folder you want:

```bash theme={null}
curl https://api.mobileboost.io/tests/folders \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "folders": [
    { "id": "kFq2b8s1TzYwm0Xd4eNc", "name": "Checkout", "parentId": null,
      "path": "Checkout", "testCount": 12 },
    { "id": "p7Rw3nVa5LcQe1Zt9uHb", "name": "Payments", "parentId": "kFq2b8s1TzYwm0Xd4eNc",
      "path": "Checkout / Payments", "testCount": 4 }
  ],
  "unfiledTestCount": 3
}
```

`testCount` counts subfolders too: the four tests in **Payments** are part of the twelve in **Checkout**.

## Create and nest folders

```bash theme={null}
curl -X POST https://api.mobileboost.io/tests/folders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Payments", "parentId": "kFq2b8s1TzYwm0Xd4eNc" }'
```

Names are for people to read, up to 60 characters. Two folders may share a name — everything that refers to a folder uses its id.

## Rename and move

`PATCH /tests/folders` renames a folder, moves it, or both in one call. `parentId: null` moves it back to the top level; omitting `parentId` leaves it where it is.

```bash theme={null}
curl -X PATCH https://api.mobileboost.io/tests/folders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "folderId": "p7Rw3nVa5LcQe1Zt9uHb", "name": "Card payments", "parentId": null }'
```

Moving a folder takes its subfolders and its tests with it. Moving one inside its own subtree is refused with a `400`, because that would detach the subtree from the tree.

## File tests into a folder

<Steps>
  <Step title="Create a test directly into one">
    ```bash theme={null}
    curl -X POST https://api.mobileboost.io/tests \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "title": "Pays with a saved card",
        "commands": ["Open the basket", "Pay with the saved card", "Verify the receipt"],
        "folderId": "p7Rw3nVa5LcQe1Zt9uHb"
      }'
    ```
  </Step>

  <Step title="Move one test">
    ```bash theme={null}
    curl -X PATCH https://api.mobileboost.io/tests \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "testId": "xMIt964RUpAB95b6YI2F", "folderId": "p7Rw3nVa5LcQe1Zt9uHb" }'
    ```

    `folderId: null` takes the test out of its folder. Omitting the field leaves the folder as it is.
  </Step>

  <Step title="Move many at once">
    ```bash theme={null}
    curl -X POST https://api.mobileboost.io/tests/folders/move \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "testIds": ["xMIt964RUpAB95b6YI2F", "b3Kd9pQw2ZxLm7Yt1Sof"],
        "folderId": "p7Rw3nVa5LcQe1Zt9uHb"
      }'
    ```

    Ids that no longer exist come back under `skippedTestIds` rather than failing the call, and a test already in that folder comes back under `unchangedTestIds`.
  </Step>
</Steps>

Changing a test's folder never re-triggers automation generation: it does not change what the test should do.

## List the tests in a folder

```bash theme={null}
curl "https://api.mobileboost.io/tests?folderId=kFq2b8s1TzYwm0Xd4eNc&includeSubfolders=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Without `includeSubfolders`, you get only the tests filed directly in that folder.

## Delete a folder

```bash theme={null}
curl -X DELETE https://api.mobileboost.io/tests/folders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "folderId": "kFq2b8s1TzYwm0Xd4eNc" }'
```

Deleting a folder deletes **no test**. Its subfolders move up to its own parent, its tests become unfiled, and the response says exactly which:

```json theme={null}
{
  "message": "Folder 'Checkout' was deleted. 1 subfolder(s) moved up, 3 test(s) unfiled. No test was deleted.",
  "folderId": "kFq2b8s1TzYwm0Xd4eNc",
  "promotedFolderIds": ["p7Rw3nVa5LcQe1Zt9uHb"],
  "unfiledTestIds": ["xMIt964RUpAB95b6YI2F"]
}
```

To delete the tests as well, call `DELETE /tests` with their ids first.

<Card title="Platform MCP server" icon="plug" href="/engineer-tooling/platform-mcp">
  The same folder operations as tools your coding agent can call.
</Card>