Fresh API

About the Fresh API

The Fresh API allows you to retrieve content from Dynamic Content with no cache. It's designed specifically for the use of static site generators (SSG), such as Next.js, NuxtJS and Gatsby, that you can use to build your entire site ahead of time.

The Fresh API is intended for use by your static site generator build tools rather than to deliver content to the user in the browser.

Fresh API usage notes

  • The Fresh API uses the same format of requests and responses as the Content Delivery 2 API.
  • The Fresh API allows you to retrieve content without a cache.
  • The Fresh API should not be used to deliver content to the end user in the browser. It is only intended for use with your build tools.
  • To use the Fresh API, you must include an API key in the header of each request. This API key will be provided to you when the API is provisioned on your chosen hubs.
  • The Fresh API is rate limited. These limits will be discussed with you at the beginning of your project.
  • You can use the filter API to list, filter and sort content and return uncached content items.
  • You should not include staged content in the build process for your static site. The code for preview and visualization should be separate to your static site code.
  • The Content Delivery SDK includes support for the Fresh API.

Why use the Fresh API

Our next generation Content Delivery API, Content Delivery 2, is optimized for speed and scalability. To ensure that content is delivered to the user in the most efficient way possible, it is cached on our Content Delivery Network (CDN) with a Time to Live (TTL) of 5 minutes. This reduces latency and provides the best experience for the user.

The Fresh API ensures that when your build is triggered you will always retrieve the uncached, latest version of your content, rather than load the content from the cache. When using a static site generator with Dynamic Content you can trigger a build using our customizable webhooks service, when a content item is published, for example.

How do I get the Fresh API?

If you want to use the Fresh API 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.

Rate limits

Requests to the Fresh API are tracked against the API keys assigned to your hubs. Each of these API keys has a rate limit associated with it. Exceeding the rate limit will result in 429 responses from the service. When receiving a 429, your code should attempt a retry after delaying the next request with exponential back-off.

If you use the Content Delivery SDK to make requests to the Fresh API, you can configure the number of retries and the delay between retries.

Using the API

To use the Fresh API to retrieve uncached content replace cdn.content.amplience.net with fresh.content.amplience.net in your request URLs for the Content Delivery 2 APIs.

In this section we provide an overview of using the Fresh API including example requests and responses. For more examples see the Content Delivery 2 API page.

Get Content by Key or ID

Retrieve the content item or slot with the delivery key or content item id.

Request method URL Description
GET https://{hubname}.fresh.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.
GET https://{hubname}.fresh.content.amplience.net/content/id/{id} id is the delivery ID for the item in UUID format.

Example: https://ampproduct-doc.fresh.content.amplience.net/content/key

Request header

Header Value Description
X-API-Key {apiKey} The API key provided to you at the beginning of your project

Note that if you provide an invalid API key then you will receive a 403 error response to any requests to the Fresh API.

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.

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.

When using field level localization, you can retrieve content for the specified locale. See locales on the Content Delivery 2 API page for more details.

Example request

The following example shows the Fresh API URL for a hub named ampproduct-doc used to retrieve a published item with the content id 6757c1ab-6458-4ece-995e-9819a5cce7ff.

You must send your API key in the request in the X-API-Key header.

Example URL:

https://ampproduct-doc.fresh.content.amplience.net/content/id/6757c1ab-6458-4ece-995e-9819a5cce7ff?format=inlined&depth=all

You can use the following cURL request to try out the API, replacing {api-key} with your API key, ampproduct-doc with your hub name, and the content id with the id of some content from your hub.

curl -H "X-API-Key: {api-key}"  "https://ampproduct-doc.fresh.content.amplience.net/content/id/6757c1ab-6458-4ece-995e-9819a5cce7ff?format=inlined&depth=all"

Example response

The JSON response for the request is shown below. This content item is a carousel that is linked to carousel slides. The content is returned in inlined format and, because depth=all is specified, each of the carousel slides is returned as well as the carousel item.

