Using the Dynamic Content Management API

Dynamic Content uses OAuth2 to authorise access to the Dynamic Content management API. On this page we explain how to obtain an access token from the Amplience authorization service using the client credentials grant type and how to include the token in an API request. The client credentials grant type is intended for use in server-to-server integrations only.

We also detail fair usage and rate limits for the API.

API key and secret

To use the API you will need an API key and secret. These credentials will be provided to you by Amplience at the beginning of your project, or you can request them from Amplience support. Your API key will define the resources to which you have access.

Your API key and secret are used to obtain an access token from the Amplience authorization service. This token must be included in the authorization header of all requests to the Dynamic Content management API and is set to expire after a set time period, generally 300 seconds.

You can also use a personal access token instead of a token generated from an API key and secret.

Getting an access token

To get an authorisation token, send a POST request to the Amplience authorisation server at https://auth.amplience.netas follows.

Request

POST  https://auth.amplience.net/oauth/token

Headers

Header	Description
Content-Type	application/x-www-form-urlencoded

Parameters

The parameters should be URL encoded and included in the body of the request:

client_id={yourclientid}&client_secret={yoursecret}&grant_type=client_credentials

Replace {yourclientid} and {yoursecret} with your client id and secret.

Parameter	Description
client_id	The client id (API key) provided to you by Amplience
client_secret	The client secret provided to you by Amplience
grant_type	Set this to client_credentials to specify that the authorisation token should be generated based on the client ID and secret

Response

Status codes

Status code	Description
200	OK. Credentials are valid.
400	Bad Request. client id or secret are not valid.

Response body

If the clientID and secret are valid, the response body will be returned as in the example below. Note that the example access_token has been truncated.

{
  "access_token": "eyJraWQiOiJhbXBsaWVuY2UtdG9rZW4tc2lnbmluZy1rZXkiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJhbXBsaWVuY2UuY29tIiwiZXhwIjoxNTUzODY4NjIyLCJqdGkiOiJMT2pvZ1dtMFM3TkRNT2VsTk96cWVnIiwiaWF0IjoxNTUzODY3MzYyLCJzd…",
  "session_expires_in": 0,
  "expires_in": 300
}

You will need to save the access token and include it in requests to the API. If the token has expired, request another token from the authorisation service. The Dynamic Content management SDK contains code to help you manage the access token.

Including the token in an API request

To make a request to the Dynamic Content management API, for example to list all the hubs you have access to you would send a request such as:

GET https://api.amplience.net/v2/content/hubs

In the request header you must set the Authorization format to "Bearer" and include the access token:

Authorization : Bearer {access_token}

Replace access_token with the access token returned by the authorization service.

If the access token is valid, then the request is processed and the response is returned.

Fair usage

The Dynamic Content Management API is intended for backend applications such as webhook integrations and should not be used in production web applications.

Rate limits

Amplience reserves the right to impose rate limits on requests to the Dynamic Content Management API. We will only do this to help guarantee service availability to all our customers.

Publish content requests

There is a rate limit of 100 requests per minute for all requests to publish and unpublish content.

Additional features

This section details features for which it is useful to include more detail than provided by the API reference.

Create localizations

A Create localizations request allows you to use the API to localize a content item for use in your backend applications such as webhook integrations and automations.

Note that you must include an access token in the authorization header of the request.

Create localizations request

POST content/content-items/{content-item-id}/localize

Replace {content-item-id} with the id of the item to be localized.

Example request URL:

The following request creates variants of the content item id b42893f6-42b9-4a0c-b4bc-c46d0d087485 for each of the locales specified in the request body.

https://api.amplience.net/v2/content/content-items/b42893f6-42b9-4a0c-b4bc-c46d0d087485/localize

Request body

The item body must contain the content item version and the locales to which you want the item to be localized. version should be the latest version of the content item. You can find the latest version from the content item properties pane in the content form.

Example request body:

The following request specifies that version 1 of the content item is localized into the fr-FR and de-DE locales.

{
  "version": 1,
  "locales": [ "fr-FR", "de-DE" ]
}

You can also list the existing localizations of a content item so you can determine the variants that have already been created.

Response

The response will contain the content item from which the variants were created. If the request is successful, an asynchronous localization job will be started which will create the requested content items for each of the specified locales.

You can only create one variant of a content item for each locale. If you attempt to create more than one variant for each locale, you will still receive a 202 accepted response, but the variant will not be created.

Status codes

Status code	Description
202	Accepted
400	Bad Request
403	Forbidden. Authorization required

Example response

An example response is shown below.

  "status": "IN_PROGRESS",
  "rootContentItem": {
    "label": "Winter banner",
    "locale": "en-US",
    "id": "b42893f6-42b9-4a0c-b4bc-c46d0d087485"
  },
  "requestedLocales": [
    "fr-FR",
    "de-DE"
  ],
  "createdBy": "e86a8e69-2c70-4a96-a112-1df4acca5ea7",
  "createdDate": "2021-11-15T15:16:41.708Z",
  "_links": {
    "content-root": {
      "href": "https://api.amplience.net/v2/content/content-items/b42893f6-42b9-4a0c-b4bc-c46d0d087485"
    },
    "findByRootContentItem": {
      "href": "https://api.amplience.net/v2/content/localization-jobs/search/findByRootContentItem?id=b42893f6-42b9-4a0c-b4bc-c46d0d087485{&page,size,sort}",
      "templated": true
    }
  }
}

Usage notes

The localize operation will create variants of the given content item and its descendants with the specified locales. If the request is successful, a localization job will be started which will create the necessary content items asynchronously.

Localized content will be created either in the same repository, or in a repository in the same localization group to which the corresponding target locale has been assigned.

You can also localized content that links to other content items, such as carousels and grids. The rules for creating variants of linked content are described in detail in localizing linked content.

In order for the localize request to be successful, the following conditions must be met:

1. The source content item must have a locale.
2. The target locales must be supported by the hub.
3. A variant of the source content item must not already exist in any of the specified locales.
4. You must specify the current version of the source content item.

Unpublishing all archived content items

The Unpublish endpoint will remove a content item from delivery so that it is no longer available using its published Content Delivery URL via ID or delivery key.

One of the most common requirements is to unpublish content that you've archived and no longer need, to reuse delivery keys, for example. You should also filter by published items because unpublishing an item that is unpublished or never published will return an error.

To unpublish all archived content do the following:

• Find all content items that have been archived and which are published. Use the Facet content items endpoint.

Note that the following will return the first 20 results. To request the next page of results, change the page parameter to &page=2 and so on.

POST https://api.amplience.net/v2/content/hubs/{hubId}/content-items/facet?page=0&query=status:"ARCHIVED"contentRepositoryId:"{contentRepositoryId}"&size=20&sort=lastModifiedDate,desc&page=1

Include the following in the JSON body so that only published items are returned:

{
"fields": [
    {
    "facetAs": "ENUM",
    "field": "publishingStatus",
    "filter": {
        "type": "IN",
        "values": [
        "LATEST",
        "EARLY"
        ]
    }
    }
],
"returnEntities": true
}

• Unpublish each content item using the Unpublish endpoint.

POST https://api.amplience.net/v2/content/content-items/{contentItemId}/unpublish