Documentation Index

Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt

Use this file to discover all available pages before exploring further.

Assets (DAM)

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.

Collections card view

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.

See also:

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.

Note
Never put your API secret in client-side code. Call the Collections API from your server, or from a serverless function, and pass only the results to the browser.

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:

Note
The Collections API is currently available in the Python SDK and the Cloudinary CLI. From other languages, call the REST endpoints directly.

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.

Caution
A dynamic collection is a rule, not a list, so you can't know in advance exactly which assets it holds. Any asset that starts matching the expression joins the collection, including assets uploaded later and assets whose tags or metadata someone changes, and everyone with access to the collection sees whatever it matches at that moment. A public page of a dynamic collection updates along with it, so assets you never intended to share can appear on a page you've already sent out. Before you publish a dynamic collection, check that its expression can't match assets you don't want exposed, and prefer a narrow expression over a broad one.

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:

Note
You can't add or remove individual assets in a dynamic collection. Change what it contains by changing its expression with PUT /collections/{collection_id}, or by changing the tags and metadata of the assets themselves. In the Media Library, an expression set through the API appears as a single Expression filter, and any filters added there are combined with it using AND.

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 that tags= is an exact, case-sensitive match, so tags="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. Use tags: 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:

Tip
If the query that selects the assets is the definition of the collection, and not a one-off, create a dynamic collection with that expression instead of adding assets on a schedule. The collection then maintains itself.

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.

Note
Asset counts and asset lists can take a few seconds to catch up after you add or remove assets. If you add assets and immediately list them, allow for a short delay or retry rather than treating the first response as final.

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.

Externally shared collection web page

Caution
A public page shows every asset in the collection to anyone who has the link, including assets marked Restricted, and lets them preview and download copies. The page is set to 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.

Note
The public page URL contains the page's ID, not the collection's, and there's no endpoint that resolves a URL back to a collection. Store the collection ID and page ID together when you publish, and use GET /collections/{collection_id}/public_pages to recover the pages of a collection you know the ID of. Links produced by other Media Library sharing features aren't collections and aren't returned by this API.

Set when the page is available

  • available_from is 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_at is 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:

  • types restricts 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. types belongs 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: true promotes 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 with download_transformation_not_available and 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_emails or allowed_domains, or allow_any: true to let anyone who verifies an address in. The two lists hold up to 500 entries between them.
  • allow_any: true collects the addresses visitors enter, so make sure your privacy notice covers it.
  • allowed_emails and allowed_domains replace 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_otp in the same request that sets them.
  • Setting protection_mode back to none removes 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. Set available_from a 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.

Note
Search results may lag shortly after tags or metadata are updated. Because this script removes collection assets that are not returned by the search, run it only after the search index has caught up, for example on a schedule. The script paginates through both lists completely; otherwise, incomplete results can cause incorrect additions or removals.

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:

  1. Make sure the download transformation references a named transformation that exists, because create_download_transformations can only promote a named transformation that's already there.
  2. Find the approved assets, paging through the search results so a campaign bigger than one page isn't truncated.
  3. Reconcile the collection, adding what's newly approved and removing what's lost its approval.
  4. Publish and protect the page, creating it with available_from a few minutes ahead and then setting protection_mode before it opens.

Fork the repo and try it yourself

The code for this app is available in GitHub.

  • Enjoy interactive learning? Check out more sample apps!

Setup instructions (after cloning from GitHub)

  1. Install the dependencies:

  2. Copy .env.example to .env, and set CLOUDINARY_URL to the environment variable found on the API Keys page of the Console Settings. Set SHARE_EMAILS to the addresses allowed to open the page.

  3. Tag a few assets both summer-campaign and approved, or set CAMPAIGN to a tag you already use.

  4. 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 200 with an empty result rather than 403, and adding or removing an asset it can't see returns 404 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.

See also:

✔️ Feedback sent!

Rate this page:

one star two stars three stars four stars five stars