How to add Forge macros (extension) to the page programmatically via REST API


I’ve created Forge App (Macro) for Confluence Cloud and it works fine when I add it manually via Confluence Web UI like “/myMacro”.

But I need to add it programmatically via REST API. I have a program that generates Confluence pages and their content on a trigger.

I’ve tried inspect app markup (that I’ve added manually) to get a storage format:

    <ac:adf-node type="extension">
        <ac:adf-attribute key="extension-type">com.atlassian.ecosystem</ac:adf-attribute>
        <ac:adf-attribute key="extension-key">...</ac:adf-attribute>
        <ac:adf-attribute key="parameters">
            <ac:adf-parameter key="local-id">...</ac:adf-parameter>
            <ac:adf-parameter key="extension-id">...</ac:adf-parameter>
            <ac:adf-parameter key="extension-title">myMacro</ac:adf-parameter>
            <ac:adf-parameter key="guest-params">
                <ac:adf-parameter key="param1">...</ac:adf-parameter>
        <ac:adf-attribute key="text">myMacro</ac:adf-attribute>
        <ac:adf-attribute key="layout">default</ac:adf-attribute>
        <ac:adf-attribute key="local-id">...</ac:adf-attribute>

And add this code to the REST API call like:

"body": {
        "storage": {
            "value": "<ac:adf-extension>...</ac:adf-extension>",
            "representation": "storage"

So I’ve got:
Error loading the extension!
on the Confluence Page

My questions:

  • Is there any documentation on this topic?
  • Can I omit “local-id” somehow? As I understand it’s unique value for each instance of macro, so I need to provide it somehow via my page generation program.
  • What have I done wrong?

Please, help


I’d say this is more of a question for Confluence than Forge. I’ll contact one of the teams involved to get their say on this.

1 Like

Okay, it appears to be possible.

The team recommends using the ADF (Atlassian Document Format) instead of the storage one.

In order to get an ADF representation of a page you can use
https://<SITE NAME><CONTENT ID>?expand=body.atlas_doc_format

1 Like