Dynamic Media with OpenAPI (2025.07-experimental)

Download OpenAPI specification:Download

Assets

APIs for working with asset binaries

Returns web-optimized binary representation of the asset in the requested output format

The seo-name doesn't have a functional impact on the image, but is provided to allow for adding SEO value to asset URLs. The assetId is an opaque string defined by the content repository that can be used to target the asset resource.

In the URL construction, an SEO name and an output image format must be provided.

Additional transformations to be applied on that output can (optionally) be specified as query parameters, and the syntax and examples are listed in the Query Parameters section of this document.

To name a few:

  • crop
  • height
  • width
  • quality
  • smartcrop
  • blur
  • sharpen
Smart Imaging
Smart imaging automatically optimizes the image delivery to provide the best balance of visual quality, image size, and response time. This results in faster page loads, reduced bandwidth usage, and a consistently high-quality experience across devices and network conditions.

  • Auto Format Conversion: Images are automatically converted to modern, web-optimized formats (such as AVIF or WebP) based on browser capabilities and customer entitlements irrespective of requested format. These formats provide better compression, thus making images smaller and faster to deliver and load. Read more at File format's impact on image delivery and rendering performance.
    To disable, set the auto-format query parameter to false.
  • Automatic Quality Adjustment: Image quality-factor is automatically applied based on the client's network conditions, ensuring faster image delivery and loading under all conditions.
    See quality and max-quality for additional information on tweaking this behaviour.
Image Composition
The API supports composing a single output image based on segregation of operations applied to specific portions of the artwork (e.g., "applying a background color to an image that has an alpha channel, but after scaling it down to occupy only 25% of the total area of the image").

To learn more about Image Composition, please review the documentation for layers
SecurityNone or Bearer
Request
path Parameters
assetId
required
string (AssetId) non-empty

ID of the asset

Example: urn:aaid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
seoName
required
string([%.\w-]+)

any url-encoded or alphanumeric, non-whitespace set of characters. may contain hyphens and dots

Examples:
banner
format
required
string

The Requested format.

NOTE: The format of the output image may be different from the requested format as smart imaging is enabled by default and based on the browser capabilities, customer entitlements, and transparency a web-optimized format is returned.

Enum: "gif" "png" "jpg" "jpeg" "webp" "avif"
Example: avif
query Parameters
object or integer

Specifies the width of the output image in pixels. This parameter allows you to control the horizontal dimension of either the final output image or a specific layer. The width must be a positive integer (minimum value: 1).

When used in combination with the height parameter, the aspect ratio of the original image is preserved. This means the actual output width may be smaller than the requested value to preserve aspect ratio.

If not defined, the image width defaults to a maximum of 2048 pixels.

Examples without layer:

  • width=200 - Set width of final output image to 200 pixels

Examples when used with a layer named layerName:

  • width[layerName]=200 - Set width of specific layer to 200 pixels

Only one of width or width[layerName] should be used at a time.

quality
integer [ 1 .. 100 ]

Specifies the compression quality for the image. Quality value ranges from 1 to 100, where 100 is the highest quality (least compression) and 1 is the lowest quality (highest compression).

A higher quality value results in better image quality but larger file size, while a lower value reduces file size at the cost of image quality.

Note: For dynamic quality based on network conditions, use max-quality instead of quality.

Example:

  • quality=85 - Set quality of final output image to 85

Only the global quality parameter is supported.

max-quality
integer [ 1 .. 100 ]

Specifies the maximum quality for the image when delivery-engine dynamically adjusts the quality of the image based on the client's network bandwidth. The value ranges from 1 to 100, where 100 is the highest quality (least compression) and 1 is the lowest quality (highest compression).

By default, the value is set to 85 and network-based dynamic quality adjustment is enabled.

Unlike the static quality parameter, max-quality acts as an upper bound. The actual quality used for image delivery may be reduced below this value depending on the round-trip time (RTT) and network conditions of the requester. This helps optimize image delivery for faster loading on slower networks by reducing file size when needed.

Note: If quality is specified, max-quality is ignored.

Example:

  • max-quality=85 - Set the maximum quality to 85; actual delivered quality may be lower based on network speed

max-quality parameter is only applied at final output image.

object or string

Applies intelligent cropping to automatically identify and preserve visually most important areas of the image for a given crop-region. This operation uses AI-powered content-aware cropping to ensure that key elements like faces, text, or focal points are retained in the output.

The smartcrop parameter expects that named-smartcrop-profiles exist and have been applied to the asset. Those predefined profile names - specifying the target dimensions and aspect ratio of the cropped image - can be supplied as values of this parameter. The cropping can be applied either to a specific layer or to the final output image.

Examples without layer:

  • smartcrop=QHD - Apply a smartcrop profile named QHD to final output image

Examples when used with a layer named layerName:

  • smartcrop[layerName]=QHD - Apply a smartcrop profile named QHD to a specific layer

Only one of smartcrop or smartcrop[layerName] should be used at a time.

NOTE: Specifying an unresolvable smartcrop profile-name (the one that hasn't been defined, or hasn't been applied to the asset being requested) will lead to an error response.

object or number

Device Pixel Ratio (DPR) (also known as CSS pixel ratio) is the relation between a device's physical pixels and logical pixels.

Enabling Device Pixel Ratio optimization with HTML5 Responsive Imaging techniques renders the image at the native resolution of the screen which makes it sharp. For more information about DPR and how it affects image resolution, see MDN Documentation for devicePixelRation property of browser-window object.

Examples without layerName:

  • dpr=2 - Renders the final output image at twice the requested dimensions to support high-DPI displays

Examples when used with a layer named layerName:

  • dpr[layerName]=2 - Renders a specific layer at twice the requested dimensions to support high-DPI displays
object or integer

Specifies the height of the image or a specific layer in pixels. When applied to the final output image or a layer, the image is scaled to match the specified height while maintaining the aspect ratio.

The value must be a positive integer (minimum: 1 pixel).

NOTE: If not defined, the height is automatically scaled to maintain aspect ratio based on the width (specified, or default). If defined alongside width, the dimensions of the output (or the layer) layer image are computed by applying fit=contain (see more here).

Examples without layer:

  • height=200 - Set height of final output image to 200 pixels

Examples when used with a layer named layerName:

  • height[layerName]=200 - Set height of specific layer to 200 pixels

Only one of height or height[layerName] should be used at a time.

object or boolean

Applies a sharpening filter to enhance the edges and details in the image. The sharpening is applied either to a specific layer or to the final output image after all scaling operations are complete.

When enabled, this operation increases the contrast between adjacent pixels to make the image appear more crisp and detailed.

Examples without layerName:

  • sharpen=true - Apply sharpening to the final output image

Examples when used with a layer named layerName:

  • sharpen[layerName]=true - Apply sharpening to a specific layer

Only one of sharpen or sharpen[layerName] should be used at a time.

object or integer

Applies a blur filter to soften the image. The blur can be applied either to a specific layer (when layerName is provided) or to the final output image (when no layerName is specified). The radius parameter determines the strength of the blur effect in pixels relative to the final output image, with a value between 0 and 100 pixels.

Examples without layerName:

  • blur=5 - Apply a blur filter to the final output image with a radius of 5 pixels

Examples when used with a layer named layerName:

  • blur[layerName]=5 - Apply a blur filter to a specific layer with a radius of 5 pixels
object or Array of strings

Crop is specified by four comma-separated values, each a number with up to two digits after the decimal point, followed by p.

First two specify the origin (top, left) of the desired cropped region as percentages of width and height of the original image, respectively.

Last two specify the size of the cropped region relative to original dimensions of the asset.

A valid crop region MUST meet both of the following constraints:

  • <x-origin> + <crop-region-width> <= 100
  • <y-origin> + <crop-region-height> <=100

Requests which don't meet aforementioned constraints will fail.

Examples:

  • crop=10p,10p,50p,50p - Crop the final output image starting at 10% from top and left, taking 50% of width and height of the final output image
  • crop[layerName]=10p,10p,50p,50p - Crop a specific layer starting at 10% from top and left, taking 50% of width and height of the final output image
object or string

