Skip to main content

Content Delivery overview

Overview
Link copied!

Our next generation of content delivery is optimized to be even faster, easier to use and more flexible. Its key features are as follows:

  • Speed. Content Delivery 2 features even faster response times than the original Content Delivery API, making it better suited to modern application architectures.

  • Delivery keys. Keys are arbitrary strings of up to 150 characters that can be associated with slots and content items. A delivery key can be used instead of the content id to retrieve content. The delivery key can be a simple string or a path such as "home-page/feature-banner". This makes it simpler to write your integration code and allows users more control over where items of content are delivered. More information about setting up delivery keys can be found on the using delivery keys page.

  • Improved formatting options. Content can be retrieved in a bandwidth optimised linked data format or inlined in a content tree. All you need to do is set the format parameter to specify how you want to retrieve the content.

  • The depth parameter gives you more control of how linked content is returned. For content such as a carousel or grid that contains links to other content, you can use the depth parameter to retrieve the root item, the item and all its dependants, or a partial dependency tree.

To find out about the filter API that is used to list, sort and filter content see the filter API page.

info

If you want to use Content Delivery 2 then it must be provisioned on your account and enabled on each hub on which you want to use it. Contact your Customer Success Manager for more details.

Using the API
Link copied!

In this section we provide an overview of the API, example usage and some sample returned content. For more information see the Content Delivery 2 API reference

You can retrieve a single content item by delivery key or id, or retrieve multiple items in the same request.

Get Content by Key
Link copied!

Retrieve the content item or slot with the delivery key.

Request URL
Link copied!

https://{hubname}.cdn.content.amplience.net/content/key/{key}

Description
Link copied!

key is the delivery key for the item. A delivery key may not start or end with "/", must be between 1 and 150 characters and cannot contain certain other special characters. See the delivery key validation page for more details.

Example
Link copied!

The following example shows the Content Delivery 2 URL for a hub named ampproduct-doc used to retrieve a published content item with the delivery key promotions/feature-carousel.

https://ampproduct-doc.cdn.content.amplience.net/content/key/promotions/feature-carousel

Once you have set a delivery key for a slot or content item you can update it, but the item must be published before it can be retrieved using the production content delivery URL.

Get Content by ID
Link copied!

Retrieve the content item or slot with the specified delivery ID.

Request URL
Link copied!

https://{hubname}.cdn.content.amplience.net/content/id/{id}

Description
Link copied!

id is the delivery ID for the item in UUID format.

Example
Link copied!

The following example shows the Content Delivery 2 URL for a hub named ampproduct-doc retrieving a published content item with the ID bd89c2ed-0ed5-4304-8c89-c0710af500e2.

https://ampproduct-doc.cdn.content.amplience.net/content/id/bd89c2ed-0ed5-4304-8c89-c0710af500e2

The examples in this section all make use of a carousel content item. The carousel links to up to 6 carousel slides, each of which links to an image content item. The depth of the dependency tree for the carousel is 2.

The carousel links to carousel slides and image content items..

Parameters
Link copied!

Additional query parameters can be used to define the format of content retrieved by ID or key.

depth
Link copied!

The depth parameter allows you to control whether to return items linked to the specified content item. For example for a carousel, you can control whether to return the carousel slides and to what level of the dependency tree content is retrieved.

The value of depth is one of the following:

ValueDescription
rootDefault. Return the root item only and not any descendants.
allReturn the root item and all its descendants. The content will be returned in the format specified by the format parameter.
0 … 22An integer between 0 and 22. Return the descendants up to the specified level of the dependency tree. Note: 0 is the same as root.

Example: no parameters
Link copied!

The following will retrieve just the root item and only the ids of its descendants. If you do not include the depth parameter, then depth=root will be used by default.

https://ampproduct-doc.cdn.content.amplience.net/content/id/bd89c2ed-0ed5-4304-8c89-c0710af500e2
{
"content": {
"_meta": {
"name": "Hats carousel",
"schema": "https://example.com/carousel",
"deliveryId": "bd89c2ed-0ed5-4304-8c89-c0710af500e2"
},
"slides": [
{
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "https://example.com/carousel-slide",
"id": "7823de65-2e67-450c-a5db-d8c9b616801b"
},
{
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "https://example.com/carousel-slide",
"id": "28c75b57-2c66-4b24-9059-ddc2b05a44d4"
},
{
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "https://example.com/carousel-slide",
"id": "f2f989b5-4a06-4a9b-9fb0-36ea3b3cae78"
},
{
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "https://example.com/carousel-slide",
"id": "efe831c2-c5b9-4cde-9c08-0f946968ab47"
}
]
}
}

Example: depth=all
Link copied!

The following will retrieve a content item and all its descendants in the default linked data format.

