Asset Changes

Overview

Asset Changes is how API clients that are storing Getty Images content on their own platforms keep up to date with the Getty Images catalog. For these clients, it is critical that they stay in sync with the catalog, especially when assets are removed from the catalog and thus need to also be removed from the client system. For most clients, the removal of deleted assets is a contractual obligation.

Asset Changes provides clients with notifications for new, updated and deleted assets. The type of notification is determined by the asset_lifecycle value for each asset in the response to a request to PUT /v3/assets/asset-changes/change-sets.

• New - assets that are newly available through the client’s license agreement.
• Update - assets that have updated metadata (usually keywords and captions).
• Delete - assets that have been removed from the Getty Images catalog or are no longer available for use. These assets must be removed from the client system.

Channels

Asset Changes are divided into channels. Each channel contains new, update, and delete messages for a particular type–Image or Film–and family–Editorial or Creative–of asset. The range of assets represented by these messages is governed by the bundles to which the client has access through its associated agreements.

Clients of Asset Changes will have up to four channels (*), one each for:

• Editorial Images
• Creative Images
• Editorial Film
• Creative Film

Clients can retrieve their list of channels via the GET /v3/asset-changes/channels endpoint. It is recommended to call this endpoint infrequently as these channels will not change once established. A good practice would be to call for the channel list once at application startup and cache the results.

(*) Prior to March 2025, channels were additonally divided by lifecycle, so a client would have separate channels for delete messages, new messages and update messages. From March 2025 onward, we will be permanently combining the lifecycles into a single channel per asset type and family.

General Process

Consuming asset changes, no matter what the asset lifecycle, consists of a general pattern:

1. Call PUT /v3/assets/asset-changes/change-sets for a specific channel ID and batch size to get the next batch of changes and the change set identifier.
2. Process these changes on the client’s end.
3. Call DELETE /v3/asset-changes/change-sets/{change-set-id} to confirm that the changes were received and processed.
4. If there were no changes in the response from the PUT call (i.e. the client is “caught up”), delay for a short period of time.
5. Start over at step 1.

New changes will not be returned from PUT /v3/assets/asset-changes/change-sets until the current change set is confirmed. If changes are not confirmed, the client will simply get the same batch that they initially called for from the PUT call.

Message Order / Lifecycle

Within the bounds of a specific channel, messages are delivered in ascending chronological order. Client systems should be designed to handle multiple messages regarding a given asset, sometimes in a short span of time. Also, since Getty does not store the state of a given asset in the context of a specific client, messages may arrive in an order that might be unexpected in terms of lifecycle. e.g. an Update message may arrive before a New. Lastly, Delete messages may arrive for assets to which clients do not have (or never had) access.

Given these points, there are some basic recommendations which should keep client systems running smoothly:

• Consider any “New” or “Update” message to be an “Upsert.” i.e. the client should first check if a record of the asset exists on the client’s side and either:
  • update the record if it exists OR
  • insert a new record.
• A “Delete” message for an asset which is unknown to a client should simply be ignored.

Example Workflow

The following diagrams illustrate an effective example of a workflow that an Asset Changes client can use to effectively consume and process messages.

Client Loop

Change Message Processor

This example expands on some simple logic for how the “Change Message Processor” from the Client Loop above might work. Note the “Upsert” recommended in Message Order / Lifecycle above.