The Confluence Cloud REST API

Content - macro body

Get macro body by macro ID

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

Returns the body of a macro in storage format, for the given macro ID. This includes information like the name of the macro, the body of the macro, and any macro parameters. This method is mainly used by Cloud apps.

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.

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.

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

Connect app scope required: READ

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:confluence-content.all

Granular:read:content.metadata:confluence

Request

Path parameters

id Required

string

The ID for the content that contains the macro.

version Required

integer

The version of the content that contains the macro. Specifying 0 as the version will return the macro body for the latest content version.

Format: int32

macroId Required

string

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'.

Example

Forge

cURL

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asApp().requestConfluence(route`/wiki/rest/api/content/{id}/history/{version}/macro/id/{macroId}`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

Responses

200

401

404

Returned if the requested macro body is returned.

Content type	Value
application/json	MacroInstance

Get macro body by macro ID and convert the representation synchronously

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.

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

Connect app scope required: READ

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:confluence-content.all

Granular:read:content.metadata:confluence

Request

Path parameters

id Required

string

The ID for the content that contains the macro.

version Required

integer

The version of the content that contains the macro. Specifying 0 as the version will return the macro body for the latest content version.

Format: int32

macroId Required

string

to Required

string

The content representation to return the macro in.

Query parameters

expand

Array<string>

A multi-value parameter indicating which properties of the content to expand.

childTypes.all returns whether the content has attachments, comments, or child pages. Use this if you only need to check whether the content has children of a particular type.
childTypes.attachment returns whether the content has attachments.
childTypes.comment returns whether the content has comments.
childTypes.page returns whether the content has child pages.
container returns the space that the content is in. This is the same as the information returned by Get space.
metadata.currentuser returns information about the current user in relation to the content, including when they last viewed it, modified it, contributed to it, or added it as a favorite.
metadata.properties returns content properties that have been set via the Confluence REST API.
metadata.labels returns the labels that have been added to the content.
metadata.frontend this property is only used by Atlassian.
operations returns the operations for the content, which are used when setting permissions.
children.page returns pages that are descendants at the level immediately below the content.
children.attachment returns all attachments for the content.
children.comment returns all comments on the content.
restrictions.read.restrictions.user returns the users that have permission to read the content.
restrictions.read.restrictions.group returns the groups that have permission to read the content. Note that this may return deleted groups, because deleting a group doesn't remove associated restrictions.
restrictions.update.restrictions.user returns the users that have permission to update the content.
restrictions.update.restrictions.group returns the groups that have permission to update the content. Note that this may return deleted groups because deleting a group doesn't remove associated restrictions.
history returns the history of the content, including the date it was created.
history.lastUpdated returns information about the most recent update of the content, including who updated it and when it was updated.
history.previousVersion returns information about the update prior to the current content update.
history.contributors returns all of the users who have contributed to the content.
history.nextVersion returns information about the update after to the current content update.
ancestors returns the parent page, if the content is a page.
body returns the body of the content in different formats, including the editor format, view format, and export format.
body.storage returns the body of content in storage format.
body.view returns the body of content in view format.
version returns information about the most recent update of the content, including who updated it and when it was updated.
descendants.page returns pages that are descendants at any level below the content.
descendants.attachment returns all attachments for the content, same as children.attachment.
descendants.comment returns all comments on the content, same as children.comment.
space returns the space that the content is in. This is the same as the information returned by Get space.

In addition, the following comment-specific expansions can be used:

extensions.inlineProperties returns inline comment-specific properties.
extensions.resolution returns the resolution status of each comment.

Style: form

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.

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.

Default: current

Valid values: current, version-at-save

Example

Forge

cURL

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asApp().requestConfluence(route`/wiki/rest/api/content/{id}/history/{version}/macro/id/{macroId}/convert/{to}`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

Responses

200

400

401

404

Returned if the requested content body is returned.

Content type	Value
application/json	ContentBody

Get macro body by macro ID and convert representation Asynchronously

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

Returns Async Id of the conversion task which will convert the macro into a content body of the desired format. The result will be available for 5 minutes after completion of the conversion.

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: '884bd9-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.

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

Connect app scope required: READ

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:confluence-content.all

Granular:read:content.metadata:confluence

Request

Path parameters

id Required

string

The ID for the content that contains the macro.

version Required

integer

The version of the content that contains the macro. Specifying 0 as the version will return the macro body for the latest content version.

Format: int32

macroId Required

string

The ID of the macro. For apps, this is passed to the macro by the Connect/Forge framework. 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'.

to Required

string

The content representation to return the macro in. Currently, the following conversions are allowed:

export_view
styled_view
view

Valid values: export_view, view, styled_view

Query parameters

expand

Array<string>

A multi-value parameter indicating which properties of the content to expand and populate.

embeddedContent
mediaToken
webresource.superbatch.metatags
webresource.superbatch.tags.all
webresource.superbatch.tags.css
webresource.superbatch.tags.data
webresource.superbatch.tags.js
webresource.superbatch.uris.all
webresource.superbatch.uris.css
webresource.superbatch.uris.data
webresource.superbatch.uris.js
webresource.tags.all
webresource.tags.css
webresource.tags.data
webresource.tags.js
webresource.uris.all
webresource.uris.css
webresource.uris.data
webresource.uris.js

Style: form

allowCache

boolean

If this field is false, the cache will erase its current value and begin a conversion. If this field is true, the cache will not erase its current value, and will set the status of the result in cache to RERUNNING. Once the data is updated, the status will change to COMPLETED. Large macros that take long to convert, and who want to show intermediate, but potentially stale data, immediately should set this field to true. Cache values are stored per macro per user per content and expansions.

Default: false

spaceKeyContext

string

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.

Default: current

Valid values: current, version-at-save

Example

Forge

cURL

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asApp().requestConfluence(route`/wiki/rest/api/content/{id}/history/{version}/macro/id/{macroId}/convert/async/{to}`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

Responses

200

401

404

Returned if the requested macro conversion request is passed to the AMQ node.

Content type	Value
application/json	AsyncId