REST Management API

The REST Management API (also called the Content Management API, or CMA) lets you create, read, update, and delete content in a Brightspot instance over HTTP using standard JSON. Common use cases include automated content ingestion pipelines, external tooling integrations, and bulk data migrations.

The API follows a CRUD model mapped to standard HTTP methods:

HTTP method	Operation
GET	Read one or more assets
POST	Create a new asset
PUT	Update an existing asset
DELETE	Remove an asset

Prerequisites

Before making API calls, confirm the following:

• The REST Management API is enabled on your Brightspot instance. Contact your Brightspot administrator if you are unsure.
• You have a valid Client ID and Client Secret. These credentials can be found on the REST API configuration in Brightspot. Contact your Brightspot administrator if you do not have access.
• You know the fully qualified Java class name of the content type you want to work with (for example, com.psddev.cms.db.Text). See Discovering content type names.

Authentication

Every request must include two HTTP headers:

Header	Description
X-Client-Id	Your API client ID
X-Client-Secret	Your API client secret

If either header is missing or invalid, the API returns 401 Unauthorized.

Base endpoint

The default base path for all content operations is:

1
/api/rest/cma/contents

Your Brightspot administrator may have configured a different base path. Check with your administrator if the default path returns 404 Not Found.

Querying content

Issue a GET request to /api/rest/cma/contents with query parameters to retrieve assets.

Query parameters

Parameter	Required	Description	Example
from	Yes	Fully qualified class name of the content type to query.	com.psddev.cms.db.Text
where	No	Predicate string to filter results. Use ? as a placeholder for values supplied via the values parameter.	name = ?
values	No	Values for ? placeholders in the where predicate, in order.	My article title
offset	No	Zero-based pagination offset. Defaults to 0.	20
limit	No	Maximum number of assets to return. Defaults to 10.	50

note

URL-encode spaces and special characters in all parameter values. For example, a space becomes %20 and = becomes %3D.

Examples

Fetch the first 10 assets of a type:

1
curl -X GET 'http://localhost/api/rest/cma/contents?from=com.psddev.cms.db.Text' \
2
-H 'X-Client-Id: {{client ID}}' \
3
-H 'X-Client-Secret: {{client secret}}'

Paginate through results (assets 21–30):

1
curl -X GET 'http://localhost/api/rest/cma/contents?from=com.psddev.cms.db.Text&offset=20&limit=10' \
2
-H 'X-Client-Id: {{client ID}}' \
3
-H 'X-Client-Secret: {{client secret}}'

Filter by name using a placeholder:

1
curl -X GET 'http://localhost/api/rest/cma/contents?from=com.psddev.cms.db.Text&where=name%20%3D%20%3F&values=My%20Content' \
2
-H 'X-Client-Id: {{client ID}}' \
3
-H 'X-Client-Secret: {{client secret}}'

Filter by publish date (epoch milliseconds):

1
curl -X GET 'http://localhost/api/rest/cma/contents?from=com.psddev.cms.db.Text&where=cms.content.publishDate%20%3E%201666367884043' \
2
-H 'X-Client-Id: {{client ID}}' \
3
-H 'X-Client-Secret: {{client secret}}'

Query response format

All API responses use a {"status": ..., "result": ...} envelope. A successful query returns:

1
{
2
  "status": "ok",
3
  "result": {
4
    "count": 42,
5
    "items": [
6
      {
7
        "_id": "00000183-fbf4-d9c6-a5f7-fbfc10db0000",
8
        "_type": "com.psddev.cms.db.Text",
9
        "name": "My Content",
10
        "text": "<b>Hello Raw HTML!</b>"
11
      }
12
    ]
13
  }
14
}

Field	Description
status	"ok" on success.
result.count	Total number of matching assets.
result.items	Array of assets matching the query, limited to the limit value.
_id	UUID of the asset. Use this value in update, read, and delete operations.
_type	Fully qualified class name of the content type.

Creating content

Issue a POST request to /api/rest/cma/contents with a JSON body to create a new asset.

The request body must include at minimum:

• _type — the fully qualified class name of the content type.
• Any required fields for that content type.

Example — create a Raw HTML asset:

1
curl -X POST 'http://localhost/api/rest/cma/contents' \
2
-H 'Content-Type: application/json' \
3
-H 'X-Client-Id: {{client ID}}' \
4
-H 'X-Client-Secret: {{client secret}}' \
5
--data-raw '{
6
    "_type": "com.psddev.cms.db.Text",
7
    "name": "My New HTML Content",
8
    "text": "<b>Hello Raw HTML!</b>",
9
    "cms.site.owner": {
10
        "_ref": "{{Site ID}}",
11
        "_type": "{{Site type ID}}"
12
    }
13
}'

A successful create request returns the newly created asset, including its assigned _id:

