Help Center

Menu

API overview

The asset management API adds a REST CRUD interface to your Matrix instance that lets you create, change and delete assets beneath a specified parent asset.

API availability

This API is not activated by default in Matrix SaaS instances. Contact customer support if you need access to the API on your system.

If you are using the Asset Management API for the first time, read Create a token.

If you have root account access to your Matrix server, you can activate the API through the System configuration screen.

To activate the asset management API:

  1. Sign in to Matrix using a root user account.

  2. Select System Configuration  System Configuration

  3. Select Edit to unlock the setting options on the screen.

  4. Locate the Enable asset management API setting and toggle the feature on.

  5. Select Save to activate the API.

Base URL

The base URL for all asset management API endpoints you create is /__management-api/.

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

Authentication

The asset management 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 Asset management API manager.

The Bearer token is sent with each request, therefore the Asset Management API is a not suited to client side solutions that expose the token.

Read Create an API token to find out how to create a token.

Read Manage asset management API tokens to learn more about managing authentication tokens.

The token value cannot be changed once it is created.

Asset management API fields and settings

Read the Create a request overview for guidance on API payload fields and settings.

API response codes

Standard HTTP status codes apply to the Asset Management API.

Success codes

The success codes are:

  • 200

  • 201

Error codes

The following codes are related to an error in the API call:

  • 400

  • 401

  • 403

  • 404

  • 422

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.

  • A 422 response code is returned when an asset type is not yet available to be managed via the Asset Management API.

If you see any of the following error messages, contact Squiz support:

  • 500

  • 501

  • 502

  • 503