Collections API guide
Last updated: Nov-18-2026
A collection groups assets from anywhere in your product environment so you can review them, hand them off, or share them, without moving the assets or changing their delivery URLs. The Collections API does everything the Media Library's Collections page does, so the systems you already run (a PIM, a CMS, a workflow tool, or an agent) can build and share collections on their own.
A typical automated flow: assets land in Cloudinary from your upload pipeline, your code adds them to a campaign collection, your creative team reviews and prepares them from inside their own tooling, and when the campaign is approved you publish the collection as a branded public page that expires on the launch date.
- For every endpoint, parameter, and response field, see the Collections API reference.
- To work with collections in the Media Library instead, see Collections.
- For the complete script that runs the flow above, see the sample app.
When to use the Collections API
Use the Collections API when a collection needs to be built, changed, or shared by software rather than by a person in the Media Library:
- Grouping on upload: add an asset to a collection as soon as it arrives, based on the folder it landed in, its tags, or its metadata.
- Grouping from an external list: build a collection from a list of SKUs, product IDs, or shot IDs that lives in your PIM, ERP, or spreadsheet.
- Self-maintaining groups: create a dynamic collection whose membership follows a saved search expression, so it updates itself as assets are tagged, retagged, or archived.
- Handing assets to another system: list a collection's assets and pull them into a media server, a broadcast system, or a partner's pipeline.
- Sharing without the Console: publish a collection as a public page from your own application, with its own expiry date, download options, and email verification, and give the resulting URL to whoever needs it.
- Custom portals: build your own branded asset portal on top of collections, or embed a collection in a web page or gallery.
If a person is going to browse, pick, and share the assets by hand, the Media Library is the better tool. The API and the Media Library act on the same collections, so you can start a collection in one and finish it in the other.
Collections or folders?
Folders and collections solve different problems, and mixing them up is the most common source of confusion when you start automating:
| Folders | Collections | |
|---|---|---|
| Definition | The storage path of an asset. Every asset sits in exactly one folder. | A grouping layer on top of storage. An asset can be in any number of collections, or none. |
| Effect on assets | Moving an asset to another folder is a real move, although the public ID and delivery URL stay the same in dynamic folder mode. | Adding or removing an asset never touches the asset, its folder, or its URL. |
| Deleting | Deleting a folder's assets deletes them from your product environment. | Deleting a collection leaves every asset exactly where it was. |
| External sharing | Can't be shared externally. | Can be published as a public page for people outside your account. |
| API | Admin API folder methods. | Collections API. |
For a fuller comparison, see Folders and collections.
Before you begin
- Collections are a premium Assets Enterprise feature, and their availability depends on your account setup. On the Assets Free plan you can create up to 3 collections with up to 50 assets each. Contact us if you need more.
- Dynamic collections, sharing collections externally, and email verification for public pages are each premium features that may need to be enabled for your account. If you need one of them, contact your Customer Success Manager.
- The API enforces the same collection roles and permissions as the Media Library. Whatever principal you authenticate as, whether an API key or a user, needs the Create collections permission to create a collection, and a collection role such as Manager or Distributor to change or publish an existing one. All users with product environment admin system roles, except MediaFlows Admins, can create and manage collections, as well as public pages. See Assign roles to give an API key the roles it needs. A collection role can only be given to an API key through the Permissions API, not in the Console, and it applies within the product environment that the key belongs to.
- Roles and permissions govern only the users and API keys in your account who manage collections. They don't apply to the people who open a public page: those viewers can be external to your organization, don't need a Cloudinary user, and can only view or download, within the limits you set on the public page itself.
How to integrate
Base URL and authentication
All Collections API endpoints live under:
Authenticate in one of two ways:
- Basic authentication with the API key and secret of your product environment, from the API Keys page of the Console Settings. Use this for server-to-server automation, where the integration acts as itself.
- A bearer JWT for a signed-in Cloudinary user, obtained through OAuth 2.0. Use this when your application acts on behalf of a person, so the call is authorized with that user's own roles and permissions.
Ways to call the API
| Method | Use it for | Getting started |
|---|---|---|
| REST | Any language. Every endpoint, with no SDK dependency. | The base URL and authentication above. |
| Python SDK | Python back ends and scripts. |
pip install "cloudinary>=1.47.0", then import cloudinary.collections. Each method is documented in the collections module source. |
| Cloudinary CLI | Trying endpoints out, one-off jobs, and shell scripts. |
pip install "cloudinary-cli>=1.18.0", then cld collections -ls to list the available methods. See the Cloudinary CLI guide. |
| MCP server | Letting an agent manage collections in a conversation. | Connect the Asset Management MCP server, which exposes every collection and public page operation as a tool. |
The Python SDK method names match the endpoints one to one, and the CLI calls the same methods, so an example written for one translates directly to the others:
Endpoints at a glance
The Python methods below all live in the cloudinary.collections module, and the module source documents the parameters each one takes:
| Endpoint | What it does | Python method |
|---|---|---|
| POST /collections | Create a manual or dynamic collection. | create_collection(name) |
| GET /collections | List and search collections. | collections() |
| GET /collections/{collection_id} | Get one collection, including its asset count and cover asset. | collection(collection_id) |
| PUT /collections/{collection_id} | Rename a collection, change its description, or change a dynamic collection's expression. | update_collection(collection_id) |
| DELETE /collections/{collection_id} | Delete a collection, leaving its assets untouched. | delete_collection(collection_id) |
| GET /collections/{collection_id}/assets | List the assets in a collection. | collection_assets(collection_id) |
| POST /collections/{collection_id}/assets | Add assets to a manual collection. | add_collection_assets(collection_id, asset_ids) |
| DELETE /collections/{collection_id}/assets | Remove assets from a manual collection. | remove_collection_assets(collection_id, asset_ids) |
| POST /collections/{collection_id}/public_pages | Publish the collection and get a shareable URL. | create_collection_public_page(collection_id) |
| GET /collections/{collection_id}/public_pages | List the collection's public pages. | collection_public_pages(collection_id) |
| GET /collections/{collection_id}/public_pages/{public_page_id} | Get one public page and its settings. | collection_public_page(collection_id, public_page_id) |
| PUT /collections/{collection_id}/public_pages/{public_page_id} | Change a page's dates, download options, or protection. | update_collection_public_page(collection_id, public_page_id) |
| DELETE /collections/{collection_id}/public_pages/{public_page_id} | Unpublish a page so the link stops working. | delete_collection_public_page(collection_id, public_page_id) |
How to use the Collections API
Create a collection
A collection is either manual or dynamic, and the type is fixed when you create it:
- A manual collection holds an explicit list of assets. It starts empty, and you decide what goes in and what comes out.
- A dynamic collection is defined by a saved search expression. Cloudinary evaluates the expression against your assets, so the collection's contents change as assets start or stop matching.
Create a manual collection with a name, and optionally a description:
The response carries the collection's ID, which every other endpoint needs:
For a dynamic collection, set type to dynamic and give it an expression:
Add assets to a collection
Adding assets to manual collections takes a JSON array of asset_id values. asset_id is the asset's immutable ID, not its public ID, so renaming or moving an asset never breaks its membership.
Removing assets works the same way, with DELETE /collections/{collection_id}/assets and the same array of asset IDs. The assets themselves aren't modified or deleted.
Find the asset IDs
Where you get the asset IDs depends on where the trigger comes from:
-
An asset you just uploaded: the upload response and the upload notification both include
asset_id. -
Assets matching a query: use the Admin API search method, with an expression over tags, folders, structured metadata, or anything else the assets are described by. Each result includes
asset_id. Note thattags=is an exact, case-sensitive match, sotags="summer"skips an asset tagged "Summer" without reporting anything. You can't work around that by adding the lowercase tag as well, because Cloudinary dedupes tags case-insensitively and keeps whichever casing arrived first. Usetags:for a token match instead, or keep your tag casing consistent at the point you write it. - Assets already in another collection: list its assets.
For example, to collect every image tagged summer-campaign that was uploaded in the last week:
List the assets in a collection
GET /collections/{collection_id} returns a collection's asset_count and cover asset, but not the assets. To read the contents, use the assets endpoint, which returns each asset's IDs, dimensions, format, size, and secure_url, 20 at a time by default and up to 100:
To walk a collection of any size, pass the next_cursor from each response back on the next request, and keep going until no cursor is returned. Send the same sort_by on every page, because a cursor is only valid for the sort it was issued with:
Anyone who can view the collection sees all of its assets, including assets in folders that aren't shared with them and assets marked Restricted. See Things to know.
Publish a collection as a public page
Publishing a collection creates a public page: a dedicated web page that shows the collection's assets, with filtering, search, previews, and downloads. The response contains the shareable URL.
noindex, so search engines don't list it, but the link is otherwise the only thing protecting the assets. Share it only with people you trust, set an expires_at, and require email verification for anything sensitive.The page reflects the collection, so assets you add or remove later, and renames of the collection or its assets, show up on the page as soon as a visitor refreshes it. A collection can have more than one public page, which is useful when different audiences need different expiry dates or download options.
Set when the page is available
-
available_fromis when the page starts working. Set it to the time you want the page to go live, for example a campaign's launch date. -
expires_atis when it stops working. Omit it for a page that never expires.
Both are ISO 8601 date-times, and you can move either of them at any time with PUT /collections/{collection_id}/public_pages/{public_page_id}.
Once a page is past expires_at, opening it reports "collection not found" rather than anything about expiry, so tell recipients when the link stops working instead of relying on the page to explain itself. To reissue a link, move expires_at forward or publish a new page.
Offer download options
show_download_original_option controls whether the page offers visitors a download-original option. Omit it to inherit the account default that an administrator sets in the Media Library Preferences. If downloading originals is turned off there, you can't turn it on for an individual page.
To offer modified copies instead, for example a watermarked or web-sized version, list named transformations in download_transformations. You reference each one by name:
-
typesrestricts a transformation to the asset types it produces sensible results for. A trim only makes sense for video, so offering it for images would only produce download errors.typesbelongs to the transformation template itself and is shared by every public page in the product environment, so you can only set it the first time a page offers that name. Omit it to offer the transformation for both images and videos. -
create_download_transformations: truepromotes any name that isn't yet a transformation template into one, so it also appears in the Console and counts toward your limit of 60 transformation templates. Without it, a name that isn't already a template fails the request withdownload_transformation_not_availableand nothing is changed.
Require email verification
By default anyone holding the URL can open the page. To add a layer of access control, set protection_mode to email_otp with PUT /collections/{collection_id}/public_pages/{public_page_id}. Visitors then have to verify an email address with a one-time code before they see anything:
- A protected page needs at least one entry in
allowed_emailsorallowed_domains, orallow_any: trueto let anyone who verifies an address in. The two lists hold up to 500 entries between them. -
allow_any: truecollects the addresses visitors enter, so make sure your privacy notice covers it. -
allowed_emailsandallowed_domainsreplace the current lists rather than adding to them. Read the page first if you want to append. - On an unprotected page the allowlist fields are ignored, so send
protection_mode: email_otpin the same request that sets them. - Setting
protection_modeback tononeremoves the protection and clears both lists. - Only the update call accepts
protection_mode, so a page that has to be protected is always created unprotected first. Setavailable_froma few minutes ahead when you create it, so the URL isn't live yet, and treat a failure to protect it as a failure to publish: delete the page instead of leaving it scheduled to open. If the delete fails too, report the collection ID and page ID so someone can unpublish it. The sample app does both.
For what visitors see, see Email verification for stakeholders.
Manage and unpublish pages
List a collection's pages with GET /collections/{collection_id}/public_pages, and read one with GET /collections/{collection_id}/public_pages/{public_page_id}. Every field is always present in the response, with unset values returned as null, false, or [], so you can read a page, change one field, and write it back without guessing what an absent field meant.
To revoke a link immediately, unpublish the page. The collection and its assets aren't affected, and you can publish a new page afterwards:
Find and clean up collections
GET /collections lists the collections the caller can read, most recently updated first, and query filters by name. A single word matches collections with a word in their name that starts with that text, so sum finds "Summer campaign 2026":
query splits the text you pass on spaces and hyphens, and returns every collection that matches at least one of the resulting words. A multi-word query therefore widens the result set rather than narrowing it: winter sale returns both "Winter Sale" and "Yearly sale". A word that matches nothing is dropped instead of returning no results, so nature xyzzy still returns "Nature".
Use this to find the collection a long-running automation created, instead of storing its ID. Because the match is per word, compare the names in the response to the name you want before acting on a result, the way find_or_create_collection does in the sample app. When a campaign is over, DELETE /collections/{collection_id} removes the collection and any public pages of it. The assets stay in your product environment, in the folders they were always in.
Automation patterns
Add an asset to a collection as soon as it's uploaded
Add the asset from the upload response, in the same code that uploads it:
When assets arrive by a route you don't control, such as the Media Library, a connector, or a partner's integration, listen for the upload notification instead and add asset_id from the webhook payload. Pick the collection from the asset's folder, tags, or metadata, which the payload also carries.
For a rule as simple as "every image tagged summer-campaign", a dynamic collection does the same job with no code and no webhook.
Keep a collection in step with an external list
When the list of what belongs in a collection lives in another system, such as the SKUs of a product line, reconcile the two: work out what the collection should hold, compare it with what it holds now, and send one add and one remove.
Pull a collection's assets into another system
To hand a collection to a media server, a broadcast system, or a partner's pipeline, page through its assets and fetch each secure_url. Add transformations to the URL if the target system needs a particular format or size.
If you'd rather hand over one file, publish the collection as a public page instead and let the recipient download the whole collection as a ZIP from the page.
Sample app
The campaign handoff sample app runs the flow at the top of this page end to end: it finds the assets approved for a campaign, reconciles them into a collection, publishes a public page that expires in 30 days and offers a web-sized download, restricts that page to the agency's addresses, and prints the link to send.
The sample is designed to be run again as campaign approvals change. Each run adds newly approved assets to the collection and removes assets that are no longer approved. Because the public page is linked to the collection, it automatically reflects those changes. The script reuses the existing collection and page instead of creating duplicates. If it cannot restrict the page to the agency’s approved addresses, it deletes the page rather than leaving an unprotected link available.
The script works in four steps, each one covered in this guide:
-
Make sure the download transformation references a named transformation that exists, because
create_download_transformationscan only promote a named transformation that's already there. - Find the approved assets, paging through the search results so a campaign bigger than one page isn't truncated.
- Reconcile the collection, adding what's newly approved and removing what's lost its approval.
-
Publish and protect the page, creating it with
available_froma few minutes ahead and then settingprotection_modebefore it opens.
The code for this app is available in GitHub.
- Enjoy interactive learning? Check out more sample apps!
Setup instructions (after cloning from GitHub)
-
Install the dependencies:
Copy .env.example to .env, and set
CLOUDINARY_URLto the environment variable found on the API Keys page of the Console Settings. SetSHARE_EMAILSto the addresses allowed to open the page.Tag a few assets both
summer-campaignandapproved, or setCAMPAIGNto a tag you already use.-
Run it:
The four steps map directly onto the REST endpoints, so you can port the script to any language from the Collections API reference.
Things to know
- Collection, asset, and page IDs are opaque strings. Don't parse them or build them yourself. Keep the IDs the API returns.
- Asset lists and counts are eventually consistent. A collection's asset list and count can lag a few seconds behind an add or a remove. Search is a separate index with its own lag, so an asset you just tagged may not match a search expression yet. Anything that compares a search result against a collection's contents, such as reconciling a collection with an external list, has to allow for both.
- Removing an asset or deleting a collection never deletes assets. To delete the files, use the Admin API or the Upload API.
- A collection's type can't be changed. To turn a manual collection into a dynamic one, create a new collection.
- Collection names aren't unique. One user can't create two collections with the same name, but different users can, so don't treat a name as a key.
- Collection access bypasses folder permissions, but never grants editing. Anyone invited to a collection can view and download all of its assets, even assets in folders that aren't shared with them, and each of the built-in collection roles covers assets marked Restricted. What a user can do to the assets themselves doesn't change: they can only add or remove assets they can already view, and editing an asset still depends on their folder and global roles.
-
A principal without access sees an empty product environment, not an error. Listing collections, or the assets in a collection, that the principal can't see returns
200with an empty result rather than403, and adding or removing an asset it can't see returns404 Unknown resource. If calls succeed but come back empty, check the principal's effective permissions with the inspect endpoint before you look for a bug in your code. - Calls count against your account's rate limits. Batch asset changes into one request where you can, instead of one request per asset.
- Collections API reference for every endpoint, parameter, and response field.
- Folders and collections for collections in the Media Library.
- Collection roles for the permissions behind each operation.
- Cloudinary MCP servers to let an agent manage collections.