{
   "content":{
      "_meta":{
         "name":"Summer carousel",
         "schema":"https://doc-example.com/carousel",
         "deliveryId":"6757c1ab-6458-4ece-995e-9819a5cce7ff"
      },
      "slides":[
         {
            "_meta":{
               "name":"Blue dress slide",
               "schema":"https://doc-example.com/carouselslide",
               "deliveryId":"4d81e399-2415-4d50-8049-164efb7360a5"
            },
            "image":{
               "_meta":{
                  "schema":"http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
               },
               "id":"8e46cbff-dcbe-4934-93d0-efdf416da97b",
               "name":"woman-checked-jacket-fllower-dress",
               "endpoint":"ampproduct",
               "defaultHost":"cdn.media.amplience.net"
            },
            "image-alt":"Blue dress"
         },
         {
            "_meta":{
               "name":"Hat slide",
               "schema":"https://doc-example.com/carouselslide",
               "deliveryId":"24b46785-cc72-4003-aeb8-2a27b98bacb1"
            },
            "image":{
               "_meta":{
                  "schema":"http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
               },
               "id":"69f8d25a-c178-4f8f-a223-7002139a5538",
               "name":"1377455-collection-spring",
               "endpoint":"ampproduct",
               "defaultHost":"cdn.media.amplience.net"
            },
            "image-alt":"Woman in hat"
         },
         {
            "_meta":{
               "name":"Bright colours slide",
               "schema":"https://doc-example.com/carouselslide",
               "deliveryId":"018a826e-31d0-4677-a9a5-7e097be8db38"
            },
            "image":{
               "_meta":{
                  "schema":"http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
               },
               "id":"33442fe3-4d2c-4c45-8c86-7ec3da73ac02",
               "name":"women-bright-colors",
               "endpoint":"ampproduct",
               "defaultHost":"classic.cdn.media.amplience.net"
            },
            "image-alt":"Bright colours slide"
         }
      ]
   }
}

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}.fresh.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.fresh.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.

Request header

Header Value Description
X-API-Key {apiKey} The API key provided to you at the beginning of your project
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.
403 Invalid API key.
500 Internal error.

Example multi get request

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.

You must send your API key in the request in the X-API-Key header.

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

To try out the request use the following cURL with your own API key and some content item ids and delivery keys from your hub.

curl -H "X-API-Key: {api-key}" -d '{"requests": [ {"id" : "eefaf401-9551-41dd-aa5e-a5362990b1b7"}, {"key": "home-page/feature-promo-banner"}]}' -H "Content-Type: application/json" -X POST https://ampproduct-doc.fresh.content.amplience.net/content/fetch

Example 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":"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"
         }
      }
   ]
}

List, filter and sort

You can also use the Fresh API to list, filter and sort content and return uncached results, using the same format of requests and responses as the Filter API. As with other Fresh API requests, you will need to include your API key in the header of each request and requests are rate limited.

To use the Fresh API to retrieve uncached content replace cdn.content.amplience.net with fresh.content.amplience.net in your request URLs for the Filter API.

In this section we'll provide an example of using the Fresh API to retrieve filtered content. You can find more details and lots of examples of how to list, filter and sort content on the Filter API page.

Request method URL Description
POST https://{hubname}.fresh.content.amplience.net/content/filter The filterable properties and (optional) sort key are included in the request body

Example: https://ampproduct-doc.fresh.content.amplience.net/content/filter

Request header

Header Value Description
X-API-Key {apiKey} The API key provided to you at the beginning of your project

Request body

Property Type Description
filterBy array An array of filterable properties and values.
Filterable properties must be specified in the trait:filterable section of a content type schema.
For each filterable property specify path and value:
path: The JSON pointer format path to the filterable property to use as a filter.
value: The value to match against.
If you specify multiple filters then all filters must be matched (AND).
sortBy
(optional)
object The sort key and sort order to use to apply to the result. If no sort key is specified then the default sort order is used. If there is no default sort order then created date is used.
The sort key must be specified in the trait:sortable section of each schema that contains the filterable property.
key: The sort key defined in the schema.
order(optional): ASC or DESC. Ascending or descending sort order. ASC is the default.

Additional optional parameters can be found on the Filter API page.