https://ampproduct-doc.cdn.content.amplience.net/content/id/bd89c2ed-0ed5-4304-8c89-c0710af500e2?depth=all
{
"content": {
"_meta": {
"name": "Hats carousel",
"schema": "https://example.com/carousel",
"deliveryId": "bd89c2ed-0ed5-4304-8c89-c0710af500e2"
},
"slides": [
{
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "https://example.com/carousel-slide",
"id": "7823de65-2e67-450c-a5db-d8c9b616801b"
},
{
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "https://example.com/carousel-slide",
"id": "28c75b57-2c66-4b24-9059-ddc2b05a44d4"
},
{
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "https://example.com/carousel-slide",
"id": "f2f989b5-4a06-4a9b-9fb0-36ea3b3cae78"
},
{
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "https://example.com/carousel-slide",
"id": "efe831c2-c5b9-4cde-9c08-0f946968ab47"
}
]
},
"linkedContent": [
{
"_meta": {
"name": "Red beret slide",
"schema": "https://example.com/carousel-slide",
"deliveryId": "efe831c2-c5b9-4cde-9c08-0f946968ab47"
},
"imageItem": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "https://schema-examples.com/example-image",
"id": "bc5fe8d2-3ed3-4363-8223-3ccd5be0ac7d"
},
"headline": "Stay warm. Stay stylish.",
"subheading": "Our latest styles."
},
{
"_meta": {
"name": "White hat slide",
"schema": "https://example.com/carousel-slide",
"deliveryId": "28c75b57-2c66-4b24-9059-ddc2b05a44d4"
},
"imageItem": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "https://schema-examples.com/example-image",
"id": "3627a6f4-afbf-4fd9-8882-644a15e95a0c"
},
"headline": "We've got you covered this winter.",
"subheading": "Warm hats for cold days."
},
{
"_meta": {
"name": "Red beret image",
"schema": "https://schema-examples.com/example-image",
"deliveryId": "bc5fe8d2-3ed3-4363-8223-3ccd5be0ac7d"
},
"image": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "da6f21ac-bf97-4757-8247-a283e5a760ec",
"name": "woman-with-red-beret-winter",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
},
"altText": "Woman in coat wearing a red beret"
},
{
"_meta": {
"name": "Coat with hood image",
"schema": "https://schema-examples.com/example-image",
"deliveryId": "860cf3a9-3dba-41d4-8e72-8dd2cff79dca"
},
"image": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "eb23a73c-e720-44c6-b3e3-61d61413f847",
"name": "winter-coat-darkblue",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
},
"altText": "Woman in a coat with hood and scarf."
},
{
"_meta": {
"name": "Black hat slide",
"schema": "https://example.com/carousel-slide",
"deliveryId": "7823de65-2e67-450c-a5db-d8c9b616801b"
},
"imageItem": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "https://schema-examples.com/example-image",
"id": "4219a628-2a8b-4d5b-81d9-2cd1ca348609"
},
"headline": "The most stylish hats.",
"subheading": "From our signature collection."
},
{
"_meta": {
"name": "Black hat image",
"schema": "https://schema-examples.com/example-image",
"deliveryId": "4219a628-2a8b-4d5b-81d9-2cd1ca348609"
},
"image": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "c06f9960-6636-4e97-b42d-c7c5aa799a83",
"name": "pexels-photo-211997",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
},
"altText": "Woman in a patterned top wearing a black hat"
},
{
"_meta": {
"name": "Coat with hood slide",
"schema": "https://example.com/carousel-slide",
"deliveryId": "f2f989b5-4a06-4a9b-9fb0-36ea3b3cae78"
},
"imageItem": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "https://schema-examples.com/example-image",
"id": "860cf3a9-3dba-41d4-8e72-8dd2cff79dca"
},
"headline": "The best of both worlds.",
"subheading": "Great coats to keep you warm."
},
{
"_meta": {
"name": "White hat image",
"schema": "https://schema-examples.com/example-image",
"deliveryId": "3627a6f4-afbf-4fd9-8882-644a15e95a0c"
},
"image": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "a7fce272-710c-4ca5-bb48-fc6689ba5e84",
"name": "woman-white-hat-winter",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
},
"altText": "Woman in a black coat with a white bobble hat."
}
]
}

Example: depth=1
Link copied!

The following retrieves the carousel content item with depth=1. No format is specified, so the content is returned in linked data format.

https://ampproduct-doc.cdn.content.amplience.net/content/id/bd89c2ed-0ed5-4304-8c89-c0710af500e2?depth=1

The carousel is the root item in the dependency tree, the carousel slides are level 1, and the image items that each carousel slide links to are level 2. By specifying a depth of 1, we are retrieving the carousel and carousel slides, and just the content item ids for the image items are shown in the linkedContent section.

