> ## 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.

# List Folders

> List the folders in your space, optionally filtered by type

## Overview

Returns the folders in your space. By default it returns **every** folder; pass `type` to return only asset folders or only video folders. Use a folder's `id` as `folder_id` when calling [Submit Asset Generation](/api-reference/assets/start), or check this list before creating a new folder to avoid duplicates.

## Authentication

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

## Query Parameters

<ParamField query="type" type="string">
  Filter by folder type: `assets` or `videos`. Omit to return folders of all types.
</ParamField>

## Response

<ResponseField name="folders" type="array">
  Array of folder objects.

  <Expandable title="folder properties">
    <ResponseField name="id" type="string">
      Unique identifier of the 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>
  </Expandable>
</ResponseField>

## Examples

<RequestExample>
  ```bash All folders theme={null}
  curl -X GET "https://app.hoox.video/api/public/v1/folder/list" \
    -H "Authorization: Bearer your_api_key"
  ```

  ```bash Asset folders only theme={null}
  curl -X GET "https://app.hoox.video/api/public/v1/folder/list?type=assets" \
    -H "Authorization: Bearer your_api_key"
  ```

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

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

  response = requests.get(url, headers=headers, params={"type": "assets"})
  print(response.json()["folders"])
  ```

  ```javascript JavaScript theme={null}
  const url = new URL('https://app.hoox.video/api/public/v1/folder/list');
  url.searchParams.set('type', 'assets');

  const res = await fetch(url, {
    headers: { 'Authorization': 'Bearer your_api_key' },
  });

  const { folders } = await res.json();
  console.log(folders);
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "folders": [
      {
        "id": "662f8c1d3a4b5e6f70123456",
        "name": "Summer Campaign",
        "type": "assets",
        "parent_folder_id": null,
        "created_at": "2026-06-19T10:00:00.000Z"
      },
      {
        "id": "662f8c1d3a4b5e6f70987654",
        "name": "Hero shots",
        "type": "assets",
        "parent_folder_id": "662f8c1d3a4b5e6f70123456",
        "created_at": "2026-06-19T10:05:00.000Z"
      }
    ]
  }
  ```
</ResponseExample>

## Notes

* Omitting `type` returns folders of every type; subfolders are identified by a non-null `parent_folder_id`.