Create Folder

Creates a folder in the caller’s workspace, at the root or inside another folder, and returns it. Pass the returned folder_id as folder_id to POST /v3/videos or POST /v3/video-translations to place the output in it, or as parent_id to this endpoint to nest another folder. Folders and their contents are visible in the HeyGen web app. Sibling folders may share a name; this endpoint never looks up an existing folder by name, so store the ids you receive rather than recreating a tree on retry, and send an Idempotency-Key so a retried request returns the folder the first attempt created.

POST /v3/folders

Create Folder

cURL

curl --request POST \
  --url https://api.heygen.com/v3/folders \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "Module 3 - Deploying to production",
  "parent_id": "7c1f0b2e3d4a4f5e8a9b0c1d2e3f4a5b",
  "type": "mixed"
}
'

201

{
  "data": {
    "folder_id": "<string>",
    "name": "<string>",
    "type": "mixed",
    "is_trash": true,
    "created_at": 1711929600,
    "updated_at": 1711929600,
    "parent_id": "<string>",
    "creator_username": "<string>"
  }
}

Authorizations

ApiKeyAuthBearerAuth

x-api-key · string · header · required

HeyGen API key. Obtain from your HeyGen dashboard.

Headers

Idempotency-Key · string

Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent.

Required string length: 1 - 255

Pattern: ^[A-Za-z0-9_\-:.]{1,255}$

Body

application/json

Request body for POST /v3/folders.

name · string · required

Folder name, 1-256 characters. Sibling folders may share a name.

Required string length: 1 - 256

Example:

"Module 3 - Deploying to production"

parent_id · string | null

ID of the folder to create this one in. Omit, pass null, or pass an empty string to create it at the workspace root. The parent must be a folder in the caller's workspace that is not in the trash.

Maximum string length: 64

Example:

"7c1f0b2e3d4a4f5e8a9b0c1d2e3f4a5b"

type · enum<string> · default: mixed

Kind of folder. 'mixed' is what the HeyGen web app's New folder action creates; 'video_translate' is what the Video Translate page creates. The web app lists all three kinds together in its folder views, and every kind accepts videos and translations placed with folder_id on POST /v3/videos and POST /v3/video-translations.

Available options: mixed, video, video_translate

Response

201

application/json

Created.

data · FolderV3 · object

A folder in the caller's workspace.

Show child attributes