--- canonical: https://amplience.com/developers/docs/release-notes/2025/filter-api-delivery-keys/ title: Filter hierarchies by delivery key description: This release includes an update to the Filter API to support filtering hierarchical content using a delivery key instead of id audience: Business User date_published: 2025-02-19 date_modified: 2025-04-30 --- # Filter hierarchical content by delivery key **Release date: 19th February 2025** We've made some changes to the [Hierarchy API](https://amplience.com/developers/docs/apis/content-delivery/hierarchy-api/) and [Filter API](https://amplience.com/developers/docs/apis/content-delivery/filter-api/#listing-and-filtering-hierarchical-content) to provide developers with more flexibility when retrieving hierarchical content. Both APIs now support retrieving content using a delivery key as well as a content item id. See [When to use the Hierarchy API and Filter API](https://amplience.com/developers/docs/dev-tools/content-modeling/hierarchies/hierarchy-content-delivery/#when-to-use-the-hierarchy-api-and-filter-api) for more details of the differences between each API. ## Using the Filter API with delivery keys The Filter API can be used to list all the immediate children of a specified node in a hierarchy. The filter request can now contain _either_ the content item id of the parent whose children you want to retrieve, or its delivery key. To filter using the delivery key, use the new `lookupBy` field in the `filterBy` request, specifying the delivery key in the value. ```json { "lookupBy": "HIERARCHY_PARENT_META_DELIVERY_KEY", "value": "ideas-and-advice" } ``` A filter request to retrieve the immediate children of a hierarchy node with the delivery key "ideas-and-advice", that also have a ranking of 4, is shown below. ```json { "filterBy": [ { "path": "/_meta/schema", "value": "https://schema-examples.com/page-hierarchy-node" }, { "lookupBy": "HIERARCHY_PARENT_META_DELIVERY_KEY", "value": "ideas-and-advice" }, { "path": "/ranking", "value": 4 } ] } ``` You can try out the query using the `cURL` request shown below. ```http curl -d '{ "filterBy":[ { "path":"/_meta/schema", "value":"https://schema-examples.com/page-hierarchy-node" }, { "lookupBy": "HIERARCHY_PARENT_META_DELIVERY_KEY", "value": "ideas-and-advice" }, { "path":"/ranking", "value": 4 } ] }' -H "Content-Type: application/json" -X POST 'https://ampproduct-doc.cdn.content.amplience.net/content/filter' ``` You can see in the response that 2 items match the filter request. ```json { "responses": [ { "content": { "_meta": { "schema": "https://schema-examples.com/page-hierarchy-node", "name": "Heating and plumbing", "deliveryKey": "ideas-and-advice/heating-and-plumbing", "deliveryId": "51d4320a-15ae-4767-96f0-0b996b4704de", "hierarchy": { "parentId": "46aeda7e-51cc-40c4-b67a-80dce0f1248a", "root": false } }, "title": "Heating and plumbing", "description": "Heating and plumbing questions", "ranking": 4 } }, { "content": { "_meta": { "schema": "https://schema-examples.com/page-hierarchy-node", "name": "Kitchen", "deliveryId": "7eb7121b-9ae3-4357-b853-fbbd199a79df", "hierarchy": { "parentId": "46aeda7e-51cc-40c4-b67a-80dce0f1248a", "root": false } }, "title": "Kitchen", "description": "Planning a new kitchen? All your questions answered here", "ranking": 4 } } ], "page": { "responseCount": 2 } } ``` ## Using the Hierarchy API with delivery keys The Hierarchy API now supports retrieving hierarchy nodes using the parent node's delivery key as well as its content item id. An example request to retrieve all children of the hierarchy node with the delivery key "ideas-and-advice" is shown below. We are requesting all nodes to a maximum level of 3. ```http https://docsportal.cdn.content.amplience.net/content/hierarchies/descendants/key/ideas-and-advice?hierarchyDepth=3 ``` The response to this request is shown below. ```json { "responses": [ { "content": { "_meta": { "schema": "https://schema-examples.com/page-hierarchy-node", "name": "Heating and plumbing", "deliveryKey": "ideas-and-advice/heating-and-plumbing", "deliveryId": "2e924e92-5c68-485f-aaa4-54d3c630227e", "hierarchy": { "parentId": "4c67ca5a-6050-490a-9859-be20e81ac89d", "root": false } }, "title": "Heating and plumbing.", "description": "All your plumbing questions answered", "ranking": 1 } }, { "content": { "_meta": { "schema": "https://schema-examples.com/page-hierarchy-node", "name": "Lighting and electrical", "deliveryKey": "ideas-and-advice/lighting-and-electrical", "deliveryId": "2dd210c1-0418-442d-8b50-bb089de773f9", "hierarchy": { "parentId": "4c67ca5a-6050-490a-9859-be20e81ac89d", "root": false } }, "title": "Lighting and electrical.", "description": "Your questions answered on all things lights and electrics", "ranking": 2 } }, { "content": { "_meta": { "schema": "https://schema-examples.com/page-hierarchy-node", "name": "How to change a socket", "deliveryKey": "lighting-and-electrical/how-to-change-a-socket", "deliveryId": "bff3769a-b8f0-4eb0-b399-b7df6cf92417", "hierarchy": { "parentId": "2dd210c1-0418-442d-8b50-bb089de773f9", "root": false } }, "title": "How to change a socket", "description": "How to safely change an electrical socket.", "ranking": 1 } }, { "content": { "_meta": { "schema": "https://schema-examples.com/page-hierarchy-node", "name": "How to run a new cable", "deliveryKey": "lighting-and-electrical/how-to-run-a-new-cable", "deliveryId": "09d8ac5b-c24c-4d2e-936e-ae4751543b2e", "hierarchy": { "parentId": "2dd210c1-0418-442d-8b50-bb089de773f9", "root": false } }, "title": "How to run a new cable", "description": "Adding a new cable, the easy and safe way.", "ranking": 2 } }, { "content": { "_meta": { "schema": "https://schema-examples.com/page-hierarchy-node", "name": "Outdoor and garden", "deliveryKey": "ideas-and-advice/outdoor-and-garden", "deliveryId": "d09cea6f-265d-4e9d-98d9-4c5e95f7afa9", "hierarchy": { "parentId": "4c67ca5a-6050-490a-9859-be20e81ac89d", "root": false } }, "title": "Outdoor and garden", "description": "Hints and tips for keeping your garden looking great.", "ranking": 3 } }, { "content": { "_meta": { "schema": "https://schema-examples.com/page-hierarchy-node", "name": "Gardening questions answered", "deliveryKey": "outdoor-and-garden/gardening-questions-answered", "deliveryId": "ce110f22-d85d-4bf1-9f20-5a6b5795ecd6", "hierarchy": { "parentId": "d09cea6f-265d-4e9d-98d9-4c5e95f7afa9", "root": false } }, "title": "Gardening questions answered", "description": "Everything you need to know about planting and care of your garden.", "ranking": 1 } }, { "content": { "_meta": { "schema": "https://schema-examples.com/page-hierarchy-node", "name": "How to sow new grass seeds", "deliveryKey": "outdoor-and-garden/gardening-questions-answered/how-to-sow-new-grass-seeds", "deliveryId": "5992d135-cd7b-4c57-ba2c-bf1103150c58", "hierarchy": { "parentId": "ce110f22-d85d-4bf1-9f20-5a6b5795ecd6", "root": false } }, "title": "How to sow new grass seeds", "description": "A new lawn made easy.", "ranking": 1 } }, { "content": { "_meta": { "schema": "https://schema-examples.com/page-hierarchy-node", "name": "Painting and decorating", "deliveryKey": "ideas-and-advice/painting-and-decorating", "deliveryId": "31c0b684-7a28-47ad-a871-f1882ec408fa", "hierarchy": { "parentId": "4c67ca5a-6050-490a-9859-be20e81ac89d", "root": false } }, "title": "Painting and decorating", "description": "How to keep your home looking good as new.", "ranking": 4 } } ], "page": { "responseCount": 8 } } ``` ## Related pages [Filter API](https://amplience.com/developers/docs/apis/content-delivery/filter-api/#listing-and-filtering-hierarchical-content) [Hierarchy API](https://amplience.com/developers/docs/apis/content-delivery/hierarchy-api/) [Hierarchy developer guides](https://amplience.com/developers/docs/dev-tools/guides-tutorials/hierarchies/)