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

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

Video Translation

Lipsync

Tools

Avatar Management

Voice Management

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