Help Center

Menu

Content API Specification

Last Updated: 13 Nov 2019

On this page

  1. Setting up Token Authorization
  2. Using the Authorization Token
  3. Root Node Restrictions
  4. BearerAuth
  5. Get the fields and attributes for an asset
    1. Responses
    2. Response samples
  6. Get the fields and attributes for an asset by URL
    1. Responses
    2. Response samples
  7. Get the lineage info of an asset
    1. Responses
    2. Response samples
  8. Get the lineage info of an asset by URL
    1. Responses
    2. Response samples
  9. Get the asset children of an asset
    1. Responses
    2. Response samples
  10. Get the asset children of an asset by URL
    1. Responses
    2. Response samples
Documentation Powered by ReDoc

Matrix API (1.1.0)

Download OpenAPI specification:Download

The Matrix Content Delivery API supports the GET HTTP Method. A 405 Method Not Allowed response will be returned in all other cases.

Setting up Token Authorization

The Matrix Content Delivery API requires the use of Authorization Bearer Tokens for authentication. Session based authentication is not supported for any endpoint other than the documentation endpoint /docs, which is additionally restricted to Backend_User, System_Administrator and Root_User Matrix User types.

Tokens can be configured by creating a Content API Token asset under the Content API Manager, available under System Management in the asset map. A randomly generated unique token value will be assigned to the token when the Content API Token asset is created. This value is immutable and cannot be changed.

To configure the token, create a Content API Token asset in your system and complete the Token and User fields in the Details screen, and then "Enable" using the status change field. You may also set Root Node Restrictions to limit the scope of access for the token.

Content API Tokens will not be valid if the asset is "Disabled", or has been trashed, and will result in a HTTP 401 Unauthorized response being returned.

Currently the user tokens must be unique and may consist of any non-whitespace characters.

Using the Authorization Token

A token must be sent in a request to the API by setting it in an Authorization: Bearer header as per RFC6750. For example:

Authorization: Bearer abcd1234

If the header is malformed, the token is invalid, or user has not been configured against the token, a HTTP 401 Unauthorized response will be returned containing a WWW-Authenticate header.

If the user assigned against the token does not have valid permissions to the requested resource, a HTTP 403 Forbidden response will be returned.

Root Node Restrictions

Root Node Restrictions can be set against Content API Tokens to restrict access to only Assets that are under, or are, the assigned Root Nodes. Requesting a resource that is not under an assigned Root Node will result in a HTTP 403 Forbidden response being returned.

If no Root Node Restrictions are set against the token, normal Matrix permissions based on the assigned user will be used.

Authentication

BearerAuth

Security scheme type: HTTP
HTTP Authorization Scheme bearer
Bearer format "Bearer abcd1234"

Asset

Get the fields and attributes for an asset

Authorizations:
BearerAuth
path Parameters
assetId
required
string
Example: 1234

ID of the asset.
Note: this may contain URL-unfriendly characters and so must be URL-encoded.

query Parameters
data
Array of strings Nullable
Example: data=attributes,contents

A list of additional asset data to return (comma-separated)

Responses

200

Successful operation

400

assetId is not a valid Asset ID

401

Authorization token malformed or invalid

403

You are not authorised to read the asset

404

Asset not found

get /assets/{assetId}
https://your-matrix-domain/__api/assets/{assetId}

Response samples

Content type
application/json
Example
page
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "type": "page",
  • "type_name": "string",
  • "version": "string",
  • "name": "string",
  • "short_name": "string",
  • "status":
    {
    },
  • "created":
    {
    },
  • "updated":
    {
    },
  • "published":
    {
    },
  • "status_changed":
    {
    },
  • "url": "string",
  • "urls":
    [
    ],
  • "attributes":
    {
    },
  • "metadata":
    {
    },
  • "contents": "string"
}

Get the fields and attributes for an asset by URL

Authorizations:
BearerAuth
query Parameters
url
required
string
Example: url=https%3A%2F%2Fmy-matrix-site%2Fsome%2Fasset%2Furl

The URL of the assets being requested. This value must be URL-encoded

data
Array of strings Nullable
Example: data=attributes,contents

A list of additional asset data to return (comma-separated)

Responses

200

Successful operation

400

assetId is not a valid Asset ID

401

Authorization token malformed or invalid

403

You are not authorised to read the asset

404

Asset not found

get /assets/by_url
https://your-matrix-domain/__api/assets/by_url

Response samples

