GET

Get macro body by macro ID

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.

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.

Data Security Policy: Not exempt from app access rules
Scopes
ClassicRECOMMENDED:read:confluence-content.all
Granular:read:content.metadata:confluence

Connect app scope requiredREAD

Request

Path parameters

id

string

Required
version

integer

Required
macroId

string

Required

Responses

Returned if the requested macro body is returned.

application/json

MacroInstance
GET/wiki/rest/api/content/{id}/history/{version}/macro/id/{macroId}
1 2 3 4 5 6 7 8 9 10 11 12 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ import api, { route } from "@forge/api"; const response = await api.asUser().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());
200Response
1 2 3 4 5 6 { "name": "<string>", "body": "<string>", "parameters": {}, "_links": {} }
GET

Get macro body by macro ID and convert the representation synchronously

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.

Data Security Policy: Not exempt from app access rules
Scopes
ClassicRECOMMENDED:read:confluence-content.all
Granular:read:content.metadata:confluence

Connect app scope requiredREAD

Request

Path parameters

id

string

Required
version

integer

Required
macroId

string

Required
to

string

Required

Query parameters

expand

array<string>

spaceKeyContext

string

embeddedContentRender

string

Responses

Returned if the requested content body is returned.

application/json

ContentBody
GET/wiki/rest/api/content/{id}/history/{version}/macro/id/{macroId}/convert/{to}
1 2 3 4 5 6 7 8 9 10 11 12 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ import api, { route } from "@forge/api"; const response = await api.asUser().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());
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 { "value": "<string>", "representation": "view", "embeddedContent": [ { "entityId": 2154, "entityType": "<string>", "entity": {} } ], "webresource": { "_expandable": { "uris": "<string>" }, "keys": [ "<string>" ], "contexts": [ "<string>" ], "uris": { "all": [ "<string>" ], "css": [ "<string>" ], "js": [ "<string>" ], "_expandable": { "css": [ "<string>" ], "js": [ "<string>" ] } }, "tags": { "all": "<string>", "css": "<string>", "data": "<string>", "js": "<string>", "_expandable": {} }, "superbatch": { "uris": { "all": [ "<string>" ], "css": [ "<string>" ], "js": [ "<string>" ] }, "tags": { "all": "<string>", "css": "<string>", "data": "<string>", "js": "<string>" }, "metatags": "<string>", "_expandable": {} } }, "mediaToken": { "collectionIds": [ "<string>" ], "contentId": "<string>", "expiryDateTime": "<string>", "fileIds": [ "<string>" ], "token": "<string>" }, "_expandable": { "content": "<string>", "embeddedContent": "<string>", "webresource": "<string>", "mediaToken": "<string>" }, "_links": {} }
GET

Get macro body by macro ID and convert representation Asynchronously

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.

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.

Data Security Policy: Not exempt from app access rules
Scopes
ClassicRECOMMENDED:read:confluence-content.all
Granular:read:content.metadata:confluence

Connect app scope requiredREAD

Request

Path parameters

id

string

Required
version

integer

Required
macroId

string

Required
to

string

Required

Query parameters

expand

array<string>

allowCache

boolean

spaceKeyContext

string

embeddedContentRender

string

Responses

Returned if the requested macro conversion request is created.

application/json

AsyncId
GET/wiki/rest/api/content/{id}/history/{version}/macro/id/{macroId}/convert/async/{to}
1 2 3 4 5 6 7 8 9 10 11 12 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ import api, { route } from "@forge/api"; const response = await api.asUser().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());
200Response
1 2 3 { "asyncId": "<string>" }

Rate this page: