Skip to main content
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.

​
Convertly HDAM

Convertly Storage is HDAM (Hybrid Digital Asset Management): a managed library for any file type with folders, tags, descriptions, and API access, combined with origin sources when assets stay on your site or bucket. Library files get Image CDN URLs by file id or slug, not by folder path. Move and reorganize freely without breaking embeds or cache keys. For the delivery model, URL shapes, and when to choose library vs origin, see Convertly HDAM.

​
API shape

Storage has two layers:
LayerEndpointsUse when
Stored filesGET /api/files, POST /api/files, PATCH /api/files/{id}, DELETE /api/files/{id}You want to browse, upload, rename, move, download, or delete files in Convertly Storage.
FoldersGET /api/folders, POST /api/folders, PATCH /api/folders/{id}, DELETE /api/folders/{id}You want to create a folder tree and list only the files or folders inside a parent.
Direct uploadsPOST /api/uploads, POST /api/uploads/completeYou want large files to upload directly to Convertly Storage with a signed upload URL or TUS resumable upload.
Bulk downloadPOST /api/files/zipBundle several stored files (or a whole folder) into one zip, tar, or tgz archive. Optionally save the archive back to Convertly Storage instead of downloading inline.
Process a stored filePOST /api/files/{id}/toolsRun any Media Tools operation against a file that already exists in Convertly Storage, without re-uploading the source bytes. The output is saved as a new stored file.
Library searchGET /api/files/searchFaceted search with tags, orientation, mime type, and facet counts. See Library metadata and search.
AI tagsPOST /api/files/{id}/ai-tagsOne-shot Forma AI tagging persisted on the file. See Library metadata and search.
Taxonomy/api/library/taxonomy/termsControlled vocabulary with synonyms and locales for tag normalization.
Root listing is explicit. Send folderId=null to GET /api/files or parentId=null to GET /api/folders when you only want root-level items. If you omit those parameters, Convertly treats the request as an account-wide list, which is useful for search and admin views.

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

​
WordPress site storage

WordPress connections use dedicated WordPress site tokens instead of standard account-wide API keys. This is the recommended agency setup because every client install gets its own storage boundary.
WordPress storage modeBehavior
No storageThe WordPress site can optimize uploads and run media tools, but it cannot browse, import, upload, or save Convertly Storage files.
Isolated storageThe WordPress site can use Convertly Storage only inside that site’s isolated scope. It cannot see the workspace’s general files or another client’s WordPress files.
Use one WordPress site token per production site. For agencies, choose No storage for optimization-only client installs and Isolated storage when a client needs its own Convertly asset area. Switching an existing WordPress site from Isolated storage to No storage blocks that site token from browsing, importing, uploading, or saving storage files. Existing isolated files remain scoped to that site and become available again only if storage is re-enabled. Revoke the WordPress site token when you want to remove the connection and delete the site’s isolated storage metadata and stored objects.

​
Shared folders from the main library

On top of isolated storage, you can share specific folders from your main workspace library with a WordPress site. Shared folders are useful for distributing brand assets, stock images, or other reusable media to client installs without exposing the rest of your library.
PermissionBehavior
Read-writeThe WordPress site can browse, import, and save files into the shared folder. Files saved by the plugin land in your main library next to the rest of the folder.
Read-onlyThe WordPress site can browse and import from the shared folder, but cannot save new files into it.
Sharing is recursive: subfolders of a shared folder are visible to the WordPress site automatically. Files imported into the WordPress Media Library stay there even after the folder is unshared. Manage shares from the Convertly dashboard at WordPress sites → site → Shared folders. Shared folders require the site token to be in Isolated storage mode. Any folder in Convertly Storage can be published as a read-only share link without exposing the rest of the workspace. The link recipient does not need a Convertly account. they get a hosted browser at convertly.sh/share/folder/{token} with preview, individual download, and a one-click zip of the whole folder. Share links are managed from the dashboard (right-click a folder → Share folder) and through an HTTP API for product integrations.
MethodEndpointUse
GET/api/folders/{id}/shareReturn the current active share for a folder, or null if none.
POST/api/folders/{id}/shareCreate a share link. Body: { "expiresInHours": "1" | "24" | "72" | "168" | "720" | "never" }. Default is 24.
DELETE/api/folders/{id}/shareRevoke the current share. The link returns “no longer available” after revocation.
The owner endpoints require an authenticated dashboard session. They are used by the dashboard share dialog and by integrations that run inside an authenticated browser context.

​
Read a shared folder

MethodEndpointUse
GET/api/share/folder/{token}Anonymous JSON listing. Returns the folder name, file metadata (filename, size, mime), per-file signed download URLs, and the share expiry.
GET/api/share/folder/{token}/zipStream the entire folder (including subfolders) as a single zip download.
Both reader endpoints are public and unauthenticated. They return the same "no longer available" response for revoked, expired, or unknown tokens so a leaked link cannot be distinguished from a never-issued one. Files imported through a share link continue to live in the owner’s Convertly Storage. sharing does not duplicate or copy bytes. Revoking the link immediately stops all reads.

