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



## 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
    description: >-
      Create videos from a prompt or an avatar, then list, fetch, deliver and
      delete them
  - name: Avatar
    description: >-
      Create avatars and looks, record consent, and generate with the Avatar 6
      model
  - name: Voice
    description: Text to speech, speech to speech, and voice cloning
  - name: Audio
    description: Music, sound effects, transcription, stem separation and audio analysis
  - name: Image
    description: Generate images
  - name: Video editing
    description: >-
      Translate, lipsync, clip, analyze and remove filler words or backgrounds
      from existing videos
  - name: Video Agent
    description: Create videos from a prompt with an agent that plans, writes and edits
  - name: Templates
    description: Generate videos from reusable templates by replacing their variables
  - name: HyperFrames
    description: Render HyperFrames compositions into video
  - name: Brand
    description: >-
      Brand kits (colors, fonts, logos) and brand glossaries (term translations
      and pronunciations)
  - name: Assets and folders
    description: Upload files and organize them in folders
  - name: Batches
    description: Submit and track videos, translations, lipsyncs and uploads in bulk
  - name: Webhooks
    description: Manage webhook endpoints and events
  - name: Feedback
    description: Tell HeyGen how a generated result turned out
  - name: Account and usage
    description: Your account, the current API key, request logs and usage
paths:
  /v3/folders:
    post:
      tags:
        - Assets and folders
      summary: Create Folder
      description: >-
        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.
      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, of a kind this endpoint creates,
            that is not in the trash. Assets library folders are flat and cannot
            hold folders.
          examples:
            - 7c1f0b2e3d4a4f5e8a9b0c1d2e3f4a5b
          title: Parent Id
        type:
          $ref: '#/components/schemas/CreatableFolderTypeV3'
          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. Folders the Assets library creates have kind 'asset'; they
            cannot be created or nested under here. Every kind is accepted as a
            folder_id destination on POST /v3/videos, POST
            /v3/video-translations and the other routes that take one, but the
            HeyGen app files only assets in an 'asset' folder, so a render
            placed in one may not appear in the Assets library view.
      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. A folder of type 'mixed', 'video' or
            'video_translate' may also be passed as parent_id to POST
            /v3/folders; 'asset' folders are flat.
          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'
        request_id:
          type: string
          description: >-
            Request identifier, also returned in the X-HeyGen-Request-Id
            response header. Include it when contacting support.
          example: 8c4f0b9e1d2a4f6b9e3c7a1d5f2b8e40
      required:
        - code
        - message
    CreatableFolderTypeV3:
      description: >-
        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}.
      enum:
        - mixed
        - video
        - video_translate
      title: CreatableFolderTypeV3
      type: string
    FolderTypeV3:
      description: >-
        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.
      enum:
        - mixed
        - video
        - video_translate
        - asset
      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.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.