Skip to main content

Dynamic Content - Management APIs (1.0.0)

Download OpenAPI specification:Download

Introduction

The Dynamic Content Management API helps you integrate your back end systems with Dynamic Content.

The API is designed for building back-office applications and you can use it for webhook integrations, content automation apps, or to integrate with your existing back end services.

To use the API, you'll need a client ID and secret. The authorization section below explains how to use the client ID and secret to obtain an access token that must be included with each request.

Authentication

oauth2

Dynamic Content uses OAuth2 to authorize access to the Dynamic Content management API.

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.

Getting an access token

To get an authorization token, send a POST request to the Amplience authorization server at https://auth.amplience.net as 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 authorization 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 authorization 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.

Usage

Routing

Resources can usually be retrieved using a /resource-types/:id endpoint. Collection resources will always be pluralised, regardless of how they are accessed. In cases where resources are nested under a parent resource, and this context is necessary for the request, this information is included in the routing. For example, while a Content Repository can be retrieved by id using GET /content-repositories/:id, to create a new Content Repository it is necessary to supply the ID of the parent Hub, so the route would take the form POST /hubs/:hubId/content-repositories.

HAL

Resources are returned in the HAL format, which provides a representation of HATEOAS information in JSON. This allows for discoverability of endpoints from responses, as a response for a resource will contain links to related resources and actions. Links are contained within a _links object, and are keyed by name. In some cases, such as resource listing or search results, linked resources are included in the response inside an _embedded object, allowing multiple resource to be returned within the same response body.

Status Codes

Response codes for the API are described in the table below.

Status Code Table

Status Code Reason Phrase Purpose
200 OK Successful retrieval or update of a resource or list of resources
201 Created Successful creation of a resource
202 Accepted A background task has been initiated, but is still processing
204 No Content Indicates the following:
* Success with deleting a resource
* Success with granting or revoking permissions
* Success with nothing to report
400 Bad Request Non-specific error with request
401 Unauthorized No valid token was supplied in the request, or the token could not be decoded
403 Forbidden The user lacks either the required functional or ACL permissions to make this request
404 Not Found The requested resource does not exist, or the user does not have access to it
405 Method Not Allowed The requested HTTP method is not permitted for this resource type
406 Not Acceptable The requested resource is not available in the format requested by the user agent
409 Conflict The requested change conflicts with the current state of the resource
415 Unsupported Media Type The format of the resource supplied by the user agent is not supported by the server
500 Internal Server Error Non specific error occurred on the server

Error Response Format

If an error occurs, the response body contains a JSON object containing an errors array. This will contain one or more error objects, containing a message field describing the error, and context specific metadata relating to this instance of the error.

HTTP/1.1 409 Conflict
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 145

{
  "errors" : [ {
    "entity" : "Hub",
    "property" : "name",
    "invalidValue" : "anya-finn",
    "message" : "name must be unique"
  } ]
}

Guidance on using HTTP PATCH

When updating a resource, the PATCH method is used. When making a PATCH request, any fields specified in the request will overwrite their associated values in the stored resource, but omitted fields will remain unchanged. This is in contrast to the PUT method, which would set omitted fields to null, and is not supported in this API. When making a PATCH request to a resource containing nested JSON objects, it is important to note that child objects are replaced completely, and do not inherit the PATCH functionality of the root object.

For example, given a stored resource in the format:

{
  "foo": {
    "bar": "abc",
    "baz": "xyz"
  },
  "bar": "123"
}

When the following request body is used in a PATCH request:

{
  "foo": {
    "bar": "def"
  }
}

The resource would be transformed to the following:

{
  "foo": {
    "bar": "def"
  },
  "bar": "123"
}

Payload Considerations

When submitting a JSON payload to the API, the first complete JSON object in the body will be accepted, and any additional information will be discarded. For example:

{
  "foo": {
    "bar": "def"
  },
  "unknownProperty": "will be ignored"
}

In the above example, there is an extra closing brace and additional characters that follow a valid JSON object. Any extra input characters like this will be ignored by the API.

Administration

Administration allows you to add or revoke permissions for users and manage access to resources.

List Administrative Operations

Lists the available administrative operations.

Responses

Response samples

Content type
application/json

Manage Access to Resources

With the ability to manage access you can control which users have which permissions to the resources you administer.

