> ## Documentation Index > Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi/external-api.json post /v3/folders openapi: 3.1.0 info: title: HeyGen External API version: 1.0.0 description: >- HeyGen's external API for programmatic AI video creation. See https://docs.heygen.com for full documentation. contact: name: HeyGen Product Infra url: https://heygen.com servers: - url: https://api.heygen.com description: Production security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: Video Agent description: Create videos from text prompts using AI - name: Videos description: Create, list, retrieve, and delete videos - name: Templates description: Generate videos from reusable templates by replacing their variables - name: Voices description: Text-to-speech and voice management - name: Audio description: Search the background-music and sound-effects catalog - name: Video Translate description: Translate videos into other languages - name: AI Clipping description: Turn long-form videos into ready-to-share short clips with captions - name: Batches description: Create and track batches of videos. - name: Video Translation Batches description: Create and track batches of video translations. - name: Lipsync Batches description: Create and track batches of lipsyncs. - name: Asset Batches description: Create and track batches of direct-to-S3 asset uploads. - name: User description: Account information and billing - name: API Keys description: Inspect the API key authenticating the current request - name: Avatars description: List and manage avatars and looks - name: Assets description: Upload files for use in video creation - name: Folders description: Create folders to organize videos and translations in the workspace - name: Webhooks description: Manage webhook endpoints and events - name: Lipsync description: Dub or replace audio on existing videos - name: Brand description: >- Brand-related resources — brand kits (colors, fonts, logos) and brand glossaries (custom term translations) - name: HyperFrames description: Render HyperFrames composition zips into video — separate from /v3/videos - name: Models description: '' - name: Filler Word Removal description: '' paths: /v3/folders: post: tags: - Folders summary: Create Folder description: >- 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. operationId: createFolderV3 parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateFolderV3Request' responses: '201': description: Created. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/FolderV3' '400': description: Invalid request parameters content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: invalid_parameter message: '''name'' must be between 1 and 256 characters.' param: name doc_url: null '401': description: Authentication failed content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: unauthorized message: Invalid or expired API key. Verify your x-api-key header. param: null doc_url: null '403': description: Forbidden content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: resource_access_denied message: You do not have write access to the parent folder. param: null doc_url: null '404': description: Resource not found content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: resource_not_found message: Parent folder not found. param: null doc_url: null '409': $ref: '#/components/responses/IdempotencyInProgress' '429': description: Rate limit exceeded content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: rate_limit_exceeded message: >- Too many requests. Retry after the duration specified in the Retry-After header. param: null doc_url: null headers: Retry-After: description: Seconds to wait before retrying schema: type: integer security: - ApiKeyAuth: [] - BearerAuth: [] components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- 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. schema: type: string pattern: ^[A-Za-z0-9_\-:.]{1,255}$ maxLength: 255 minLength: 1 example: 550e8400-e29b-41d4-a716-446655440000 schemas: CreateFolderV3Request: additionalProperties: false description: Request body for POST /v3/folders. properties: name: description: Folder name, 1-256 characters. Sibling folders may share a name. examples: - Module 3 - Deploying to production maxLength: 256 minLength: 1 title: Name type: string parent_id: anyOf: - maxLength: 64 type: string - type: 'null' default: null description: >- 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. examples: - 7c1f0b2e3d4a4f5e8a9b0c1d2e3f4a5b title: Parent Id type: $ref: '#/components/schemas/FolderTypeV3' default: mixed description: >- 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. required: - name title: CreateFolderV3Request type: object FolderV3: description: A folder in the caller's workspace. properties: folder_id: description: >- Unique folder identifier. Pass as folder_id to POST /v3/videos or POST /v3/video-translations, or as parent_id to POST /v3/folders. title: Folder Id type: string name: description: Folder name. title: Name type: string parent_id: anyOf: - type: string - type: 'null' default: null description: >- ID of the containing folder. Absent for a folder at the workspace root. title: Parent Id type: $ref: '#/components/schemas/FolderTypeV3' description: Kind of folder; see the type field of POST /v3/folders. is_trash: description: Whether the folder is in the trash. title: Is Trash type: boolean created_at: description: Unix timestamp (seconds) when the folder was created. examples: - 1711929600 title: Created At type: integer updated_at: description: Unix timestamp (seconds) when the folder was last updated. examples: - 1711929600 title: Updated At type: integer creator_username: anyOf: - type: string - type: 'null' default: null description: Username of the workspace member who created the folder. title: Creator Username required: - folder_id - name - type - is_trash - created_at - updated_at title: FolderV3 type: object StandardAPIError: type: object properties: code: type: string description: Machine-readable error code example: invalid_parameter message: type: string description: Human-readable error message example: Video not found param: type: - string - 'null' description: Which request field caused the error doc_url: type: - string - 'null' description: Link to error documentation errors: type: array description: >- Per-item error details for batch/multi-node failures (e.g. graph compilation errors by node). items: $ref: '#/components/schemas/StandardAPIErrorDetail' required: - code - message FolderTypeV3: description: >- The kinds of folder a caller can create. These are the non-batch folder kinds the web app itself creates. Batch parents and brand kits also live in the same table but are not folders a caller organizes content into, so they are not offered here. enum: - mixed - video - video_translate title: FolderTypeV3 type: string StandardAPIErrorDetail: type: object properties: code: type: string description: Machine-readable error code example: unknown_node_type message: type: string description: Human-readable error message example: Unknown node type node_id: type: string description: Graph node id this error pertains to, if applicable port: type: string description: Port name on the node this error pertains to, if applicable path: type: string description: Field path within the item this error pertains to, if applicable required: - code - message responses: IdempotencyInProgress: description: >- A prior request with this Idempotency-Key is still in progress. Wait for the original request to complete, then retry. content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: request_in_progress message: >- A request with this Idempotency-Key is already in progress. Retry shortly. param: null doc_url: null securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: HeyGen API key. Obtain from your HeyGen dashboard. BearerAuth: type: http scheme: bearer description: OAuth2 bearer token. ````