--- canonical: https://amplience.com/developers/docs/release-notes/2024/hierarchy-enhancements/ title: Hierarchy enhancements description: Release notes for Dynamic Content (6 November 2024) — introducing the Hierarchy API, enabling developers to retrieve all descendants of a hierarchy node to a specified depth via the Content Delivery API. audience: Business User image: https://cdn.media.amplience.net/i/ampproduct/hierarchy-api-2?w=1200&h=630 image_width: 1200 image_height: 630 date_published: 2024-10-31 date_modified: 2024-11-19 --- # The Hierarchy API **Release date: 6th November 2024** [Hierarchies](https://amplience.com/developers/docs/dev-tools/guides-tutorials/hierarchies/) can be used to model anything from a page structure for a website to a structured list of product content. This release features a new Hierarchy API that makes hierarchies easier and more efficient for developers to work with. The Hierarchy API is a new Content Delivery API that allows developers to do the following: - Get all the nodes at all levels of a hierarchy. - 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. ### Using the Hierarchy API Given the ID of a hierarchy node, this API will return the descendants to the level specified. Specify the [hub name](https://amplience.com/developers/docs/apis/content-delivery/content-delivery-overview/#finding-the-hub-name) and the content item id of the parent node whose descendants will be returned. The optional `hierarchyDepth` parameter allows you to choose how many levels deep to traverse the hierarchy. If you don't specify `hierarchyDepth` then only the immediate descendants of the specified node will be returned (a depth of 1). ```html https://{hubname}.cdn.content.amplience.net/content/hierarchies/descendants/id/{id} ``` 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. You can also sort the content items in the API response using your own predefined sort key. See the [Hierarchy API](https://amplience.com/developers/docs/apis/content-delivery/hierarchy-api/) page for more detail and examples. ### Example The image below shows a hierarchy created from our [page hierarchy](https://amplience.com/developers/docs/schema-reference/schema-examples/hierarchies/page-hierarchy/) schema example. The parent node is "Ideas and advice", a content item with the id `4c67ca5a-6050-490a-9859-be20e81ac89d`. ![The ideas and advice hierarchy](https://cdn.media.amplience.net/i/ampproduct/hierarchy-api-2?w=1880&fmt=png 'The ideas and advice hierarchy') The entire hierarchy has a depth of 3 levels. To retrieve all descendants of the 'Ideas and advice' node, we specify the following hierarchy API request, with a hierarchy depth of 3. ```html https://docsportal.cdn.content.amplience.net/content/hierarchies/descendants/id/4c67ca5a-6050-490a-9859-be20e81ac89d?hierarchyDepth=3 ``` You can see the response to this request by expanding the section below. The response is returned in the default sort order, returning "Heating and plumbing", "Lighting and electrical" and all its descendants, "Outdoor and garden" and all its descendants and then "Painting and decorating". You can also use define your own sort key to sort the response.
Example response ```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 } } ```
### Retrieving uncached content If you're building a static site, you can also use the updated [Fresh API](https://amplience.com/developers/docs/apis/content-delivery/fresh/#hierarchy-api) to retrieve all descendants of a hierarchy node with no cache. ## Related pages [Hierarchy developer guide](https://amplience.com/developers/docs/dev-tools/guides-tutorials/hierarchies/) [Working with hierarchies](https://amplience.com/developers/docs/user-guides/produce-content/hierarchies/) [Hierarchy API](https://amplience.com/developers/docs/apis/content-delivery/hierarchy-api/) [Fresh API](https://amplience.com/developers/docs/apis/content-delivery/fresh/#hierarchy-api)