Content type
application/json
Example
page
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "type": "page",
  • "type_name": "string",
  • "version": "string",
  • "name": "string",
  • "short_name": "string",
  • "status":
    {
    },
  • "created":
    {
    },
  • "updated":
    {
    },
  • "published":
    {
    },
  • "status_changed":
    {
    },
  • "url": "string",
  • "urls":
    [
    ],
  • "attributes":
    {
    },
  • "metadata":
    {
    },
  • "contents": "string"
}

Get the lineage info of an asset

Authorizations:
BearerAuth
path Parameters
assetId
required
string
Example: 1234

ID of the asset.
Note: this may contain URL-unfriendly characters and so must be URL-encoded.

query Parameters
data
Array of strings Nullable
Example: data=attributes,contents

A list of additional asset data to return (comma-separated)

Responses

200

A collection of Asset Links

400

assetId is not a valid Asset ID

401

Authorization token malformed or invalid

403

You are not authorised to read the asset

404

Asset not found

get /assets/{assetId}/lineage/site
https://your-matrix-domain/__api/assets/{assetId}/lineage/site

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "links":
    [
    ],
  • "assets":
    [
    ]
}

Get the lineage info of an asset by URL

Authorizations:
BearerAuth
query Parameters
url
required
string
Example: url=https%3A%2F%2Fmy-matrix-site%2Fsome%2Fasset%2Furl

The URL of the assets being requested. This value must be URL-encoded

data
Array of strings Nullable
Example: data=attributes,contents

A list of additional asset data to return (comma-separated)

Responses

200

A collection of Asset Links

400

assetId is not a valid Asset ID

401

Authorization token malformed or invalid

403

You are not authorised to read the asset

404

Asset not found

get /assets/by_url/lineage/site
https://your-matrix-domain/__api/assets/by_url/lineage/site

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "links":
    [
    ],
  • "assets":
    [
    ]
}

Get the asset children of an asset

Authorizations:
BearerAuth
path Parameters
assetId
required
string
Example: 1234

ID of the asset.
Note: this may contain URL-unfriendly characters and so must be URL-encoded.

query Parameters
data
Array of strings Nullable
Example: data=attributes,contents

A list of additional asset data to return (comma-separated)

limit
integer >= 0 Nullable
Default: 100
Example: limit=20

How many child assets to return in the current request

page
integer >= 1 Nullable
Default: 1
Example: page=2

The page of results to returns in the current request

asset_types
Array of strings Nullable
Example: asset_types=page_standard,folder

Filter child assets by asset types. Specify multiple asset types with a comma-separated list

sort_by
string Nullable
Enum: "id" "type" "version" "name" "short_name" "status.id" "created.date" "created.user_id" "updated.date" "updated.user_id" "published.date" "published.user_id" "status_changed.date" "status_changed.userid"
Example: sort_by=status

Sort child assets by standard asset fields

sort_order
string Nullable
Enum: "asc" "desc"
Example: sort_order=desc

Sort child assets in ascending or descending order

Responses

200

Asset Children response filter info

400

assetId is not a valid Asset ID

401

Authorization token malformed or invalid

403

You are not authorised to read the asset

404

Asset not found

get /assets/{assetId}/children
https://your-matrix-domain/__api/assets/{assetId}/children

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "links":
    [
    ],
  • "assets":
    [
    ],
  • "page_info":
    [
    ]
}

Get the asset children of an asset by URL

Authorizations:
BearerAuth
query Parameters
url
required
string
Example: url=https%3A%2F%2Fmy-matrix-site%2Fsome%2Fasset%2Furl

The URL of the assets being requested. This value must be URL-encoded

data
Array of strings Nullable
Example: data=attributes,contents

A list of additional asset data to return (comma-separated)

limit
integer >= 0 Nullable
Default: 100
Example: limit=20

How many child assets to return in the current request

page
integer >= 1 Nullable
Default: 1
Example: page=2

The page of results to returns in the current request

asset_types
Array of strings Nullable
Example: asset_types=page_standard,folder

Filter child assets by asset types. Specify multiple asset types with a comma-separated list

sort_by
string Nullable
Enum: "id" "type" "version" "name" "short_name" "status.id" "created.date" "created.user_id" "updated.date" "updated.user_id" "published.date" "published.user_id" "status_changed.date" "status_changed.userid"
Example: sort_by=status

Sort child assets by standard asset fields

sort_order
string Nullable
Enum: "asc" "desc"
Example: sort_order=desc

Sort child assets in ascending or descending order

Responses

200

Asset Children response filter info

400

assetId is not a valid Asset ID

401

Authorization token malformed or invalid

403

You are not authorised to read the asset

404

Asset not found

get /assets/by_url/children
https://your-matrix-domain/__api/assets/by_url/children

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "links":
    [
    ],
  • "assets":
    [
    ],
  • "page_info":
    [
    ]
}

Back to top