Support for filtering by common ancestor in Confluence REST API v2 (equivalent for /descendant endpoint)


The app that I’m working on (Scroll Viewport Cloud), and several other apps by K15t have many features that work on page trees (all descendants of a page).

In REST v1 there is descendant endpoint that returns all the pages belonging to a page tree rooted at given page. Like all REST v1 endpoints, that endpoint also supports expansions.

The v1 /descendant endpoint has not been marked as deprecated, and I have not seen any equivalent in the REST v2.

Eg my colleague @jens has raised a question about plans for a “descendants” endpoint in the REST v2 here. The answer back then was “this is not currently planned but if there is enough of an ask for this we will get it prioritized!”

I would want to ask what is the current status of introducing an endpoint like “get pages by ancestor”? Even more powerful solution could be to add an option to use an “ancestor” filter as a query parameter in different endpoints (eg “get pages”, “get labels”, “get content properties”).

If no v2 replacement is planned, is it recommend to keep using the v1 /descendant endpoint for this use case also when the codebase is otherwise migrated to use the v2 API?


Ps. I’ll be on vacation for a few weeks starting tomorrow, so I won’t reply to any possible questions in that period. But would love to see some progress / discussion on this topic once I’m back!


Hi @riku!

I appreciate the question and the forward thinking around the descendants endpoints & retrieving the content tree.

To answer the question: We have not yet tackled the design for the descendant V2 endpoint(s) to replace (and ideally upgrade) the descendant V1 endpoints.

Our goal is to introduce a set of endpoints that is more performant, scalable, and useful than their V1 counterparts. We are open to any feedback / ideas such as the above (ancestor filters), and will keep all of these in mind as we design the functionality.

In the meantime - the recommendation is to continue to use the V1 descendant endpoints, and only once there is parity in V2 would these endpoints be marked as deprecated.

Thanks so much!