Asset model

Folders, assets, capabilities, and metadata as the content endpoints return them.

The content endpoints return two kinds of item: folders and assets. Folder browse and search both return the same envelope, so once you can read one result you can read the other. This page describes that shape. The individual endpoint references describe the requests that produce it.

Result envelope

{
  "folders": [
    { "id": "folder-123", "name": "Brand Assets" }
  ],
  "assets": [
    { "id": "asset-456", "name": "logo.png" }
  ],
  "filters": [],
  "more": "p2",
  "capabilities": {},
  "totalAssetsCount": 218
}

Field	Type	Meaning
`folders`	array	Subfolders at this level. Each carries at least an `id` and a `name`. Browse into one by passing its `id` to the folder endpoint.
`assets`	array	Assets at this level. The asset shape is described below.
`filters`	array	Search facets the connection exposes, mainly on search results (some providers also return them on folder browse). Same structure as the `filters` from Provider info. Render them in the search UI. Empty when the provider has no facets.
`more`	string \| number	Opaque pagination cursor for the `assets` list. Present when more assets exist beyond this page, absent at the end. Pass it back unchanged. See Pagination.
`capabilities`	object	What the current user may do in this folder (add an asset, add a subfolder, and so on). See Capabilities.
`totalAssetsCount`	number	Total assets in this folder or search across all pages. Counts assets, not folders.

The asset shape is normalized by CI HUB across every DAM, so the same field carries the same meaning whether the provider is Bynder, AEM, or Frontify. Each provider fills the fields its system supports and adds provider-specific fields beyond the common set. Read the fields your integration needs and ignore the rest.

Folders and assets

Folders form a tree. Start from the root folder, read its folders array, and browse into a child by its id. Assets are the leaves: the files a user selects, downloads, or inserts.

Folder and asset IDs are opaque strings and can contain slashes, because some DAMs encode a path into the ID. Pass them through as you received them, without URL-encoding the slashes; the endpoints accept the ID as a catch-all path segment.

Asset shape

{
  "id": "asset-456",
  "name": "logo.png",
  "parentPath": "/Brand Assets",
  "mimeType": "image/png",
  "fileSize": 48213,
  "xSizePx": 1200,
  "ySizePx": 630,
  "created": 1714003200000,
  "modified": 1715212800000,
  "version": 3,
  "thumbnailUrl": "https://stage.ci-hub.com/api/v1/assets/thumbnail?...",
  "downloadUrl": "https://stage.ci-hub.com/api/v1/assets/download/asset-456?cihubSig=...",
  "assetDetailsExternalUrl": "https://dam.example.com/assets/456",
  "downloadHashSha256": "9f86d081...",
  "conversions": [],
  "values": [],
  "capabilities": {}
}

Field	Type	Meaning
`id`	string	Asset identifier. Opaque, may contain slashes.
`name`	string	Display name.
`parentPath`	string	Human-readable folder path. Optional.
`mimeType`	string	Content type, for example `image/png`.
`fileSize`	number	Size in bytes.
`xSizePx` / `ySizePx`	number	Pixel dimensions, for image assets.
`created` / `modified`	number	Epoch milliseconds.
`version`	number	Version number of the asset.
`thumbnailUrl`	string	URL for a preview image. See Asset URLs.
`downloadUrl`	string	URL for the full file. See Asset URLs.
`assetDetailsExternalUrl`	string	Link that opens the asset in the provider's own UI.
`type`	string	Asset kind, for example `PRODUCT` on PIM-style providers. The value set is provider-dependent.
`downloadHash*`	string	Content hash for integrity checks. Exactly one appears (for example `downloadHashSha256`); which one depends on the provider's `assetHashAlgorithm` (see Provider info).
`conversions`	array	Alternate renditions (sizes, formats), each with its own URL. May be empty.
`values`	array	Provider metadata fields (custom attributes, tags). Optional.
`capabilities`	object	Per-asset permissions. See Capabilities.

Providers add their own fields beyond this set (a caption, a copyright string, a low-resolution URL). Treat the asset as provider-specific past the common fields and read only what you use.

Capabilities

capabilities reports what the current user may do, as boolean flags. Use them to gate affordances in your UI rather than discovering a restriction when a call fails. Common flags:

Flag	Meaning
`canAddAsset`	Upload an asset into this folder.
`canAddFolder`	Create a subfolder.
`canUpdateAsset`	Replace an asset's file.
`canDeleteAsset` / `canDeleteFolder`	Delete the item.
`canRenameAsset` / `canRenameFolder`	Rename the item.
`canLockAsset` / `canUnlockAsset`	Lock or unlock the item.

A flag that is absent means the provider does not report on that action. Phase 1 of the SDK is read-only, so the write-related flags are informational for now.

Metadata

values is an optional array of the provider's metadata fields for an asset (custom attributes, keywords, tags), each entry carrying an identifier and a value. The set of fields is defined by the DAM and varies between connections, so read by field identifier rather than position.

Provider-dependent behavior

Not every DAM supports every feature. Versioning, similarity search, and asset detail are present on some providers and absent on others. Read Provider info once a connection exists to learn what the connected provider supports, and gate your UI on that.

Most providers return plain file assets. Some PIM-style providers also expose products and snippets, marking them with a type (such as PRODUCT) and carrying their structured fields under values. The type value set is provider-dependent, so read it by value rather than assuming a fixed list.

Pagination →

The more cursor and the size parameter

Asset URLs →

Resolve and fetch thumbnail and download URLs