{
"content": {
"_meta": {
"name": "Hats carousel",
"schema": "https://example.com/carousel",
"deliveryKey": "promotions/feature-carousel",
"deliveryId": "bd89c2ed-0ed5-4304-8c89-c0710af500e2"
},
"slides": [
{
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "https://example.com/carousel-slide",
"id": "7823de65-2e67-450c-a5db-d8c9b616801b"
},
{
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "https://example.com/carousel-slide",
"id": "28c75b57-2c66-4b24-9059-ddc2b05a44d4"
},
{
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "https://example.com/carousel-slide",
"id": "f2f989b5-4a06-4a9b-9fb0-36ea3b3cae78"
},
{
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "https://example.com/carousel-slide",
"id": "efe831c2-c5b9-4cde-9c08-0f946968ab47"
}
]
},
"linkedContent": [
{
"_meta": {
"name": "Red beret slide",
"schema": "https://example.com/carousel-slide",
"deliveryId": "efe831c2-c5b9-4cde-9c08-0f946968ab47"
},
"imageItem": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "https://schema-examples.com/example-image",
"id": "bc5fe8d2-3ed3-4363-8223-3ccd5be0ac7d"
},
"headline": "Stay warm. Stay stylish.",
"subheading": "Our latest styles."
},
{
"_meta": {
"name": "White hat slide",
"schema": "https://example.com/carousel-slide",
"deliveryId": "28c75b57-2c66-4b24-9059-ddc2b05a44d4"
},
"imageItem": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "https://schema-examples.com/example-image",
"id": "3627a6f4-afbf-4fd9-8882-644a15e95a0c"
},
"headline": "We've got you covered this winter.",
"subheading": "Warm hats for cold days."
},
{
"_meta": {
"name": "Black hat slide",
"schema": "https://example.com/carousel-slide",
"deliveryId": "7823de65-2e67-450c-a5db-d8c9b616801b"
},
"imageItem": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "https://schema-examples.com/example-image",
"id": "4219a628-2a8b-4d5b-81d9-2cd1ca348609"
},
"headline": "The most stylish hats.",
"subheading": "From our signature collection."
},
{
"_meta": {
"name": "Coat with hood slide",
"schema": "https://example.com/carousel-slide",
"deliveryId": "f2f989b5-4a06-4a9b-9fb0-36ea3b3cae78"
},
"imageItem": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "https://schema-examples.com/example-image",
"id": "860cf3a9-3dba-41d4-8e72-8dd2cff79dca"
},
"headline": "The best of both worlds.",
"subheading": "Great coats to keep you warm."
}
]
}

format
Link copied!

The format parameter allows you to specify whether content is retrieved in bandwidth optimised linked data format or inlined as a content tree.

ValueDescription
linkedDefault. Returns the content in a bandwidth optimised format.
inlinedReturns the content inlined as a content tree.

If you do not include the format parameter, then format=linked will be used by default.

Example: format = inlined, depth = all
Link copied!

The following retrieves the carousel content item used in the depth section inlined with depth=all. Note that entire dependency tree is returned: the carousel, carousel slides and all of the linked image item content items.

The item can be retrieved by delivery key:

https://ampproduct-doc.cdn.content.amplience.net/content/key/promotions/feature-carousel?depth=all&format=inlined

You can also retrieve the item by id with the same parameters:

https://ampproduct-doc.cdn.content.amplience.net/content/id/bd89c2ed-0ed5-4304-8c89-c0710af500e2?depth=all&format=inlined
{
"content": {
"_meta": {
"name": "Hats carousel",
"schema": "https://example.com/carousel",
"deliveryKey": "promotions/feature-carousel",
"deliveryId": "bd89c2ed-0ed5-4304-8c89-c0710af500e2"
},
"slides": [
{
"_meta": {
"name": "Black hat slide",
"schema": "https://example.com/carousel-slide",
"deliveryId": "7823de65-2e67-450c-a5db-d8c9b616801b"
},
"imageItem": {
"_meta": {
"name": "Black hat image",
"schema": "https://schema-examples.com/example-image",
"deliveryId": "4219a628-2a8b-4d5b-81d9-2cd1ca348609"
},
"image": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "c06f9960-6636-4e97-b42d-c7c5aa799a83",
"name": "pexels-photo-211997",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
},
"altText": "Woman in a patterned top wearing a black hat"
},
"headline": "The most stylish hats.",
"subheading": "From our signature collection."
},
{
"_meta": {
"name": "White hat slide",
"schema": "https://example.com/carousel-slide",
"deliveryId": "28c75b57-2c66-4b24-9059-ddc2b05a44d4"
},
"imageItem": {
"_meta": {
"name": "White hat image",
"schema": "https://schema-examples.com/example-image",
"deliveryId": "3627a6f4-afbf-4fd9-8882-644a15e95a0c"
},
"image": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "a7fce272-710c-4ca5-bb48-fc6689ba5e84",
"name": "woman-white-hat-winter",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
},
"altText": "Woman in a black coat with a white bobble hat."
},
"headline": "We've got you covered this winter.",
"subheading": "Warm hats for cold days."
},
{
"_meta": {
"name": "Coat with hood slide",
"schema": "https://example.com/carousel-slide",
"deliveryId": "f2f989b5-4a06-4a9b-9fb0-36ea3b3cae78"
},
"imageItem": {
"_meta": {
"name": "Coat with hood image",
"schema": "https://schema-examples.com/example-image",
"deliveryId": "860cf3a9-3dba-41d4-8e72-8dd2cff79dca"
},
"image": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "eb23a73c-e720-44c6-b3e3-61d61413f847",
"name": "winter-coat-darkblue",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
},
"altText": "Woman in a coat with hood and scarf."
},
"headline": "The best of both worlds.",
"subheading": "Great coats to keep you warm."
},
{
"_meta": {
"name": "Red beret slide",
"schema": "https://example.com/carousel-slide",
"deliveryId": "efe831c2-c5b9-4cde-9c08-0f946968ab47"
},
"imageItem": {
"_meta": {
"name": "Red beret image",
"schema": "https://schema-examples.com/example-image",
"deliveryId": "bc5fe8d2-3ed3-4363-8223-3ccd5be0ac7d"
},
"image": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "578da168-591d-402f-b243-6f701cf9f1ee",
"name": "red-coat-red-beret",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
},
"altText": "Woman in coat wearing a red beret"
},
"headline": "Stay warm. Stay stylish.",
"subheading": "Our latest styles."
}
]
}
}