Authorizations:
oauth2

Responses

Response samples

Content type
application/json
{}

List Operations on a resource

Given the id of a resource for which you are an administrator, you can see the various operations that you can perform. Simply follow the appropriate link for the resource passing in the id.

Resource Type Required Functional Permissions Required ACLs
hubs CONTENT:FUNCTIONAL:ADMIN:MANAGE_ACCESS CONTENT:FUNCTIONAL:HUB:MANAGE_ACCESS Hub - READ``Hub - MANAGE_ACCESS
content-repositories CONTENT:FUNCTIONAL:ADMIN:MANAGE_ACCESS CONTENT:FUNCTIONAL:REPOSITORY:MANAGE_ACCESS Hub - READ ContentRepository - MANAGE_ACCESS
Authorizations:
oauth2
path Parameters
resource
required
string
Enum: "hubs" "content-repositories"
Example: hubs

Resource Type

resourceId
required
string
Example: 00112233445566778899aabb

Resource ID

Responses

Response samples

Content type
application/json

List members on a resource

The memebrs link will list the memebrs that have access to a particular resource. This includes the member's id (sid) and the list of permissions they have.

Resource Type Required Functional Permissions Required ACLs
hubs CONTENT:FUNCTIONAL:ADMIN:MANAGE_ACCESS CONTENT:FUNCTIONAL:HUB:MANAGE_ACCESS Hub - READ Hub - MANAGE_ACCESS
content-repositories CONTENT:FUNCTIONAL:ADMIN:MANAGE_ACCESS CONTENT:FUNCTIONAL:REPOSITORY:MANAGE_ACCESS Hub - READ ContentRepository - MANAGE_ACCESS
Authorizations:
oauth2
path Parameters
resource
required
string
Enum: "hubs" "content-repositories"
Example: hubs

Resource Type

resourceId
required
string
Example: 00112233445566778899aabb

Resource ID

Responses

Response samples

Content type
application/json
Example
{}

Get a member by id

Given a resource and a member id you can navigate directly to a specific member by following the "member" link from the resource.

Resource Type Required Functional Permissions Required ACLs
hubs CONTENT:FUNCTIONAL:ADMIN:MANAGE_ACCESS CONTENT:FUNCTIONAL:HUB:MANAGE_ACCESS Hub - READ Hub - MANAGE_ACCESS
content-repositories CONTENT:FUNCTIONAL:ADMIN:MANAGE_ACCESS CONTENT:FUNCTIONAL:REPOSITORY:MANAGE_ACCESS Hub - READ ContentRepository - MANAGE_ACCESS
Authorizations:
oauth2
path Parameters
resource
required
string
Enum: "hubs" "content-repositories"
Example: hubs

Resource Type

resourceId
required
string
Example: 00112233445566778899aabb

Resource ID

sid
required
string
Example: alice

Member ID

Responses

Response samples

Content type
application/json

Revoking permissions

Revoke access to a specific resource by deleting a members permission.
From a member, follow the "revoke-permission" link passing in the permission to delete.
You can specify one or multiple permissions. Multiple permissions are comma separated.

Resource TypeRequired Functional PermissionsRequired ACLs
hubsCONTENT:FUNCTIONAL:ADMIN:MANAGE_ACCESS CONTENT:FUNCTIONAL:HUB:MANAGE_ACCESSHub - READ
Hub - MANAGE_ACCESS
content-repositoriesCONTENT:FUNCTIONAL:ADMIN:MANAGE_ACCESS CONTENT:FUNCTIONAL:REPOSITORY:MANAGE_ACCESSHub - READ
ContentRepository - MANAGE_ACCESS

Authorizations:
oauth2
path Parameters
resource
required
string
Enum: "hubs" "content-repositories"
Example: hubs

Resource Type

resourceId
required
string
Example: 00112233445566778899aabb

Resource ID

sid
required
string
Example: alice

Member ID

permissions
required
string
Example: READ,EDIT

Permission(s) to revoke (comma separated list)

Responses

Manage Modules on Resources

Modules offer additional functionality which is not enabled by default. With the ability to manage modules you can control which modules are enabled on the resources you administer.

Authorizations:
oauth2

Responses

Response samples

Content type
application/json

List Module Operations on a Hub

Given the id of a hub for which you are an administrator, you can see the various module management operations that you can perform. Simply follow the appropriate link for the resource passing in the id.

