The hierarchy API allows you to get all descendants of a hierarchy node. We have included an increased maximum page size for the API response so that you can retrieve an entire hierarchy with fewer requests.
The API is designed to make it easier to work with hierarchies used to model use cases such as the following examples:
Getting all the nodes at all levels of a hierarchy used for a site map or to model store locations.
Easily retrieve descendants of a specified node in a part of a hierarchy. This could be a product category such as "Electricals" or "Homeware" in a page hierarchy, or a section of a site map.
Retrieving uncached content with the Fresh API
If you are building a static site, you can retrieve all descendants of a hierarchy node using the Fresh API
Given the ID or delivery key of a hierarchy node, this API will return the descendants to the level specified.
The API uses a pre-sort algorithm, starting with the first child node of a parent, retrieving all of its descendants, and then retrieving the descendants of each of its sibling nodes in turn.
The following example shows how to retrieve all descendants of the hierarchy node with the content item id 4c67ca5a-6050-490a-9859-be20e81ac89d to a depth of 3 levels.
The content-type of the response header is application/json; charset=UTF-8.
Items will be returned pre-ordered using the specified sort order. The default, and currently only supported, key for sorting is createdDate.
Property
Type
Description
responses
array
An array of content
page
object
responseCount: the number of items returned in the response cursor: If there are further items to retrieve, then cursor will be included in the response. Include this in the pageCursor parameter of the request to get the next page of results. See pagination
{ "responses":[ { "content":{ "_meta":{ "name":"Heating and plumbing", "schema":"https://schema-examples.com/page-hierarchy-node", "deliveryKey":"ideas-and-advice/heating-and-plumbing", "hierarchy":{ "parentId":"4c67ca5a-6050-490a-9859-be20e81ac89d", "root":false }, "deliveryId":"2e924e92-5c68-485f-aaa4-54d3c630227e" }, "title":"Heating and plumbing", "description":"All your plumbing questions answered", "ranking":1 } }, { "content":{ "_meta":{ "name":"Lighting and electrical", "schema":"https://schema-examples.com/page-hierarchy-node", "deliveryKey":"ideas-and-advice/lighting-and-electrical", "hierarchy":{ "parentId":"4c67ca5a-6050-490a-9859-be20e81ac89d", "root":false }, "deliveryId":"2dd210c1-0418-442d-8b50-bb089de773f9" }, "title":"Lighting and electrical", "description":"Your questions answered on all things lights and electrics", "ranking":2 } }, { "content":{ "_meta":{ "name":"How to change a socket", "schema":"https://schema-examples.com/page-hierarchy-node", "deliveryKey":"lighting-and-electrical/how-to-change-a-socket", "hierarchy":{ "parentId":"2dd210c1-0418-442d-8b50-bb089de773f9", "root":false }, "deliveryId":"bff3769a-b8f0-4eb0-b399-b7df6cf92417" }, "title":"How to change a socket", "description":"How to safely change an electrical socket", "ranking":1 } }, { "content":{ "_meta":{ "name":"How to run a new cable", "schema":"https://schema-examples.com/page-hierarchy-node", "deliveryKey":"lighting-and-electrical/how-to-run-a-new-cable", "hierarchy":{ "parentId":"2dd210c1-0418-442d-8b50-bb089de773f9", "root":false }, "deliveryId":"09d8ac5b-c24c-4d2e-936e-ae4751543b2e" }, "title":"How to run a new cable", "description":"Adding a new cable, the easy and safe way", "ranking":2 } }, { "content":{ "_meta":{ "name":"Outdoor and garden", "schema":"https://schema-examples.com/page-hierarchy-node", "deliveryKey":"ideas-and-advice/outdoor-and-garden", "hierarchy":{ "parentId":"4c67ca5a-6050-490a-9859-be20e81ac89d", "root":false }, "deliveryId":"d09cea6f-265d-4e9d-98d9-4c5e95f7afa9" }, "title":"Outdoor and garden", "description":"Hints and tips for keeping your garden looking great", "ranking":3 } }, { "content":{ "_meta":{ "name":"Gardening questions answered", "schema":"https://schema-examples.com/page-hierarchy-node", "deliveryKey":"outdoor-and-garden/gardening-questions-answered", "hierarchy":{ "parentId":"d09cea6f-265d-4e9d-98d9-4c5e95f7afa9", "root":false }, "deliveryId":"ce110f22-d85d-4bf1-9f20-5a6b5795ecd6" }, "title":"Gardening questions answered", "description":"Everything you need to know about planting and care of your garden", "ranking":1 } }, { "content":{ "_meta":{ "name":"How to sow new grass seeds", "schema":"https://schema-examples.com/page-hierarchy-node", "deliveryKey":"outdoor-and-garden/gardening-questions-answered/how-to-sow-new-grass-seeds", "hierarchy":{ "parentId":"ce110f22-d85d-4bf1-9f20-5a6b5795ecd6", "root":false }, "deliveryId":"5992d135-cd7b-4c57-ba2c-bf1103150c58" }, "title":"How to sow new grass seeds", "description":"A new lawn made easy", "ranking":1 } }, { "content":{ "_meta":{ "name":"Painting and decorating", "schema":"https://schema-examples.com/page-hierarchy-node", "deliveryKey":"ideas-and-advice/painting-and-decorating", "hierarchy":{ "parentId":"4c67ca5a-6050-490a-9859-be20e81ac89d", "root":false }, "deliveryId":"31c0b684-7a28-47ad-a871-f1882ec408fa" }, "title":"Painting and decorating", "description":"How to keep your home looking good as new", "ranking":4 } } ], "page":{ "responseCount":8 } }
By default content will be returned sorted by date created, but you can specify your own sort order for the content items returned in the Hierarchy API response. To define a sort option you need to include a trait:sortable object in your content type schema containing the sort key and the path to one or more properties used to sort the content.
The following trait:sortable from the page hierarchy node schema example specifies a "default" sort using the property ranking. If ranking is equal, the title property will be used.
The Hierarchy API will pre-sort content according to the sort order that you specify in your initial API request. If your content is returned over multiple pages, then you must make sure that you include the same sort key to request each page of data that you specified in the initial request.
The hierarchy API uses pagination for the response, with up to 100 content items returned for each page. You can specify the maximum page size using the maxPageSize parameter. If the parameter is not specified then a page size of 50 will be used.
If the number of items returned is greater the page size then the page object returned in the response will contain a cursor field. To get the next page of results include this cursor value in the pageCursor parameter in the subsequent request.
If no cursor field is included in the response then you've reached the final page of items.
Use content item ids and delivery keys consistently
In a request that returns a paginated response, you must use the content item id or delivery key consistently across all requests. For example, you can't use a content item id to request the first page of responses and then use a delivery key to request any subsequent pages.
The maximum page size for results will vary according to whether you are using the production URL or virtual staging. If you specify a maximum page size greater than the supported page size, then content will be returned up to the maximum page size, and you can retrieve further pages by including pageCursor in the request until the last page is reached.
The page object in the response includes cursor which can be used to retrieve the next page of results.
{ "responses":[ { "content":{ "_meta":{ "name":"Heating and plumbing", "schema":"https://schema-examples.com/page-hierarchy-node", "deliveryKey":"ideas-and-advice/heating-and-plumbing", "hierarchy":{ "parentId":"4c67ca5a-6050-490a-9859-be20e81ac89d", "root":false }, "deliveryId":"2e924e92-5c68-485f-aaa4-54d3c630227e" }, "title":"Heating and plumbing", "description":"All your plumbing questions answered", "ranking":1 } }, { "content":{ "_meta":{ "name":"Lighting and electrical", "schema":"https://schema-examples.com/page-hierarchy-node", "deliveryKey":"ideas-and-advice/lighting-and-electrical", "hierarchy":{ "parentId":"4c67ca5a-6050-490a-9859-be20e81ac89d", "root":false }, "deliveryId":"2dd210c1-0418-442d-8b50-bb089de773f9" }, "title":"Lighting and electrical", "description":"Your questions answered on all things lights and electrics", "ranking":2 } }, { "content":{ "_meta":{ "name":"How to change a socket", "schema":"https://schema-examples.com/page-hierarchy-node", "deliveryKey":"lighting-and-electrical/how-to-change-a-socket", "hierarchy":{ "parentId":"2dd210c1-0418-442d-8b50-bb089de773f9", "root":false }, "deliveryId":"bff3769a-b8f0-4eb0-b399-b7df6cf92417" }, "title":"How to change a socket", "description":"How to safely change an electrical socket", "ranking":1 } }, { "content":{ "_meta":{ "name":"How to run a new cable", "schema":"https://schema-examples.com/page-hierarchy-node", "deliveryKey":"lighting-and-electrical/how-to-run-a-new-cable", "hierarchy":{ "parentId":"2dd210c1-0418-442d-8b50-bb089de773f9", "root":false }, "deliveryId":"09d8ac5b-c24c-4d2e-936e-ae4751543b2e" }, "title":"How to run a new cable", "description":"Adding a new cable, the easy and safe way", "ranking":2 } } ], "page":{ "responseCount":4, "cursor":"G_MAAByHsXto_W2itTguRbb2nk5UHk8CFFqYcMuMaoEnVxdTb52-LpZucKo5Z4_zQAFPM73YALTrkNIw5nhTzJV6F1C_fN943ktzrty2cZIRatDGcAs8LdTOOz0K5lsvqDk_671HGJeYEIGBBH1uj5qlSpiSkZQdoFLox2g75FG91vgEGOzL039gzu01OFWWLR4l0cyUQQU=" } }
The value of cursor from the response can be included in the pageCursor parameter in the next request as follows:
The next page of results is returned. There is no cursor included in the response so we know this is the final page of results.
{ "responses":[ { "content":{ "_meta":{ "name":"Outdoor and garden", "schema":"https://schema-examples.com/page-hierarchy-node", "deliveryKey":"ideas-and-advice/outdoor-and-garden", "hierarchy":{ "parentId":"4c67ca5a-6050-490a-9859-be20e81ac89d", "root":false }, "deliveryId":"d09cea6f-265d-4e9d-98d9-4c5e95f7afa9" }, "title":"Outdoor and garden", "description":"Hints and tips for keeping your garden looking great", "ranking":3 } }, { "content":{ "_meta":{ "name":"Gardening questions answered", "schema":"https://schema-examples.com/page-hierarchy-node", "deliveryKey":"outdoor-and-garden/gardening-questions-answered", "hierarchy":{ "parentId":"d09cea6f-265d-4e9d-98d9-4c5e95f7afa9", "root":false }, "deliveryId":"ce110f22-d85d-4bf1-9f20-5a6b5795ecd6" }, "title":"Gardening questions answered", "description":"Everything you need to know about planting and care of your garden", "ranking":1 } }, { "content":{ "_meta":{ "name":"How to sow new grass seeds", "schema":"https://schema-examples.com/page-hierarchy-node", "deliveryKey":"outdoor-and-garden/gardening-questions-answered/how-to-sow-new-grass-seeds", "hierarchy":{ "parentId":"ce110f22-d85d-4bf1-9f20-5a6b5795ecd6", "root":false }, "deliveryId":"5992d135-cd7b-4c57-ba2c-bf1103150c58" }, "title":"How to sow new grass seeds", "description":"A new lawn made easy", "ranking":1 } }, { "content":{ "_meta":{ "name":"Painting and decorating", "schema":"https://schema-examples.com/page-hierarchy-node", "deliveryKey":"ideas-and-advice/painting-and-decorating", "hierarchy":{ "parentId":"4c67ca5a-6050-490a-9859-be20e81ac89d", "root":false }, "deliveryId":"31c0b684-7a28-47ad-a871-f1882ec408fa" }, "title":"Painting and decorating", "description":"How to keep your home looking good as new", "ranking":4 } } ], "page":{ "responseCount":4 } }
As with the Content Delivery API, you can use the Hierarchy API to retrieve all of the field level localized content in a hierarchy, or filter it by a specific locale using the locale parameter.
A simple site menu hierarchy, with field level localized string fields for the name and description, is shown below. We've entered values for the en-GB, fr-FR and de-DE locales.
To retrieve only the content for the fr-FR locale to 3 levels of the hierarchy, use the following request, specifying fr-FR in the locale parameter.
The Hierarchy API supports the same locale filtering rules as the Content Delivery API:
locale=* will return content for the first locale that contains a value
locale=en-* will return content for the first locale that has "en" as a language code
Multiple locales separated by a comma will be evaluated from left to right until a matching locale is found. For example, locale=fr-BE,en-GB will first look for content for the fr-BE locale and if none is available will look for content with the en-GB locale.
If a locale cannot be found for a localized property then null will be returned.
To retrieve unpublished content using the Hierarchy API, use a virtual staging environment (VSE) in place of the production URL. The virtual staging domain is associated with the hub from which the content is retrieved. A VSE is usually set up for you at the beginning of your project and can be copied from the visualization settings in the Dynamic Content app.
The body of the request and parameters will be the same as when using the production URL.
The following example will return the latest version of the descendants of the hierarchy node 4c67ca5a-6050-490a-9859-be20e81ac89d to a depth of 3 levels. This will include any nodes that have not yet been published, as well as the latest version of published nodes.
When using a virtual staging domain, the latest version of content will be returned. Virtual staging domains pinned to date and time and snapshotIDs are currently not supported, so you cannot use the Hierarchy API in content preview apps. See the Using virtual staging with Dynamic Content page for more details about virtual staging.
