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

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

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

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 URLs

Request method: GET

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

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

Description

key is the delivery key for the item. A delivery key may not start or end with "/", must be between 1 and 150 characters and cannot contain certain other special characters.
See the delivery key validation 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

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 URL

Request method: POST

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

Description

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

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

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

Status code	Description
200	The request has succeeded. Errors may be shown for individual items.
400	Bad Request.
403	Invalid API key.
405	Method not allowed. Returned if you call the Fresh API from a browser (not currently supported).
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 URL

Request method: POST

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

Description

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

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

Request body

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

Hierarchy API

The Fresh API to can be used with the Hierarchy Get all descendants API to retrieve all descendants of a hierarchy node and return uncached results.

Request URL

Request method: GET

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

Description

The properties, including the hierarchy depth and page size are included as path parameters. See parameters for more details.

Example URL:

https://docsportal.fresh.content.amplience.net/content/hierarchies/descendants/id/4c67ca5a-6050-490a-9859-be20e81ac89d?hierarchyDepth=3

Request header

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

Parameters

The API accepts the following path parameters, all of which are optional.

Parameter	Description
hierarchyDepth	Returns descendants of the parent node to the specified depth. The maximum depth is 14, the default depth is 1. The parent node is level 0
sortByKey	The custom sort order. Note: Content is sorted by creation date if sort order is not specified. See sorting for more details
sortByOrder	The sort order for the items in the response. Ascending (asc) or descending (desc). Ascending order is used if sort order is not specified
maxPageSize	The maximum page size. See pagination
pageCursor	Include to retrieve the next page of results if you have cursor from a previous response. See pagination

Example request

An example URL is shown below. You will need to include this in a request with the API key in the header. The parameters in this example are used to retrieve all descendants of the hierarchy node with the id 4c67ca5a-6050-490a-9859-be20e81ac89d to a depth of 3 levels.

https://docsportal.fresh.content.amplience.net/content/hierarchies/descendants/id/4c67ca5a-6050-490a-9859-be20e81ac89d?hierarchyDepth=3

To try out the request use the following cURL with your own API key and the content item id of a hierarchy node from your hub.

curl -H "X-API-Key: {api-key}"  "https://docsportal.fresh.content.amplience.net/content/hierarchies/descendants/id/4c67ca5a-6050-490a-9859-be20e81ac89d?hierarchyDepth=3"

Example response

The JSON response to an example Hierarchy API request is shown below:

{
  "responses": [
    {
      "content": {
        "_meta": {
          "name": "Heating and plumbing",
          "schema": "https://schema-examples.com/page-hierarchy-node",
          "deliveryKey": "ideas-and-advice/heating-and-plumbing",
          "hierarchy": {
            "parentId": "4c67ca5a-6050-490a-9859-be20e81ac89d",
            "root": false
          },
          "deliveryId": "2e924e92-5c68-485f-aaa4-54d3c630227e"
        },
        "title": "Heating and plumbing",
        "description": "All your plumbing questions answered",
        "ranking": 1
      }
    },
    {
      "content": {
        "_meta": {
          "name": "Lighting and electrical",
          "schema": "https://schema-examples.com/page-hierarchy-node",
          "deliveryKey": "ideas-and-advice/lighting-and-electrical",
          "hierarchy": {
            "parentId": "4c67ca5a-6050-490a-9859-be20e81ac89d",
            "root": false
          },
          "deliveryId": "2dd210c1-0418-442d-8b50-bb089de773f9"
        },
        "title": "Lighting and electrical",
        "description": "Your questions answered on all things lights and electrics",
        "ranking": 2
      }
    },
    {
      "content": {
        "_meta": {
          "name": "How to change a socket",
          "schema": "https://schema-examples.com/page-hierarchy-node",
          "deliveryKey": "lighting-and-electrical/how-to-change-a-socket",
          "hierarchy": {
            "parentId": "2dd210c1-0418-442d-8b50-bb089de773f9",
            "root": false
          },
          "deliveryId": "bff3769a-b8f0-4eb0-b399-b7df6cf92417"
        },
        "title": "How to change a socket",
        "description": "How to safely change an electrical socket",
        "ranking": 1
      }
    },
    {
      "content": {
        "_meta": {
          "name": "How to run a new cable",
          "schema": "https://schema-examples.com/page-hierarchy-node",
          "deliveryKey": "lighting-and-electrical/how-to-run-a-new-cable",
          "hierarchy": {
            "parentId": "2dd210c1-0418-442d-8b50-bb089de773f9",
            "root": false
          },
          "deliveryId": "09d8ac5b-c24c-4d2e-936e-ae4751543b2e"
        },
        "title": "How to run a new cable",
        "description": "Adding a new cable, the easy and safe way",
        "ranking": 2
      }
    },
    {
      "content": {
        "_meta": {
          "name": "Outdoor and garden",
          "schema": "https://schema-examples.com/page-hierarchy-node",
          "deliveryKey": "ideas-and-advice/outdoor-and-garden",
          "hierarchy": {
            "parentId": "4c67ca5a-6050-490a-9859-be20e81ac89d",
            "root": false
          },
          "deliveryId": "d09cea6f-265d-4e9d-98d9-4c5e95f7afa9"
        },
        "title": "Outdoor and garden",
        "description": "Hints and tips for keeping your garden looking great",
        "ranking": 3
      }
    },
    {
      "content": {
        "_meta": {
          "name": "Gardening questions answered",
          "schema": "https://schema-examples.com/page-hierarchy-node",
          "deliveryKey": "outdoor-and-garden/gardening-questions-answered",
          "hierarchy": {
            "parentId": "d09cea6f-265d-4e9d-98d9-4c5e95f7afa9",
            "root": false
          },
          "deliveryId": "ce110f22-d85d-4bf1-9f20-5a6b5795ecd6"
        },
        "title": "Gardening questions answered",
        "description": "Everything you need to know about planting and care of your garden",
        "ranking": 1
      }
    },
    {
      "content": {
        "_meta": {
          "name": "How to sow new grass seeds",
          "schema": "https://schema-examples.com/page-hierarchy-node",
          "deliveryKey": "outdoor-and-garden/gardening-questions-answered/how-to-sow-new-grass-seeds",
          "hierarchy": {
            "parentId": "ce110f22-d85d-4bf1-9f20-5a6b5795ecd6",
            "root": false
          },
          "deliveryId": "5992d135-cd7b-4c57-ba2c-bf1103150c58"
        },
        "title": "How to sow new grass seeds",
        "description": "A new lawn made easy",
        "ranking": 1
      }
    },
    {
      "content": {
        "_meta": {
          "name": "Painting and decorating",
          "schema": "https://schema-examples.com/page-hierarchy-node",
          "deliveryKey": "ideas-and-advice/painting-and-decorating",
          "hierarchy": {
            "parentId": "4c67ca5a-6050-490a-9859-be20e81ac89d",
            "root": false
          },
          "deliveryId": "31c0b684-7a28-47ad-a871-f1882ec408fa"
        },
        "title": "Painting and decorating",
        "description": "How to keep your home looking good as new",
        "ranking": 4
      }
    }
  ],
  "page": {
    "responseCount": 8
  }
}

Related pages

Content Delivery API

Content Delivery SDK

Filter API

Adding and updating delivery keys

Visualizations

Content preview apps