Content Management API

Introduction

The Content Management API can be used to get, create, and update a single document, page, or resource bundle at a time, or to get and link translations of existing documents, pages, and folders.

📘

Development project scope

All operations except translation operations are performed within the context of a developer project, and all writes are performed on an unpublished variant of a page or document associated with the project.

Translation operations are performed on published and unpublished variants of the documents and pages.

📘

Translation operation limitations

When linking existing content as translation, make sure that the content is not being edited during the linking operation. Otherwise linked content could be overridden and translation links could be lost.

When linking a document or page that is part of a project, make sure not to switch between project variants in the CMS for the given document or page (i.e. do not switch from the project variant to core, or vice versa). This action would get the previous version of the document or page from the version history which does not have the translation link created by the linking service. This is a known limitation which will be removed in future releases.

🚧

Limitation

Currently, the Content Management API does not support images and assets.

Authorization

The Content Management API is a protected management API and requires authorization using a token. See API Authorization for instructions on how to obtain and use a token.

Updates and conflict prevention

When updating an existing resource, you must include the entire resource including all its existing unchanged properties. It's not possible to update only a subset of properties. Read more about how to handle updates and conflict prevention.

API reference

Developer tools

To aid developers in working and learning the Content Management API, the following tools and resources are provided:

Public environment

If you don't have access to a Bloomreach environment yet, you can use the Public Developer Environment. Follow the instructions to retrieve an authentication token and easily explore the APIs.

Run in Postman

Import the Content Management API collection and try the endpoints in Postman. The collection provides many examples of how the endpoints can be used.

The only thing needed to use the Postman collection is to setup the environment variables:

  • brxHost: the URL of your Bloomreach Content environment
  • x-auth-token: the Authentication token

Switch legacy mode setting

The Content Management API provides a /settings/{setting_name} utility endpoint. Use this to view and change settings specific to the Content Management API. Currently, there's one setting that is exposed via this endpoint, namely uselegacycontainerpaths. This setting can be used to enable or disable the new format of container paths in payloads containing Page entities.

Authentication

The API requires authentication using a token. See API Authorization for instructions on how to obtain and use a token.

Get the current status of the setting

Request

GET /management/content/v1/settings/uselegacycontainerpaths

Response

The API response is a string with the current value of the uselegacycontainerpaths setting. Its value can be either 'true' or 'false', showing whether your project uses the legacy container path format or not.

Update the setting

Request

PUT /management/content/v1/settings/uselegacycontainerpaths
Accept: text/plain
Content-type: text/plain


'true'

Response

A successful job returns 200 OK, meaning that the setting was changed for the project.

A failed job can return a 403 ForbiddenError response if the authorization for the API failed, or if the user doesn't have the required permissions to update the setting.