Skip to main content

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.

info

Fresh API usage notes

  • The Fresh API uses the same format of requests and responses as the Content Delivery 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.
  • Note that if you do attempt to use the Fresh API from a browser, the OPTIONS request sent by the browser to preflight the API request will return a 405 (method not allowed) response.
  • 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.
  • 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 Fresh API
Link copied!

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?
Link copied!

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
Link copied!

The Fresh API is rate limited. The limits are: 100 requests per second, with a burst limit of 200 requests per second.

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
Link copied!

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
Link copied!

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

Request URLs
Link copied!

Request method: GET

https://{hubname}.fresh.content.amplience.net/content/key/{key}
https://{hubname}.fresh.content.amplience.net/content/id/{id}

Description
Link copied!

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

id is the delivery ID for the item in UUID format

Example:

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

Request header
Link copied!

HeaderValueDescription
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
Link copied!

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

depth
Link copied!

The depth parameter allows you to control whether to return items linked to the specified content item. For example for a carousel, you can control whether to return the carousel slides.

ValueDescription
rootDefault. Return the root item only and not any descendants.
allReturn the root item and all its descendants. The content will be returned in the format specified by the format parameter.

format
Link copied!

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

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

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

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
Link copied!

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
Link copied!

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
Link copied!

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

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

Request URL
Link copied!

Request method: POST

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

Description
Link copied!

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

Example URL:

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

Request body
Link copied!

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

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.

Request header
Link copied!

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

Notes
Link copied!

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

Response
Link copied!

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

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

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

PropertyDescription
responses
array		An array of content, linkedContent or error codes.
content: The content item requested | error: An error type and message.

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.

Status codes
Link copied!

Status codeDescription
200The request has succeeded. Errors may be shown for individual items.
400Bad Request.
403Invalid API key.
405Method not allowed. Returned if you call the Fresh API from a browser (not currently supported).
500Internal error.

Example multi get request
Link copied!

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

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
Link copied!

{
  "responses": [
    {
      "content": {
        "_meta": {
          "name": "spring-banner",
          "schema": "http://docexample.com/tutorialbanner.json",
          "deliveryKey": "main-section-feature--banner",
          "deliveryId": "eefaf401-9551-41dd-aa5e-a5362990b1b7"
        },
        "background": {
          "_meta": {
            "schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
          },
          "id": "499ceb10-18dc-48be-baa7-306f938928cd",
          "name": "womaninfield",
          "endpoint": "ampproduct",
          "defaultHost": "cdn.media.amplience.net"
        },
        "headline": "Get ready for Spring",
        "strapline": "It will be here before you know it",
        "calltoactiontext": "Visit our Spring Collection",
        "calltoactionurl": "http://www.example.com/spring"
      }
    },
    {
      "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
Link copied!

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 URL
Link copied!

Request method: POST

https://{hubname}.fresh.content.amplience.net/content/filter

Description
Link copied!

The filterable properties and (optional) sort key are included in the request body.

Example URL:

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

Request header
Link copied!

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

Request body
Link copied!

PropertyDescription
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
Link copied!

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
Link copied!

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

Visualizations

Content preview apps