Image Preset represents a predefined collection of sizing and formatting modifiers for output image. Image Preset is a feature provided in AEM Assets. Post generation of a preset, it can be applied to the output image by specifying the preset name in this modifier.

To generate a preset, please refer to the documentation here.

Examples without layer:

  • preset=preset-name

Examples when used with a layer named layerName:

  • preset[layerName]=preset-name
layers
string

Layers allow composition of a single output image from multiple segregations, each of which may have specific operations applied to them. Search for layerName in the documentation to identify the parameters that can be applied to layers.

The layers which segregate the operations (and are finally aggregated to compose the single output image) are addressed by the names in the value of this parameter. These names are then used in rest of the parameters (which can be applied to layers) in the URL. The names are to be separated by the | character, and need to appear in the order in which they are painted when aggregated to produce the output image (rightmost layer specified in this parameter is painted the last when composing the aggregate.

Layer names are case-sensitive and can have any alphanumeric characters (a-z, A-Z, 0-9).

NOTE: base is reserved for the "base" layer - the lowermost layer (even if specified in the layers parameter at any other position) and will always be included (even if omitted from the layers parameter). i.e., layers=base|mid|top, layers=mid|top and layers=mid|base|top are all equivalent, and the recommendation is to follow either the first or the second pattern.

NOTE: Nested layers are not supported, and the layers parameter can not applied to any other layer. e.g., layers=top&layers[top]=top1|top2 is invalid.

Examples:
a request for a final output image composed of two layers.
layers=top
a request for a final output image composed of three layers.
layers=base|mid|top
a request for a final output image composed of three layers, but the base layer is omitted.
layers=mid|top
object or object

Specifies the resizing behavior when fitting the image within the output dimensions specified with width or height.

In the following description of the mode options, it is assumed that

  • xScale is the ratio of the original image width to the output image width, and
  • yScale is the ratio of the original image height to the output image height.

It takes the following values:

Parameter Description
contain (default) Scales the original image so that it fits the bounding-box of width and height dimensions while preserving the aspect-ratio of the image-content. The output image has the exact size specified with width and height, with additional transparent pixels (padding) added to the output. The smaller of xScale and yScale is applied.
constrain Scales the original image so that it fits the bounding-box of width and height dimensions while preserving the aspect-ratio. The output image may be smaller than specified with width and height to avoid additional transparent pixes (padding) to the output, and is never cropped. The smaller of xScale and yScale is applied.
crop Scales the original image so that it fills a bounding-box of width and height dimensions. The output image has the exact size specified with width and height, but may be cropped to avoid additional transparent pixes (padding) to the output. The larger of xScale and yScale is applied.

The color and transparency of the whitespace fill is determined by background-color and transparency.

Examples without layer:

  • fit=contain

Examples when used with a layer named layerName:

  • fit[layerName]=contain

NOTE: Attempting to apply fit without requesting atleast one of width or height (explicitly, or implicitly) will result in an error.

(ColorFormatString (ColorFormatString (string) or ColorFormatString (string) or ColorFormatString (string) or ColorFormatString (string))) or object

Specifies the background color for the transparent areas of the image or selected layer.

This operation takes following parameter values:

Parameter Description
colorspace (Mandatory) One of the supported colorspaces, with or without alpha
color-value (Mandatory) A color value corresponding to the specified colorspace, specified in hexadecimal

Defaults to fully transparent.

Composite Imaging - Usage with layers
background-color can be used with and without addressing a specific, named layer. However, based on the operations performed on the implicit base layer, background-color's behaviour can help achieve additional effects in the composite images.

Certain operations can introduce transparent pixels (padding, see fit) beyond the bounds of the image that forms the base layer. In such cases, specifying background-color without any layer qualifier allows specifying the color to apply to the padding.
More concretely:
  • background-color=rgb,ff0000: apply saturated red to the background of the base layer, including padding beyond the bounding-box of the base layer.
  • background-color[base]=rgb,ff0000: apply saturated red to the background of the base layer, but only within the bounding-box of the base layer and exclude any padding from being affected by the operation.

Examples without layer name:

  • background-color=gray,7F - Gray color
  • background-color=graya,7FFF - Gray color with alpha
  • background-color=rgb,808080 - RGB color
  • background-color=rgba,32808080 - RGB color with alpha

Examples with layer name:

  • background-color[layerName]=gray,7F - Gray color for specific layer
  • background-color[layerName]=graya,7FFF - Gray color with alpha for specific layer
  • background-color[layerName]=rgb,808080 - RGB color for specific layer
  • background-color[layerName]=rgba,32808080 - RGB color with alpha for specific layer
(ColorFormatString (ColorFormatString (string) or ColorFormatString (string) or ColorFormatString (string) or ColorFormatString (string))) or object

Specifies the foreground color for the image or selected layer.

This operation takes following parameter values:

Parameter Description
colorspace (Mandatory) One of the supported colorspaces, with or without alpha
color-value (Mandatory) A color value corresponding to the specified colorspace, specified in hexadecimal

Defaults to fully transparent.

Examples without layer name:

  • foreground-color=gray,7F - Gray color
  • foreground-color=graya,7FFF - Gray color with alpha
  • foreground-color=rgb,808080 - RGB color
  • foreground-color=rgba,32808080 - RGB color with alpha

Examples with layer name:

  • foreground-color[layerName]=gray,7F - Gray color for specific layer
  • foreground-color[layerName]=graya,7FFF - Gray color with alpha for specific layer
  • foreground-color[layerName]=rgb,808080 - RGB color for specific layer
  • foreground-color[layerName]=rgba,32808080 - RGB color with alpha for specific layer
auto-format
boolean

Controls the behaviour of browser format conversion for Smart Imaging capabilities. When auto-format is true, the requested format is ignored and a web-optimized format based on image-characteristics, browser capabilities, and license-entitlement is selected automatically.

The default value is true, which enables automatic format conversion. This can be disabled by specifying auto-format as false, in which case the requested output-format will be returned.

For example,

  • When true, an avif output is delivered (if the browser supports avif and the license-entitlements allow it), even when the requested format is jpeg.
  • When true, a webp output is delivered if the browser doesn't support avif, but does support webp, even when the requested format is jpeg.
  • When true, a jpeg output is delivered if the browser doesn't support avif or webp and the image doesn't have an alpha channel (transparency), even when the requested format is avif.
  • When false, a jpeg output is delivered (irrespective of the browser capabilities and license-entitlements) when the requested format is jpeg.

Examples:

  • auto-format=true - Enable browser format conversion (default)
  • auto-format=false - Disable browser format conversion
object or object

Applies an Unsharp Masking filter on the output image to produce a sharpening effect. The effect can be tuned for intensity, radius (measured in pixels), and a threshold of contrast (beyond which the effect is ignored). This modifier uses the same options as Photoshop's "Unsharp Mask" filter.

This operation accepts following parameters in the value:

Parameter Description
amount (Mandatory) Filter strength factor (real 0-500).
radius (Mandatory) Filter kernel radius in pixels (real 0-1000).
threshold (Optional, default: 0) Filter threshold level (int 0-255).
monochrome (Optional, default: false) If true, only applies to the image brightness (intensity). If false, applies to all color components separately.

Examples without layer:

  • unsharp-mask=100,10 - apply basic unsharp mask operation to the output image
  • unsharp-mask=100,10 - apply basic unsharp mask operation to the output image
  • unsharp-mask=100,10,10,true - apply the unsharp unsharp mask operation to the output image

Examples when used with a layer named layerName:

  • unsharp-mask[layerName]=100,10 - apply basic unsharp mask operation to the layer
  • unsharp-mask[layerName]=100,10 - apply basic unsharp mask operation to the layer
  • unsharp-mask[layerName]=100,10,10,true - apply the unsharp unsharp mask operation to brightness component of the image
attachment
string

Setting this parameter to true forces "download" prompt in browser by adapting the Content-Disposition appropriately.

Default is false.

Enum: "true" "1" "false" "0"
Example: attachment=true
object or string

Flips (mirrors) the image or a specific layer horizontally, vertically, or both. This operation is useful for adjusting the orientation of content within layers.

Supported values:

  • h - Horizontal flip (left-to-right mirror)
  • v - Vertical flip (top-to-bottom mirror)
  • hv - Both horizontal and vertical flip

Examples without layer:

  • flip=h - Flip the final output image horizontally
  • flip=v - Flip the final output image vertically
  • flip=hv - Flip the final output image both horizontally and vertically

Examples when used with a layer named layerName:

  • flip[layerName]=h - Flip a specific layer horizontally
  • flip[layerName]=v - Flip a specific layer vertically
  • flip[layerName]=hv - Flip a specific layer both horizontally and vertically

Only one of flip or flip[layerName] should be used at a time.

object or integer

Rotates the image or a specific layer by a fixed angle in clockwise direction. The rotation is performed around the center point of the image or layer.

Rotation angle must be a multiple of 90 degrees and can be either of '90', '180', or '270' degrees clockwise.

Examples without layer:

  • rotate=90 - Rotate final output image 90 degrees clockwise
  • rotate=180 - Rotate final output image 180 degrees
  • rotate=270 - Rotate final output image 270 degrees clockwise

Examples when used with a layer named layerName:

  • rotate[layerName]=90 - Rotate specific layer 90 degrees clockwise
  • rotate[layerName]=180 - Rotate specific layer 180 degrees
  • rotate[layerName]=270 - Rotate specific layer 270 degrees clockwise

Only one of rotate or rotate[layerName] should be used at a time.

fallback
string
This modifier is currently in Limited Availability.
Click here to learn how to request access.

Specifies the fallback image to be used when the requested image cannot be found. This is useful for substituting missing images with default images.

If the original image does not exist and no fallback is specified, an error is returned.

Important: If the fallback image itself does not exist, an error is returned.

Examples without layer:

  • fallback=urn:aaid:aem:1a034bee-ebda-4787-bad3-f924d0772b75 - Use a specific image as fallback when the requested image is not found

NOTE: When a fallback image is used, it replaces the missing image while maintaining the original request's attributes for the layer.

Array of FourTuple (integers) or Array of FourTupleRelative (strings) or object
This modifier is currently in Limited Availability.
Click here to learn how to request access.

Adds additional pixels around a layer (e.g., adding a border) or makes the layer smaller by clipping-off pixels. The extend operation is applied to the output image or layer after other modifiers have been applied.

The default value is 0,0,0,0, which means no change to the layer rectangle.

The extended area is filled with background-color, or if not specified, remains transparent.

Can be specified as:

  • Four comma-separated values specifying the number of pixels to add to (positive values) or remove from (negative values) the left, top, right, and bottom edge of the layer rectangle
  • Four comma-separated values followed by 'p' for relative (percent) dimensions relative to the original layer rectangle size

Examples without layer:

  • extend=5,5,5,5 - Add 5 pixels margin to all sides
  • extend=0,30,0,0 - Add 30 pixels margin to top only
  • extend=-10,-10,-10,-10 - Cut off 10 pixels from all sides
  • extend=10p,10p,10p,10p - Add 10% margin to all sides (relative)

Examples when used with a layer named layerName:

  • extend[layerName]=5,5,5,5 - Add 5 pixels margin to specific layer on all sides
  • extend[layerName]=10,0,10,0 - Add 10 pixels margin to left and right of specific layer
  • extend[layerName]=-5,0,-5,0 - Cut off 5 pixels from left and right of specific layer
  • extend[layerName]=20p,30p,80p,90p - Apply relative margins to specific layer
string or object
This modifier is currently in Limited Availability.
Click here to learn how to request access.

Specifies one or more clipping paths to be applied to the base layer (learn more about base layer here) or the selected layer, with optional inversion.

A clipping path is a vector path or shape used to isolate a portion of an image. Some image formats (such as TIFFs, PSDs, etc.) can embed clipping paths within the image-binary and identify them by names (ASCII strings). This modifier allows selection of named clipping paths as embedded in the image and applies them to the specified layer.

Normal vs Inverted Clipping:

  • Normal clipping: Any parts of the layer that fall outside the area defined by the clipping path are rendered transparent
  • Inverted clipping: Any parts of the layer that fall within the area defined by the clipping path are rendered transparent (prefix path name with ~)

More than one clipping path name (separated by ,) can be specified. When multiple clipping paths are specified, each path is processed with its specified behavior (normal or inverted), and the results are combined to determine the final clipping effect on the layer.

Any clipping path names not found in the image are ignored when generating final output. If the intersection of selected clipping paths is an empty path, then the complete modifier is ignored.

Examples:

  • clip-path-names=path1 - Apply normal clipping with path "path1" on the base layer
  • clip-path-names=~path1 - Apply inverted clipping with path "path1" (makes area inside path transparent) on the base layer
  • clip-path-names[layerName]=path1,~path2,path3 - Apply normal clipping for "path1" and "path3", inverted clipping for "path2"
  • clip-path-names[layerName]=~path1,~path2 - Apply inverted clipping for intersection of "path1" and "path2"
integer or object
This modifier is currently in Limited Availability.
Click here to learn how to request access.

Allows increasing or decreasing the transparency of the output image.

Examples without layer:

  • transparency=50 - Set the transparency to 50%

Examples when used with a layer named layerName:

  • transparency[layerName]=50 - Set the transparency of specific layer to 50%
object
This modifier is currently in Limited Availability.
Click here to learn how to request access.

Controls the visibility of a layer without modifying the request URL structure. This is useful for:

  • Conditional content delivery - Show/hide layers based on user preferences, device capabilities, etc.
  • Preset-based workflows - Use a single URL template with multiple layers and programmatically control which layers are visible

Examples:

  • hide-layer[layerName]=false - The layer will be rendered normally (this is the default behaviour when hide-layer[layerName]modifier isn't specified)
  • hide-layer[layerName]=true - Hide the specified layer if previously defined (layer will not be rendered). Specifying a layerName that doesn't exist makes this modifier a no-op.
object or boolean
This modifier is currently in Limited Availability.
Click here to learn how to request access.

Inverts each color component for a negative image effect.

Examples without layer:

  • invert-color=true - Invert the colors of the final output image.

Examples when used with a layer named layerName:

  • invert-color[layerName]=true - Invert the colors of the layer.
object or object
This modifier is currently in Limited Availability.
Click here to learn how to request access.

Colorizes the image data while preserving shadows and highlights.

Colorize accepts the following parameter values:

Parameter Description
color (Mandatory) Replacement RGB color value.
autobrightness/noautobrightness (Optional, default autobrightness) Enable/Disable automatic brightness compensation.
contrast (Optional, default contrast) Adjusts the contrast level.

The second parameter specifies whether the brightness of the source image should be adjusted before colorizing. Specify noautobrightness to disable the automatic brightness compensation or autobrightness to adjust the brightness automatically so that the median value is at 50% intensity.

Set the contrast value to 0 to preserve the contrast range of the input image, or specify a desired contrast range with a value greater than 0. A value of 100 maximizes the contrast. Typical values might be between 30 and 70.

The colorizing algorithm uses only the luminance information in the image data. This conversion to grayscale is simple and not color-managed. colorize always outputs RGB data, even if the input is grayscale or CMYK

Properties:

  • The contrast value is ignored if brightness compensation is turned off.
  • The color-value specified in RGB color parameter is automatically converted to as appropriate to source image's or layer's pixel type before application.
  • CMYK images are converted to RGB before the operation is applied.

Colorization is disabled by default.

Examples without layer:

  • colorize=a0b0c0,autobrightness,50 - Colorize the image with a blue tint.

Examples when used with a layer named layerName:

  • colorize[layerName]=a0b0c0,autobrightness,50 - Colorize the layer with a blue tint.
integer or object
This modifier is currently in Limited Availability.
Click here to learn how to request access.

Decreases or increases the image brightness. The adjustment range is from -100 to +100, where -100 is the darkest and +100 is the brightest.

The default value is 0, which means no change in brightness.

Examples without layer:

  • brightness=10 - Increase brightness by 10 units
  • brightness=-10 - Decrease brightness by 10 units

Examples when used with a layer named layerName:

  • brightness[layerName]=10 - Increase brightness of specific layer by 10 units
  • brightness[layerName]=-10 - Decrease brightness of specific layer by 10 units

Only one of brightness or brightness[layerName] should be used at a time.

integer or object
This modifier is currently in Limited Availability.
Click here to learn how to request access.

Adjusts the image contrast by increasing the brightness of pixels with more than 50% brightness, and reducing the brightness of pixels with less than 50% brightness. The adjustment range is from -100 to +100, where -100 provides the lowest contrast and +100 provides the highest contrast.

The default value is 0, which means no change in contrast.

Examples without layer:

  • contrast=50 - Increase contrast by 50 units
  • contrast=-12 - Decrease contrast by 12 units

Examples when used with a layer named layerName:

  • contrast[layerName]=50 - Increase contrast of specific layer by 50 units
  • contrast[layerName]=-12 - Decrease contrast of specific layer by 12 units

Only one of contrast or contrast[layerName] should be used at a time.

string or object
This modifier is currently in Limited Availability.
Click here to learn how to request access.

Specifies how certain operations will behave if the image has a mask. This modifier allows specifying whether the operations that take mask into consideration are applied within the masked region (normal) or outside (inverted).

Following modifiers can alter their output when applied alongside mask:

  • colorize
  • hue
  • saturation
  • brightness
  • contrast
  • blur
  • sharpen
  • noise
  • invert-color

If no value is provided, mask modifier is off.

The following table illustrates the effect depending on availability and type of the mask (alpha channel) associated with the source image:

Mask Types:

  • Unassociated mask (straight alpha): RGB values are stored independently of transparency. Full color information is retained regardless of transparency level.
  • Associated mask (pre-multiplied alpha): RGB values are multiplied by alpha. Fully transparent areas lose their original color data.
Value Unassociated mask Associated mask
normal Foreground area of image Foreground area of image or layer
inverted Background area of image Background area of image or layer filled with solid black

Examples without layer:

  • mask=normal - Apply normal mask behavior
  • mask=inverted - Invert the mask to affect background area

Examples when used with a layer named layerName:

  • mask[layerName]=normal - Apply normal mask behavior to specific layer
  • mask[layerName]=inverted - Invert mask for specific layer to colorize background

Only one of mask or mask[layerName] should be used at a time.

object or integer
This modifier is currently in Limited Availability.
Click here to learn how to request access.

Changes the saturation of each visible pixel of the layer or output image. This allows for adjusting the color intensity of the image.

The saturation value can be an integer between -100 and +100:

  • Positive values increase color saturation
  • Negative values decrease color saturation
  • -100 fully desaturates the image (converts to grayscale)
  • 0 leaves the saturation unchanged

Examples without layer:

  • saturation=50 - Increase saturation of the output image by 50%
  • saturation=-60 - Decrease saturation of the output image by 60%
  • saturation=45 - Increase saturation for a high-key appearance
  • saturation=-35 - Decrease saturation for a more muted look
  • saturation=0 - Keep original saturation (no change)

Examples when used with a layer named layerName:

  • saturation[layerName]=50 - Increase saturation of the specified layer by 50%
  • saturation[layerName]=-100 - Fully desaturate the specified layer (convert to grayscale)
object or integer
This modifier is currently in Limited Availability.
Click here to learn how to request access.

Shifts the hue of each visible pixel of the layer or output image by the specified amount.

It takes value adjustment in degrees (-180…+180 int).

Properties: Applies to the current layer or to the output image. CMYK images or layers are converted to RGB before the operation is applied.

Examples without layer:

  • hue=50

Examples when used with a layer named layerName:

  • hue[layerName]=50
object or string
This modifier is currently in Limited Availability.
Click here to learn how to request access.

Adds random noise to the foreground image data.

Default value is 0 (no noise applied).

This operation takes following parameter values:

Parameter Description
amount (Mandatory) amount of noise in percent (0-100 int).
type (Optional) type of noise (uniform, gaussian). Default type: uniform
monochrome (Optional) monochromaticity of the added noise (false for color noise, true for monochrome). Default monochrome: false

Examples without layer:

  • noise=10 - Add 10% uniform noise to the image
  • noise=10,gaussian - Add 10% gaussian noise to the image
  • noise=10,uniform,true - Add 10% monochrome uniform noise to the image

Examples when used with a layer named layerName:

  • noise[layerName]=10 - Add 10% uniform noise to the specified layer
  • noise[layerName]=10,gaussian - Add 10% gaussian noise to the specified layer
  • noise[layerName]=10,uniform,true - Add 10% monochrome uniform noise to the specified layer

Note: The monochrome parameter has no effect for grayscale outputs since color noise is not possible to add.

object
This modifier is currently in Limited Availability.
Click here to learn how to request access.

Specifies the type of blending when there are multiple layers. Simulates commonly used blending modes available in Photoshop.

Value can be one of

  • dissolve
  • lighten
  • darken
  • multiply
  • screen

Examples:

  • blending-mode[layerName]=multiply - Apply multiply blending mode to specific layer
  • blending-mode[layerName]=lighten - Apply lighten blending mode to specific layer
  • blending-mode[layerName]=screen - Apply screen blending mode to specific layer
object or integer
This modifier is currently in Limited Availability.
Click here to learn how to request access.

Applies morphological erosion operation to pixels in the image. The value is in pixels relative to the output image.

This modifier performs an erosion (contraction) of the features in the image. See dilate modifier for a dilation (expansion) of image features.

NOTE: Specifying erode and dilate at the same time for a given source or layer isn't supported and can result in undefined behaviour. Examples without layer:

  • erode=3 - Contract image features by 3 pixels
  • erode=10 - Contract image features by 10 pixels Examples when used with a layer named layerName:
  • erode[layerName]=5 - Contract features in specific layer by 5 pixels
  • erode[layerName]=8 - Contract features in specific layer by 8 pixels
object or integer
This modifier is currently in Limited Availability.
Click here to learn how to request access.

Applies morphological dilation operation to pixels in the image. The value is in pixels relative to the output image.

This modifier performs a dilation (expansion) of the features in the image. See erode modifier for an erosion (contraction) of image features.

NOTE: Specifying dilate and erode at the same time for a given source or layer isn't supported and can result in undefined behaviour.

Examples without layer:

  • dilate=3 - Expand image features by 3 pixels
  • dilate=10 - Expand image features by 10 pixels Examples when used with a layer named layerName:
  • dilate[layerName]=5 - Expand features in specific layer by 5 pixels
  • dilate[layerName]=8 - Expand features in specific layer by 8 pixels
object
This modifier is currently in Limited Availability.
Click here to learn how to request access.

Specifies the position of the center of a given layer relative to center of the base layer.

The base layer is the asset specified by {assetId} in the API path /adobe/assets/{assetId}/as/seoname.<extn> - this is the primary layer onto which all other layers are positioned.

Can be specified as pixel offset or normalized offset from this layer's center to the base layer's center.

Can be specified as:

  • Pixel offset from this layer's center to the base layer's center
  • Normalized offset from this layer's center to the base layer's center using 'p' suffix (relative coordinates)

Positive values move the layer towards the right/bottom, and negative towards the left/top. With relative coordinates, 50p,50p moves the layer by half the base layer width and height down and right.

Examples:

  • position[layerName]=100,100 - Position layer 100 pixels right and down from base layer
  • position[layerName]=50p,50p - Position layer by half the base layer width and height down and right
  • position[layerName]=-50,25 - Position layer 50 pixels left and 25 pixels down from base layer
  • position[layerName]=0p,0p - Position layer center at same location as base layer center (default)
object
This modifier is currently in Limited Availability.
Click here to learn how to request access.

Specifies the assetId to be used as the source for a specific layer. The layer name is case-sensitive.

Can only be used with a layer.

Examples:

  • source[top]=urn:aaid:aem:1a034bee-ebda-4787-bad3-f924d0772b75 - Set the source for layer "top" to the specified assetId for this layers=top should exist in the query parameters
  • source[background]=urn:aaid:aem:1a034bee-ebda-4787-bad3-f924d0772b75 - Set the source for layer "background" to the specified assetId for this layers=background should exist in the query parameters

NOTE: This can be only used with layers modifier.

object or string
This modifier is currently in Limited Availability.
Click here to learn how to request access.

Crop to the bounding box of one or more embedded named paths in the source image. This cropping, in turn, changes the size of the image.

Key features:

  • (only) ASCII path names are supported
  • Intersection operation: When multiple crop names are specified, the image is cropped to the intersection of all specified path bounding boxes simultaneously
  • The operation changes the actual size of the image

Examples:

  • crop-names=border-with-curved-corners - Crop the final output image to the bounding box of the path named "border-with-curved-corners"
  • crop-names=border1,border2 - Crop to the intersection of the bounding boxes of "border1" and "border2"
  • crop-names[layerName]=border-with-curved-corners - Crop the specified layer to the bounding box of the path named "border-with-curved-corners"
  • crop-names[layerName]=border1,border2 - Crop the layer to the intersection of the bounding boxes of "border1" and "border2"
  • crop-names[layerName]=custom-path - Crop to the bounding box of a custom path named "custom-path"

Note: This operation is ignored if:

  • No path with the specified name is found in the layer source image
  • The intersection of multiple paths results in an empty region
print-resolution
integer >= 1
This modifier is currently in Limited Availability.
Click here to learn how to request access.

Defines the print resolution value of the output image.

Setting the print resolution does not change the pixel size of the output image.

Examples:

  • print-resolution=300 - Set the print resolution to 300 dpi
header Parameters
If-None-Match
string

The If-None-Match header field makes the request method conditional on a recipient cache or origin server either not having any current representation of the target resource, when the field value is "*", or having a selected representation with an entity tag that does not match any of those listed in the field value.

For more details, please head over to RFC9110.

Responses
200

Web-optimized version of the asset

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

404

Not Found

get/{assetId}/as/{seoName}.{format}
Request samples
Response samples
application/problem+json
{}

Returns a web-optimized binary representation of the asset

This is a convenience API for /adobe/assets/{assetId}/as/{seoname}.{format}?... that applies following defaults:

  • format => avif (based on image-characteristics, browser-capabilities and license-entitlements, falls back to an appropriate format (webp/png/jpeg) if avif-output can't be delivered. See auto-format and format for more details)
  • quality => 65
  • width => 1024
SecurityNone or Bearer
Request
path Parameters
assetId
required
string (AssetId) non-empty

ID of the asset

Example: urn:aaid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
header Parameters
If-None-Match
string

The If-None-Match header field makes the request method conditional on a recipient cache or origin server either not having any current representation of the target resource, when the field value is "*", or having a selected representation with an entity tag that does not match any of those listed in the field value.

For more details, please head over to RFC9110.

Responses
200

Web-optimized version of the asset

304

Not Modified

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

404

Not Found

get/{assetId}
Request samples
Response samples
application/problem+json
{}

Returns the originally uploaded binary for the asset

The Original Asset Delivery API accepts an asset ID corresponding to the asset and delivers the bitstream as-is (as it was uploaded). This is a convenience API for /adobe/assets/{assetId}/renditions/{renditionName}/as/{seoname} with renditionName defaulting to original.

SecurityNone or Bearer
Request
path Parameters
assetId
required
string (AssetId) non-empty

ID of the asset

Example: urn:aaid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
seoName
required
string([%.\w-]+)

any url-encoded or alphanumeric, non-whitespace set of characters. may contain hyphens and dots

Examples:
banner
header Parameters
If-None-Match
string

The If-None-Match header field makes the request method conditional on a recipient cache or origin server either not having any current representation of the target resource, when the field value is "*", or having a selected representation with an entity tag that does not match any of those listed in the field value.

For more details, please head over to RFC9110.

Responses
200

Original binary of the asset

304

Not Modified

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

404

Not Found

get/{assetId}/original/as/{seoName}
Request samples
Response samples
application/problem+json
{}

Returns a pre-generated (on AEM Assets authoring environment) rendition of the asset

The Asset Rendition Delivery API accepts an asset ID corresponding to the asset and the rendition name, and delivers the selected asset's specified rendition's bitstream as-is (as present on AEM Assets authoring environment).

SecurityNone or Bearer
Request
path Parameters
assetId
required
string (AssetId) non-empty

ID of the asset

Example: urn:aaid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
renditionName
required
string([%.\w-]+)

any url-encoded or alphanumeric, non-whitespace set of characters that need to match one of the renditions uploaded/created for the specified asset. may contain hyphens and dots

Examples:
banner
seoName
required
string([%.\w-]+)

any url-encoded or alphanumeric, non-whitespace set of characters. may contain hyphens and dots

Examples:
banner
query Parameters
attachment
string

Setting this parameter to true forces "download" prompt in browser by adapting the Content-Disposition appropriately.

Default is false.

Enum: "true" "1" "false" "0"
Example: attachment=true
header Parameters
If-None-Match
string

The If-None-Match header field makes the request method conditional on a recipient cache or origin server either not having any current representation of the target resource, when the field value is "*", or having a selected representation with an entity tag that does not match any of those listed in the field value.

For more details, please head over to RFC9110.

Responses
200

Binary of the specified rendition for the selected asset

304

Not Modified

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

404

Not Found

get/{assetId}/renditions/{renditionName}/as/{seoName}
Request samples
Response samples
application/problem+json
{}

Returns a list of static renditions of an asset

The List Renditions API accepts an asset ID and returns the static renditions associated with the asset. A success response includes list of available renditions and their attributes.

SecurityBearer
Request
path Parameters
assetId
required
string (AssetId) non-empty

ID of the asset

Example: urn:aaid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
header Parameters
If-None-Match
string

The If-None-Match header field makes the request method conditional on a recipient cache or origin server either not having any current representation of the target resource, when the field value is "*", or having a selected representation with an entity tag that does not match any of those listed in the field value.

For more details, please head over to RFC9110.

Responses
200

List of available renditions

304

Not Modified

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

404

Not Found

get/{assetId}/renditions
Request samples
Response samples
application/json
{
  • "assetId": "urn:aaid:aem:1a034bee-ebda-4787-bad3-f924d0772b75",
  • "repo:name": "string",
  • "items": [
    ]
}

Head request for list of static renditions of an asset

Returns headers, including an ETag for the specified asset, which can be a lighter method of checking for the change in list of static renditions, without sending a full GET request.

SecurityBearer
Request
path Parameters
assetId
required
string (AssetId) non-empty

ID of the asset

Example: urn:aaid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
Responses
200

OK

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

404

Not Found

head/{assetId}/renditions
Request samples
Response samples
application/problem+json
{}

Returns a list of smart crops of an asset

The List Smart Crop API accepts an asset ID and retrieves the associated smart crops for the specified asset. A successful response returns a list of smart crops along with their attributes, providing details such as dimensions.

NOTE: This API is used by Adobe's Content Hub application. Using this API directly isn’t covered in Adobe Support agreements.

SecurityBearer
Request
path Parameters
assetId
required
string (AssetId) non-empty

ID of the asset

Example: urn:aaid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
query Parameters
limit
integer <int32> (Limit) [ 1 .. 50 ]

For a paginated request, this parameter defines the maximum number of items to retrieve.

cursor
string (Cursor) non-empty

A cursor is an opaque string that can be used in API calls which support paginating the response. A non-existent cursor signifies that the returned list does not have more elements.

header Parameters
If-None-Match
string

The If-None-Match header field makes the request method conditional on a recipient cache or origin server either not having any current representation of the target resource, when the field value is "*", or having a selected representation with an entity tag that does not match any of those listed in the field value.

For more details, please head over to RFC9110.

Responses
200

List of smart crops

304

Not Modified

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

404

Not Found

get/{assetId}/smartCrops
Request samples
Response samples
application/json
{
  • "assetId": "urn:aaid:aem:1a034bee-ebda-4787-bad3-f924d0772b75",
  • "repo:name": "string",
  • "items": [
    ],
  • "cursor": "string"
}

Head request for list of smart crops of an asset

Returns headers, including an ETag for the specified asset, which can be a lighter method of checking for the change in list of smart crops, without sending a full GET request.

NOTE: This API is used by Adobe's Content Hub application. Using this API directly isn’t covered in Adobe Support agreements.

SecurityBearer
Request
path Parameters
assetId
required
string (AssetId) non-empty

ID of the asset

Example: urn:aaid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
Responses
200

OK

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

404

Not Found

head/{assetId}/smartCrops
Request samples
Response samples
application/problem+json
{}

Returns the originally uploaded binary for the asset.Deprecated

The Original Asset Delivery API accepts an asset ID corresponding to the asset and delivers the bitstream as-is (as it was uploaded).

This API is deprecated, please use /adobe/assets/{assetId}/original/as/{seo-name}

SecurityNone or Bearer
Request
path Parameters
assetId
required
string (AssetId) non-empty

ID of the asset

Example: urn:aaid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
seoName
required
string([%.\w-]+)

any url-encoded or alphanumeric, non-whitespace set of characters. may contain hyphens and dots

Examples:
banner
header Parameters
If-None-Match
string

The If-None-Match header field makes the request method conditional on a recipient cache or origin server either not having any current representation of the target resource, when the field value is "*", or having a selected representation with an entity tag that does not match any of those listed in the field value.

For more details, please head over to RFC9110.

Responses
200

Original binary of the asset

304

Not Modified

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

404

Not Found

get/deliver/{assetId}/{seoName}
Request samples
Response samples
application/problem+json
{}

Search for activated assets based on specified criteria

Search Activated Assets

SecurityBearer and ApiKeyAuth
Request
Request Body schema: application/json
required
required
Array of OrQuery (object) or AndQuery (object) or NotQuery (object) or MatchQuery (object) or TermQuery (object) or RangeQuery (object) (CompositeQuery) [ 1 .. 5 ] items

List of Composite query. CompositeQueries in this list are AND'd.

orderBy
string (OrderBy) non-empty

The value of an orderBy parameter contains a comma-separated list of expressions used to sort the items.

The expression may include the suffix asc for ascending or desc for descending, separated from the property name by one or more spaces. If asc or desc is not specified, the service will order by the specified property in ascending order.

Items will be sorted by the result values of the first expression; items with the same value for the first expression are sorted by the result value of the second expression and so on. The sort order is the inherent order for the type of the property.

limit
integer <int32> (Limit) [ 1 .. 50 ]

For a paginated request, this parameter defines the maximum number of items to retrieve.

cursor
string (Cursor) non-empty

A cursor is an opaque string that can be used in API calls which support paginating the response. A non-existent cursor signifies that the returned list does not have more elements.

Responses
200

Asset Search Response

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

500

The server encountered an unexpected error. Retrying the request after a certain time could help.

post/search
Request samples
application/json
{
  • "query": [
    ],
  • "orderBy": "metadata.repositoryMetadata.repo:size desc,metadata.repositoryMetadata.repo:createDate asc",
  • "limit": 50
}
Response samples
application/json
{
  • "hits": {
    },
  • "cursor": "[\"45600323\",1478539971]",
  • "search_metadata": {
    }
}

Create a token for asset search, analytics, and settings.

Create short-lived token with access restrictions for searching assets and performing operations on specified indexes.

SecurityBearer
Request
header Parameters
X-Adobe-Accept-Experimental
required
integer
Value: 1
Request Body schema: application/json
required
indexes
required
Array of strings

Specify indexes to grant access to.

Items Enum: "assets" "collections" "linkshares" "querysuggestions"
operationType
required
string

Specifiy the type of operation.

Enum: "search" "analytics" "settings"
Responses
200

The API returns a token along with its validity.

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

500

The server encountered an unexpected error. Retrying the request after a certain time could help.

post/search/token
Request samples
application/json
{
  • "indexes": [
    ],
  • "operationType": "search"
}
Response samples
application/json
{
  • "token": "YTgyMzMwOTkzMjA2Mzk5OWUxNjhjYmIwMGZkNGFmMzk2NDU3ZjMyYTg1NThiZjgx",
  • "expiryTime": "2024-02-28T21:39:02.417-0800",
  • "appId": "5HEOA9BAT1"
}

Metadata

APIs for working with asset metadata

Head request for asset metadata

Returns headers, including an ETag for the specified asset metadata, which can be a lighter method of checking for the existence of, or validating a cached version of an asset's metadata without sending a full GET request.

SecurityNone or Bearer
Request
path Parameters
assetId
required
string non-empty

ID of the asset to access

Examples:
urn:aaid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
Responses
200

OK

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

404

Not Found

head/{assetId}/metadata
Request samples
Response samples
application/problem+json
{}

Delivers the specified asset's metadata

Asset metadata contains those metadata values that have been extracted from the asset, configured by the user, or derived from the asset during asset processing. Repository metadata contains metadata properties that are set and maintained by the repository during system operations.

SecurityNone or Bearer
Request
path Parameters
assetId
required
string non-empty

ID of the asset to access

Examples:
urn:aaid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
header Parameters
If-None-Match
string

The If-None-Match header field makes the request method conditional on a recipient cache or origin server either not having any current representation of the target resource, when the field value is "*", or having a selected representation with an entity tag that does not match any of those listed in the field value.

For more details, please head over to RFC9110.

Responses
200

Metadata for the specified asset

304

Not Modified

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

404

Not Found

get/{assetId}/metadata
Request samples
Response samples
application/json
{
  • "value": {
    }
}

Videos

APIs for working with videos

Delivers the Player container for specified Video asset.

The Delivery API accepts an assetId, and if the ID corresponds to a video asset, delivers Player for video streaming. The asset ID is an opaque string defined by the content repository. The entity composing the Delivery URLs must know them apriori.

SecurityNone or Bearer
Request
path Parameters
assetId
required
string (AssetId) non-empty

ID of the asset

Example: urn:aaid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
Responses
200

Response Video in Player.

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

404

Not Found

get/{assetId}/play
Request samples
Response samples
application/problem+json
{}

Delivers the playback manifests for specified Video asset in the selected output format.

The Delivery API accepts an asset ID, and if the ID corresponds to a video asset, delivers the playback manifest in the requested protocol. The asset ID is an opaque string defined by the content repository. The entity composing the Delivery URLs must know them apriori. If the asset is not a video asset, client gets a 404 response.

SecurityNone or Bearer
Request
path Parameters
assetId
required
string (AssetId) non-empty

ID of the asset

Example: urn:aaid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
format
required
string (VideoManifestFormatParam)

Desired Playback manifest format

Enum: "m3u8" "mpd"
Example: m3u8
Responses
200

Response Video Manifests in selected format

304

Not Modified

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

404

Not Found

get/{assetId}/manifest.{format}
Request samples
Response samples
application/problem+json
{}

Image Presets

APIs for working with image presets

Returns a list of image presets

The List Image Presets API returns the image presets configured for the given tenant. A successful response includes a list of available image presets and their attributes.

NOTE: This API is used by Adobe's Content Hub application. Using this API directly isn’t covered in Adobe Support agreements.

SecurityBearer
Request
query Parameters
limit
integer <int32> (Limit) [ 1 .. 50 ]

For a paginated request, this parameter defines the maximum number of items to retrieve.

cursor
string (Cursor) non-empty

A cursor is an opaque string that can be used in API calls which support paginating the response. A non-existent cursor signifies that the returned list does not have more elements.

header Parameters
If-None-Match
string

The If-None-Match header field makes the request method conditional on a recipient cache or origin server either not having any current representation of the target resource, when the field value is "*", or having a selected representation with an entity tag that does not match any of those listed in the field value.

For more details, please head over to RFC9110.

Responses
200

List of available image presets

304

Not Modified

401

Unauthorized

403

Forbidden

get/imagePresets
Request samples
Response samples
application/json
{
  • "cursor": "123",
  • "items": [
    ]
}

Collections

APIs for working with asset collections

Create a collection

Creates a collection that represents a group of Asset(s) and/or Collection(s).

NOTE: This API is used by Adobe's Content Hub application. Using this API directly isn’t covered in Adobe Support agreements.

SecurityBearer
Request
Request Body schema: application/json
required
title
required
string non-empty

Title of the Collection

description
string

A short description of the Collection

required
Array of objects

The items in the Collection

property name*
additional property
any
Responses
201

Returns information on the recently created collection, including its metadata.

202

Accepted

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

post/collections
Request samples
application/json
{
  • "title": "Product Images",
  • "description": "Images approved for use in the product catalog",
  • "items": [
    ]
}
Response samples
application/json
{
  • "id": "urn:cid:aem:1a034bee-ebda-4787-bad3-f924d0772b75",
  • "repositoryMetadata": {
    },
  • "collectionMetadata": {
    }
}

List all Collections

Retrieves all the Collections available in the repository.

NOTE: This API is used by Adobe's Content Hub application. Using this API directly isn’t covered in Adobe Support agreements.

SecurityBearer
Request
query Parameters
limit
integer <int32> (Limit) [ 1 .. 50 ]

For a paginated request, this parameter defines the maximum number of items to retrieve.

cursor
string (Cursor) non-empty

A cursor is an opaque string that can be used in API calls which support paginating the response. A non-existent cursor signifies that the returned list does not have more elements.

Responses
200

Collections retrieved successfully

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

get/collections
Request samples
Response samples
application/json
{
  • "cursor": "string",
  • "items": [
    ]
}

Retrieve a Collection's Metadata

Retrieves collection metadata for a given collection id along with Etag representing the current state of the collection.

NOTE: This API is used by Adobe's Content Hub application. Using this API directly isn’t covered in Adobe Support agreements.

SecurityBearer
Request
path Parameters
collectionId
required
string (CollectionId) non-empty

ID of the collection

Example: urn:cid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
header Parameters
If-None-Match
string

The If-None-Match header field makes the request method conditional on a recipient cache or origin server either not having any current representation of the target resource, when the field value is "*", or having a selected representation with an entity tag that does not match any of those listed in the field value.

For more details, please head over to RFC9110.

X-Adobe-Accept-Experimental
required
integer
Value: 1
Responses
200

Collection Metadata Retrieved successfully

304

Not Modified

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

404

Not Found

get/collections/{collectionId}
Request samples
Response samples
application/json
{
  • "id": "urn:cid:aem:1a034bee-ebda-4787-bad3-f924d0772b75",
  • "repositoryMetadata": {
    },
  • "collectionMetadata": {
    }
}

Head request for a collection metadata

Returns headers, including an ETag for the specified collection, which can be a lighter method of checking for the existence of, or validating a cached version of an collection without sending a full GET request.

NOTE: This API is used by Adobe's Content Hub application. Using this API directly isn’t covered in Adobe Support agreements.

SecurityNone or Bearer
Request
path Parameters
collectionId
required
string (CollectionId) non-empty

ID of the collection

Example: urn:cid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
Responses
200

OK

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

404

Not Found

head/collections/{collectionId}
Request samples
Response samples
application/problem+json
{}

Delete a Collection

Deletes a collection for a given collection id. If the delete operation requires more than a few seconds to complete, a status link with the jobId is returned in the response header that can be used to check the status.

NOTE: This API is used by Adobe's Content Hub application. Using this API directly isn’t covered in Adobe Support agreements.

SecurityBearer
Request
path Parameters
collectionId
required
string (CollectionId) non-empty

ID of the collection

Example: urn:cid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
header Parameters
If-Match
required
string

The If-Match header field makes the request method conditional on the recipient origin server either having at least one current representation of the target resource, when the field value is "*", or having a current representation of the target resource that has an entity tag matching a member of the list of entity tags provided in the field value.

For more details, please head over to RFC9110.

Responses
202

Accepted

204

Collection deleted successfully.

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

428

Precondition Required

delete/collections/{collectionId}
Request samples
Response samples
application/problem+json
{}

Update a collection's metadata

Updates the metadata for a given collection id.

NOTE: This API is used by Adobe's Content Hub application. Using this API directly isn’t covered in Adobe Support agreements.

SecurityBearer
Request
path Parameters
collectionId
required
string (CollectionId) non-empty

ID of the Collection

Example: urn:cid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
header Parameters
If-Match
required
string

The If-Match header field makes the request method conditional on the recipient origin server either having at least one current representation of the target resource, when the field value is "*", or having a current representation of the target resource that has an entity tag matching a member of the list of entity tags provided in the field value.

For more details, please head over to RFC9110.

Request Body schema: application/json-patch+json
title
string non-empty

Title of the Collection

description
string

A short description of the Collection

property name*
additional property
any
Responses
204

No Content

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

428

Precondition Required

post/collections/{collectionId}
Request samples
application/json-patch+json
{
  • "title": "New Title",
  • "description": "New Description"
}
Response samples
application/problem+json
{}

Get collection items

Retrieve a paginated list of the items in the specified collection.

NOTE: This API is used by Adobe's Content Hub application. Using this API directly isn’t covered in Adobe Support agreements.

SecurityBearer
Request
path Parameters
collectionId
required
string (CollectionId) non-empty

ID of the collection

Example: urn:cid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
query Parameters
limit
integer <int32> (Limit) [ 1 .. 50 ]

For a paginated request, this parameter defines the maximum number of items to retrieve.

cursor
string (Cursor) non-empty

A cursor is an opaque string that can be used in API calls which support paginating the response. A non-existent cursor signifies that the returned list does not have more elements.

header Parameters
If-None-Match
string

The If-None-Match header field makes the request method conditional on a recipient cache or origin server either not having any current representation of the target resource, when the field value is "*", or having a selected representation with an entity tag that does not match any of those listed in the field value.

For more details, please head over to RFC9110.

X-Adobe-Accept-Experimental
required
integer
Value: 1
Responses
200

Collection Retrieved successfully

304

Not Modified

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

404

Not Found

get/collections/{collectionId}/items
Request samples
Response samples
application/json
{
  • "cursor": "string",
  • "self": [
    ],
  • "items": [
    ]
}

Head request for collection items

Returns headers, including an ETag for the specified assets collection, which can be a lighter method of checking for the existence of, or validating a cached version of an collection without sending a full GET request.

NOTE: This API is used by Adobe's Content Hub application. Using this API directly isn’t covered in Adobe Support agreements.

SecurityNone or Bearer
Request
path Parameters
collectionId
required
string (CollectionId) non-empty

ID of the collection

Example: urn:cid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
query Parameters
limit
integer <int32> (Limit) [ 1 .. 50 ]

For a paginated request, this parameter defines the maximum number of items to retrieve.

cursor
string (Cursor) non-empty

A cursor is an opaque string that can be used in API calls which support paginating the response. A non-existent cursor signifies that the returned list does not have more elements.

Responses
200

OK

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

404

Not Found

head/collections/{collectionId}/items
Request samples
Response samples
application/problem+json
{}

Update collection items

If the update operation requires more than a few seconds to complete, response includes a Location header which contains the URL to poll for status of this operation.

NOTE: This API is used by Adobe's Content Hub application. Using this API directly isn’t covered in Adobe Support agreements.

SecurityBearer
Request
path Parameters
collectionId
required
string (CollectionId) non-empty

ID of the Collection

Example: urn:cid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
header Parameters
If-Match
required
string

The If-Match header field makes the request method conditional on the recipient origin server either having at least one current representation of the target resource, when the field value is "*", or having a current representation of the target resource that has an entity tag matching a member of the list of entity tags provided in the field value.

For more details, please head over to RFC9110.

Request Body schema: application/json
Array
Any of:

Adds or removes an item from the collection.

op
required
string >= 3 characters

Identifies this operation as an add or remove operation

Enum: "add" "remove"
id
required
string non-empty

The ID of the item to add or remove. The ID can specify an asset or a collection.

type
required
string >= 5 characters

The type of item that is referenced by the id. Valid values are asset or collection.

Enum: "asset" "collection"
Responses
202

Accepted

204

No Content

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

428

Precondition Required

post/collections/{collectionId}/items
Request samples
application/json
[
  • {
    },
  • {
    }
]
Response samples
application/problem+json
{}

Retrieve a collection's job async status

Retrieves the current job's status for a collection.

NOTE: This API is used by Adobe's Content Hub application. Using this API directly isn’t covered in Adobe Support agreements.

SecurityBearer
Request
path Parameters
jobId
required
string non-empty
header Parameters
X-Adobe-Accept-Experimental
required
integer
Value: 1
Responses
200

Status of a task being processed

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

404

Not Found

get/collections/jobs/{jobId}/status
Request samples
Response samples
application/json
{
  • "operation": "aem.assets.collections.deleteCollection",
  • "status": 200,
  • "description": "Collection deleted successfully",
  • "data": {
    },
  • "errors": [ ],
  • "warnings": []
}

Events

Events generated by assets delivery tier

Asset delivery disabled eventWebhook

Event triggered when an asset can no longer be rendered through new DM APIs. This is used by applications when processing of asset(s) in delivery tier takes a long time, for example, video assets or assets going through any ML pipeline.

SecurityNone
Request
Request Body schema: application/json
id
required
string non-empty

An identifier for the event. When used in combination with the source property, it allows for each instance of an event to be uniquely identified. That is to say, the combination of the source + id properties will be unique for each distinct event. If a duplicate event is re-sent (e.g. due to a network error) it may have the same id and should be treated as a duplicate.

source
required
string <uri> non-empty ^acct:aem(-cmstg)?-p\d+-e\d+@adobe\.com$

An instance of the acct URI scheme that uniquely identifies the producer of this event, of the format acct:aem-p<programId>-e<environmentId>@adobe.com.

specversion
required
string >= 3 characters

The version of the CloudEvents specification which the event uses. AEM events use the CloudEvents spec version 1.0.2, hence this value will be 1.0.

Value: "1.0"
type
required
string >= 4 characters ^aem\..*$

The type for the event. This will identify the AEM solution that has dispatched the event and may also include the type of entity and the activity that occurred.

Value: "aem.assets.asset.removed_from_delivery"
datacontenttype
required
string non-empty

The format of the data in the event. This will always be application/json for AEM events.

Value: "application/json"
dataschema
string <uri>

An optional attribute, which may point to a JSON schema document that covers the data object.

time
required
string <date-time> non-empty

A timestamp of when the event occurred.

required
object

The event payload.

Responses
200

Asset delivery disabled event data is received successfully

Request samples
application/json
{
  • "specversion": "1.0",
  • "type": "aem.assets.asset.removed_from_delivery",
  • "source": "acct:aem-p56789-e12345@adobe.com",
  • "id": "7c1104e5-4cd7-47d6-a50f-2568c480f2e9",
  • "time": "2018-04-05T17:31:00Z",
  • "datacontenttype": "application/json",
  • "data": {
    }
}

Asset delivery ready eventWebhook

Event triggered when an asset is ready for delivery through new DM APIs. This is used by applications when processing of asset(s) in delivery tier takes a long time, for example, video assets or assets going through any ML pipeline.

SecurityNone
Request
Request Body schema: application/json
id
required
string non-empty

An identifier for the event. When used in combination with the source property, it allows for each instance of an event to be uniquely identified. That is to say, the combination of the source + id properties will be unique for each distinct event. If a duplicate event is re-sent (e.g. due to a network error) it may have the same id and should be treated as a duplicate.

source
required
string <uri> non-empty ^acct:aem(-cmstg)?-p\d+-e\d+@adobe\.com$

An instance of the acct URI scheme that uniquely identifies the producer of this event, of the format acct:aem-p<programId>-e<environmentId>@adobe.com.

specversion
required
string >= 3 characters

The version of the CloudEvents specification which the event uses. AEM events use the CloudEvents spec version 1.0.2, hence this value will be 1.0.

Value: "1.0"
type
required
string >= 4 characters ^aem\..*$

The type for the event. This will identify the AEM solution that has dispatched the event and may also include the type of entity and the activity that occurred.

Value: "aem.assets.asset.ready_for_delivery"
datacontenttype
required
string non-empty

The format of the data in the event. This will always be application/json for AEM events.

Value: "application/json"
dataschema
string <uri>

An optional attribute, which may point to a JSON schema document that covers the data object.

time
required
string <date-time> non-empty

A timestamp of when the event occurred.

required
object

The event payload.

Responses
200

Asset delivery ready event data is received successfully

Request samples
application/json
{
  • "specversion": "1.0",
  • "type": "aem.assets.asset.ready_for_delivery",
  • "source": "acct:aem-p56789-e12345@adobe.com",
  • "id": "7c1104e5-4cd7-47d6-a50f-2568c480f2e9",
  • "time": "2018-04-05T17:31:00Z",
  • "datacontenttype": "application/json",
  • "data": {
    }
}

Archives

APIs for generating archives containing binaries (one or more assets, with one or more renditions) in one of the supported archival formats (e.g., zip).

Archival Request API

Request creation of an archive for the asset references specified in the request payload. The response contains an identifier and metadata pertaining to the archive request. The result of the operation will be one or more archives. The API may use various factors to determine the number of archives required to complete the operation. For example, very large archive request might be split into multiple files. Consumers of this API should use the response Location header to poll for the status of the archive creation request. The polling interval should be determined by the Retry-After header value. Invalid assets specified for inclusion in the archive will not fail the overall creation process. Instead, the API will create a archive containing the assets it could find, with invalid asset references appearing as warnings in the final status response.

NOTE: This API is used by Adobe's Content Hub application. Using this API directly isn’t covered in Adobe Support agreements.

SecurityBearer or ApiKeyAuth
Request
Request Body schema: application/json
required
required
Array of objects non-empty

Assets to be included in the archive. By default, any custom renditions generated via Processing Profiles and original rendition are included, and all others are excluded. The request can optionally specify renditions that MUST be included-in or excluded-from the archive being requested.

format
string (ArchiveFormat)
Default: "zip"

The output format of the archive

Value: "zip"
namePrefix
string

The name to use for the created archive file(s). Note that the API will treat this as a suggestion, and reserves the right to change the final archive name as needed. If not provided, the API will assign its own file name according to any logic it deems fit.

Responses
202

Accepted

400

Bad Request. The Problem Details object will provide more information about the exact cause.

401

Unauthorized

403

Forbidden

415

Unsupported Media Type. When provided as a response to a PATCH request, the response will provide an Accept-Patch response header to notify the client what patch document media types are supported.

500

The server encountered an unexpected error. Retrying the request after a certain time could help.

post/archives
Request samples
application/json
{
  • "items": [
    ],
  • "format": "zip",
  • "namePrefix": "assets"
}
Response samples
application/json
{
  • "id": "1a034bee-ebda-4787-bad3-f924d0772b75",
  • "format": "zip",
  • "submittedBy": "person@company.com",
  • "submittedDate": "2024-02-28T21:39:02.417-0800"
}

Archival Request Status API

Get the status of the archive creation request

NOTE: This API is used by Adobe's Content Hub application. Using this API directly isn’t covered in Adobe Support agreements.

SecurityBearer or ApiKeyAuth
Request
path Parameters
archiveId
required
string (ArchiveId) non-empty

Identifier for the archive under-process/processed by the service

Example: 1a034bee-ebda-4787-bad3-f924d0772b75
Responses
200

Ok

401

Unauthorized

403

Forbidden

404

Not Found

500

The server encountered an unexpected error. Retrying the request after a certain time could help.

get/archives/{archiveId}/status
Request samples
Response samples
application/json
{}

Archive File Download API

For a given archiveId, one or more archive files can be created. Archival Request Status API provides the list of archive files available for the archiveId. This API enables download of any/all of those files.

NOTE: This API is used by Adobe's Content Hub application. Using this API directly isn’t covered in Adobe Support agreements.

SecurityNone or Bearer or ApiKeyAuth
Request
path Parameters
archiveId
required
string (ArchiveId) non-empty

Identifier for the archive under-process/processed by the service

Example: 1a034bee-ebda-4787-bad3-f924d0772b75
fileName
required
string

The name of the archive file to retrieve. Archive files available for download against this archiveId can be retrieved through the Archival Request Status API.

Example: assets.zip
query Parameters
token
string

a time limited token allowing anonymous retrieval of the archive file. The token will be included in the URLs presented in Archival Request Status API response for requests that have their status as COMPLETED.

Responses
302

Found

404

Not Found

500

The server encountered an unexpected error. Retrying the request after a certain time could help.

get/archives/{archiveId}/files/{fileName}
Request samples
Response samples
application/problem+json
{}