Authorizations:
oauth2
path Parameters
hubId
required
string
Example: 00112233445566778899aabb

Hub ID

Responses

Response samples

Enable the Search Index module on a hub

Enable the Search Indexes module (Algolia Search) on the specified hub. Simply follow the appropriate link for the resource passing in the id.

Authorizations:
oauth2
path Parameters
hubId
required
string
Example: 00112233445566778899aabb

Hub ID

Responses

Response samples

Content type
application/json
{}

Enable the Content Delivery 2 module on a hub

Enable the Content Delivery 2 module on the specified hub. Simply follow the appropriate link for the resource passing in the id.

Authorizations:
oauth2
path Parameters
hubId
required
string
Example: 00112233445566778899aabb

Hub ID

Responses

Response samples

Content type
application/json
{}

Content Items

Text Search Query Syntax

A simple query syntax is provided to allow full text search on content items. Several characters have special meaning and are reserved:

Table 2. Reserved Search Characters

Description Symbol
Negation Operator -
Field Search Operator :
Quote (for exact search) "
Comma (list multiple search terms) ,

Please note that the text search is case insensitive, and will only display content items within the hub. See the following examples for an explanation of the query syntax:

Table 3. Text Search Examples

Query Meaning
apple Find all content items containing the word "apple"
apple orange Find all content items containing the words "apple" AND "orange"
apple,orange Find all content items containing either "apple" OR "orange"
apple -orange Find all content items that contain the word "apple" but NOT "orange"
-apple-orange Find all content items that don’t contain "apple-orange" (hyphens in the middle of a word are not treated as negation)
label:apple Find all content items that contain the word "apple" within the "label" field
"apple:orange" Find all content items containing "apple:orange" (quotes must be used to search for a colon character)
apple label:orange Find all content items containing the word "apple" anywhere within them, AND the word "orange" in the label field

Update Multiple Content Items

Update Multiple Content Items

Authorizations:
oauth2
Request Body schema: application/json

Update Multiple Content Items

Array ([ 1 .. 100 ] items)
object

Body

label
string

Label

version
number >= 1

Version

folderId
string

Folder ID

assignees
string

Assignee

id
string <uuid>

ID

Responses

Request samples

Content type
application/json
[]

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Get Content Item

Get a Content Item

Authorizations:
oauth2
path Parameters
contentItemId
required
string
Example: 00112233-4455-6677-8899-aabbccddeeff

Content Item ID

Responses

Response samples

Content type
application/json
{}

Update Content Item

Update a Content Item. Please note that deliveryKey can only be set when Content Delivery 2 is enabled.

Authorizations:
oauth2
path Parameters
contentItemId
required
string
Example: 00112233-4455-6677-8899-aabbccddeeff

Content Item ID

Request Body schema: application/json

Updated Content Item

Supports one or multiple Content Items

object
label
string non-empty

Label

folderId
string

Folder ID

assignees
Array of arrays

Assignees

locale
string

Locale

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Archive Content Item

Archive a Content Item

Authorizations:
oauth2
path Parameters
contentItemId
required
string
Example: 00112233-4455-6677-8899-aabbccddeeff

Content Item ID

Request Body schema: application/json

Version to archive

version
required
integer

Version to archive

Responses

Request samples

Content type
application/json
{
  • "version": 1
}

Response samples

Content type
application/json
{}

Get Content Item Associations

Get Content Item Associations

Authorizations:
oauth2
path Parameters
contentItemId
required
string
Example: 00112233-4455-6677-8899-aabbccddeeff

Content Item ID

Responses

Response samples

Content type
application/json
{}

Assigning a Delivery Key

Assign a delivery key to a content item or slot and replace any existing key. The delivery key must meet the validation rules and be unique within the hub.

The current version of the content item must be included in the request payload. If the version specified is not the current one, then a 400 error will be returned in the response.

Authorizations:
oauth2
path Parameters
contentItemId
required
string
Example: 00112233-4455-6677-8899-aabbccddeeff

Content Item ID

Request Body schema: application/json

Assign Content Item Delivery Key request