Example: format = inlined, depth = 1
Link copied!

The following retrieves the carousel content item inlined with depth=1.

https://ampproduct-doc.cdn.content.amplience.net/content/id/bd89c2ed-0ed5-4304-8c89-c0710af500e2?depth=1&format=inlined

The carousel is the root item in the dependency tree, the carousel slides are level 1, and the image items that each carousel slide links to are level 2. By specifying a depth of 1, we are retrieving the carousel and carousel slides and just the content item id for the image items.

{
"content": {
"_meta": {
"name": "Hats carousel",
"schema": "https://example.com/carousel",
"deliveryId": "bd89c2ed-0ed5-4304-8c89-c0710af500e2"
},
"slides": [
{
"_meta": {
"name": "Black hat slide",
"schema": "https://example.com/carousel-slide",
"deliveryId": "7823de65-2e67-450c-a5db-d8c9b616801b"
},
"imageItem": [
{
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "https://schema-examples.com/example-image",
"id": "4219a628-2a8b-4d5b-81d9-2cd1ca348609"
}
],
"headline": "The most stylish hats.",
"subheading": "From our signature collection."
},
{
"_meta": {
"name": "White hat slide",
"schema": "https://example.com/carousel-slide",
"deliveryId": "28c75b57-2c66-4b24-9059-ddc2b05a44d4"
},
"imageItem": [
{
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "https://schema-examples.com/example-image",
"id": "3627a6f4-afbf-4fd9-8882-644a15e95a0c"
}
],
"headline": "We've got you covered this winter.",
"subheading": "Warm hats for cold days."
},
{
"_meta": {
"name": "Coat with hood slide",
"schema": "https://example.com/carousel-slide",
"deliveryId": "f2f989b5-4a06-4a9b-9fb0-36ea3b3cae78"
},
"imageItem": [
{
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "https://schema-examples.com/example-image",
"id": "860cf3a9-3dba-41d4-8e72-8dd2cff79dca"
}
],
"headline": "The best of both worlds.",
"subheading": "Great coats to keep you warm."
},
{
"_meta": {
"name": "Red beret slide",
"schema": "https://example.com/carousel-slide",
"deliveryId": "efe831c2-c5b9-4cde-9c08-0f946968ab47"
},
"imageItem": [
{
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "https://schema-examples.com/example-image",
"id": "bc5fe8d2-3ed3-4363-8223-3ccd5be0ac7d"
}
],
"headline": "Stay warm. Stay stylish.",
"subheading": "Our latest styles."
}
]
}
}

locale
Link copied!

When content items are created from content type schemas that include localized properties, users can enter a separate value in the localized fields for each of the locales that are available on a hub. An example is shown in the image below.

A content item with localizable properties. Users can enter values for each supported locale.

You can use the Content Delivery 2 API to retrieve the full localized content for all locales, or filter it by a specific locale using the locale parameter.

For example the following delivery URL will return the content localized for the French locale for the content item (shown above) with the delivery key "main-page-feature-banner". You can retrieve the content by delivery key or id.

https://ampproduct-doc.cdn.content.amplience.net/content/key/main-page-feature-banner?depth=all&format=inlined&locale=fr-FR

Locale filtering rules
Link copied!

There are a number of rules that are used to determine which locale to use based on the locale parameter.

  • An exact match such as locale=fr-FR will return content for the chosen locale
  • locale=* will return content for the first locale that contains a value
  • locale=en-* will return content for the first locale that has "en" as a language code
  • You can specify multiple locales separated by a comma and these will be evaluated from left to right until a matching locale is found. For example, locale=fr-BE,en-GB will first look for content for the fr-BE locale and if none is available will look for content with the en-GB locale.

If a locale cannot be found for a localized property then that property value will be set to null.

For more information about locales, see the localization overview section.

