> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convertly.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Download or save multiple stored files as a single archive

> Bundle a set of stored files into a zip, tar, or tgz archive. Pass `fileIds` for explicit selection, `folderId` to archive a folder (with `recursive: true` to include subfolders), or omit both to grab root-level files. Set `saveToFiles: true` and an optional `targetFolderId` to drop the archive back into Convertly Storage instead of returning the bytes inline.



## OpenAPI

````yaml /openapi.json post /api/files/zip
openapi: 3.1.0
info:
  title: Convertly API
  version: 1.0.0
  description: >-
    Convertly provides production API endpoints for media conversion,
    compression, Image CDN delivery, Forma AI, HLS/DASH video streaming, media
    tools, async jobs, workflows, webhooks, and Convertly Storage.
  license:
    name: Proprietary
    url: https://convertly.sh/terms
servers:
  - url: https://convertly.sh
security:
  - bearerAuth: []
  - apiKeyAuth: []
paths:
  /api/files/zip:
    post:
      tags:
        - Files
      summary: Download or save multiple stored files as a single archive
      description: >-
        Bundle a set of stored files into a zip, tar, or tgz archive. Pass
        `fileIds` for explicit selection, `folderId` to archive a folder (with
        `recursive: true` to include subfolders), or omit both to grab
        root-level files. Set `saveToFiles: true` and an optional
        `targetFolderId` to drop the archive back into Convertly Storage instead
        of returning the bytes inline.
      operationId: createArchiveFromStoredFiles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ZipRequest'
      responses:
        '200':
          description: >-
            Archive bytes streamed as application/zip, application/x-tar, or
            application/gzip. When `saveToFiles=true` the response is JSON with
            the new stored file instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoredFileResponse'
            application/zip:
              schema:
                type: string
                format: binary
            application/x-tar:
              schema:
                type: string
                format: binary
            application/gzip:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
components:
  schemas:
    ZipRequest:
      type: object
      description: >-
        Provide exactly one of `fileIds` or `folderId`. Omit both to archive the
        account's root-level files.
      properties:
        fileIds:
          type: array
          items:
            type: string
            format: uuid
          description: Explicit list of stored file IDs to include.
        folderId:
          type:
            - string
            - 'null'
          format: uuid
          description: Archive every file in this folder.
        recursive:
          type: boolean
          default: true
          description: >-
            Used with `folderId`. When true, includes files in subfolders; the
            archive preserves the folder structure.
        format:
          type: string
          enum:
            - zip
            - tar
            - tgz
          default: zip
        saveToFiles:
          type: boolean
          default: false
          description: >-
            When true, save the archive back to Convertly Storage and return
            JSON. When false, stream the archive bytes inline.
        targetFolderId:
          type:
            - string
            - 'null'
          format: uuid
          description: Where to save the archive when `saveToFiles=true`. Defaults to root.
    StoredFileResponse:
      type: object
      properties:
        file:
          $ref: '#/components/schemas/StoredFile'
      required:
        - file
    StoredFile:
      type: object
      properties:
        id:
          type: string
          format: uuid
        filename:
          type: string
        mime_type:
          type: string
        size_bytes:
          type: integer
        folder_id:
          type:
            - string
            - 'null'
          format: uuid
        created_at:
          type: string
          format: date-time
        downloadUrl:
          type:
            - string
            - 'null'
          format: uri
      required:
        - id
        - filename
        - mime_type
        - size_bytes
        - created_at
    Error:
      type: object
      properties:
        error:
          type: string
        upgradeUrl:
          type: string
      required:
        - error
  responses:
    Error:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Dashboard-generated Convertly API key. Keys currently begin with
        `cvly_`.
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Alternative API key header for server-side clients.

````