Overview of the create request

The payload of the asset management API create request is separated into two sections.

{

"asset": {… },

"parent": {… }

}

Asset details

The asset section of the request contains the details of the asset you want to create.

In this example, you are creating a folder because it is a simple process.

The supported asset types are described in the asset management API documentation.

Use the type field to specify the type of asset you want to create.

{

"type": "folder",

"attributes": {
"name": "my-first-folder"
}

}

The attributes field contains the details of the asset you are creating. In the example above, only name is supplied.

Parent details

The parent section of the request describes how you want to link your new asset to a parent asset:

{
"asset_id": "1",         (1)
"link_type": "menu"      (2)
}

The asset_id field is the asset ID under which you want to create the folder asset. In this example, the value 1 represents the root node in the Matrix instance.

The user associated with the token you are using must have write permissions on the root asset to be able to create the new asset there. You can use any asset ID you want to, but the user must have write permissions on the chosen parent asset.

2 The link_type field specifies how the link is treated in the menu and asset tree. In this example, the value menu tells Matrix that this asset will appear in the asset tree and the frontend navigation when creating menus.

What are links?

The most primitive structure in Matrix is an asset. Assets have types, attributes, and values. They are not stand-alone entities - the relationships with other assets are what give assets their meaning. These relationships are called links. All the relationships between assets in Matrix are defined by links and the values that make up the link entities.

A link model looks like the following:

{
"link_id": "277",
"major_id": "270",
"minor_id": "271",
"link_type": "hidden",
"value": "",
"sort_order": 0,
"is_dependent": false,
"is_exclusive": true
}

In the example above, the request uses the /assets/<asset id>/links endpoint with the asset ID (270) to display the links associated with the asset.

Link types

The link model will return the following link types.

link_id

The unique identifier for this link. This parameter is usually only used for deletion within the API.

major_id and minor_id

Major_id and minor_id refer to the asset ID. Links are directional, with the direction defined using major and minor IDs. The major_id is the originating asset, and the minor_id is the destination asset. If you look at the asset tree in the Matrix admin screens, all the parent assets are major_ids, and all the children are minor_ids.

link_type

Link type is an enum of values menu, hidden, invisible, and reference.

menu allows this link to be rendered in the frontend sites’ IA/menu structure. This link type also makes the link visible in the administration asset tree.

hidden hides the link in the frontend sites’ IA/menu structure. It will be visible in the administration asset tree.

invisible - hides the link from both the frontend sites’ IA/menu structure and the administration asset tree. This link type is primarily used for asset types where you want to preserve the relationship between assets, such as form responses and form questions, but do not want the responses cluttering up your admin asset tree.

value

A field to define additional data about the link relationship. For example, value must be set on a standard page to define the relationship between the content and the bodycopy_div. In that relationship, the value must be div_contents.

sort_order

The order in which the link is rendered in the tree relative to its sibling links. A value of -1 can be used when creating an asset to sort the new asset at the bottom of the sibling links.

is_dependent

Is used to define the special relationship between assets which require multiple assets to function. For example, is_dependent must be set to true for the relationship between content_type_wysiwyg and its parent bodycopy_div.

is_exclusive

This parameter locks this child asset underneath the parent asset. When set to true, it will prevent the asset from being moved in the admin UI or creating an additional link to a second parent.

Walking the tree

You can navigate the asset tree using links as described in this pseudocode example:

 function doWorkWithLink(link)      (1)

 function getLinks(id)              (2)

 toSearchList = getLinks(starting_link_id)

 while length of toSearchList greater than zero
  link = pop toSearchList
  doWorkWithLink(link)

  childLinks = getLinks(link.minor_id) (3)

  append childLinks to toSearchList

1	Do something meaningful with a link.
2	Returns an array of child links.
3	Note the use of `minor_id` so that child links are read.

In this example, an array of child links is created from a given link ID.

Help Center

Menu