Get multiple content items
Link copied!

Use this request to retrieve multiple content items or slots by id or delivery key.

Note that this is a POST request, while Get Content by Key and Get Content by id are GET requests and are used to retrieve individual items.

Request URL
Link copied!

Request method: POST

https://{hubname}.cdn.content.amplience.net/content/fetch

Description
Link copied!

The ids and delivery keys of the items to retrieve are specified in the request body.

Example:

https://ampproduct-doc.cdn.content.amplience.net/content/fetch

Request body
Link copied!

PropertyTypeDescription
parameters (optional)objectSettings to apply to all items returned in the response.

depth: root (default) or all. See depth for more details.
format: linked (default) or inline. See format for more details.
locale: Retrieve content for the specified locale. See locale for more details. Note that if no parameters are specified the defaults will be used.
requestsarrayAn array of ids and delivery keys. For each item specify key or id.

key: the delivery key of the item to return | id: the id of the item to return

overrides: (optional). Parameters to be applied to this item. See the overrides example for an example request and response.

See examples for example requests and responses showing different combinations of parameters.

Notes
Link copied!

The combined maximum number of ids and delivery keys that can be included in a request is 12.

Response
Link copied!

The content-type of the response header is application/json; charset=UTF-8.

  • Items will be returned in the order in which they are requested.

  • When requesting multiple items, if one item cannot be retrieved, for example if an item with the specified id or delivery key cannot be found, then an error will be shown for that individual request and the other content items will still be returned.

PropertyTypeDescription
responsesarrayAn array of content, linkedContent or error codes.

content: The content item requested | error: An error type and message. See partial error reponse for an example. Note: when requesting content in linked data format, items linked to another content item, such as a carousel or grid, will be returned as

linkedContent. See the overrides example for an example response including linked content.

Status codes
Link copied!

Status codeDescription
200The request has succeeded. Errors may be shown for individual items
400Bad Request.
500Internal error

Example: no parameters
Link copied!

A simple request body to retrieve two content items, one by id and one by key is shown below. No parameters are specified, so the defaults will be used.

{
"requests": [
{
"id": "eefaf401-9551-41dd-aa5e-a5362990b1b7"
},
{
"key": "home-page/feature-promo-banner"
}
]
}

To try out the request use the following cURL.

curl -d '{"requests": [ {"id" : "eefaf401-9551-41dd-aa5e-a5362990b1b7"}, {"key": "home-page/feature-promo-banner"}]}' -H "Content-Type: application/json" -X POST https://ampproduct-doc.cdn.content.amplience.net/content/fetch
{
"responses": [
{
"content": {
"_meta": {
"name": "spring-banner",
"schema": "http://docexample.com/tutorialbanner.json",
"deliveryKey": "main-section-feature--banner",
"deliveryId": "eefaf401-9551-41dd-aa5e-a5362990b1b7"
},
"background": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "499ceb10-18dc-48be-baa7-306f938928cd",
"name": "womaninfield",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
},
"headline": "Get ready for Spring",
"strapline": "It will be here before you know it",
"calltoactiontext": "Visit our Spring Collection",
"calltoactionurl": "http://www.example.com/spring"
}
},
{
"content": {
"_meta": {
"name": "winter-banner",
"schema": "http://docexample.com/tutorialbanner.json",
"deliveryKey": "home-page/feature-promo-banner",
"deliveryId": "660b863e-0747-4462-8de2-1796cdaf2d16"
},
"background": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "fc0d9587-9c1c-4e0a-8135-01a2dec6c789",
"name": "exotic-fashion-hat",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
},
"headline": "Spring is here!",
"strapline": "Wrap up. Stay calm. Drink some tea.",
"calltoactiontext": "Buy some tea",
"calltoactionurl": "http://www.amplience.com"
}
}
]
}

Example: depth and format parameters
Link copied!

In this example 3 items are requested, one of which is a carousel that includes links to other content items. depth is set to all so the carousel and all of its dependents will be returned.

{
"parameters": {
"depth": "all",
"format": "inlined"
},
"requests": [
{
"id": "eefaf401-9551-41dd-aa5e-a5362990b1b7"
},
{
"key": "home-page/feature-promo-banner"
},
{
"id": "2d9871c5-01bc-4a85-b6d9-1c0baa1607cc"
}
]
}

You can use the following curl example to try this out.

