Skip to main content

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.

The Transfer API moves external files into Convertly. Use it to fetch a public URL, store a ZIP archive as files, or import a folder from Google Drive, S3, or Dropbox. For production workloads, prefer destination: "convertly-storage". Convertly can store the result, return signed download URLs, preserve extracted ZIP paths as folders, and keep large imports away from your app server. Single-file URL transfers into Convertly Storage are asynchronous by default. The request creates a transfer job and returns 202 Accepted with a jobId; poll GET /api/jobs/{jobId} or subscribe to job updates to read the stored file result when it completes.

​
Public URL transfer

curl -X POST "https://convertly.sh/api/transfer" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceUrl": "https://example.com/assets/product-photo.png",
    "destination": "convertly-storage",
    "filename": "product-photo.png"
  }'
The response is queued: 
{
  "jobId": "job_123",
  "status": "pending",
  "mode": "async"
}
When the job completes, GET /api/jobs/job_123 includes the stored file metadata and signed download URL in results. destination: "download" returns the fetched file as the response body. destination: "convertly-storage" stores the file asynchronously by default. Set "async": false only for small request/response workflows where you explicitly want the API request to wait for storage.

​
ZIP transfer and extract

Set extract: true to download a ZIP archive, extract it, and save each entry into Convertly Storage. 
curl -X POST "https://convertly.sh/api/transfer" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceUrl": "https://example.com/client-assets.zip",
    "destination": "convertly-storage",
    "extract": true,
    "extractOptions": {
      "folderName": "Client assets",
      "preservePaths": true,
      "maxFiles": 500
    }
  }'
Convertly creates a folder, preserves ZIP subfolders by default, stores each extracted file, and returns the stored file records.

​
Cloud folder import

Use cloudSource instead of sourceUrl to import files from a provider API.

​
Google Drive

Google Drive imports use the Google Drive account connected in the Convertly dashboard. 
{
  "destination": "convertly-storage",
  "cloudSource": {
    "provider": "google-drive",
    "folderId": "1abcDriveFolderId",
    "recursive": true
  }
}
Use fileId instead of folderId to import a single Google Drive file.

​
S3

S3 imports use request-scoped credentials. The credentials are used for the import request and are not stored. 
{
  "destination": "convertly-storage",
  "cloudSource": {
    "provider": "s3",
    "bucket": "product-assets",
    "prefix": "spring-catalog/",
    "region": "us-east-1",
    "accessKeyId": "AKIA...",
    "secretAccessKey": "...",
    "recursive": true
  }
}
Use key instead of prefix to import one S3 object.

​
Dropbox

Dropbox imports use a request-scoped Dropbox access token. 
{
  "destination": "convertly-storage",
  "cloudSource": {
    "provider": "dropbox",
    "path": "/Client Assets",
    "accessToken": "sl...",
    "recursive": true
  }
}

​
Request fields

FieldTypeDescription
sourceUrlstringPublic http or https URL. Use this or cloudSource, not both.
cloudSourceobjectProvider import configuration for Google Drive, S3, or Dropbox.
destinationstringdownload or convertly-storage. Cloud and extract transfers require storage.
filenamestringOptional filename for public URL transfers.
contentTypestringOptional content type override.
asyncbooleanFor single-file URL transfers into Convertly Storage, queue the transfer as a background job. Defaults to true.
extractbooleanExtract a ZIP archive into Convertly Storage.
extractOptions.preservePathsbooleanPreserve ZIP subfolders. Defaults to true.
extractOptions.folderNamestringName of the root folder created in Convertly Storage.
extractOptions.targetFolderIdstringParent Convertly folder for extracted or imported files.
extractOptions.maxFilesnumberMaximum extracted files. Defaults to 500.
extractOptions.maxEntryBytesnumberMaximum extracted size for one ZIP entry.
extractOptions.maxTotalBytesnumberMaximum total extracted size.

​
Response

Queued storage transfers return a job envelope. Completed transfer jobs expose the stored file in the job results. Synchronous storage transfers, ZIP extraction, and cloud folder imports return stored file or folder metadata immediately. 
{
  "folder": {
    "id": "folder_123",
    "name": "Client assets"
  },
  "files": [
    {
      "id": "file_123",
      "filename": "hero.webp",
      "mimeType": "image/webp",
      "sizeBytes": 482391,
      "storagePath": "user-id/uploaded/...",
      "downloadUrl": "https://..."
    }
  ],
  "usage": {
    "processedTransferBytes": 964782,
    "pricingBucket": "processed_transfer"
  }
}

​
Pricing

Transfer API usage counts against monthly processed transfer. Convertly meters source read plus destination write, so a 100 MB file stored in Convertly counts as about 200 MB of processed transfer. ZIP extraction counts the archive download plus extracted bytes written to storage. Stored files count toward your Convertly Storage quota. Storage overage is billed on monthly peak overage growth.

​
Safety and scaling

Convertly blocks localhost, private-network, and non-HTTP source URLs. ZIP extraction rejects path traversal, skips directory entries, and enforces file-count and extracted-size limits. Single-file URL-to-storage transfers run in the background worker. Convertly streams the remote response to temporary disk, then streams the file into object storage instead of buffering the whole file in the web request. The archive path is designed to avoid loading the entire ZIP into memory: Convertly downloads the archive to temporary disk, then extracts entries one at a time. Cloud imports process files sequentially and cap imports at 500 files per request.