Example request

The request body for a filter request to retrieve content filtered by the "pdp-content-block" content type and multiple properties is shown below.

You must send your API key in the request in the X-API-Key header.

{
    "filterBy": [
        {
            "path": "/_meta/schema",
            "value": "https://schema-examples.com/pdp-content-block"
        },
        {
            "path": "/categoryId",
            "value": "mens-accessories-ties"
        }
    ],
    "sortBy": { "key": "default", "order": "DESC" }
}

You can try out a filter request with the Fresh API using the following cURL with your own API key, hub name, and content created from the product details schema.

curl -d '{
   "filterBy":[
      {
         "path":"/_meta/schema",
         "value":"https://schema-examples.com/pdp-content-block"
      },
      {
         "path":"/categoryId",
         "value":"mens-accessories-ties"
      },
      {
         "path":"/productFamily",
         "value":"Silk"
      }
   ]
}' -H "X-API-Key: {api-key}" -X POST 'https://ampproduct-doc.fresh.content.amplience.net/content/filter'
Example response

The JSON response to the example filter request is shown below.

{
  "responses": [
    {
      "content": {
        "_meta": {
          "name": "PDP Content- Blue Tie",
          "schema": "https://schema-examples.com/pdp-content-block",
          "deliveryId": "86ca6b81-2d8f-44b2-b4d5-1ef543833323"
        },
        "hidden": true,
        "content": [
          {
            "_meta": {
              "name": "Yellow tie image",
              "schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
            },
            "id": "5c2de1b2-7c52-413b-80f5-477b6d772ab0",
            "contentType": "https://schema-examples.com/pdp-example-image.json"
          }
        ],
        "sku": "382734M",
        "categoryId": "mens-accessories-ties",
        "productFamily": "Silk",
        "priority": 5
      }
    },
    {
      "content": {
        "_meta": {
          "name": "PDP Content- Blue Tie",
          "schema": "https://schema-examples.com/pdp-content-block",
          "deliveryId": "5eac5385-9c90-4a1a-b4b0-9b97c70733d1"
        },
        "hidden": true,
        "content": [
          {
            "_meta": {
              "name": "Red tie image",
              "schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
            },
            "id": "eba6fa30-ef50-4eb2-9aee-3f40593f5d0c",
            "contentType": "https://schema-examples.com/pdp-example-image.json"
          }
        ],
        "sku": "386758M",
        "categoryId": "mens-accessories-ties",
        "productFamily": "Wool",
        "priority": 3
      }
    },
    {
      "content": {
        "_meta": {
          "name": "PDP Content- Blue Tie",
          "schema": "https://schema-examples.com/pdp-content-block",
          "deliveryId": "adf3e049-2540-400e-9302-575b8cc024c3"
        },
        "hidden": false,
        "content": [
          {
            "_meta": {
              "name": "Purple tie image",
              "schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
            },
            "id": "77c80a82-2b06-45aa-8ce7-c4eca419df6e",
            "contentType": "https://schema-examples.com/pdp-example-image.json"
          }
        ],
        "sku": "382738M",
        "categoryId": "mens-accessories-ties",
        "productFamily": "Silk",
        "priority": 3
      }
    },
    {
      "content": {
        "_meta": {
          "name": "PDP Content- Blue Tie",
          "schema": "https://schema-examples.com/pdp-content-block",
          "deliveryId": "635b67e2-a750-46b6-8657-6ef96712fa43"
        },
        "hidden": false,
        "content": [
          {
            "_meta": {
              "name": "Blue tie image",
              "schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
            },
            "id": "424ce20b-e276-49b0-9dd1-6129d8ab74ef",
            "contentType": "https://schema-examples.com/pdp-example-image.json"
          }
        ],
        "sku": "387534M",
        "categoryId": "mens-accessories-ties",
        "productFamily": "Wool",
        "priority": 2
      }
    }
  ],
  "page": {
    "responseCount": 4
  }
}

Content Delivery 2

Content Delivery SDK

Filter API

Adding and updating delivery keys

Content Delivery 2 API reference

Visualizations

Content preview apps