curl -d' { "parameters": { "depth": "all", "format": "inlined" }, "requests": [ { "id": "eefaf401-9551-41dd-aa5e-a5362990b1b7" }, { "key": "home-page/feature-promo-banner" }, { "id": "2d9871c5-01bc-4a85-b6d9-1c0baa1607cc" } ] } ' -H "Content-Type: application/json" -X POST https://ampproduct-doc.cdn.content.amplience.net/content/fetch
{
"responses": [
{
"content": {
"_meta": {
"name": "spring-banner",
"schema": "http://docexample.com/tutorialbanner.json",
"deliveryKey": "main-section-feature--banner",
"deliveryId": "eefaf401-9551-41dd-aa5e-a5362990b1b7"
},
"background": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "499ceb10-18dc-48be-baa7-306f938928cd",
"name": "womaninfield",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
},
"headline": "Get ready for Spring",
"strapline": "It will be here before you know it",
"calltoactiontext": "Visit our Spring Collection",
"calltoactionurl": "http://www.example.com/spring"
}
},
{
"content": {
"_meta": {
"name": "winter-banner",
"schema": "http://docexample.com/tutorialbanner.json",
"deliveryKey": "home-page/feature-promo-banner",
"deliveryId": "660b863e-0747-4462-8de2-1796cdaf2d16"
},
"background": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "fc0d9587-9c1c-4e0a-8135-01a2dec6c789",
"name": "exotic-fashion-hat",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
},
"headline": "Spring is here!",
"strapline": "Wrap up. Stay calm. Drink some tea.",
"calltoactiontext": "Buy some tea",
"calltoactionurl": "http://www.amplience.com"
}
},
{
"content": {
"_meta": {
"name": "spring-carousel",
"schema": "http://example.com/carousel.json",
"deliveryId": "2d9871c5-01bc-4a85-b6d9-1c0baa1607cc"
},
"slides": [
{
"_meta": {
"name": "white-hat",
"schema": "http://example.com/carouselslide.json",
"deliveryId": "b848b43e-6e7f-482e-b652-cb076b6a9bb2"
},
"image": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "7facf6f8-fea8-4f19-ac65-d9535ba1bf38",
"name": "white-winter-hat",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
},
"image-alt": "Woman in a white hat"
},
{
"_meta": {
"name": "couple-in-sweaters",
"schema": "http://example.com/carouselslide.json",
"deliveryId": "da105865-fddc-4e3b-88eb-f7aaf11db860"
},
"image": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "ac91e82b-25e9-4da4-bd26-42b21ab21977",
"name": "snow-fashion",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
},
"image-alt": "couple in sweaters"
},
{
"_meta": {
"name": "green-coat",
"schema": "http://example.com/carouselslide.json",
"deliveryId": "903f32d0-bc49-4398-948c-e53eac818909"
},
"image": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "b926c31d-9092-4f8e-b14d-e0c7f311bb3e",
"name": "woman-red-hair-green-scarf",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
}
},
{
"_meta": {
"name": "red-coat-in-the-snow",
"schema": "http://example.com/carouselslide.json",
"deliveryId": "4acc9fac-d075-42a9-bf76-61055e0fdf59"
},
"image": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "d9a61e3f-0a7d-4aff-a532-dec8c1aa07b8",
"name": "girl-red-coat-cold",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
}
}
]
}
}
]
}

Example: overrides parameter for an individual request
Link copied!

In this example request we are requesting 3 items including a carousel. For the carousel ("id": "2d9871c5-01bc-4a85-b6d9-1c0baa1607cc"), we are overriding the parameters using the overrides property to request the content in linked data format.

