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

# Create Folder

> Create an asset or video folder in your space to organize your library

## Overview

Creates a folder in your space to keep your library organized. A folder is scoped to a **type** — either `assets` (images/videos generated via [Submit Asset Generation](/api-reference/assets/start)) or `videos` (videos produced through the video workflow).

For asset folders, pass the returned `id` as `folder_id` when calling [Submit Asset Generation](/api-reference/assets/start) and the outputs land in that folder.

<Tip>
  When you start a batch of generations or work on a specific project, create a dedicated folder first and route every generation into it. It keeps the space tidy and makes the assets easy to find in the dashboard.
</Tip>

## Authentication

<Info>
  This endpoint requires API key authentication. Include your API key in the `Authorization` header.
</Info>

## Request Body

<ParamField body="name" type="string" required>
  Display name of the folder.
</ParamField>

<ParamField body="type" type="string" default="assets">
  Folder type: `assets` or `videos`. Determines which library the folder appears in.
</ParamField>

<ParamField body="parent_folder_id" type="string">
  ID of an existing folder **of the same type** to nest this one under. Omit (or pass `null`) to create a folder at the root of the library.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier of the created folder. For an asset folder, pass this as `folder_id` to [Submit Asset Generation](/api-reference/assets/start).
</ResponseField>

<ResponseField name="name" type="string">
  Name of the folder.
</ResponseField>

<ResponseField name="type" type="string">
  Folder type: `assets` or `videos`.
</ResponseField>

<ResponseField name="parent_folder_id" type="string">
  ID of the parent folder, or `null` for a root folder.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

## Examples

<RequestExample>
  ```bash Asset folder theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/folder/create" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Summer Campaign",
      "type": "assets"
    }'
  ```

  ```bash Video folder theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/folder/create" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Q3 Ads",
      "type": "videos"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.hoox.video/api/public/v1/folder/create"
  headers = {"Authorization": "Bearer your_api_key"}

  response = requests.post(url, headers=headers, json={"name": "Summer Campaign", "type": "assets"})
  folder = response.json()

  # Route generations into the asset folder
  requests.post(
      "https://app.hoox.video/api/public/v1/asset/start",
      headers=headers,
      json={
          "type": "image",
          "model": "flux-2-pro",
          "prompt": "Product shot of a ceramic mug on a marble counter.",
          "folder_id": folder["id"],
      },
  )
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch('https://app.hoox.video/api/public/v1/folder/create', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_api_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ name: 'Summer Campaign', type: 'assets' }),
  });

  const folder = await res.json();
  console.log(folder.id);
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": "662f8c1d3a4b5e6f70123456",
    "name": "Summer Campaign",
    "type": "assets",
    "parent_folder_id": null,
    "created_at": "2026-06-19T10:00:00.000Z"
  }
  ```

  ```json 400 Validation Failed theme={null}
  {
    "error": "Validation failed",
    "details": [
      { "code": "missing_field", "message": "name is required", "field": "name" }
    ]
  }
  ```

  ```json 400 Invalid Parent theme={null}
  {
    "error": "folder_id does not reference an existing assets folder",
    "details": [
      { "code": "invalid_value", "message": "folder_id does not reference an existing assets folder" }
    ]
  }
  ```
</ResponseExample>

## Notes

* `type` defaults to `assets` when omitted.
* A `parent_folder_id` must reference a folder of the **same** `type`, otherwise the request fails with `invalid_value`.
* Use [List Folders](/api-reference/folders/list) to retrieve existing folder IDs before creating duplicates.