Skip to main content

Filter hierarchical content by delivery key

Release date: 19th February 2025

We've made some changes to the Hierarchy API and Filter API 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 for more details of the differences between each API.

Using the Filter API with delivery keys
Link copied!

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.

{
       "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.

{
   "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.

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.

{
   "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
Link copied!

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. 

https://docsportal.cdn.content.amplience.net/content/hierarchies/descendants/key/ideas-and-advice?hierarchyDepth=3

The response to this request is shown below.

{
  "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
  }
}

Filter API

Hierarchy API

Hierarchy developer guides