---
name: asset-management
description: "Advise on Contentstack Assets, the standalone digital asset management (DAM) product: spaces and workspaces, folders, asset types and metadata, localization, saved views, filtering by user-defined fields, AI tags and alt text, duplicate management, versions, trash and restore, visual markups, and linking to CMS stacks. Use when a user asks about the Assets DAM, spaces, workspaces, duplicate sets, saved views or visual markups. Not for the CMS stack asset library; use cms-assets for that."
allowed-tools: Read Grep Glob
---

# Asset Management (Contentstack Assets DAM)

## Description

Advise on Contentstack Assets, the standalone DAM product (also called "Asset Management" in some docs). Cover spaces and workspaces, folders, roles, asset types and metadata, localization, filters and saved views, AI-assisted metadata, duplicate management, versions, trash and restore, visual markups, and CMS integration.

## When to Use

Use when a user asks about the Contentstack Assets DAM: organizing assets in spaces, workspaces and folders, modeling asset metadata, AI tags and alt text, finding and removing duplicates, versioning, restoring deleted assets, visual markups, or using Assets with a CMS stack.

Do not use for the CMS stack asset library (stack-level uploads, folders, Image Delivery API, publishing to environments). Route those questions to `cms-assets`. If it is unclear which one the user means, ask whether they work in an Assets space or in the asset library inside a stack.

## User Problem

Teams adopting Contentstack Assets need to structure spaces and workspaces sensibly, model metadata so assets are findable, use AI features safely, keep the library free of duplicates, and understand what is and is not recoverable when assets are deleted or replaced.

## Success Criteria

- Distinguish the Assets DAM from the CMS asset library.
- Use the product's own terminology: space, workspace, main workspace, asset type, system metadata, user-defined metadata, duplicate set, visual markup.
- State documented behavior and limits accurately, and say plainly when something is not documented.
- Warn about irreversible or hard-to-reverse actions before the user takes them.

## Expected Inputs

- Which product the user means (Assets space or CMS stack library)
- Organization shape (brands, regions, teams) and number of spaces
- Asset types and metadata the team needs
- The specific task or problem (duplicates, restore, versions, AI settings, markups)

## Expected Outputs

- Space, workspace and folder structure recommendations
- Asset type and metadata modeling guidance
- Step-by-step UI paths for the task
- Gotchas and irreversible-action warnings
- Pointers to the official docs for anything not covered here

## Example User Requests

- How should I split my brands and regions across spaces and workspaces?
- How do I add custom fields to my images?
- How do I add a language to a workspace?
- Can I save a set of filters and reuse it?
- How do I search assets by a custom field value?
- Can Assets tag my images and write alt text automatically?
- How do I find and remove duplicate images?
- I deleted a folder by mistake. Can I get it back?
- How do I roll back to an earlier version of an asset?
- How do I add hotspots to a product image?
- How do I use assets from a space in my CMS entries?

## Workflow Summary

1. Confirm the user means the Assets DAM, not the CMS asset library.
2. Identify the topic: structure, metadata, AI, duplicates, versions, trash, markups, or CMS integration.
3. Answer with documented behavior using the product's terminology.
4. Flag limits and irreversible actions.
5. Link to the relevant docs page for anything undocumented or likely to change.

## Instructions

### Spaces and workspaces

- A **space** is the top-level container, often one per brand, business unit or region. Roles, permissions and settings are governed at the space level, so each space is managed independently.
- A **workspace** is an isolated environment inside a space. Every space has a **main workspace**. New workspaces are created from the main workspace or from another parent workspace, inherit its assets, metadata and configuration, and keep their own changes isolated from the parent.
- A space can be linked to one or more CMS stacks, and assets can be reused across stacks.
- Recommend a small number of spaces and workspaces. Over-fragmenting adds management overhead.
- Space Settings > General holds the title (required) and description. The Space UID is generated by the system and cannot be changed.
- Deleting a space is irreversible. It removes the space's assets, users and collaborators. Always warn before recommending it.
- Duplicate Management is configured per workspace. AI Settings live under Space Settings.

### Folders

- Create a folder with **+ New > New Folder**. Name is required and description is optional. Folders appear in the listing and in the Folders section of the Filters panel.
- Recommend a folder structure that matches how teams search, such as by campaign, asset category or brand, and keep it consistent across workspaces.

### Roles and permissions

- Access is governed per space through roles, teams and associations. Where the user needs the exact predefined roles or asset-level sharing options, direct them to the current Assets documentation rather than guessing.
- For least privilege, give contributors only the access they need and restrict delete and settings permissions to a few administrators.

### Asset types and metadata

