Folders

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`	`videos:write`
`GET /v3/folders/{folder_id}`	`videos:read`

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

Create a folder

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"
  }'

Response

{
  "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. 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:

{
  "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. 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} 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.

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.

Auth

User Info

Models

Video Generation

Video Composition

On Brand

Realtime Video

Avatar Management

Voice Management

Video Translation

Lipsync

Tools

Asset Management

Batches

Webhook

Limits

Socials

For Agents

Integrations

Create a folder

Put content in it

Check a folder

​Create a folder

​Put content in it

​Check a folder

Create a folder

Put content in it

Check a folder