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.

Convertly can store uploads and generated outputs, but storage is not required for every media conversion. Use storage when you want files to appear in the Convertly file manager, keep stored file IDs, or process async jobs. Leave it off when your product only needs immediate download URLs.

​
Storage defaults

WorkflowDefault behavior
Dashboard conversionSaves files when storage is available. If the account is full, Convertly still converts and shows a notice that the files were not saved.
POST /api/uploadsCreates a direct-to-storage upload session with signed upload and TUS resumable details.
POST /api/uploads/completeRecords a completed direct upload in Convertly Storage metadata.
POST /api/convert and POST /api/compress with an API keyStorage is off by default. Add saveToStorage=true only when you explicitly want Convertly to persist uploaded and generated files.
Async jobs through POST /api/jobsJobs are storage-backed because workers need persisted source files. API-key requests must explicitly send saveToStorage=true.
Anonymous conversionDoes not create stored file records.

​
File roles

RoleDescription
uploadedThe original file accepted by Convertly before processing.
convertedA generated output file, compressed file, or archive created by Convertly.

​
Direct and Resumable Uploads

Use direct upload sessions for large files. Convertly returns a signed upload URL and a TUS configuration, so file bytes go directly to object storage instead of through Convertly’s web process. 
curl -X POST "https://convertly.sh/api/uploads" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "launch-video.mp4",
    "contentType": "video/mp4",
    "sizeBytes": 734003200,
    "resumable": true
  }'
After the direct or TUS upload finishes, call POST /api/uploads/complete with the complete.body payload returned by the session endpoint.

​
Download URLs

Synchronous conversion responses include a downloadUrl. When storage is off, this is returned as a direct data URL for immediate download or handoff to your product. When storage is enabled and the file is saved, Convertly returns a temporary signed storage URL and a storedFileId.

​
Storage limits

Storage is plan-aware. Convertly checks whether a request would exceed the user’s storage limit before saving uploads or outputs. Pro, Business, and Enterprise tiers can continue past selected limits when overage billing is enabled.

​
What happens at the limit

Synchronous dashboard and API conversions still complete when storage is full. The response includes converted files as download URLs, and Convertly reports that the files were not saved: 
{
  "files": [],
  "storage": {
    "saved": false,
    "notice": "Storage limit reached. Your conversion completed, but files were not saved to Convertly storage."
  }
}
Async jobs are different: they require persisted source files so the background worker can process them. If an API customer wants no persisted files, use POST /api/convert or POST /api/compress without saveToStorage=true. For Pro, Business, and Enterprise plans, overage billing can allow selected storage overages when enabled. If overage is not enabled, stored workflows should delete files, upgrade, or increase storage before continuing.

Review plan limits

See storage, file size, batch size, concurrency, and currency request limits.