- Metadata comes in layers: **system metadata** (read-only: file name, UID, URLs, MIME type, size, created and modified details), **general metadata**, and **user-defined metadata** from custom fields.
- Each **asset type** maps to one MIME type and one file extension. On upload, a matching type applies automatically and its fields appear. System types cover images, audio, video, documents and archives, and you can add custom types.
- User-defined fields are reusable across asset types. The currently supported field types are single line text, number, select and group. The product docs have listed this set differently over time, so point the user to the Asset Modeling docs if they need a type that isn't on this list.
- Mandatory fields must be filled before an upload or save can finish. Use them sparingly so uploads are not blocked on optional information.
- Edit metadata for an individual asset in the configurable metadata panel.
- User-defined fields exist only in the Assets (DAM) product. The CMS stack asset library and its Management API don't read or update them, so direct any request to read or write custom metadata from code to the Assets (DAM) API. See the Assets API reference at https://www.contentstack.com/docs/developers/apis/assets-api for the current endpoints.
- **Filters and saved views:** User-defined fields can be used as filters when browsing assets, so well-modeled fields make the library searchable. A filter combination can be saved as a **saved view** and reused later instead of rebuilding the filters each time. Advise modeling fields with filtering in mind, for example a select field for campaign or usage rights.

### Localization

- Assets supports localized asset versions within a space.
- Adding a language is a two-step process:
  1. Add the language in product settings.
  2. Add it to each workspace that needs it: **Space Settings > Workspaces >** pick the workspace **> Manage Locales**.
- Locales are enabled per workspace, so a language added in product settings does not appear in a workspace until it is added there.

### Searching assets and filtering by user-defined fields

Use the Assets API search endpoint. Full reference: https://www.contentstack.com/docs/developers/apis/assets-api/search

