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.
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
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.
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.
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.
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.
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 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.
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.
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.
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 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.
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.
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.
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.
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.
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.
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.
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.
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.
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".
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.
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.
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.
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.
The following will retrieve unpublished content with the id c19009c5-8621-48eb-b208-13aa8027c6e7 from the virtual staging environment kuifkfmrgfsv1qjsmei8dbbnq.staging.bigcontent.io.
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.
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.
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.
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.
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.
