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

# Get Folder

> Returns one folder in your workspace, including one in the trash (`is_trash`). Use it to check that a stored `folder_id` still exists. Deleted folders and folders in other workspaces return 404.



## OpenAPI

````yaml /openapi/external-api.json get /v3/folders/{folder_id}
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/{folder_id}:
    get:
      tags:
        - Assets and folders
      summary: Get Folder
      description: >-
        Returns one folder in your workspace, including one in the trash
        (`is_trash`). Use it to check that a stored `folder_id` still exists.
        Deleted folders and folders in other workspaces return 404.
      operationId: getFolderV3
      parameters:
        - name: folder_id
          in: path
          required: true
          schema:
            type: string
          description: Unique folder identifier
      responses:
        '200':
          description: Successful response
          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'
        '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
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: resource_not_found
                  message: >-
                    Folder 7c1f0b2e3d4a4f5e8a9b0c1d2e3f4a5b not found in this
                    workspace.
                  param: folder_id
                  doc_url: null
        '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:
  schemas:
    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
    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
  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.