---
canonical: https://amplience.com/developers/docs/apis/content-delivery/hierarchy-api/
title: Hierarchy API
description: Guide to Amplience Content Delivery Hierarchy API that allows you to get all descendants of a hierarchy node
audience: Developer
image: https://cdn.media.amplience.net/i/ampproduct/hierarchy-localized-content-1?w=1200&h=630
image_width: 1200
image_height: 630
date_published: 2024-07-25
date_modified: 2026-05-11
---
# Hierarchy API
The hierarchy API allows you to get all descendants of a [hierarchy](https://amplience.com/developers/docs/dev-tools/guides-tutorials/hierarchies/) 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.
> **Info: 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](https://amplience.com/developers/docs/apis/content-delivery/fresh/#hierarchy-api)
## Get all descendants
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.
### Request URL
Request method: `GET`.
Specify the [hub name](https://amplience.com/developers/docs/apis/content-delivery/content-delivery-overview/#finding-the-hub-name) and either the content item id or delivery key of the parent node whose descendants will be returned.
#### Content item id
```html
https://{hubname}.cdn.content.amplience.net/content/hierarchies/descendants/id/{id}
```
#### Delivery key
```html
https://{hubname}.cdn.content.amplience.net/content/hierarchies/descendants/key/{key}
```
**Note**: The parent item will not be returned in the response.
### Parameters
The API accepts the following path parameters, all of which are optional.
| Parameter | Description |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hierarchyDepth` | Returns descendants of the parent node to the specified depth.
The maximum depth is 14, the default depth is 1. The parent node is level 0 |
| `sortByKey` | The custom sort order.
**Note**: Content is sorted by creation date if sort order is not specified. See [Sorting](#sorting) for more details |
| `sortByOrder` | The sort order for the items in the response. Ascending (asc) or descending (desc). Ascending order is used if sort order is not specified |
| `maxPageSize` | The maximum page size. See [pagination](#pagination) |
| `pageCursor` | Include to retrieve the next page of results if you have `cursor` from a previous response. See [pagination](#pagination) |
### Example request URL
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.
```html
https://docsportal.cdn.content.amplience.net/content/hierarchies/descendants/id/4c67ca5a-6050-490a-9859-be20e81ac89d?hierarchyDepth=3
```
The same request using the content item's delivery key of `ideas-and-advice` is as follows:
```html
https://docsportal.cdn.content.amplience.net/content/hierarchies/descendants/key/ideas-and-advice?hierarchyDepth=3
```
### Response
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](#pagination) |
#### Example response
An example response is shown below:
```json
{
"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
}
}
```
## Sorting
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](https://amplience.com/developers/docs/schema-reference/schema-examples/hierarchies/page-hierarchy/#page-hierarchy-node) schema example specifies a "default" sort using the property `ranking`. If `ranking` is equal, the `title` property will be used.
```json
"trait:sortable": {
"sortBy": [
{
"key": "default",
"paths": [
"/ranking",
"/title"
]
}
]
}
```
You can specify that request returns results using this sorted using this sort key as follows:
```html
https://docsportal.cdn.content.amplience.net/content/hierarchies/descendants/id/4c67ca5a-6050-490a-9859-be20e81ac89d?hierarchyDepth=3&sortByKey=default
```
#### Using sort with pagination
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.
## Pagination
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.
> **Note: 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 supported page size
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.
### Page size example
In the following example the page size is set to 4, so a maximum of 4 content items will be returned in the response.
```html
https://docsportal.cdn.content.amplience.net/content/hierarchies/descendants/id/4c67ca5a-6050-490a-9859-be20e81ac89d?hierarchyDepth=3&maxPageSize=4
```
The `page` object in the response includes `cursor` which can be used to retrieve the next page of results.
```json
{
"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:
```html
https://docsportal.cdn.content.amplience.net/content/hierarchies/descendants/id/4c67ca5a-6050-490a-9859-be20e81ac89d?hierarchyDepth=3&maxPageSize=4&pageCursor=G_MAAByHsXto_W2itTguRbb2nk5UHk8CFFqYcMuMaoEnVxdTb52-LpZucKo5Z4_zQAFPM73YALTrkNIw5nhTzJV6F1C_fN943ktzrty2cZIRatDGcAs8LdTOOz0K5lsvqDk_671HGJeYEIGBBH1uj5qlSpiSkZQdoFLox2g75FG91vgEGOzL039gzu01OFWWLR4l0cyUQQU=
```
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.
```json
{
"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
}
}
```
## Locales
As with the [Content Delivery API](https://amplience.com/developers/docs/apis/content-delivery/content-delivery-overview/#locale), 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](https://amplience.com/developers/docs/dev-tools/guides-tutorials/localization/) 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.
```html
https://ampproduct-doc.cdn.content.amplience.net/content/hierarchies/descendants/id/cc0d019a-2870-4abd-a3b5-3a872ddc720b?hierarchyDepth=3&locale=fr-FR
```
If the `locale` parameter is not included, then content for all locales is returned.
### Locale filtering
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.
## Using the Hierarchy API with unpublished content
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.
```
{virtualstagingdomain}/content/hierarchies/descendants/id/{id}
```
For the virtual staging domain `l05lyya2raie1qr0tzfpiowti.staging.bigcontent.io` the request URL will be as follows:
```
l05lyya2raie1qr0tzfpiowti.staging.bigcontent.io/content/hierarchies/descendants/id/{id}
```
When using a virtual staging domain with no snapshot or timestamp parameters, the latest version of content will be returned.
### Example- Retrieving unpublished content
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.
```
l05lyya2raie1qr0tzfpiowti.staging.bigcontent.io/content/hierarchies/descendants/id/4c67ca5a-6050-490a-9859-be20e81ac89d?hierarchyDepth=3
```
## Using the Hierarchy API for content previews
You can retrieve content from virtual staging domains pinned to date and time for use in [content previews](https://amplience.com/developers/docs/dev-tools/guides-tutorials/content-previews/), as well as quick preview using an edition id, but this support is currently classified as beta.
### Optimizing performance
In order to optimize performance when implementing content previews containing hierarchical content, you should ensure that only those nodes that need to be updated are scheduled.
When you make a request to retrieve content from a virtual staging domain pinned to a date and time, the more hierarchy nodes that you have scheduled, the more time the API requires to evaluate nodes and this increases latency. We recommend that you schedule only those parts of a hierarchy that need to be updated, and if possible schedule individual nodes rather than the entire hierarchy.
To schedule a part of a hierarchy, or an individual node, open the hierarchy in Dynamic Content, select the hierarchy node that you want to schedule and click "Add to edition" from the node's menu. You will be given the option to schedule the individual node, or the node and all its descendants.
## Usage notes
- Linked content is not returned.
- The `depth` and `format` parameters cannot be specified.
- The maximum page size for both the production and virtual staging URL is 100, the default is 50 if no `maxPageSize` is specified.
## Related pages
[Content Delivery overview](https://amplience.com/developers/docs/apis/content-delivery/content-delivery-overview)
[Hierarchies](https://amplience.com/developers/docs/dev-tools/guides-tutorials/hierarchies)
[Content Delivery SDK](https://github.com/amplience/dc-delivery-sdk-js)