Migrate from deprecated Media Bank asset endpoints

Two Media Bank endpoints for reading asset data are deprecated and scheduled for removal on
1 October 2026:

Deprecated endpoint	Replacement endpoint
`GET /assets/{id}`	`POST /assets/{id}/views`
`POST /assets/search/by-ids`	`POST /assets/views/by-ids`

The replacement endpoints let you request only the asset data you need. Update and test your client
against the Test environment before the deprecated endpoints are removed.

Select the asset data you need

Pass a views array in the request body. The supported views are:

View	Returned data
`METADATA`	Asset number, name, description, file name, timestamps, creator, and internal/published flags
`MEDIAINFO`	Media type, content type, storage information, file size, dimensions, resolution, duration, and image flags
`LABELS`	Asset labels
`ATTRIBUTES`	Asset attribute values

You can limit ATTRIBUTES to selected attribute definitions:

{
  "views": [
    {
      "type": "ATTRIBUTES",
      "definitionIds": ["attribute-definition-id"]
    }
  ]
}

If views is empty or omitted, the response contains only asset IDs.

Migrate a single-asset request

The asset ID remains in the path, but the method changes from GET to POST and the request gains a
body.

Deprecated request:

curl "$BLUESTONE_API_BASE/media-bank/assets/$ASSET_ID" \
  -H "Authorization: Bearer $TOKEN"

Replacement request:

curl -X POST "$BLUESTONE_API_BASE/media-bank/assets/$ASSET_ID/views" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "views": [
      { "type": "METADATA" },
      { "type": "MEDIAINFO" }
    ]
  }'

The replacement returns the asset ID and the requested sections:

{
  "id": "asset-id",
  "metadata": {
    "number": "ASSET-001",
    "name": "Product image",
    "fileName": "product-image.jpg"
  },
  "mediaInfo": {
    "mediaType": "IMAGE",
    "contentType": "image/jpeg",
    "fileSize": 123456
  }
}

Do not expect sections that were not included in views.

Retrieve product and category associations

The deprecated asset response also contained products and categories. These associations are not
available in the replacement Media Bank response. Media Bank supports only METADATA, MEDIAINFO,
LABELS, and ATTRIBUTES; there is no PRODUCTS or CATEGORIES view.

Retrieve associations from the PIM API instead.

Products linked to assets

Use POST /pim/products/list/views/by-assets. For a single asset, pass its ID in assetIds. If you
only need the matching product IDs, omit views:

curl -X POST "$BLUESTONE_API_BASE/pim/products/list/views/by-assets" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assetIds": ["asset-id"],
    "page": 0,
    "pageSize": 100
  }'

For several asset IDs, request the product ASSETS view so each returned product can be mapped back
to the assets it contains:

{
  "assetIds": ["asset-id-1", "asset-id-2"],
  "page": 0,
  "pageSize": 100,
  "views": [
    { "type": "ASSETS" }
  ]
}

The endpoint accepts up to 100 asset IDs per request. Follow the product response pagination until all
matches have been retrieved.

Categories linked to an asset

Use GET /pim/catalogs/nodes/assets/{asset-id}:

curl "$BLUESTONE_API_BASE/pim/catalogs/nodes/assets/$ASSET_ID?page=0&pageSize=1000" \
  -H "Authorization: Bearer $TOKEN"

The response contains the categories associated with that asset. Follow its pagination if necessary.

If a client previously obtained asset details, products, and categories in one Media Bank call, it
must now combine the Media Bank view response with these PIM lookups.

Migrate a bulk request

The replacement bulk endpoint accepts between 1 and 100 asset IDs. Rename assetIds to ids and
remove the legacy paging and ordering fields.

Deprecated request:

{
  "assetIds": ["asset-id-1", "asset-id-2"],
  "order": "SPECIFIED",
  "page": 0,
  "resultsPerPage": 100
}

Replacement request:

curl -X POST "$BLUESTONE_API_BASE/media-bank/assets/views/by-ids" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["asset-id-1", "asset-id-2"],
    "views": [
      { "type": "METADATA" },
      { "type": "LABELS" }
    ]
  }'

The response contains a data array:

{
  "data": [
    {
      "id": "asset-id-1",
      "metadata": {
        "number": "ASSET-001",
        "fileName": "product-image.jpg"
      },
      "labels": ["Product image"]
    }
  ]
}

Map returned items by id instead of relying on their array position.