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

# Create Test Folder

> Create one folder in the test repository. The parent is addressed by path (preferred) or id, and defaults to the root.

<Info>
  **Permission Required**: `project:edit-tests`
</Info>

Create one folder in the test repository. Folders are addressed by path
(`"regression/smoke"`) rather than UUID, so the parent is normally given as
`parent_path`. Omit both parent fields to create the folder at the root.

The resulting `path` is the string accepted by `folder_path` in
[Create Test](/api-reference/tests/create-test),
[Update Test](/api-reference/tests/update-test), and
[List Tests](/api-reference/tests/list-tests) — so this endpoint is what lets a
client build the folder it wants to file new tests under.

## Request Body

<ParamField body="test_folder" type="object" required>
  Folder definition

  <Expandable title="test_folder properties">
    <ParamField body="test_folder.name" type="string" required>
      Folder name. Cannot contain `/`, and cannot have leading or trailing
      whitespace — both would make the folder unaddressable by path.
    </ParamField>

    <ParamField body="test_folder.parent_path" type="string">
      Parent folder addressed by path. `null` or `"/"` means the root. Mutually
      exclusive with `parent_folder_id`.
    </ParamField>

    <ParamField body="test_folder.parent_folder_id" type="string">
      Pre-resolved parent folder UUID, as returned by
      [List Test Folders](/api-reference/test-folders/list-test-folders).
      Mutually exclusive with `parent_path`.
    </ParamField>

    <ParamField body="test_folder.description" type="string">
      Optional description shown in the folder details dialog.
    </ParamField>

    <ParamField body="test_folder.tags" type="string[]">
      Optional tags applied to the folder.
    </ParamField>

    <ParamField body="test_folder.create_intermediate_parents" type="boolean" default="false">
      When `parent_path` names a folder that does not exist yet, create the
      missing segments instead of returning `404`. Defaults to `false` so a typo
      surfaces as an error rather than silently building a new hierarchy.
    </ParamField>
  </Expandable>
</ParamField>

## Response

Returns the newly created folder with status `201`.

<ResponseField name="id" type="string" required>
  Folder UUID
</ResponseField>

<ResponseField name="name" type="string" required>
  Folder name (just the leaf segment)
</ResponseField>

<ResponseField name="path" type="string" required>
  Resolved folder path (e.g. `"regression/smoke"`)
</ResponseField>

<ResponseField name="parent_folder_id" type="string">
  Parent folder UUID, or `null` for top-level folders
</ResponseField>

<ResponseField name="parent_path" type="string" required>
  Resolved parent path, or `"/"` for top-level folders
</ResponseField>

<ResponseField name="created_intermediate_paths" type="string[]" required>
  Parents that had to be created on the way to the requested one. Empty unless
  `create_intermediate_parents` was set.
</ResponseField>

## Errors

| Status | When |
| - | - |
| `400` | Invalid folder name, or both `parent_path` and `parent_folder_id` supplied |
| `404` | `parent_path` does not exist and `create_intermediate_parents` was not set |
| `409` | A folder with that name already exists in the same parent |

<RequestExample>
  ```bash cURL theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  curl -X POST "https://nunu.ai/api/v1/project/your-project-id/test-folders" \
    -H "X-Api-Key: YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "test_folder": {
        "name": "smoke",
        "parent_path": "regression",
        "description": "Critical-path smoke tests",
        "tags": ["nightly"],
        "create_intermediate_parents": true
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  {
    "id": "f01a3b1c-9d2e-4f05-8c7a-1a2b3c4d5e6f",
    "name": "smoke",
    "path": "regression/smoke",
    "parent_folder_id": "e10b2c3d-4e5f-6789-abcd-ef0123456789",
    "parent_path": "regression",
    "created_intermediate_paths": ["regression"]
  }
  ```
</ResponseExample>


## OpenAPI

````yaml POST /project/{projectId}/test-folders
openapi: 3.1.0
info:
  title: nunu.ai API
  description: >-
    The nunu.ai Public API allows you to programmatically interact with your
    projects, manage test runs, and upload builds.
  version: 1.0.0
servers:
  - url: https://nunu.ai/api/v1
security:
  - apiKeyAuth: []
paths:
  /project/{projectId}/test-folders:
    parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
        description: >-
          The project ID. You can copy it from the project settings page or the
          project URL in the dashboard.
    post:
      tags:
        - Tests
      summary: Create Test Folder
      description: >-
        Create one folder in the test repository. The parent is addressed by
        path (preferred) or id, and defaults to the root.
      operationId: createTestFolder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTestFolderRequest'
      responses:
        '201':
          description: Test folder created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedTestFolder'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Parent folder path not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: A folder with that name already exists in the same parent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CreateTestFolderRequest:
      type: object
      required:
        - test_folder
      properties:
        test_folder:
          type: object
          required:
            - name
          properties:
            name:
              type: string
              description: Folder name. Cannot contain "/" or leading/trailing whitespace.
            parent_path:
              type: string
              nullable: true
              description: >-
                Parent folder addressed by path. null or "/" means root.
                Mutually exclusive with parent_folder_id.
            parent_folder_id:
              type: string
              format: uuid
              description: >-
                Pre-resolved parent folder id. Mutually exclusive with
                parent_path.
            description:
              type: string
              nullable: true
            tags:
              type: array
              items:
                type: string
            create_intermediate_parents:
              type: boolean
              default: false
              description: Create missing segments of parent_path instead of returning 404.
    CreatedTestFolder:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        path:
          type: string
        parent_folder_id:
          type: string
          format: uuid
          nullable: true
        parent_path:
          type: string
        created_intermediate_paths:
          type: array
          items:
            type: string
          description: >-
            Parents created on the way to the requested one. Empty unless
            create_intermediate_parents was set.
    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        details:
          type: object
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: API key for authentication

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.