--- canonical: https://amplience.com/developers/docs/apis/content-delivery/content-delivery-overview/ title: Overview description: The Amplience next generation of content delivery is optimized to be even faster, easier to use and more flexible, with delivery keys and formatting options. audience: Developer image: https://cdn.media.amplience.net/i/ampproduct/docs-content-graph?w=1200&h=630 image_width: 1200 image_height: 630 date_published: 2022-06-23 date_modified: 2025-09-02 --- # HTTP Content Delivery 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 v2 features even faster response times than the original Content Delivery v1 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](https://amplience.com/developers/docs/dev-tools/guides-tutorials/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](#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](#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](https://amplience.com/developers/docs/apis/content-delivery/filter-api) page. > **Info:** If you want to use Content Delivery v2 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 In this section we provide an overview of the API, example usage and some sample returned content. For more information see the [Content Delivery v2 API reference](https://amplience.com/developers/docs/apis/content-delivery-reference) You can retrieve a single content item by [delivery key](#get-content-by-key) or [id](#get-content-by-id), or [retrieve multiple items](#get-multiple-content-items) in the same request. ## Get Content by Key Retrieve the content item or slot with the delivery key. #### Request URL ``` https://{hubname}.cdn.content.amplience.net/content/key/{key} ``` #### Description `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](https://amplience.com/developers/docs/dev-tools/guides-tutorials/delivery-keys) page for more details. #### Example The following example shows the Content Delivery v2 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 Retrieve the content item or slot with the specified delivery ID. #### Request URL ``` https://{hubname}.cdn.content.amplience.net/content/id/{id} ``` #### Description `id` is the delivery ID for the item in UUID format. #### Example The following example shows the Content Delivery v2 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 ``` ## Carousel example 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..](https://cdn.media.amplience.net/i/ampproduct/docs-content-graph?w=1880&fmt=png 'The carousel links to carousel slides and image content items.') ## Parameters Additional query parameters can be used to define the format of content retrieved by ID or key. ### depth 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: | Value | Description | | ------ | -------------------------------------------------------------------------------------------------------------------------------------- | | root | **Default**. Return the root item only and not any descendants. | | all | Return the root item and all its descendants. The content will be returned in the format specified by the format parameter. | | 0 … 22 | An 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 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 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 ``` ```json { "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 The following retrieves the [carousel](#carousel-example) 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. ```json { "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 The format parameter allows you to specify whether content is retrieved in bandwidth optimised linked data format or inlined as a content tree. | Value | Description | | ------- | ----------------------------------------------------------------- | | linked | **Default**. Returns the content in a bandwidth optimised format. | | inlined | Returns 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 The following retrieves the carousel content item used in the [depth](#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 ``` ```json { "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 The following retrieves the [carousel](#carousel-example) 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. ```json { "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 When content items are created from content type schemas that include [localized properties](https://amplience.com/developers/docs/dev-tools/guides-tutorials/localization), 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.](https://cdn.media.amplience.net/i/ampproduct/content-delivery-locales-v2?w=1880&fmt=png 'A content item with localizable properties. Users can enter values for each supported locale.') You can use the Content Delivery v2 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 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](https://amplience.com/developers/docs/user-guides/produce-content/localize) section. ## Get multiple content items 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](#get-content-by-key) and [Get Content by id](#get-content-by-id) are GET requests and are used to retrieve individual items. #### Request URL Request method: POST ``` https://{hubname}.cdn.content.amplience.net/content/fetch ``` #### Description 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 | Property | Type | Description | | ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | parameters (_optional_) | object | Settings to apply to all items returned in the response.

