Content Delivery 2

Overview

Our next generation of content delivery is optimised to be even faster, easier to use and more flexible. Compared to the existing Content Delivery API it offers the following additional features:

  • Speed. Content Delivery 2 features even faster response times than the 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.

How do I get Content Delivery 2?

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

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

Retrieve the content item or slot with the delivery key.

URL Description
https://{hubname}.cdn.content.amplience.net/content/key/{key} 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

The following example shows the Content Delivery 2 URL for a hub named ampproduct-doc used to retrieve a published item with the delivery key home-page/main-feature-slot.

https://ampproduct-doc.cdn.content.amplience.net/content/key/home-page/main-feature-slot

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.

URL Description
https://{hubname}.cdn.content.amplience.net/content/id/{id} id is the delivery ID for the item in UUID format.

Example

The following example shows the Content Delivery 2 URL for a hub named ampproduct-doc retrieving a published content item with the ID c19009c5-8621-48eb-b208-13aa8027c6e7.

https://ampproduct-doc.cdn.content.amplience.net/content/id/c19009c5-8621-48eb-b208-13aa8027c6e7

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.

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.
Examples

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/9c912e92-0825-4e70-8de9-b2ea4fb2a1c6
{ 
  "content":{ 
    "_meta":{ 
      "name":"winter-carousel",
      "schema":"http://example.com/carousel.json",
      "deliveryId":"9c912e92-0825-4e70-8de9-b2ea4fb2a1c6"
    },
    "slides":[ 
      { 
        "_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"
      },
      { 
        "_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"
      }
    ]
  }
}

The following will retrieve a content item and all its descendants:

https://ampproduct-doc.cdn.content.amplience.net/content/id/9c912e92-0825-4e70-8de9-b2ea4fb2a1c6?depth=all
{ 
  "content":{ 
    "_meta":{ 
      "name":"winter-carousel",
      "schema":"http://example.com/carousel.json",
      "deliveryId":"9c912e92-0825-4e70-8de9-b2ea4fb2a1c6"
    },
    "slides":[ 
      { 
        "_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"
      },
      { 
        "_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"
      }
    ]
  },
  "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":"i1.adis.ws"
      }
    },
    { 
      "_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":"i1.adis.ws"
      }
    },
    { 
      "_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":"i1.adis.ws"
      }
    },
    { 
      "_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":"i1.adis.ws"
      }
    }
  ]
}

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.

Examples

The following will retrieve a slot with the delivery key home-page/main-feature-slot in inlined format and with depth=all.

https://ampproduct-doc.cdn.content.amplience.net/content/key/home-page/main-feature-slot?depth=all&format=inlined
{ 
  "content":{ 
    "_meta":{ 
      "name":"home-page-feature-slot",
      "schema":"http://docexample.com/tutorialbannerslot.json",
      "deliveryKey":"home-page/main-feature-slot",
      "edition":{ 
        "id":"5de4ff7552faff0001478d17",
        "start":"2019-12-02T12:14:00.000Z",
        "end":"2019-12-09T23:59:59.999Z"
      },
      "deliveryId":"5d69bdef-df0b-4680-acfc-0bdaa2a82bed"
    },
    "bannerslot":{ 
      "_meta":{ 
        "name":"winter-banner",
        "schema":"http://docexample.com/tutorialbanner.json",
        "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":"i1.adis.ws"
      },
      "headline":"Winter is here",
      "strapline":"Wrap up. Stay calm. Drink tea.",
      "calltoactiontext":"Buy some tea",
      "calltoactionurl":"http://www.amplience.com"
    }
  }
}

The following retrieves the carousel content item used in the depth section inlined with depth=all.

https://ampproduct-doc.cdn.content.amplience.net/content/id/9c912e92-0825-4e70-8de9-b2ea4fb2a1c6?depth=all&format=inlined
{ 
  "content":{ 
    "_meta":{ 
      "name":"winter-carousel",
      "schema":"http://example.com/carousel.json",
      "deliveryId":"9c912e92-0825-4e70-8de9-b2ea4fb2a1c6"
    },
    "slides":[ 
      { 
        "_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":"i1.adis.ws"
        }
      },
      { 
        "_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":"i1.adis.ws"
        }
      },
      { 
        "_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":"i1.adis.ws"
        }
      },
      { 
        "_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":"i1.adis.ws"
        }
      }
    ]
  }
}

locale

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
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

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 by key or id

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 method URL Description
POST https://{hubname}.cdn.content.amplience.net/content/fetch 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 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.
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 for an example request and response.

See examples 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 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
Status code Description
200 The request has succeeded. Errors may be shown for individual items
400 Bad Request.
500 Internal error

Examples

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.

{
  "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":"i1.adis.ws"
            },
            "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":"i1.adis.ws"
            },
            "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.

{
  "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":"i1.adis.ws"
            },
            "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":"i1.adis.ws"
            },
            "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":"i1.adis.ws"
                  },
                  "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":"i1.adis.ws"
                  },
                  "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":"i1.adis.ws"
                  }
               },
               {
                  "_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":"i1.adis.ws"
                  }
               }
            ]
         }
      }
   ]
}
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.

{
  "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":"i1.adis.ws"
            },
            "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":"i1.adis.ws"
            },
            "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":"i1.adis.ws"
               },
               "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":"i1.adis.ws"
               }
            },
            {
               "_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":"i1.adis.ws"
               }
            },
            {
               "_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":"i1.adis.ws"
               },
               "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".

{
  "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
{
   "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":"i1.adis.ws"
            },
            "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":"i1.adis.ws"
                  },
                  "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":"i1.adis.ws"
                  },
                  "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":"i1.adis.ws"
                  }
               },
               {
                  "_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":"i1.adis.ws"
                  }
               }
            ]
         }
      }
   ]
}

Retrieving unpublished content

To retrieve unpublished 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.

URL Description
{virtualstagingdomain}/content/id/{id} id is the delivery ID for the item in UUID format.
{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 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
The content item properties pane includes a Content Delivery 2 section

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

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 name is shown in the properties window
The hub name is shown in the properties window

Usage notes

  • Note that when content is published on hubs that have Content Delivery 2 enabled, it is accessible from both the 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.

Using the Content Delivery 2 API with Insomnia and Postman

The Content Delivery 2 API uses the OpenAPI format which can be imported into API tools such as such as Insomnia 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 2 API reference, or you can download it directly and import the JSON file into your chosen API tool.

You can import the Content Delivery 2 API specification into Insomnia or Postman
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 2 API reference

Blog post: Our new and improved API documentation

results matching ""

    No results matching ""