- **Endpoint:** `POST <host>/api/{object_type}/search`. `object_type` is required. Folders are not searchable here.
- **Host by region:** use the base URL for your region from the [Assets API overview](https://www.contentstack.com/docs/developers/apis/assets-api): AWS NA (`am-api.contentstack.com`), AWS EU (`eu-am-api.contentstack.com`), Azure NA (`azure-na-am-api.contentstack.com`) or GCP NA (`gcp-na-am-api.contentstack.com`).
- **Headers:** send either `authorization: Bearer <OAuth access token>` or `authtoken` (your Contentstack authtoken). A management token is not accepted. `x-cs-api-version` is required (default `4`). With `authtoken`, `organization_uid` is also required. Read tokens from environment variables.
- **Text search:** `search_text`, `search_field` and `search_terms_operator` (`and` or `or`). `search_field` accepts only `all`, `title`, `name`, `url` or `category`, so it cannot target user-defined fields.
- **Structured filters:** put conditions in `query`, combined with nested `$and` and `$or` clauses. The docs match a field to a value, for example `{ "category": "image" }`, and don't document other operators. To filter a user-defined field, reference it by its full path, `user_defined_fields.<group>.<field>`, and test the filter against your space, since the public page doesn't cover user-defined fields.
- **Scope and paging:** `spaces` limits the search and is a plain array of space UIDs, as in the docs example. Use `limit` and `skip` for paging, and `fields` to trim the response.
- Deleted items are excluded unless `include_deleted_items` or `filter_only_deleted_items` is set.

Example request body:

```json
{
  "query": {
    "$and": [
      { "user_defined_fields.asset_rights.license_type": "Creative Commons" }
    ]
  },
  "limit": 50,
  "spaces": ["<space_uid>"]
}
```

- Check the response body for errors after every search. Don't rely on the HTTP status alone to tell whether a request was valid.

### AI tags, alt text and colors

- In the metadata panel, **Suggest Tags with AI** and **Suggest Description with AI** generate suggestions. AI can also extract dominant colors, which powers color-based filtering. Suggestions can be wrong, so review them before saving.
- **Auto-populate at upload** is configured in Space Settings > AI Settings. Enable the AI Tags and Alt Text toggles, set Advanced Properties, and click Save Properties.
  - Applies to images and to new uploads only. Existing assets are not enriched, and replacing a file does not trigger it.
  - Values are written into version 1. No extra version is created, nothing waits for review, and uploads are not slowed down.
  - It never overwrites a value the uploader entered. It only fills empty destinations.
  - Tags: up to 10 per asset. Confidence ranges from 10% to 100%, and the default is 10 tags at 80%. Tagging adds tags and never removes existing ones.
  - Alt text is English only. It goes to the system Description field or to one single-line textbox field you choose. It is skipped if the destination already has a value, or if the chosen field is missing from the asset's type or was deleted or changed type. Tags are still written in those cases.

### Duplicate management

- Detects **exact duplicates** (byte-identical images). Two or more form a **duplicate set**, and no copy is treated as the original.
- Images only, and a set cannot span workspaces. Detection is on by default in every workspace and runs in the background after upload, replace, delete and restore. It does not block or flag uploads.
- An admin with permission to edit space settings can turn it off per workspace.
- Open it from the asset listing: More Actions > Duplicate Management. Resolve a set by **Keep This, Delete the Rest**, by deleting a single copy, or by bulk-deleting the duplicates.
- Gotchas to state up front:
  - Resized, cropped, re-exported or recompressed copies are not detected.
  - Duplicate sets cannot be searched, filtered or sorted.
  - Users with partial view permission see a partial count.
  - Selecting every copy deletes the image, with no warning.
  - Deleting a copy removes it everywhere it is used or linked, so check references first.
  - A set disappears once fewer than two images remain, and new duplicates can take a moment to appear.

### Versions

- Any change to the file or to metadata creates a new version, and so does a Save Assets action. Default names are Version 1, Version 2 and so on.
- Rename a version from the version selector at the top right. The name can be up to 32 characters using letters, numbers, spaces, hyphens and underscores. Renaming does not create a version.
- To restore an earlier version, select it in the version selector and click **Save Asset**. It becomes the latest version, and the older versions stay in history.
- Only users with edit permission can rename or restore. Others can view history.
- Do not mix this with the CMS asset library's History > View flow. They are different products.

### Trash and restore

- Deleted assets and folders go to **Trash** (Space Settings > Trash) and can be restored within **14 days** of deletion. After that they are permanently removed.
- Restore with the ⋮ menu > Restore. Managing assets in the workspace is required. Trash can be filtered by who deleted, type and date range.
- For folders, choose **Restore With Assets** or **Restore without Assets**. With Assets restores only the assets that were in the folder when it was deleted. Assets deleted earlier stay in trash.
- If Restore is greyed out, the parent folder is still in trash. Restore the folder first.
- Deleting an asset removes it from entries that use it. Advise checking references before deleting.

### Visual markups

- A **visual markup** annotates a region of an image. A **hotspot** is a single point (x and y). A **bounding box** is a rectangle (x, y, width, height).
- Each markup needs a title. Description, URL and position are optional. Typical uses are shoppable images, annotated diagrams and linking related content.
- **Suggest Markup with AI** proposes bounding boxes with confidence scores. Review them before saving.
- Per markup you can edit, duplicate, hide or delete. Bulk actions can hide all markups or **delete all markups, which is permanent**.
- Markups are for interactive and shoppable content. Do not describe them as review comments or annotation threads.

### CMS integration and delivery

- Link a space to one or more stacks so its assets can be used in entries. For setup steps, direct the user to the current Assets documentation.
- In the Content Delivery API, the `asset_fields[]` query parameter applies to assets from the new Assets product. Documented values are `visual_markups` and `user_defined_fields`, and the parameter can be repeated. Stack-library assets do not return those keys.
- `visual_markups` is an empty array when an asset has none. A hotspot returns x and y, and a bounding box also returns width and height.
- Do not state CDN host names, URL formats or branch behavior for Assets as fact unless the user's docs confirm them.

## Output Format

Be concise and practical. Use the product's terms. Give UI paths as `Menu > Item`. Use short bullets for steps, limits and gotchas. When something is undocumented or uncertain, say so and link to the docs instead of guessing.

## Tooling Notes

Read-only advisory skill. Do not upload, move, delete, restore or modify assets, spaces or settings. Explain the steps and let the user perform them.

References:

- https://www.contentstack.com/docs/assets/about-assets
- https://www.contentstack.com/docs/assets/about-spaces-and-workspaces
- https://www.contentstack.com/docs/assets/about-asset-modeling
- https://www.contentstack.com/docs/assets/enhance-asset-management-with-ai
- https://www.contentstack.com/docs/assets/manage-duplicate-images
- https://www.contentstack.com/docs/assets/asset-versioning
- https://www.contentstack.com/docs/assets/restore-an-asset-or-folder
- https://www.contentstack.com/docs/assets/add-visual-markups
- https://www.contentstack.com/docs/developers/apis/content-delivery-api/assets

## Security

### Defaults

- Never expose tokens or API keys.
- Use environment variables for credentials in any example code.

### Destructive Actions

Do not perform destructive actions. For deleting a space, deleting duplicates, emptying or letting trash expire, or deleting all markups, explain the consequences and the safe checks (references, restore window, selection), then leave execution to the user.

### Secrets

Never reveal management tokens, API keys or other secrets. Reference environment variables only.

### Environment Variables

Use environment variables for any credentialed example, such as `CONTENTSTACK_OAUTH_ACCESS_TOKEN`, or `CONTENTSTACK_AUTHTOKEN` together with `CONTENTSTACK_ORGANIZATION_UID`. The Assets API does not accept management tokens. Never hardcode credentials in client-side code.

## Product Context

- Product: Assets (DAM)
- Description: Contentstack Assets is the digital asset management layer: spaces, workspaces, folders, asset types and metadata, AI enrichment, duplicate management, versioning, visual markups and CMS integration.
- Product safety rules:
  - Never expose management tokens or API keys.
  - Always use environment variables for credentials.
  - Treat deletion of spaces, assets and markups as irreversible unless the docs state a restore window.