> ## 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. # Files and Storage > Convertly HDAM storage: uploads, folders, metadata, and optional persistence for dashboard and API workflows. 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](/docs/image-cdn/url-structure#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](/docs/image-cdn/hdam-storage). ## API shape Storage has two layers: | Layer | Endpoints | Use when | | --------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Stored files | `GET /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. | | Folders | `GET /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 uploads | `POST /api/uploads`, `POST /api/uploads/complete` | You want large files to upload directly to Convertly Storage with a signed upload URL or TUS resumable upload. | | Bulk download | `POST /api/files/zip` | Bundle 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 file | `POST /api/files/{id}/tools` | Run any [Media Tools](/docs/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 search | `GET /api/files/search` | Faceted search with tags, orientation, mime type, and facet counts. See [Library metadata and search](/docs/library-metadata). | | AI tags | `POST /api/files/{id}/ai-tags` | One-shot Forma AI tagging persisted on the file. See [Library metadata and search](/docs/library-metadata#ai-auto-tagging-sdk-one-liner). | | Taxonomy | `/api/library/taxonomy/terms` | Controlled 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 | Workflow | Default behavior | | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | Dashboard conversion | Saves 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/uploads` | Creates a direct-to-storage upload session with signed upload and TUS resumable details. | | `POST /api/uploads/complete` | Records a completed direct upload in Convertly Storage metadata. | | `POST /api/convert` and `POST /api/compress` with an API key | Storage is off by default. Add `saveToStorage=true` only when you explicitly want Convertly to persist uploaded and generated files. | | Async jobs through `POST /api/jobs` | Jobs are storage-backed because workers need persisted source files. API-key requests must explicitly send `saveToStorage=true`. | | Anonymous conversion | Does 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 mode | Behavior | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | No storage | The WordPress site can optimize uploads and run media tools, but it cannot browse, import, upload, or save Convertly Storage files. | | Isolated storage | The 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. | Permission | Behavior | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Read-write | The 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-only | The 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. ## Public share links 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. ### Manage a share link | Method | Endpoint | Use | | -------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `GET` | `/api/folders/{id}/share` | Return the current active share for a folder, or `null` if none. | | `POST` | `/api/folders/{id}/share` | Create a share link. Body: `{ "expiresInHours": "1" \| "24" \| "72" \| "168" \| "720" \| "never" }`. Default is `24`. | | `DELETE` | `/api/folders/{id}/share` | Revoke 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 | Method | Endpoint | Use | | ------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `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}/zip` | Stream 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. | Provider | What you can import | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Google Drive** | Folders and files from the connected Google account. Also available through the [Transfer API](/docs/transfer-api#google-drive) with `cloudSource`. | | **SharePoint & OneDrive** | Personal 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 | Role | Description | | ----------- | -------------------------------------------------------------------------- | | `uploaded` | The original file accepted by Convertly before processing. | | `converted` | A 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: | Identifier | Required? | Example path segment | | ------------- | --------------------------------- | -------------------------------------- | | **File UUID** | Default (always available) | `11111111-1111-1111-1111-111111111111` | | **CDN slug** | Generated from filename; editable | `hero-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. ```bash theme={"system"} # 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](/docs/image-cdn/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. ```bash theme={"system"} 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: ```bash theme={"system"} 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: ```bash theme={"system"} 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. ```bash theme={"system"} 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: ```json theme={"system"} { "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](/docs/archive-api#scheduled-folder-snapshots) 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](/docs/archive-api#folder-archive-jobs-storage). ## 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](/limits#file-and-storage-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: ```json theme={"system"} { "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](/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. Storage, file size, batch size, concurrency, and overage behavior by plan.