**depth:** root (default) or all. See [depth](#depth) for more details.
**format**: linked (default) or inline. See [format](#format) for more details.
**locale:** Retrieve content for the specified locale. See [locale](#locale) for more details. Note that if no parameters are specified the defaults will be used. | | requests | array | An 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](#example-overrides-parameter-for-an-individual-request) for an example request and response. | See [examples](#get-multiple-content-items) for example requests and responses showing different combinations of parameters. #### Notes The combined maximum number of ids and delivery keys that can be included in a request is 12. #### Response 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. | Property | Type | Description | | --------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | responses | array | An array of content, linkedContent or error codes.

**content**: The content item requested | **error**: An error type and message. See [partial error reponse](#example-partial-error-response) 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](#example-overrides-parameter-for-an-individual-request) for an example response including linked content. | #### Status codes | Status code | Description | | ----------- | ------------------------------------------------------------------- | | 200 | The request has succeeded. Errors may be shown for individual items | | 400 | Bad Request. | | 500 | Internal error | #### Example: no parameters 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. ```json { "requests": [ { "id": "eefaf401-9551-41dd-aa5e-a5362990b1b7" }, { "key": "home-page/feature-promo-banner" } ] } ``` To try out the request use the following [cURL](https://github.com/curl/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 ``` ```json { "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 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. ```json { "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 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 ``` ```json { "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 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. ```json { "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 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 ``` ```json { "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 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". ```json { "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 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. ```json { "error": { "type": "CONTENT_NOT_FOUND", "message": "Not found", "data": { "deliveryKey": "home-page/featur-promo-banner" } } } ``` #### Example request body: error response ```json { "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 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](https://amplience.com/developers/docs/apis/content-delivery/filter-api). ### Unpublishing linked content 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](https://amplience.com/developers/docs/concepts/relationships/#content-links) to it. So if you unpublish a carousel slide and then query the [dependency tree](#depth) of its parent (the carousel), the carousel slide will still be returned in the list of dependents. If you have any [content references](https://amplience.com/developers/docs/concepts/relationships/#content-references) to unpublished content, retrieving content using these references will return a 404 status code. ## Retrieving unpublished content 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 ``` {virtualstagingdomain}/content/id/{id} ``` `id` is the delivery ID for the item in UUID format. #### Retrieving unpublished content by key ``` {virtualstagingdomain}/content/key/{key} ``` `key` is the item's delivery key. #### Example 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 Using the [item properties pane](https://amplience.com/developers/docs/user-guides/produce-content/create/#content-item-properties) is a convenient way to find the URL to retrieve the content item or slot. On those hubs that have Content Delivery v2 enabled, the Content delivery section of the properties window will display the URL required to retrieve the item using the Content Delivery v2 API. ![The content item properties pane includes a Content Delivery v2 section.](https://cdn.media.amplience.net/i/ampproduct/content-item-properties-v2?w=1880&fmt=png 'The content item properties pane includes a Content Delivery v2 section.') For items that have a delivery key, a URL is shown to retrieve the content using the Content Delivery v2 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 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](https://amplience.com/developers/docs/apis/content-management-reference). ![The hub name is shown in the properties window.](https://cdn.media.amplience.net/i/ampproduct/hub-name-v2?w=1880&fmt=png 'The hub name is shown in the properties window.') ## Usage notes - Note that when content is published on hubs that have Content Delivery v2 enabled, it is accessible from both the original Content Delivery v1 API and the Content Delivery v2 API. However, features such as delivery keys are only available when using the Content Delivery v2 API. - The Time To Live (TTL) for the Content Delivery Network (CDN) used by Content Delivery v2 is 5 minutes. ## OpenAPI format The Content Delivery v2 API uses the [OpenAPI](http://spec.openapis.org/oas/v3.0.2) format which can be imported into API tools such as such as [Insomnia](https://insomnia.rest/) or [Postman](https://www.getpostman.com/). 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](https://amplience.com/developers/docs/apis/content-delivery-reference). You can import the JSON file into your chosen API tool. ![You can import the Content Delivery v2 API specification into Insomnia or Postman.](https://cdn.media.amplience.net/i/ampproduct/cdv2-insomnia-1?w=1880&fmt=png 'You can import the Content Delivery v2 API specification into Insomnia or Postman.') You can find more out more in our [API documentation blog post](https://productblog.amplience.com/blog/dc-api-docs-update/). ## Related pages [Adding and updating delivery keys](https://amplience.com/developers/docs/dev-tools/guides-tutorials/delivery-keys) [Content delivery v2 API reference](https://amplience.com/developers/docs/apis/content-delivery-reference) [Filter API](https://amplience.com/developers/docs/apis/content-delivery/filter-api) [Blog post: Our new and improved API documentation](https://productblog.amplience.com/blog/dc-api-docs-update/) [Content Delivery v1 API](https://amplience.com/developers/docs/apis/content-delivery/legacy-content-delivery/)