{
"parameters": {
"depth": "all",
"format": "inlined"
},
"requests": [
{
"id": "eefaf401-9551-41dd-aa5e-a5362990b1b7"
},
{
"key": "home-page/feature-promo-banner"
},
{
"id": "2d9871c5-01bc-4a85-b6d9-1c0baa1607cc",
"overrides": {
"format": "linked"
}
]
}

You can use the following curl example to try this request.

 curl -d' {"parameters": { "depth": "all", "format": "inlined" }, "requests": [ { "id": "eefaf401-9551-41dd-aa5e-a5362990b1b7" }, { "key": "home-page/feature-promo-banner" }, { "id": "2d9871c5-01bc-4a85-b6d9-1c0baa1607cc", "overrides": { "format": "linked" } } ] } ' -H "Content-Type: application/json" -X POST https://ampproduct-doc.cdn.content.amplience.net/content/fetch
{
"responses": [
{
"content": {
"_meta": {
"name": "spring-banner",
"schema": "http://docexample.com/tutorialbanner.json",
"deliveryKey": "main-section-feature--banner",
"deliveryId": "eefaf401-9551-41dd-aa5e-a5362990b1b7"
},
"background": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "499ceb10-18dc-48be-baa7-306f938928cd",
"name": "womaninfield",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
},
"headline": "Get ready for Spring",
"strapline": "It will be here before you know it",
"calltoactiontext": "Visit our Spring Collection",
"calltoactionurl": "http://www.example.com/spring"
}
},
{
"content": {
"_meta": {
"name": "winter-banner",
"schema": "http://docexample.com/tutorialbanner.json",
"deliveryKey": "home-page/feature-promo-banner",
"deliveryId": "660b863e-0747-4462-8de2-1796cdaf2d16"
},
"background": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "fc0d9587-9c1c-4e0a-8135-01a2dec6c789",
"name": "exotic-fashion-hat",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
},
"headline": "Spring is here!",
"strapline": "Wrap up. Stay calm. Drink some tea.",
"calltoactiontext": "Buy some tea",
"calltoactionurl": "http://www.amplience.com"
}
},
{
"content": {
"_meta": {
"name": "spring-carousel",
"schema": "http://example.com/carousel.json",
"deliveryId": "2d9871c5-01bc-4a85-b6d9-1c0baa1607cc"
},
"slides": [
{
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "http://example.com/carouselslide.json",
"id": "b848b43e-6e7f-482e-b652-cb076b6a9bb2"
},
{
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "http://example.com/carouselslide.json",
"id": "da105865-fddc-4e3b-88eb-f7aaf11db860"
},
{
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "http://example.com/carouselslide.json",
"id": "903f32d0-bc49-4398-948c-e53eac818909"
},
{
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
"contentType": "http://example.com/carouselslide.json",
"id": "4acc9fac-d075-42a9-bf76-61055e0fdf59"
}
]
},
"linkedContent": [
{
"_meta": {
"name": "white-hat",
"schema": "http://example.com/carouselslide.json",
"deliveryId": "b848b43e-6e7f-482e-b652-cb076b6a9bb2"
},
"image": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "7facf6f8-fea8-4f19-ac65-d9535ba1bf38",
"name": "white-winter-hat",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
},
"image-alt": "Woman in a white hat"
},
{
"_meta": {
"name": "red-coat-in-the-snow",
"schema": "http://example.com/carouselslide.json",
"deliveryId": "4acc9fac-d075-42a9-bf76-61055e0fdf59"
},
"image": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "d9a61e3f-0a7d-4aff-a532-dec8c1aa07b8",
"name": "girl-red-coat-cold",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
}
},
{
"_meta": {
"name": "green-coat",
"schema": "http://example.com/carouselslide.json",
"deliveryId": "903f32d0-bc49-4398-948c-e53eac818909"
},
"image": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "b926c31d-9092-4f8e-b14d-e0c7f311bb3e",
"name": "woman-red-hair-green-scarf",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
}
},
{
"_meta": {
"name": "couple-in-sweaters",
"schema": "http://example.com/carouselslide.json",
"deliveryId": "da105865-fddc-4e3b-88eb-f7aaf11db860"
},
"image": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "ac91e82b-25e9-4da4-bd26-42b21ab21977",
"name": "snow-fashion",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
},
"image-alt": "couple in sweaters"
}
]
}
]
}

Example partial error response
Link copied!

In this example request we are requesting 3 items but, in order to demonstrate a partial error response, we have introduced a typo into the request for the item with the delivery key "home-page/feature-promo-banner".

{
"parameters": {
"depth": "all",
"format": "inlined"
},
"requests": [
{
"id": "eefaf401-9551-41dd-aa5e-a5362990b1b7"
},
{
"key": "home-page/featur-promo-banner"
},
{
"id": "2d9871c5-01bc-4a85-b6d9-1c0baa1607cc",
"overrides": {
"format": "linked"
}
]
}

You can use the following curl example to try this request.

 curl -d' {"parameters": { "depth": "all", "format": "inlined" }, "requests": [ { "id": "eefaf401-9551-41dd-aa5e-a5362990b1b7" }, { "key": "home-page/featur-promo-banner" }, { "id": "2d9871c5-01bc-4a85-b6d9-1c0baa1607cc"} ] } ' -H "Content-Type: application/json" -X POST https://ampproduct-doc.cdn.content.amplience.net/content/fetch

Note that the other items are returned and the error is shown for the request containing a typo in the delivery key. To assist with debugging, error responses will include the request delivery key or id.

{
"error": {
"type": "CONTENT_NOT_FOUND",
"message": "Not found",
"data": {
"deliveryKey": "home-page/featur-promo-banner"
}
}
}

Example request body: error response
Link copied!

{
"responses": [
{
"content": {
"_meta": {
"name": "spring-banner",
"schema": "http://docexample.com/tutorialbanner.json",
"deliveryKey": "main-section-feature--banner",
"deliveryId": "eefaf401-9551-41dd-aa5e-a5362990b1b7"
},
"background": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "499ceb10-18dc-48be-baa7-306f938928cd",
"name": "womaninfield",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
},
"headline": "Get ready for Spring",
"strapline": "It will be here before you know it",
"calltoactiontext": "Visit our Spring Collection",
"calltoactionurl": "http://www.example.com/spring"
}
},
{
"error": {
"type": "CONTENT_NOT_FOUND",
"message": "Not found",
"data": {
"deliveryKey": "home-page/featur-promo-banner"
}
}
},
{
"content": {
"_meta": {
"name": "spring-carousel",
"schema": "http://example.com/carousel.json",
"deliveryId": "2d9871c5-01bc-4a85-b6d9-1c0baa1607cc"
},
"slides": [
{
"_meta": {
"name": "white-hat",
"schema": "http://example.com/carouselslide.json",
"deliveryId": "b848b43e-6e7f-482e-b652-cb076b6a9bb2"
},
"image": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "7facf6f8-fea8-4f19-ac65-d9535ba1bf38",
"name": "white-winter-hat",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
},
"image-alt": "Woman in a white hat"
},
{
"_meta": {
"name": "couple-in-sweaters",
"schema": "http://example.com/carouselslide.json",
"deliveryId": "da105865-fddc-4e3b-88eb-f7aaf11db860"
},
"image": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "ac91e82b-25e9-4da4-bd26-42b21ab21977",
"name": "snow-fashion",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
},
"image-alt": "couple in sweaters"
},
{
"_meta": {
"name": "green-coat",
"schema": "http://example.com/carouselslide.json",
"deliveryId": "903f32d0-bc49-4398-948c-e53eac818909"
},
"image": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "b926c31d-9092-4f8e-b14d-e0c7f311bb3e",
"name": "woman-red-hair-green-scarf",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
}
},
{
"_meta": {
"name": "red-coat-in-the-snow",
"schema": "http://example.com/carouselslide.json",
"deliveryId": "4acc9fac-d075-42a9-bf76-61055e0fdf59"
},
"image": {
"_meta": {
"schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
},
"id": "d9a61e3f-0a7d-4aff-a532-dec8c1aa07b8",
"name": "girl-red-coat-cold",
"endpoint": "ampproduct",
"defaultHost": "cdn.media.amplience.net"
}
}
]
}
}
]
}

