---
title: "Create Folder"
method: POST
path: "/v3/folders"
tags: ["Folders"]
---

# Create Folder

`POST /v3/folders`

## Request

- Base URL: `https://api.heygen.com`
- URL: `https://api.heygen.com/v3/folders`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Creates a folder at the root or inside `parent_id`. Pass its `folder_id` to POST /v3/videos or POST /v3/video-translations to file output there. Names need not be unique, so store the ids you receive. Send an Idempotency-Key to make retries safe.

## Headers

- `Idempotency-Key` string

## Request body

- CreateFolderV3Request: Request body for POST /v3/folders.
  - `name` string, required: Folder name, 1-256 characters. Sibling folders may share a name.
  - `parent_id` string, nullable: 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, of a kind this endpoint creates, that is not in the trash. Assets library folders are flat and cannot hold folders.
  - `type` 'mixed' | 'video' | 'video_translate': The kinds POST /v3/folders creates, and the kinds a parent_id may name. Assets library folders ('asset') are created in the HeyGen app; existing ones are accepted as a folder_id destination and returned by GET /v3/folders/{folder_id}.

## Response `201`

Created.

- object
  - `data` FolderV3: A folder in the caller's workspace.
    - `folder_id` string, required: Unique folder identifier. Pass as folder_id to POST /v3/videos or POST /v3/video-translations. A folder of type 'mixed', 'video' or 'video_translate' may also be passed as parent_id to POST /v3/folders; 'asset' folders are flat.
    - `name` string, required: Folder name.
    - `parent_id` string, nullable: ID of the containing folder. Absent for a folder at the workspace root.
    - `type` 'mixed' | 'video' | 'video_translate' | 'asset', required: The kinds of folder this API knows: what GET returns and what a folder_id destination may name. These are the kinds the HeyGen app's New folder actions create. Brand kits and batch parents are not folders, so an id that resolves to one is reported as not found. Only 'mixed', 'video' and 'video_translate' folders may be a parent_id; 'asset' folders are flat.
    - `is_trash` boolean, required: Whether the folder is in the trash.
    - `created_at` integer, required: Unix timestamp (seconds) when the folder was created.
    - `updated_at` integer, required: Unix timestamp (seconds) when the folder was last updated.
    - `creator_username` string, nullable: Username of the workspace member who created the folder.

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication failed
- `403`: Forbidden
- `404`: Resource not found
- `409`: A prior request with this Idempotency-Key is still in progress. Wait for the original request to complete, then retry.
- `429`: Rate limit exceeded

## Changes

- **2026-11-03** `7dfa5e59b4f5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/heygen/apis/heygen-external-api/changes/v3/folders/post.md)

---

[API](https://skmtc.dev/heygen/apis/heygen-external-api.md) - [All operations](https://skmtc.dev/heygen/apis/heygen-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/heygen/apis/heygen-external-api/revisions/7dfa5e59b4f5?raw)