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

# Transfer a remote file

> Fetch a public HTTP(S) file URL and return it directly or save it to Convertly Storage. Single-file URL-to-storage transfers are queued asynchronously by default. Usage counts against processed transfer.



## OpenAPI

````yaml /openapi.json post /api/transfer
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/transfer:
    post:
      tags:
        - Media
      summary: Transfer a remote file
      description: >-
        Fetch a public HTTP(S) file URL and return it directly or save it to
        Convertly Storage. Single-file URL-to-storage transfers are queued
        asynchronously by default. Usage counts against processed transfer.
      operationId: transferFile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferRequest'
      responses:
        '200':
          description: Transferred file bytes or Convertly Storage metadata
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                $ref: '#/components/schemas/TransferStorageResponse'
        '202':
          description: Transfer job queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncJobAccepted'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '402':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '413':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
components:
  schemas:
    TransferRequest:
      type: object
      description: Provide exactly one of sourceUrl or cloudSource.
      properties:
        sourceUrl:
          type: string
          format: uri
          description: >-
            Public HTTP(S) file URL. Localhost and private network targets are
            blocked.
        destination:
          type: string
          enum:
            - download
            - convertly-storage
          default: download
        filename:
          type: string
          maxLength: 180
        contentType:
          type: string
          maxLength: 120
        async:
          type: boolean
          default: true
          description: >-
            Queue single-file URL transfers into Convertly Storage as background
            jobs. Set false only for small synchronous storage requests.
        extract:
          type: boolean
          default: false
          description: Extract a ZIP archive into Convertly Storage.
        extractOptions:
          type: object
          properties:
            preservePaths:
              type: boolean
              default: true
            folderName:
              type: string
            targetFolderId:
              type:
                - string
                - 'null'
              format: uuid
            maxFiles:
              type: integer
              default: 500
            maxEntryBytes:
              type: integer
            maxTotalBytes:
              type: integer
        cloudSource:
          type: object
          properties:
            provider:
              type: string
              enum:
                - google-drive
                - s3
                - dropbox
            fileId:
              type: string
            folderId:
              type: string
            bucket:
              type: string
            key:
              type: string
            prefix:
              type: string
            region:
              type: string
            endpoint:
              type: string
              format: uri
            accessKeyId:
              type: string
            secretAccessKey:
              type: string
              writeOnly: true
            sessionToken:
              type: string
              writeOnly: true
            accessToken:
              type: string
              writeOnly: true
            path:
              type: string
            recursive:
              type: boolean
              default: true
            targetFolderId:
              type:
                - string
                - 'null'
              format: uuid
          required:
            - provider
    TransferStorageResponse:
      type: object
      properties:
        folder:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
        file:
          type: object
          properties:
            id:
              type:
                - string
                - 'null'
            filename:
              type: string
            mimeType:
              type: string
            sizeBytes:
              type: integer
            storagePath:
              type: string
            downloadUrl:
              type:
                - string
                - 'null'
        files:
          type: array
          items:
            type: object
            properties:
              id:
                type:
                  - string
                  - 'null'
              filename:
                type: string
              mimeType:
                type: string
              sizeBytes:
                type: integer
              storagePath:
                type: string
              downloadUrl:
                type:
                  - string
                  - 'null'
        extracted:
          type: object
          properties:
            fileCount:
              type: integer
            archiveBytes:
              type: integer
            extractedBytes:
              type: integer
        imported:
          type: object
          properties:
            fileCount:
              type: integer
        usage:
          type: object
          properties:
            processedTransferBytes:
              type: integer
            pricingBucket:
              type: string
              enum:
                - processed_transfer
    AsyncJobAccepted:
      type: object
      properties:
        jobId:
          type: string
        status:
          type: string
          enum:
            - pending
        mode:
          type: string
          enum:
            - async
        message:
          type: string
      required:
        - jobId
        - status
        - mode
    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.

````