Help Center

Menu

API overview

The content API is a read-only (GET) interface: it can not update information stored in Matrix.

By accessing the information stored in assets programmatically, you can use Matrix as a data source that powers other digital experiences.

Some examples of information accessible to the content API include:

  • Get data from a single asset

  • Get the site lineage of an asset

  • Get the direct children of an asset.

The content API’s security uses a management asset to create API token assets. These tokens provide read-only API access to root nodes in your Matrix system, based on the user account and root node you select for each token. You can set up the content API token to allow access to asset information from your entire site or a small section.

Base URL

The base URL for all content API endpoints you create is /__api/.

For example, if your site URL was example.com the base URL translates to https://example.com/__api/.

Authentication

The content API uses Authorization Bearer Tokens for authentication. Session-based authentication is not supported.

A token must be sent in a request to the API using an Authorization: Bearer statement.

Authorization: Bearer abcd1234

The “Bearer” statement keyword is case sensitive. For more information about this statement type, refer to the IETF RFC6750.

A randomly-generated unique token value is assigned when you create a token asset using the Content API Manager. Read Manage content API tokens to learn more about creating and managing authentication tokens.

The token value cannot be changed once it is created.

Error responses

An HTTP 401 Unauthorised response containing a WWW-Authenticate header is returned under the following conditions:

  • The header is malformed.

  • The token is invalid because of the following reasons:

    • The asset is disabled or moved into the Trash.

    • A user has not been configured against the token.

  • An HTTP 403 Forbidden response is returned under the following conditions:

    • The user that is configured against the token does not have valid permissions to the requested asset.

    • The request is trying to access an asset that is not under an assigned root asset.

  • An HTTP 404 Not Found response is returned under the following conditions:

    • The requested endpoint does not exist.

    • The requested asset does not exist.

  • A 405 Method Not Allowed response is returned when anything other than a GET method verb is used in a request payload.

API reference documentation

Endpoint documentation is available from the following locations:

You can download the full API specification in OpenAPI v3 format by selecting Download within the reference documentation.