1
{
2
  "status": "ok",
3
  "result": {
4
    "_id": "00000183-fbf4-d9c6-a5f7-fbfc10db0000",
5
    "_type": "com.psddev.cms.db.Text",
6
    "name": "My New HTML Content",
7
    "text": "<b>Hello Raw HTML!</b>"
8
  }
9
}

Reading a single asset

To fetch a specific asset by its UUID, issue a GET request with the ID appended to the endpoint path:

1
GET /api/rest/cma/contents/{{UUID}}

Example:

1
curl -X GET 'http://localhost/api/rest/cma/contents/00000183-fbf4-d9c6-a5f7-fbfc10db0000' \
2
-H 'X-Client-Id: {{client ID}}' \
3
-H 'X-Client-Secret: {{client secret}}'

A successful response returns the asset:

1
{
2
  "status": "ok",
3
  "result": {
4
    "_id": "00000183-fbf4-d9c6-a5f7-fbfc10db0000",
5
    "_type": "com.psddev.cms.db.Text",
6
    "name": "My New HTML Content",
7
    "text": "<b>Hello Raw HTML!</b>"
8
  }
9
}

Updating content

Issue a PUT request with the asset UUID in the path and a JSON body containing only the fields you want to update. Fields omitted from the body are left unchanged.

1
PUT /api/rest/cma/contents/{{UUID}}

Example — update the text field of an existing asset:

1
curl -X PUT 'http://localhost/api/rest/cma/contents/00000183-fbf4-d9c6-a5f7-fbfc10db0000' \
2
-H 'Content-Type: application/json' \
3
-H 'X-Client-Id: {{client ID}}' \
4
-H 'X-Client-Secret: {{client secret}}' \
5
--data-raw '{
6
    "text": "<b>Hello UPDATED Raw HTML!</b>"
7
}'

A successful update returns the full updated asset in the response result.

Deleting content

Issue a DELETE request with the asset UUID in the path to remove an asset from Brightspot.

1
DELETE /api/rest/cma/contents/{{UUID}}

Example:

1
curl -X DELETE 'http://localhost/api/rest/cma/contents/00000183-fbf4-d9c6-a5f7-fbfc10db0000' \
2
-H 'X-Client-Id: {{client ID}}' \
3
-H 'X-Client-Secret: {{client secret}}'

A successful delete returns an HTTP success response.

warning

Deleting an asset is irreversible. Brightspot does not move deleted assets to a trash or archive.

Error responses

The API returns standard HTTP status codes. When an error occurs, the response body uses the same status/result envelope with status set to "error".

For client errors (4xx), result is null — the HTTP status code is the diagnostic signal:

1
{
2
  "status": "error",
3
  "result": null
4
}

For server errors (500), result contains a message field:

1
{
2
  "status": "error",
3
  "result": {
4
    "message": "Internal Server Error"
5
  }
6
}

Status code	Meaning
400 Bad Request	The request body or query parameters are malformed or missing required fields.
401 Unauthorized	The X-Client-Id or X-Client-Secret header is missing or invalid.
404 Not Found	The requested asset UUID does not exist, or the endpoint path is incorrect.
500 Internal Server Error	An unexpected server-side error occurred. Check Brightspot logs for details.

Discovering content type names

The from parameter and the _type field in request bodies require the fully qualified Java class name of a Brightspot content type. There are two ways to find this value:

• Dari Debug tool — Navigate to /_debug/query on your Brightspot instance. The Type dropdown lists all available content types with their fully qualified names.
• CMA CLI — Use the list-types and show-type commands in the Brightspot REST CMA CLI to query your instance directly and return fully qualified type names.
• Source code — If you have access to the project's Java source, the class name is the package plus class name of the content type (for example, com.example.project.Article).

Standard Brightspot types always begin with com.psddev. Custom project types typically follow your organization's package naming convention.

Working with references

When a content field stores a reference to another asset (for example, an article referencing an author), the API represents that reference as a nested object with _ref and _type keys:

1
{
2
  "_type": "com.example.project.Article",
3
  "headline": "My Article",
4
  "author": {
5
    "_ref": "00000183-0000-0000-0000-000000000000",
6
    "_type": "com.example.project.Author"
7
  }
8
}

To set a reference field on create or update, supply the target asset's _id as the _ref value and its _type as the _type value.

Site ownership

When creating content in a multi-site Brightspot instance, include the cms.site.owner field to assign the asset to the correct site. Omitting this field may assign the asset to the global site or cause an error depending on your instance configuration.

1
"cms.site.owner": {
2
    "_ref": "{{Site UUID}}",
3
    "_type": "{{Site type — e.g., com.psddev.cms.db.Site}}"
4
}

To find a site's UUID and type, query the com.psddev.cms.db.Site type using a GET request.