Introducing Macro and Asynchronous Conversions

We’ve recently added new ways to perform content body conversions; including support for directly converting a macro’s nested body content to a display format.

To reduce timeouts for apps that convert their nested content to export_view; apps can now request asynchronous conversion, and obtain the result via a new GET endpoint.

To request an asynchronous conversion to export_view, developers can use

POST /wiki/rest/api/contentbody/convert/async/{to}

with the same path and body params they use with the existing conversion endpoint without async in the path. The endpoint will return an async id instead of a the converted content body, and the latter can be polled for at GET /wiki/rest/api/contentbody/convert/{asyncId}.

Apps can also now use the macro body conversion endpoint to convert their nested content directly to export_view, view, and styled_view - synchronously or asynchronously, and use the same GET endpoint as above for the asynchronous result. This removes the need for developers to use 2 api calls, one to get the macro body, and one to convert it.

These endpoints will both use the same path as the existing GET macro body endpoint, but will add /convert/{to} and /convert/async/{to}, returning a Content Body, or an async id, respectively.

Our aim is to make these endpoints as similar to the existing ones as possible in hopes that developers whose conversions are prone to time out will try these out with little effort.

The changelog for these endpoints can be found here.


Awesome, thank you! This will be very useful for our apps.

Maybe now is the time to close [CE-671] - Ecosystem Jira :slight_smile:


Hi @EmileGivental,

it’s amazing to see that you’re making improvements in this area!

Since with the new async rendering endpoint you already have this job architecture in place, I was wondering whether you might have anything planned for a bulk conversion endpoint as well? Our apps often convert lots (hundreds, thousands) of pages at the same time which results in a high number of requests. Something like a bulk conversion endpoint could massively reduce the number of requests we need to send to Confluence.


1 Like

Hi @SvenSchatter,

Thanks for the question. This is not currently planned. In this bulk request, would you want to start 100 async conversions, but get the results one-by-one via polling? Otherwise I worry that we will just be slowing down all conversions to the speed of the slowest one if we are to put all the conversions in one result. I do see the use case for starting many at once though.