> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Folders

> Create folders in your HeyGen workspace over the API and place generated videos and translations in them. Folders show up in the HeyGen web app.

<img className="w-full h-44 object-cover rounded-xl" src="https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-7.webp?fit=max&auto=format&n=hfMXXwJzjE7vBSYZ&q=85&s=02bcf90d74d8b9887ce224de6b8a130b" alt="" noZoom width="1400" height="788" data-path="images/theme/research-7.webp" />

Create a folder, then pass its `folder_id` when you generate. The output lands in that folder in the HeyGen web app.

| Endpoint | Scope |
| - | - |
| [`POST /v3/folders`](/reference/create-folder) | `videos:write` |
| [`GET /v3/folders/{folder_id}`](/reference/get-folder) | `videos:read` |

A key scoped only to `translations:write` can place translations in a folder, but cannot create or read one.

## Create a folder

```bash theme={null}
curl -X POST https://api.heygen.com/v3/folders \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: course-42-module-3" \
  -d '{
    "name": "Module 3 - Deploying to production",
    "parent_id": "a2b9e4c1d7f04e3a9c6b5d8e1f2a3b4c"
  }'
```

```json Response theme={null}
{
  "data": {
    "folder_id": "7c1f0b2e3d4a4f5e8a9b0c1d2e3f4a5b",
    "name": "Module 3 - Deploying to production",
    "parent_id": "a2b9e4c1d7f04e3a9c6b5d8e1f2a3b4c",
    "type": "mixed",
    "is_trash": false,
    "created_at": 1711929600,
    "updated_at": 1711929600,
    "creator_username": "e5f6a7b8c9d04e1f8a2b3c4d5e6f7a8b"
  }
}
```

| Field | Notes |
| - | - |
| `name` | Required, 1-256 characters. |
| `parent_id` | Folder to nest inside: must be in your workspace and not in the trash. Omit, `null`, or `""` for the workspace root, where the response has no `parent_id`. |
| `type` | `mixed` (default), `video`, or `video_translate`. All three accept videos and translations. |

## Put content in it

Pass `folder_id` on any of these:

* [`POST /v3/videos`](/reference/create-video)
* [`POST /v3/video-translations`](/reference/create-video-translation)
* [`POST /v3/video-translations/proofreads`](/reference/create-proofread-session)
* [`POST /v3/lipsyncs`](/reference/create-lipsync)
* [`POST /v3/templates/{template_id}`](/reference/generate-video-from-template)

```json theme={null}
{
  "type": "avatar",
  "avatar_id": "...",
  "script": "...",
  "folder_id": "7c1f0b2e3d4a4f5e8a9b0c1d2e3f4a5b"
}
```

The folder must be in your workspace, not in the trash, and writable by you. Otherwise the request returns `404` before anything is created.

## Check a folder

[`GET /v3/folders/{folder_id}`](/reference/get-folder) confirms a stored id still exists. Trashed folders return `is_trash: true`. Any other id (deleted, another workspace's, or not a folder) returns `404`.

<Tip>
  Folder names can repeat, and the API never matches by name. Store the ids you get back, and send an `Idempotency-Key` so a retry returns the same folder.
</Tip>