Dynamic Content Management API reference

Base URL: https://api.amplience.net/v2/content

OpenAPI Spec: content-management.json. Import into Postman, Insomnia, or any OpenAPI-compatible tool, or use directly with AI coding tools for accurate completions.

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, or a personal access token. 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.

Authorization

OAuth 2.0

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

To send a request to the Content Management API you must include an authorization token in the header of each request.

There are two ways to obtain one:

An API key and secret can be used to request a short-lived token from the Amplience authorization service. These tokens expire after 300 seconds. Your API key and secret will be provided by Amplience at the start of your project, or you can request them from Amplience support.

A personal access token (PAT) is a longer-lived alternative generated via the GraphQL Management API. PATs are created per user per organization and do not expire, but can be deleted. See Personal access tokens for details on creating and managing them.

Regardless of how a token is generated, include it in the authorization header in the same way.

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, or a personal access token.

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.

API sections

Hubs

API reference for hub endpoints. Covers hub management, settings, bulk operations, and sharing.

Sections: Hubs

Content repositories

API reference for content repository endpoints. Covers repository management, feature assignment, content type assignment, and sharing.

Sections: Content Repositories

Content types

API reference for content type endpoints. Covers content type registration, updating, archiving, and assignment to repositories.

Sections: Content Types

Content items

API reference for content item endpoints. Covers creating, updating, publishing, archiving, localizing, and searching content items.

Sections: Content Items

Folders and hierarchy

API reference for folder and hierarchy endpoints. Covers folder management within repositories and hierarchy node operations.

Sections: Folders · Hierarchy Node · Hierarchies Publish · Hierarchies Snapshot

Events and editions

API reference for event and edition endpoints. Covers campaign events, scheduled editions, slots, and conflict resolution.

Sections: Events · Editions · Slots

Snapshots and publishing jobs

API reference for snapshot and publishing job endpoints. Covers immutable content snapshots and publishing job management.

Sections: Snapshots · Publishing Jobs

Webhooks

API reference for webhook endpoints. Covers webhook configuration, request history, and resending.

Sections: Webhooks

Workflows and localization

API reference for workflow and localization endpoints. Covers workflow states, locale assignment, and localization group management.

Sections: Workflows · Localization · Locale Labels

Search indexes

API reference for search index endpoints. Covers Algolia search index configuration, content type assignment, and analytics.

Sections: Search Indexes · Search Indexes - Analytics

Extensions and integrations

API reference for extension and integration endpoints. Covers UI extensions and Salesforce SFCC and SFMC integrations.

Sections: Extensions · Integrations · Salesforce Commerce Cloud (SFCC) · Salesforce Marketing Cloud (SFMC)

Content sync

API reference for content sync endpoints. Covers deep sync jobs, job status, cross-hub content repository mapping, and sync balance usage.

Sections: Jobs · Balances · Content Repository Mapping

Administration

API reference for administration endpoints. Covers access control, permissions management, and feature module enablement.

Sections: Administration