Unpublishing content
Link copied!

You can unpublish content so that it can no longer be retrieved using its production Content Delivery URL. When you query unpublished, or never been published, content using its production URL, a 404 response will be returned with a "CONTENT_NOT_FOUND" error.

Unpublished content will also be removed from results returned by the Filter API.

Unpublishing linked content
Link copied!

When you unpublish content, linked content will not be unpublished automatically. So if you unpublish a carousel that is linked to carousel slides, the linked content will remain published.

If you unpublish a linked content item, then it will still be returned when you query published items that contain content links to it. So if you unpublish a carousel slide and then query the dependency tree of its parent (the carousel), the carousel slide will still be returned in the list of dependents.

If you have any content references to unpublished content, retrieving content using these references will return a 404 status code.

Retrieving unpublished content
Link copied!

To retrieve unpublished (or never published) content by id or key, for previews and visualizations, use a virtual staging environment in place of the production delivery URL. The virtual staging domain is associated with the hub from which the content is retrieved.

Retrieving unpublished content by id
Link copied!

{virtualstagingdomain}/content/id/{id}

id is the delivery ID for the item in UUID format.

Retrieving unpublished content by key
Link copied!

{virtualstagingdomain}/content/key/{key}

key is the item's delivery key.

Example
Link copied!

The following will retrieve unpublished content with the id c19009c5-8621-48eb-b208-13aa8027c6e7 from the virtual staging environment kuifkfmrgfsv1qjsmei8dbbnq.staging.bigcontent.io.

kuifkfmrgfsv1qjsmei8dbbnq.staging.bigcontent.io/content/id/c19009c5-8621-48eb-b208-13aa8027c6e7?depth=all&format=inlined

Item properties
Link copied!

Using the item properties pane is a convenient way to find the URL to retrieve the content item or slot.

On those hubs that have Content Delivery 2 enabled, a section in the properties window will display the URL required to retrieve the item using the Content Delivery 2 API.

The content item properties pane includes a Content Delivery 2 section.

A content item with localizable properties. Users can enter values for each supported locale

For items that have a delivery key, a URL is shown to retrieve the content using the content delivery 2 API using either the id (1) or delivery key (2). For content items and slots that don't have a delivery key, only the delivery URL to retrieve the content using the id is included.

Finding the hub name
Link copied!

The hub name used in the APIs is available from the "properties" item from the "settings" menu. In this example the hub name is "ampproduct-doc".

The hub ID is also displayed and can be copied by clicking the icon to the right of the id. This is particularly useful if you need the hub id when using the content management API.

The hub name is shown in the properties window.

Usage notes
Link copied!

  • Note that when content is published on hubs that have Content Delivery 2 enabled, it is accessible from both the original Content Delivery API and the Content Delivery 2 API. However, features such as delivery keys are only available when using the Content Delivery 2 API.

  • The Time To Live (TTL) for the Content Delivery Network (CDN) used by Content Delivery 2 is 5 minutes.

OpenAPI format
Link copied!

The Content Delivery 2 API uses the OpenAPI format which can be imported into API tools such as such as Insomnia or Postman. This is a great way to get familiar with the API, the request format and responses.

A button to download the API spec can be found at the top of the content delivery API reference. You can import the JSON file into your chosen API tool.

You can import the Content Delivery 2 API specification into Insomnia or Postman.

You can find more out more in our API documentation blog post.

Adding and updating delivery keys

Content delivery API reference

Filter API

Blog post: Our new and improved API documentation

Content Delivery API (legacy)