​
Cloud connections (dashboard)

Connect cloud drives from Settings → Connections in the dashboard account menu. Connected accounts let you import files into Assets without downloading them to your laptop first.
ProviderWhat you can import
Google DriveFolders and files from the connected Google account. Also available through the Transfer API with cloudSource.
SharePoint & OneDrivePersonal OneDrive and SharePoint document libraries you can access with the linked Microsoft account. Browse and import from the Convert and Assets pickers in the dashboard.
SharePoint imports are dashboard-first today. Use Convert or Assets → import from cloud after connecting. Google Drive folder imports can also be automated with POST /api/transfer when the same account is connected.

​
File roles

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

​
Image CDN identifiers

Library assets in HDAM use direct CDN mapping. The URL path uses one of:
IdentifierRequired?Example path segment
File UUIDDefault (always available)11111111-1111-1111-1111-111111111111
CDN slugGenerated from filename; editablehero-summer, catalog-card-01
New uploads get readable slugs automatically. UUID URLs remain valid for every file, so you can remove a slug or keep using UUID-based integrations without breaking delivery. 
# Edit the generated slug (unique per workspace)
curl -X PATCH "https://convertly.sh/api/files/{id}" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "cdnSlug": "hero-summer" }'

# Remove a slug and use UUID-only URLs again
curl -X PATCH "https://convertly.sh/api/files/{id}" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "cdnSlug": null }'
Renaming the display filename does not change CDN URLs. Folders organize the file manager only; they are not part of library CDN URLs. Full URL composition (hostname, delivery alias, slug vs UUID, origin sources): URL structure.

​
Direct uploads

Use direct upload sessions for large files. Convertly returns a signed upload URL so file bytes go directly to Convertly 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
  }'
The response’s upload block contains a signedUrl and the HTTP method to use (a plain PUT of the file bytes). Some storage backends also return a resumable block with a TUS endpoint for chunked uploads of very large files. use it when present, otherwise do a single PUT to signedUrl. After the upload finishes, call POST /api/uploads/complete with the complete.body payload returned by the session endpoint. That payload already carries the storage details Convertly needs to register the file, so pass it through unchanged. The returned complete.url uses the request’s public forwarded hostname, so it remains callable behind a reverse proxy.

​
Folders

Folders are metadata records, not path prefixes. Files point at folders with folder_id, and folders point at parent folders with parent_id. Create a root folder: 
curl -X POST "https://convertly.sh/api/folders" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Client assets",
    "color": "#A855F7",
    "parentId": null
  }'
List root folders: 
curl "https://convertly.sh/api/folders?parentId=null" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY"
Move a folder by patching parentId. Use null to move it back to the root. Convertly rejects moves into the same folder or one of its descendants. 
curl -X PATCH "https://convertly.sh/api/folders/{folderId}" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parentId": "target-parent-folder-id"
  }'
Rename and move can be sent together: 
{
  "name": "Approved assets",
  "parentId": null
}

​
Folder snapshot backups

Convertly can take point-in-time ZIP, tar, or tgz snapshots of any folder in your asset library. Snapshots are stored in a dedicated Backups area in the dashboard (Assets → Backups) so they stay separate from day-to-day files. The Backups tab lists every source folder that has at least one snapshot; open a folder to browse its snapshot history, download copies, or delete old versions.

​
Manual backups

From Assets, open a folder and choose Back up folder (folder menu or toolbar). Convertly packages the folder asynchronously and saves the archive under Backups, mirroring the source folder name. A progress toast links to the snapshot when it finishes.

​
Scheduled snapshots

Each folder can have its own recurring schedule (daily, weekly, or monthly) with timezone, retention count, and retention days. Manage schedules from Folder menu → Schedule snapshots in Assets, or through the Archive API with POST /api/folder-archive-schedules. Due schedules run automatically; completed snapshots appear in Backups like manual backups.

​
Restore and download

Snapshots are normal stored archive files. Download any snapshot individually, select several for a bulk zip download, or delete versions you no longer need. Restoring means downloading a snapshot and re-uploading or extracting files into the folder you want — Convertly does not overwrite live Assets in place. Folder archive jobs, schedule fields, and API polling: Archive API — Folder archive jobs.

​
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 HDAM storage limit before saving uploads or outputs. Pro, Business, and Enterprise can continue past selected limits when overage billing is enabled. Allowances and overage rates: Limits.

​
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. See Limits. Adaptive video output uses the same storage meter. HLS/DASH manifests, renditions, captions, and posters are included in account storage usage, and deleting a video stream removes that packaged output from Convertly Storage.

Review plan limits

Storage, file size, batch size, concurrency, and overage behavior by plan.