GET /wiki/rest/api/content/{id}/history/{version}/macro/id/{macroId}/convert/{to}

Returns the body of a macro in format specified in path, for the given macro ID. This includes information like the name of the macro, the body of the macro, and any macro parameters.

About the macro ID: When a macro is created in a new version of content, Confluence will generate a random ID for it, unless an ID is specified (by an app). The macro ID will look similar to this: '50884bd9-0cb8-41d5-98be-f80943c14f96'. The ID is then persisted as new versions of content are created, and is only modified by Confluence if there are conflicting IDs.

For Forge macros, the value for macro ID is the "local ID" of that particular ADF node. This value can be retrieved either client-side by calling view.getContext() and accessing "localId" on the resulting object, or server-side by examining the "local-id" parameter node inside the "parameters" node.

Note that there are other attributes named "local-id", but only this particular one is used to store the macro ID.

Example: <ac:adf-node type="extension"> <ac:adf-attribute key="extension-type">com.atlassian.ecosystem</ac:adf-attribute> <ac:adf-attribute key="parameters"> <ac:adf-parameter key="local-id">e9c4aa10-73fa-417c-888d-48c719ae4165</ac:adf-parameter> </ac:adf-parameter> </ac:adf-node>

Note, to preserve backwards compatibility this resource will also match on the hash of the macro body, even if a macro ID is found. This check will eventually become redundant, as macro IDs are generated for pages and transparently propagate out to all instances.

This backwards compatibility logic does not apply to Forge macros; those can only be retrieved by their ID.

Permissions required: Permission to view the content that the macro is in.

Servers

https://your-domain.atlassian.net

Path parameters

Name	Type	Required	Description
`id`	String	Yes	The ID for the content that contains the macro.
`to`	String	Yes	The content representation to return the macro in.
`version`	Integer	Yes	The version of the content that contains the macro. Specifying `0` as the `version` will return the macro body for the latest content version.
`macroId`	String	Yes	The ID of the macro. This is usually passed by the app that the macro is in. Otherwise, find the macro ID by querying the desired content and version, then expanding the body in storage format. For example, '/content/196611/version/7?expand=content.body.storage'.

Query parameters

Name Type Required Description

Name	Type	Required	Description
`spaceKeyContext`	String	No	The space key used for resolving embedded content (page includes, files, and links) in the content body. For example, if the source content contains the link `<ac:link><ri:page ri:content-title="Example page" /><ac:link>` and the `spaceKeyContext=TEST` parameter is provided, then the link will be converted to a link to the "Example page" page in the "TEST" space.
`expand[]`	Array	No	A multi-value parameter indicating which properties of the content to expand and populate. Expands are dependent on the `to` conversion format and may be irrelevant for certain conversions (e.g. `macroRenderedOutput` is redundant when converting to `view` format). If rendering to `view` format, and the body content being converted includes arbitrary nested content (such as macros); then it is necessary to include webresource expands in the request. Webresources for content body are the batched JS and CSS dependencies for any nested dynamic content (i.e. macros). `embeddedContent` returns metadata for nested content (e.g. page included using page include macro) `mediaToken` returns JWT token for retrieving attachment data from Media API `macroRenderedOutput` additionally converts body to view format `webresource.superbatch.uris.js` returns all common JS dependencies as static URLs `webresource.superbatch.uris.css` returns all common CSS dependencies as static URLs `webresource.superbatch.uris.all` returns all common dependencies as static URLs `webresource.superbatch.tags.all` returns all common JS dependencies as html `<script>` tags `webresource.superbatch.tags.css` returns all common CSS dependencies as html `<style>` tags `webresource.superbatch.tags.js` returns all common dependencies as html `<script>` and `<style>` tags `webresource.uris.js` returns JS dependencies specific to conversion `webresource.uris.css` returns CSS dependencies specific to conversion `webresource.uris.all` returns all dependencies specific to conversion `webresource.tags.all` returns common JS dependencies as html `<script>` tags `webresource.tags.css` returns common CSS dependencies as html `<style>` tags `webresource.tags.js` returns common dependencies as html `<script>` and `<style>` tags
`embeddedContentRender`	String	No	Mode used for rendering embedded content, like attachments. `current` renders the embedded content using the latest version. `version-at-save` renders the embedded content using the version at the time of save. Possible values: `"version-at-save"` `"current"` Default value: "current"

spaceKeyContext

String

The space key used for resolving embedded content (page includes, files, and links) in the content body. For example, if the source content contains the link <ac:link><ri:page ri:content-title="Example page" /><ac:link> and the spaceKeyContext=TEST parameter is provided, then the link will be converted to a link to the "Example page" page in the "TEST" space.

expand[]

Array

A multi-value parameter indicating which properties of the content to expand and populate. Expands are dependent on the to conversion format and may be irrelevant for certain conversions (e.g. macroRenderedOutput is redundant when converting to view format).

If rendering to view format, and the body content being converted includes arbitrary nested content (such as macros); then it is necessary to include webresource expands in the request. Webresources for content body are the batched JS and CSS dependencies for any nested dynamic content (i.e. macros).

embeddedContent returns metadata for nested content (e.g. page included using page include macro)
mediaToken returns JWT token for retrieving attachment data from Media API
macroRenderedOutput additionally converts body to view format
webresource.superbatch.uris.js returns all common JS dependencies as static URLs
webresource.superbatch.uris.css returns all common CSS dependencies as static URLs
webresource.superbatch.uris.all returns all common dependencies as static URLs
webresource.superbatch.tags.all returns all common JS dependencies as html <script> tags
webresource.superbatch.tags.css returns all common CSS dependencies as html <style> tags
webresource.superbatch.tags.js returns all common dependencies as html <script> and <style> tags
webresource.uris.js returns JS dependencies specific to conversion
webresource.uris.css returns CSS dependencies specific to conversion
webresource.uris.all returns all dependencies specific to conversion
webresource.tags.all returns common JS dependencies as html <script> tags
webresource.tags.css returns common CSS dependencies as html <style> tags
webresource.tags.js returns common dependencies as html <script> and <style> tags

embeddedContentRender

String

Mode used for rendering embedded content, like attachments.

current renders the embedded content using the latest version.
version-at-save renders the embedded content using the version at the time of save.

Possible values:

"version-at-save"
"current"

Default value: "current"

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.