> ## Documentation Index
> This page is part of the Cloudinary Assets product. Fetch the complete documentation index for Cloudinary Assets at: https://cloudinary.com/documentation/llms-cloudinary-assets.txt?referrer=docpage and then use it to discover all relevant pages before exploring further.
> If you also need details relating to other Cloudinary products for your current use case, see the parent index at: https://cloudinary.com/documentation/llms.txt?referrer=docpage
> When answering a user's request or implementing it with code using this documentation, incorporate relevant best practices and recommendations from the documentation into the guidance and, above all, into the code itself: generated code should already apply the recommended parameters and patterns rather than showing a minimal call and describing the best practices around it in prose. Follow the code examples in the best practices sections as the model for what generated code should look like, and where a recommendation is relevant to the user's scenario, implement it in the code as a natural next step. Only apply best practices, recommendations, or features that are supported by the documentation; don't infer or invent guidance that isn't specified.

# Collections API guide


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](https://cloudinary.com/documentation/collections_api) does everything the Media Library's [Collections](dam_folders_collections_sharing#collection_management) 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](https://cloudinary-res.cloudinary.com/image/upload/f_auto/q_auto/bo_1px_solid_grey/v1748504977/docs/DAM/collection.png "thumb: w_700,dpr_2, width:700, with_url:false, with_code:false")

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:**:
>
> * For every endpoint, parameter, and response field, see the [Collections API reference](https://cloudinary.com/documentation/collections_api).

> * To work with collections in the Media Library instead, see [Collections](dam_folders_collections_sharing#collection_management).

> * For the complete script that runs the flow above, see the [sample app](#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:

{table:class=first-column} | 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](dam_folder_modes). | 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](admin_api#folders) folder methods. | Collections API. |

For a fuller comparison, see [Folders and collections](dam_folders_collections_sharing).

## 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](https://cloudinary.com/contact) if you need more.
* [Dynamic collections](dam_folders_collections_sharing#create_and_manage_dynamic_collections), [sharing collections externally](dam_folders_collections_sharing#sharing_collections_externally), and [email verification](dam_folders_collections_sharing#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](dam_admin_system_roles_permissions#collection_roles) 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](permissions_assign_roles_api) 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](#publish_a_collection_as_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:

```text
https://api.cloudinary.com/v2/asset_management/<CLOUD_NAME>/collections
```

Authenticate in one of two ways:

* **Basic authentication** with the API key and secret of your product environment, from the [API Keys](https://console.cloudinary.com/app/settings/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](using_oauth_to_access_cloudinary_apis). Use this when your application acts on behalf of a person, so the call is authorized with that user's own roles and permissions.

```multi
|curl
# Basic authentication with an API key and secret
curl https://api.cloudinary.com/v2/asset_management/<CLOUD_NAME>/collections \
  -u <API_KEY>:<API_SECRET>

# A user's OAuth access token
curl https://api.cloudinary.com/v2/asset_management/<CLOUD_NAME>/collections \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
```

> **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

{table:class=first-column} 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](https://github.com/cloudinary/pycloudinary/blob/master/cloudinary/collections.py). |
| **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](cloudinary_cli) guide. |
| **MCP server** | Letting an agent manage collections in a conversation. | Connect the [Asset Management MCP server](cloudinary_llm_mcp#available_mcp_servers), 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:

```multi
|curl
curl https://api.cloudinary.com/v2/asset_management/<CLOUD_NAME>/collections?max_results=5 \
  -u <API_KEY>:<API_SECRET>

|python
import cloudinary.collections

collections = cloudinary.collections.collections(max_results=5)

|cli
cld collections collections -o max_results 5
```

> **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](https://github.com/cloudinary/pycloudinary/blob/master/cloudinary/collections.py) documents the parameters each one takes:

{table:class=narrow_first_col} Endpoint | What it does | Python method |
|---|---|---|
| [POST /collections](https://cloudinary.com/documentation/collections_api#tag/collections/POST/{cloud_name}/collections) | Create a manual or dynamic collection. | `create_collection(name)` |
| [GET /collections](https://cloudinary.com/documentation/collections_api#tag/collections/GET/{cloud_name}/collections) | List and search collections. | `collections()` |
| [GET /collections/{collection_id}](https://cloudinary.com/documentation/collections_api#tag/collections/GET/{cloud_name}/collections/{collection_id}) | Get one collection, including its asset count and cover asset. | `collection(collection_id)` |
| [PUT /collections/{collection_id}](https://cloudinary.com/documentation/collections_api#tag/collections/PUT/{cloud_name}/collections/{collection_id}) | Rename a collection, change its description, or change a dynamic collection's expression. | `update_collection(collection_id)` |
| [DELETE /collections/{collection_id}](https://cloudinary.com/documentation/collections_api#tag/collections/DELETE/{cloud_name}/collections/{collection_id}) | Delete a collection, leaving its assets untouched. | `delete_collection(collection_id)` |
| [GET /collections/{collection_id}/assets](https://cloudinary.com/documentation/collections_api#tag/collections/GET/{cloud_name}/collections/{collection_id}/assets) | List the assets in a collection. | `collection_assets(collection_id)` |
| [POST /collections/{collection_id}/assets](https://cloudinary.com/documentation/collections_api#tag/collections/POST/{cloud_name}/collections/{collection_id}/assets) | Add assets to a manual collection. | `add_collection_assets(collection_id, asset_ids)` |
| [DELETE /collections/{collection_id}/assets](https://cloudinary.com/documentation/collections_api#tag/collections/DELETE/{cloud_name}/collections/{collection_id}/assets) | Remove assets from a manual collection. | `remove_collection_assets(collection_id, asset_ids)` |
| [POST /collections/{collection_id}/public_pages](https://cloudinary.com/documentation/collections_api#tag/collections/POST/{cloud_name}/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](https://cloudinary.com/documentation/collections_api#tag/collections/GET/{cloud_name}/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}](https://cloudinary.com/documentation/collections_api#tag/collections/GET/{cloud_name}/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}](https://cloudinary.com/documentation/collections_api#tag/collections/PUT/{cloud_name}/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}](https://cloudinary.com/documentation/collections_api#tag/collections/DELETE/{cloud_name}/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](search_expressions). Cloudinary evaluates the expression against your assets, so the collection's contents change as assets start or stop matching.

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](#publish_a_collection_as_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:

```multi
|curl
curl -X POST https://api.cloudinary.com/v2/asset_management/<CLOUD_NAME>/collections \
  -u <API_KEY>:<API_SECRET> \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer campaign 2026",
    "description": "Approved photography for the summer campaign launch."
  }'

|python
import cloudinary.collections

collection = cloudinary.collections.create_collection(
    "Summer campaign 2026",
    description="Approved photography for the summer campaign launch.",
)

|cli
cld collections create_collection "Summer campaign 2026" \
  -o description "Approved photography for the summer campaign launch."
```

The response carries the collection's ID, which every other endpoint needs:

```json
{
  "data": {
    "id": "9f2a6c41b8d35e07a1c4e8b2d6f03a95",
    "name": "Summer campaign 2026",
    "creator_type": "api",
    "creator_id": "614338531296742",
    "created_at": "2026-11-12T10:15:00Z",
    "updated_at": "2026-11-12T10:15:00Z",
    "description": "Approved photography for the summer campaign launch.",
    "type": "manual"
  }
}
```

For a dynamic collection, set `type` to `dynamic` and give it an expression:

```multi
|curl
curl -X POST https://api.cloudinary.com/v2/asset_management/<CLOUD_NAME>/collections \
  -u <API_KEY>:<API_SECRET> \
  -H "Content-Type: application/json" \
  -d '{
    "name": "All summer campaign images",
    "type": "dynamic",
    "configuration": {
      "expression": "tags=\"summer-campaign\" AND resource_type:image"
    }
  }'

|python
import cloudinary.collections

collection = cloudinary.collections.create_collection(
    "All summer campaign images",
    type="dynamic",
    configuration={"expression": 'tags="summer-campaign" AND resource_type:image'},
)

|cli
cld collections create_collection "All summer campaign images" \
  -o type dynamic \
  -O configuration '{"expression": "tags=\"summer-campaign\" AND resource_type:image"}'
```

> **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}](https://cloudinary.com/documentation/collections_api#tag/collections/PUT/{cloud_name}/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.

```multi
|curl
curl -X POST https://api.cloudinary.com/v2/asset_management/<CLOUD_NAME>/collections/9f2a6c41b8d35e07a1c4e8b2d6f03a95/assets \
  -u <API_KEY>:<API_SECRET> \
  -H "Content-Type: application/json" \
  -d '["0caf158ac6ea700e5a8138b000b5eb3b", "68b2d48db43f332c4837e880c8c53803"]'

|python
import cloudinary.collections

cloudinary.collections.add_collection_assets(
    "9f2a6c41b8d35e07a1c4e8b2d6f03a95",
    ["0caf158ac6ea700e5a8138b000b5eb3b", "68b2d48db43f332c4837e880c8c53803"],
)

|cli
cld collections add_collection_assets 9f2a6c41b8d35e07a1c4e8b2d6f03a95 \
  '["0caf158ac6ea700e5a8138b000b5eb3b", "68b2d48db43f332c4837e880c8c53803"]'
```

Removing assets works the same way, with [DELETE /collections/{collection_id}/assets](https://cloudinary.com/documentation/collections_api#tag/collections/DELETE/{cloud_name}/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](image_upload_api_reference#upload) response and the [upload notification](notifications) both include `asset_id`.
* **Assets matching a query**: use the Admin API [search](search_method) method, with an [expression](search_expressions) 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](#list_the_assets_in_a_collection).

For example, to collect every image tagged `summer-campaign` that was uploaded in the last week:

```python
import cloudinary.search
import cloudinary.collections

result = (
    cloudinary.search.Search()
    .expression('tags="summer-campaign" AND resource_type:image AND uploaded_at>1w')
    .max_results(100)
    .execute()
)

asset_ids = [asset["asset_id"] for asset in result["resources"]]
cloudinary.collections.add_collection_assets("9f2a6c41b8d35e07a1c4e8b2d6f03a95", asset_ids)
```

> **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}](https://cloudinary.com/documentation/collections_api#tag/collections/GET/{cloud_name}/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:

```multi
|curl
curl "https://api.cloudinary.com/v2/asset_management/<CLOUD_NAME>/collections/9f2a6c41b8d35e07a1c4e8b2d6f03a95/assets?max_results=100&sort_by=created_at%20desc" \
  -u <API_KEY>:<API_SECRET>

|python
import cloudinary.collections

page = cloudinary.collections.collection_assets(
    "9f2a6c41b8d35e07a1c4e8b2d6f03a95",
    max_results=100,
    sort_by="created_at desc",
)

|cli
cld collections collection_assets 9f2a6c41b8d35e07a1c4e8b2d6f03a95 \
  -o max_results 100 -o sort_by "created_at desc"
```

```json
{
  "data": [
    {
      "asset_id": "0caf158ac6ea700e5a8138b000b5eb3b",
      "public_id": "campaigns/summer/beach-hero",
      "display_name": "beach-hero",
      "resource_type": "image",
      "type": "upload",
      "format": "jpg",
      "bytes": 2351968,
      "width": 2500,
      "height": 1660,
      "secure_url": "https://res.cloudinary.com/<CLOUD_NAME>/image/upload/v1640033333/campaigns/summer/beach-hero.jpg",
      "created_at": "2026-11-10T20:48:53Z"
    }
  ],
  "next_cursor": "eb3ca622c7e7acbc26d521c5dc892c5878bce77b1",
  "total_count": 7
}
```

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:

```python
import cloudinary.collections

def all_assets(collection_id):
    options = {"max_results": 100, "sort_by": "created_at desc"}
    while True:
        page = cloudinary.collections.collection_assets(collection_id, **options)
        for asset in page["data"]:
            yield asset
        cursor = page.get("next_cursor")
        if not cursor:
            return
        options["next_cursor"] = cursor
```

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](dam_manage_asset_protection#access_control_modes). See [Things to know](#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.

```multi
|curl
curl -X POST https://api.cloudinary.com/v2/asset_management/<CLOUD_NAME>/collections/9f2a6c41b8d35e07a1c4e8b2d6f03a95/public_pages \
  -u <API_KEY>:<API_SECRET> \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer campaign preview",
    "available_from": "2026-11-12T00:00:00Z",
    "expires_at": "2026-12-12T00:00:00Z",
    "show_download_original_option": true
  }'

|python
import cloudinary.collections

page = cloudinary.collections.create_collection_public_page(
    "9f2a6c41b8d35e07a1c4e8b2d6f03a95",
    name="Summer campaign preview",
    available_from="2026-11-12T00:00:00Z",
    expires_at="2026-12-12T00:00:00Z",
    show_download_original_option=True,
)

|cli
cld collections create_collection_public_page 9f2a6c41b8d35e07a1c4e8b2d6f03a95 \
  -o name "Summer campaign preview" \
  -o available_from "2026-11-12T00:00:00Z" \
  -o expires_at "2026-12-12T00:00:00Z" \
  -O show_download_original_option true
```

```json
{
  "data": {
    "id": "abd83314957c85e71d802b478f1a3781",
    "url": "https://collection.cloudinary.com/<CLOUD_NAME>/abd83314957c85e71d802b478f1a3781",
    "name": "Summer campaign preview",
    "available_from": "2026-11-12T00:00:00Z",
    "expires_at": "2026-12-12T00:00:00Z",
    "show_download_original_option": true,
    "download_transformations": [],
    "protection_mode": "none",
    "allowed_emails": [],
    "allowed_domains": [],
    "allow_any": false,
    "custom_layout_url": null
  }
}
```

![Externally shared collection web page](https://cloudinary-res.cloudinary.com/image/upload/q_auto/f_auto/bo_1px_solid_grey/v1702809859/docs/DAM/shared_filtered_collections_webpage.png "thumb: w_700,dpr_2, width:700, with_url:false, with_code:false")

A public page shows every asset in the collection to anyone who has the link, including assets marked [Restricted](dam_manage_asset_protection#access_control_modes), 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](#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](https://cloudinary.com/documentation/collections_api#tag/collections/GET/{cloud_name}/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}](https://cloudinary.com/documentation/collections_api#tag/collections/PUT/{cloud_name}/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](dam_admin_media_library_options#download_options_for_external_sharing). 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](named_transformations) in `download_transformations`. You reference each one by name:

```json
{
  "download_transformations": [
    { "name": "web_1200" },
    { "name": "watermarked" },
    { "name": "trimmed_preview", "types": ["video"] }
  ],
  "create_download_transformations": true
}
```

* `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](dam_editing_and_transformations#transformation_templates) 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}](https://cloudinary.com/documentation/collections_api#tag/collections/PUT/{cloud_name}/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:

```multi
|curl
curl -X PUT https://api.cloudinary.com/v2/asset_management/<CLOUD_NAME>/collections/9f2a6c41b8d35e07a1c4e8b2d6f03a95/public_pages/abd83314957c85e71d802b478f1a3781 \
  -u <API_KEY>:<API_SECRET> \
  -H "Content-Type: application/json" \
  -d '{
    "protection_mode": "email_otp",
    "allowed_emails": ["alice@agency.example.com"],
    "allowed_domains": ["partner.example.com"]
  }'

|python
import cloudinary.collections

page = cloudinary.collections.update_collection_public_page(
    "9f2a6c41b8d35e07a1c4e8b2d6f03a95",
    "abd83314957c85e71d802b478f1a3781",
    protection_mode="email_otp",
    allowed_emails=["alice@agency.example.com"],
    allowed_domains=["partner.example.com"],
)

|cli
cld collections update_collection_public_page \
  9f2a6c41b8d35e07a1c4e8b2d6f03a95 abd83314957c85e71d802b478f1a3781 \
  -o protection_mode email_otp \
  -O allowed_emails '["alice@agency.example.com"]' \
  -O allowed_domains '["partner.example.com"]'
```

* 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](#sample_app) does both.

For what visitors see, see [Email verification for stakeholders](dam_folders_collections_sharing#email_verification_for_stakeholders).

#### Manage and unpublish pages

List a collection's pages with [GET /collections/{collection_id}/public_pages](https://cloudinary.com/documentation/collections_api#tag/collections/GET/{cloud_name}/collections/{collection_id}/public_pages), and read one with [GET /collections/{collection_id}/public_pages/{public_page_id}](https://cloudinary.com/documentation/collections_api#tag/collections/GET/{cloud_name}/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:

```multi
|curl
curl -X DELETE https://api.cloudinary.com/v2/asset_management/<CLOUD_NAME>/collections/9f2a6c41b8d35e07a1c4e8b2d6f03a95/public_pages/abd83314957c85e71d802b478f1a3781 \
  -u <API_KEY>:<API_SECRET>

|python
import cloudinary.collections

cloudinary.collections.delete_collection_public_page(
    "9f2a6c41b8d35e07a1c4e8b2d6f03a95",
    "abd83314957c85e71d802b478f1a3781",
)

|cli
cld collections delete_collection_public_page \
  9f2a6c41b8d35e07a1c4e8b2d6f03a95 abd83314957c85e71d802b478f1a3781
```

### Find and clean up collections

[GET /collections](https://cloudinary.com/documentation/collections_api#tag/collections/GET/{cloud_name}/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":

```multi
|curl
curl "https://api.cloudinary.com/v2/asset_management/<CLOUD_NAME>/collections?query=sum&sort_by=name%20asc" \
  -u <API_KEY>:<API_SECRET>

|python
import cloudinary.collections

collections = cloudinary.collections.collections(query="sum", sort_by="name asc")

|cli
cld collections collections -o query sum -o sort_by "name asc"
```

`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](#sample_app) does in the sample app. When a campaign is over, [DELETE /collections/{collection_id}](https://cloudinary.com/documentation/collections_api#tag/collections/DELETE/{cloud_name}/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:

```python
import cloudinary.uploader
import cloudinary.collections

result = cloudinary.uploader.upload(
    "product-shot.jpg",
    asset_folder="campaigns/summer",
    tags=["summer-campaign"],
)

cloudinary.collections.add_collection_assets(
    "9f2a6c41b8d35e07a1c4e8b2d6f03a95",
    [result["asset_id"]],
)
```

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](notifications) 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.

```python
"""Keep a Cloudinary collection in sync with assets tagged for selected SKUs."""

import cloudinary
import cloudinary.collections
import cloudinary.search

COLLECTION_ID = "60a230807620151a0d2aaa6872819ba4"
SKUS = ["SKU-1021", "SKU-1044", "SKU-1092"]  # Retrieved from your PIM

def iter_matching_assets(expression):
    """Yield every asset matching a Search API expression."""
    next_cursor = None

    while True:
        search = (
            cloudinary.search.Search()
            .expression(expression)
            .max_results(500)
        )

        if next_cursor:
            search = search.next_cursor(next_cursor)

        result = search.execute()
        yield from result["resources"]

        next_cursor = result.get("next_cursor")
        if not next_cursor:
            break

def iter_collection_assets(collection_id):
    """Yield every asset in a collection."""
    next_cursor = None

    while True:
        params = {"max_results": 100}

        if next_cursor:
            params["next_cursor"] = next_cursor

        result = cloudinary.collections.collection_assets(
            collection_id,
            **params,
        )
        yield from result["data"]

        next_cursor = result.get("next_cursor")
        if not next_cursor:
            break

def reconcile_collection(collection_id, skus):
    """Add missing assets and remove assets that no longer match the SKUs."""
    if not skus:
        raise ValueError("At least one SKU is required.")

    # Tag matching is exact and case-sensitive.
    expression = " OR ".join(f'tags="{sku}"' for sku in skus)

    desired_assets = {
        asset["asset_id"]
        for asset in iter_matching_assets(expression)
    }

    # Avoid emptying the collection because of a typo or casing mismatch.
    if not desired_assets:
        raise ValueError(
            f"No assets matched {expression!r}; refusing to empty the collection."
        )

    collection_assets = {
        asset["asset_id"]
        for asset in iter_collection_assets(collection_id)
    }

    assets_to_add = desired_assets - collection_assets
    assets_to_remove = collection_assets - desired_assets

    print(
        f"Desired: {len(desired_assets)} | "
        f"Current: {len(collection_assets)} | "
        f"Add: {len(assets_to_add)} | "
        f"Remove: {len(assets_to_remove)}"
    )

    if assets_to_add:
        cloudinary.collections.add_collection_assets(
            collection_id,
            list(assets_to_add),
        )

    if assets_to_remove:
        cloudinary.collections.remove_collection_assets(
            collection_id,
            list(assets_to_remove),
        )

reconcile_collection(COLLECTION_ID, SKUS)
```

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

```python
import pathlib
import requests
import cloudinary.collections

# all_assets() is the paging helper from above.
for asset in all_assets("9f2a6c41b8d35e07a1c4e8b2d6f03a95"):
    target = pathlib.Path("/media-server/incoming") / f"{asset['asset_id']}.{asset['format']}"
    with requests.get(asset["secure_url"], stream=True) as response:
        response.raise_for_status()
        with target.open("wb") as file:
            for chunk in response.iter_content(chunk_size=1 << 20):
                file.write(chunk)
```

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](https://github.com/cloudinary-devs/cld-collections-campaign-handoff) 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`](#offer_download_options) can only promote a named transformation that's already there.
1. **Find the approved assets**, [paging through the search results](#keep_a_collection_in_step_with_an_external_list) so a campaign bigger than one page isn't truncated.
1. **Reconcile the collection**, adding what's newly approved and [removing what's lost its approval](#keep_a_collection_in_step_with_an_external_list).
1. **Publish and protect the page**, creating it with `available_from` a few minutes ahead and then [setting `protection_mode`](#require_email_verification) before it opens.

> **Fork the repo and try it yourself :custom-icon='https://cloudinary-res.cloudinary.com/image/upload/v1778586152/docsite/brand-assets/github.svg' :invert-icon**:
>
> The code for this app is available in [GitHub](https://github.com/cloudinary-devs/cld-collections-campaign-handoff).

> * Enjoy interactive learning? Check out more [sample apps](code_explorers)!

### Setup instructions (after cloning from GitHub)

1. Install the dependencies:

    ```bash
    pip install -r requirements.txt
    ```
1. Copy **.env.example** to **.env**, and set `CLOUDINARY_URL` to the environment variable found on the [API Keys](https://console.cloudinary.com/app/settings/api-keys) page of the Console Settings. Set `SHARE_EMAILS` to the addresses allowed to open the page.
1. Tag a few assets both `summer-campaign` and `approved`, or set `CAMPAIGN` to a tag you already use.
1. Run it:

    ```bash
    python publish_campaign.py
    ```

The four steps map directly onto the REST endpoints, so you can port the script to any language from the [Collections API reference](https://cloudinary.com/documentation/collections_api).

## 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](#keep_a_collection_in_step_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](dam_admin_system_roles_permissions#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](permissions_assign_roles_api#view_effective_permissions) 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:**:
>
> * [Collections API reference](https://cloudinary.com/documentation/collections_api) for every endpoint, parameter, and response field.

> * [Folders and collections](dam_folders_collections_sharing) for collections in the Media Library.

> * [Collection roles](dam_admin_system_roles_permissions#collection_roles) for the permissions behind each operation.

> * [Cloudinary MCP servers](cloudinary_llm_mcp) to let an agent manage collections.
