> ## Documentation Index
> Fetch the complete documentation index at: https://developers.heygen.com/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.

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-7.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=02bcf90d74d8b9887ce224de6b8a130b)

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`](https://developers.heygen.com/reference/create-folder) | `videos:write` |
| [`GET /v3/folders/{folder_id}`](https://developers.heygen.com/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"
  }'
```

The response returns the new `folder_id` along with its `name`, `parent_id`, `type`, `is_trash` and timestamps ([reference](https://developers.heygen.com/reference/create-folder.md)).

| Field | Notes |
| - | - |
| `name` | Required, 1-256 characters. |
| `parent_id` | Folder to nest inside: must be in your workspace and not in the trash. Assets library folders (`type: "asset"`) can't be a parent, since they don't hold other folders. 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`](https://developers.heygen.com/reference/create-video)
* [`POST /v3/video-translations`](https://developers.heygen.com/reference/create-video-translation)
* [`POST /v3/video-translations/proofreads`](https://developers.heygen.com/reference/create-proofread-session)
* [`POST /v3/lipsyncs`](https://developers.heygen.com/reference/create-lipsync)
* [`POST /v3/templates/{template_id}`](https://developers.heygen.com/reference/generate-video-from-template)

```json theme={null}
{
  "type": "avatar",
  "avatar_id": "...",
  "engine": { "type": "heygen-avatar-6" },
  "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.

Existing folders from the HeyGen app's Assets library are also accepted as a `folder_id`, and come back from `GET /v3/folders/{folder_id}` with `type: "asset"`. The Assets library view lists only assets, so a video or translation placed there may not show up in it. `POST /v3/folders` cannot create these folders, and they cannot hold other folders, so they are never a valid `parent_id`.

## Check a folder

[`GET /v3/folders/{folder_id}`](https://developers.heygen.com/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.


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