deliveryKey
required
string (DeliveryKey) [ 1 .. 150 ] characters ^(?!.*[/]{2})[A-Za-z0-9-_]+[A-Za-z0-9-_/]*(?<...

Delivery key

version
required
number (Version) >= 1

Version

Responses

Request samples

Content type
application/json
{
  • "deliveryKey": "promo-page/main-banner",
  • "version": 1
}

Response samples

Content type
application/json
{}

List Content Item History

List Content Item History

Authorizations:
oauth2
path Parameters
contentItemId
required
string
Example: 00112233-4455-6677-8899-aabbccddeeff

Content Item ID

Responses

Response samples

Content type
application/json
{}

Finding Content by Epoch

Find content items that are candidates for being published at a point in time.

Authorizations:
oauth2
query Parameters
epoch
number
Example: epoch=1546300800

Epoch Time

time
number
Example: time=2019-01-01T00:00:00.000Z

Time

Responses

Response samples

Content type
application/json
{}

Restore Content by Content Version Number

Restore Content by Content Version Number

Authorizations:
oauth2
path Parameters
contentItemId
required
string
Example: 00112233-4455-6677-8899-aabbccddeeff

Content Item ID

Request Body schema: application/json

Restore Content by Content Version Number request body

version
required
number

Version

restoreVersion
required
number

Restore Version

Responses

Request samples

Content type
application/json
{
  • "version": 2,
  • "restoreVersion": 1
}

Response samples

Content type
application/json
{}

Unarchive Content Item

Unarchive a Content Item

Authorizations:
oauth2
path Parameters
contentItemId
required
string
Example: 00112233-4455-6677-8899-aabbccddeeff

Content Item ID

Request Body schema: application/json

Version to unarchive

version
required
integer

Version to unarchive

Responses

Request samples

Content type
application/json
{
  • "version": 1
}

Response samples

Content type
application/json
{}

List Content Item Versions

List Content Item Versions

Authorizations:
oauth2
path Parameters
contentItemId
required
string
Example: 00112233-4455-6677-8899-aabbccddeeff

Content Item ID

Responses

Response samples

Content type
application/json
{}

Finding Content by Content Version Number

Finding Content by Content Version Number

Authorizations:
oauth2
path Parameters
contentItemId
required
string
Example: 00112233-4455-6677-8899-aabbccddeeff

Content Item ID

query Parameters
version
number
Example: version=1

Version

Responses

Response samples

Content type
application/json
{}

List Content Item History for a Version

List Content Item History for a Version

Authorizations:
oauth2
path Parameters
contentItemId
required
string
Example: 00112233-4455-6677-8899-aabbccddeeff

Content Item ID

version
required
string
Example: 1

Version

Responses

Response samples

Content type
application/json
{}

Assigning a Workflow State

Assigning a Workflow State to a Content Item

Authorizations:
oauth2
path Parameters
contentItemId
required
string
Example: 00112233-4455-6677-8899-aabbccddeeff

Content Item ID

Request Body schema: application/json

Version to unarchive

version
required
integer

Version to unarchive

state
required
string

Workflow State ID

Responses

Request samples

Content type
application/json
{
  • "version": 1,
  • "state": "00112233445566778899aabb"
}

Response samples

Content type
application/json
{}

Getting Linked Content Items

Get Linked Content Items

Authorizations:
oauth2
query Parameters
id
required
string
Example: id=00112233-4455-6677-8899-aabbccddeeff

Id

Responses

Response samples

Content type
application/json
{}

List Content Items

This lists all of the Content Items within this Content Repository

Authorizations:
oauth2
path Parameters
contentRepositoryId
required
string
Example: 00112233445566778899aabb

Content Repository ID

query Parameters
projection
string
Value: "projection"
Example: projection=basic

"basic" - omits the body property from the return Content Items

page
integer

Page number

folderId
string
Example: folderId=00112233445566778899aabb

Folder ID

status
string

Status

excludeHierarchicalChildren
boolean
Example: excludeHierarchicalChildren=true

Exclude hierarchical child items

size
integer
Example: size=20

Page size

sort
string
Example: sort=createdDate,asc

Sort paramter

Responses

Response samples

Content type
application/json
{}

Create Content Item

Create a Content Item. Please note that deliveryKey can only be set when Content Delivery 2 is enabled. Copying a content item will not copy the deliveryKey.

Authorizations:
oauth2
path Parameters
contentRepositoryId
required
string
Example: 00112233445566778899aabb

Content Repository ID

Request Body schema: application/json

Content Item

required
object
label
required
string non-empty

Label

folderId
string

Folder ID

locale
string

Locale

object

Responses

Request samples

Content type
application/json
Example
{
  • "body": {},
  • "label": "Banner Ad Homepage",
  • "folderId": "00112233445566778899aabb",
  • "locale": "en",
  • "assignees": [
    ]
}

Response samples

Content type
application/json
{}

Copy Content Item

Copy a Content Item. Please note that deliveryKey can only be set when Content Delivery 2 is enabled. Copying a content item will not copy the deliveryKey.

Authorizations:
oauth2
path Parameters
contentRepositoryId
required
string
Example: 00112233445566778899aabb

Content Repository ID

sourceContentItemId
required
string
Example: 00112233-4455-6677-8899-aabbccddeeff

Source Content Item ID (used to copy an existing Content Item)

Request Body schema: application/json

Content Item

required
object
label
required
string non-empty

Label

folderId
string

Folder ID

locale
string

Locale

object

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Faceting Content Items with Search by Text

Facet content items and search by text. See Text Search Query Syntax for a summary of the query syntax.

Authorizations:
oauth2
path Parameters
hubId
required
string
Example: 00112233445566778899aabb

Hub ID

query Parameters
sort
string
Example: sort=createdDate

Sort

createdDate.dir
string
Enum: "asc" "desc"
Example: createdDate.dir=desc

Direction of sort

Request Body schema: application/json

Facet Content Items

required
Array of objects
returnEntities
boolean

Return Entities

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Filtering Content Items by Collection Keys

Filter content items using Collection Keys.

Authorizations:
oauth2
path Parameters
hubId
required
string
Example: 00112233445566778899aabb

Hub ID

Request Body schema: application/json

Filter Content Items

collectionKey
required
string

collectionKey

object
object

Responses

Request samples

Content type
application/json
{
  • "collectionKey": "hubName:527c95fd10c77e96b5164633b445271ffc0392031b6c99448cbaec579767b76b",
  • "sortBy": {
    },
  • "page": {
    }
}

Response samples

Content type
application/json
{}

Search Content Items by Text

Text is the default search field. See Text Search Query Syntax for a summary of the query syntax.

Authorizations:
oauth2
path Parameters
hubId
required
string
Example: 00112233445566778899aabb

Hub ID

query Parameters
query
required
string
Example: query=uniondusk

Query

Responses

Response samples

Content type
application/json
{}

Content Repositories

Get Content Repository

Get a new Content Repository

Authorizations:
oauth2
path Parameters
contentRepositoryId
required
string
Example: 00112233445566778899aabb

Content Repository ID

Responses

Response samples

Content type
application/json
{}

Update Content Repository

Update the Content Repository

Authorizations:
oauth2
path Parameters
contentRepositoryId
required
string
Example: 00112233445566778899aabb

Content Repository ID

Request Body schema: application/json

Updated Content Repository

name
string non-empty

Name

label
string non-empty

Name

Responses

Request samples

Content type
application/json
{
  • "name": "inspiration",
  • "label": "inspiration"
}

Response samples

Content type
application/json
{}

List Content Items

This lists all of the Content Items within this Content Repository

Authorizations:
oauth2
path Parameters
contentRepositoryId
required
string
Example: 00112233445566778899aabb

Content Repository ID

query Parameters
projection
string
Value: "projection"
Example: projection=basic

"basic" - omits the body property from the return Content Items

page
integer

Page number

folderId
string
Example: folderId=00112233445566778899aabb

Folder ID

status
string

Status

excludeHierarchicalChildren
boolean
Example: excludeHierarchicalChildren=true

Exclude hierarchical child items

size
integer
Example: size=20

Page size

sort
string
Example: sort=createdDate,asc

Sort paramter

Responses

Response samples

Content type
application/json
{}

Assign Content Type to Content Repository

Assign Content Type to a Content Repository

Authorizations:
oauth2
path Parameters
contentRepositoryId
required
string
Example: 00112233445566778899aabb

Content Repository ID

Request Body schema: application/json

Content Type ID to assign to the Content Reposiroty

contentTypeId
required
string

Content Type ID

Responses

Request samples

Content type
application/json
{
  • "contentTypeId": "00112233445566778899aabb"
}

Response samples

Content type
application/json
{