Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Confluence Cloud REST Content - macro body API
description: This document describes the REST API and resources provided by Confluence.
termsOfService: https://atlassian.com/terms/
version: 1.0.0
servers:
- url: //your-domain.atlassian.net
tags:
- name: Content - Macro Body
description: ''
paths:
/wiki/rest/api/content/{id}/history/{version}/macro/id/{macroId}:
get:
tags:
- Content - Macro Body
summary: Get macro body by macro ID
description: '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:
com.atlassian.ecosystem
e9c4aa10-73fa-417c-888d-48c719ae4165
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.'
operationId: getMacroBodyByMacroId
parameters:
- name: id
in: path
description: The ID for the content that contains the macro.
required: true
schema:
type: string
- name: version
in: path
description: 'The version of the content that contains the macro. Specifying `0` as the `version` will return
the macro body for the latest content version.'
required: true
schema:
type: integer
format: int32
- name: macroId
in: path
description: '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''.'
required: true
schema:
type: string
responses:
'200':
description: Returned if the requested macro body is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/MacroInstance'
'401':
description: 'Returned if the authentication credentials are incorrect or missing
from the request.'
content: {}
'404':
description: 'Returned if;
- There is no content with the given ID.
- The calling user does not have permission to view the content.
- The macro does not exist in the specified version.
- There is no macro matching the given macro ID or hash.'
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- read:confluence-content.all
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- read:confluence-content.all
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:content.metadata:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: READ
/wiki/rest/api/content/{id}/history/{version}/macro/id/{macroId}/convert/{to}:
get:
tags:
- Content - Macro Body
summary: Get macro body by macro ID and convert the representation synchronously
description: '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:
com.atlassian.ecosystem
e9c4aa10-73fa-417c-888d-48c719ae4165
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.'
operationId: getAndConvertMacroBodyByMacroId
parameters:
- name: id
in: path
description: The ID for the content that contains the macro.
required: true
schema:
type: string
- name: version
in: path
description: 'The version of the content that contains the macro. Specifying `0` as the `version` will return
the macro body for the latest content version.'
required: true
schema:
type: integer
format: int32
- name: macroId
in: path
description: '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''.'
required: true
schema:
type: string
- name: to
in: path
required: true
description: The content representation to return the macro in.
schema:
type: string
- $ref: '#/components/parameters/bodyConversionExpand'
- name: spaceKeyContext
in: query
description: '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.'
schema:
type: string
- name: embeddedContentRender
in: query
description: '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.'
schema:
type: string
default: current
enum:
- current
- version-at-save
responses:
'200':
description: Returned if the requested content body is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentBody'
'400':
description: Returned if invalid content representation is requested, or context is missing.
'401':
description: 'Returned if the authentication credentials are incorrect or missing
from the request.'
content: {}
'404':
description: 'Returned if;
- There is no content with the given ID.
- The calling user does not have permission to view the content.
- The macro does not exist in the specified version.
- There is no macro matching the given macro ID or hash.'
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- read:confluence-content.all
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- read:confluence-content.all
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:content.metadata:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: READ
/wiki/rest/api/content/{id}/history/{version}/macro/id/{macroId}/convert/async/{to}:
get:
tags:
- Content - Macro Body
summary: Get macro body by macro ID and convert representation Asynchronously
description: '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:
com.atlassian.ecosystem
e9c4aa10-73fa-417c-888d-48c719ae4165
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.'
operationId: getAndAsyncConvertMacroBodyByMacroId
parameters:
- name: id
in: path
description: The ID for the content that contains the macro.
required: true
schema:
type: string
- name: version
in: path
description: 'The version of the content that contains the macro. Specifying `0` as the `version` will return
the macro body for the latest content version.'
required: true
schema:
type: integer
format: int32
- name: macroId
in: path
description: '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''.'
required: true
schema:
type: string
- name: to
in: path
required: true
description: 'The content representation to return the macro in.
Currently, the following conversions are allowed:
- `export_view`
- `styled_view`
- `view`'
schema:
type: string
enum:
- export_view
- view
- styled_view
- $ref: '#/components/parameters/bodyConversionExpand'
- name: allowCache
in: query
description: "Controls whether conversion results are cached and reused for identical requests.\n\n- `false`: Each request creates a new conversion task, even if an identical request was made previously.\n- `true`: Enables caching behavior for identical requests from the same user.\n - If no cached result exists, a new conversion task is created\n - If a cached result exists, the existing task is marked as RERUNNING and will complete with status COMPLETED\n - Returns the same task ID for identical requests, allowing you to retrieve the cached result\n\nFor large macros that are slow to convert and for which it is acceptable to show cached data, set this field to `true`."
schema:
type: boolean
default: false
- name: spaceKeyContext
in: query
description: '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.'
schema:
type: string
- name: embeddedContentRender
in: query
description: '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.'
schema:
type: string
default: current
enum:
- current
- version-at-save
responses:
'200':
description: Returned if the requested macro conversion request is created.
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncId'
'401':
description: 'Returned if the authentication credentials are incorrect or missing
from the request.'
content: {}
'404':
description: 'Returned if;
- There is no content with the given ID.
- The calling user does not have permission to view the content.
- The macro does not exist in the specified version.
- There is no macro matching the given macro ID or hash.'
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- read:confluence-content.all
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- read:confluence-content.all
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:content.metadata:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: READ
components:
schemas:
AsyncId:
required:
- asyncId
type: object
properties:
asyncId:
type: string
EmbeddedContent:
type: object
additionalProperties: true
properties:
entityId:
type: integer
format: int64
entityType:
type: string
entity:
$ref: '#/components/schemas/Embeddable'
SuperBatchWebResources:
type: object
properties:
uris:
type: object
properties:
all:
oneOf:
- type: array
items:
type: string
- type: string
css:
oneOf:
- type: array
items:
type: string
- type: string
js:
oneOf:
- type: array
items:
type: string
- type: string
tags:
type: object
properties:
all:
type: string
css:
type: string
data:
type: string
js:
type: string
metatags:
type: string
_expandable:
type: object
additionalProperties: true
WebResourceDependencies:
type: object
properties:
_expandable:
type: object
additionalProperties: true
properties:
uris:
oneOf:
- type: string
- type: object
additionalProperties: true
keys:
type: array
items:
type: string
contexts:
type: array
items:
type: string
uris:
type: object
properties:
all:
oneOf:
- type: array
items:
type: string
- type: string
css:
oneOf:
- type: array
items:
type: string
- type: string
js:
oneOf:
- type: array
items:
type: string
- type: string
_expandable:
type: object
additionalProperties: true
properties:
css:
oneOf:
- type: array
items:
type: string
- type: string
js:
oneOf:
- type: array
items:
type: string
- type: string
tags:
type: object
properties:
all:
type: string
css:
type: string
data:
type: string
js:
type: string
_expandable:
type: object
additionalProperties: true
superbatch:
$ref: '#/components/schemas/SuperBatchWebResources'
ContentBody:
required:
- representation
- value
type: object
properties:
value:
type: string
representation:
type: string
enum:
- view
- export_view
- styled_view
- storage
- editor
- editor2
- anonymous_export_view
- wiki
- atlas_doc_format
- raw
embeddedContent:
type: array
items:
$ref: '#/components/schemas/EmbeddedContent'
webresource:
$ref: '#/components/schemas/WebResourceDependencies'
mediaToken:
type: object
properties:
collectionIds:
type: array
items:
type: string
contentId:
type: string
expiryDateTime:
type: string
fileIds:
type: array
items:
type: string
token:
type: string
_expandable:
type: object
properties:
content:
type: string
embeddedContent:
type: string
webresource:
type: string
mediaToken:
type: string
_links:
$ref: '#/components/schemas/GenericLinks'
Embeddable:
type: object
additionalProperties: true
GenericLinks:
type: object
additionalProperties:
oneOf:
- type: object
additionalProperties: true
- type: string
MacroInstance:
type: object
properties:
name:
type: string
body:
type: string
parameters:
type: object
_links:
$ref: '#/components/schemas/GenericLinks'
parameters:
bodyConversionExpand:
name: expand
in: query
description: "A multi-value parameter indicating which properties of the content to expand and populate. Expands are dependent on the\n`to` conversion format and may be irrelevant for certain conversions (e.g. `macroRenderedOutput` is redundant when\nconverting to `view` format). \n\nIf rendering to `view` format, and the body content being converted includes arbitrary nested content (such as macros); then it is \nnecessary to include webresource expands in the request. Webresources for content body are the batched JS and CSS dependencies for\nany nested dynamic content (i.e. macros).\n\n- `embeddedContent` returns metadata for nested content (e.g. page included using page include macro)\n- `mediaToken` returns JWT token for retrieving attachment data from Media API\n- `macroRenderedOutput` additionally converts body to view format\n- `webresource.superbatch.uris.js` returns all common JS dependencies as static URLs\n- `webresource.superbatch.uris.css` returns all common CSS dependencies as static URLs\n- `webresource.superbatch.uris.all` returns all common dependencies as static URLs\n- `webresource.superbatch.tags.all` returns all common JS dependencies as html `<script>` tags\n- `webresource.superbatch.tags.css` returns all common CSS dependencies as html `<style>` tags\n- `webresource.superbatch.tags.js` returns all common dependencies as html `<script>` and `<style>` tags\n- `webresource.uris.js` returns JS dependencies specific to conversion\n- `webresource.uris.css` returns CSS dependencies specific to conversion\n- `webresource.uris.all` returns all dependencies specific to conversion \n- `webresource.tags.all` returns common JS dependencies as html `<script>` tags\n- `webresource.tags.css` returns common CSS dependencies as html `<style>` tags\n- `webresource.tags.js` returns common dependencies as html `<script>` and `<style>` tags"
style: form
explode: false
schema:
type: array
items:
type: string
securitySchemes:
basicAuth:
type: http
description: You can access this resource via basic auth.
scheme: basic
oAuthDefinitions:
type: oauth2
description: This API uses OAuth 2 with the authorizationCode grant flow.
flows:
authorizationCode:
authorizationUrl: https://auth.atlassian.com/authorize
tokenUrl: https://auth.atlassian.com/oauth/token
scopes:
read:confluence-content.all: Read all content, including content body (expansions permitted). Note, APIs using this scope may also return data allowed by read:confluence-space.summary. However, this scope is not a substitute for read:confluence-space.summary.
read:confluence-content.permission: Read content permissions.
read:confluence-content.summary: Read a summary of the content, which is the content without expansions. Note, APIs using this scope may also return data allowed by read:confluence-space.summary. However, this scope is not a substitute for read:confluence-space.summary.
write:confluence-content: Permits the creation of pages, blogs, comments and questions.
read:confluence-space.summary: Read a summary of space information without expansions.
write:confluence-space: Create, update and delete space information.
write:confluence-file: Upload attachments.
read:confluence-props: Read content properties.
write:confluence-props: Write content properties.
search:confluence: Search Confluence. Note, APIs using this scope may also return data allowed by read:confluence-space.summary and read:confluence-content.summary. However, this scope is not a substitute for read:confluence-space.summary or read:confluence-content.summary.
manage:confluence-configuration: Manage global settings.
read:confluence-groups: Read user groups.
write:confluence-groups: Create, remove and update user groups.
read:confluence-user: Read users.
readonly:content.attachment:confluence: Download attachments of a Confluence page or blogpost that you have access to.
read:content:confluence: View content.
read:content-details:confluence: View content details.
write:content:confluence: Create and update content.
delete:content:confluence: Delete content.
read:space-details:confluence: View space details.
read:analytics.content:confluence: View analytics for content.
read:audit-log:confluence: View audit records.
write:audit-log:confluence: Create audit records.
read:configuration:confluence: View Confluence settings.
write:configuration:confluence: Update Confluence settings.
read:page:confluence: View pages.
write:page:confluence: Create and update pages.
delete:page:confluence: Delete pages.
read:blogpost:confluence: View blogposts.
write:blogpost:confluence: Create and update blogposts.
delete:blogpost:confluence: Delete blogposts.
read:whiteboard:confluence: View whiteboards.
write:whiteboard:confluence: Create and update whiteboards.
delete:whiteboard:confluence: Delete whiteboards.
read:custom-content:confluence: View custom content.
write:custom-content:confluence: Create and update custom content.
delete:custom-content:confluence: Delete custom content.
read:attachment:confluence: View and download content attachments.
write:attachment:confluence: Create and update attachments.
delete:attachment:confluence: Delete attachments.
read:comment:confluence: View comments.
write:comment:confluence: Create and update comments.
delete:comment:confluence: Delete comments.
read:template:confluence: View content templates.
write:template:confluence: Create, update and delete content templates.
read:label:confluence: View labels.
write:label:confluence: Add and remove labels.
read:content.permission:confluence: Check content permissions.
read:content.property:confluence: View content properties.
write:content.property:confluence: Create, update and delete content properties.
read:content.restriction:confluence: View content restrictions.
write:content.restriction:confluence: Update content restrictions.
read:content.metadata:confluence: View content summaries.
read:watcher:confluence: View content watchers.
write:watcher:confluence: Add and remove content watchers.
read:group:confluence: View groups.
write:group:confluence: Create and delete groups.
read:inlinetask:confluence: View tasks.
write:inlinetask:confluence: Update tasks.
read:relation:confluence: View entity relationships.
write:relation:confluence: Create and update entity relationships.
read:space:confluence: View spaces.
write:space:confluence: Create and update spaces.
delete:space:confluence: Delete spaces.
read:space.permission:confluence: View space permissions.
write:space.permission:confluence: Update space permissions.
read:space.property:confluence: View space properties.
write:space.property:confluence: Create, update and delete space properties.
read:user.property:confluence: View user properties.
write:user.property:confluence: Create, update and delete user properties.
read:space.setting:confluence: View space settings.
write:space.setting:confluence: Update space settings.
read:user:confluence: View user details.
moderate:core-content:confluence: Moderate core contents
moderate:comment:confluence: Moderate comments
read:email-address:confluence: View email addresses of all users regardless of the user’s profile visibility settings.
externalDocs:
description: The online and complete version of the Confluence Cloud REST API docs.
url: https://developer.atlassian.com/cloud/confluence/rest/
x-atlassian-narrative:
documents:
- title: About
anchor: about
body: 'This is the reference for the Confluence Cloud REST API. This API is the primary way to get and
modify data in Confluence Cloud, whether you are developing an app or any other integration.
Use it to interact with Confluence entities, like pages and blog posts, spaces, users, groups,
and more.'
- title: Authentication and authorization
anchor: auth
body: '**Authentication:** If you are building a Cloud app, authentication is implemented via JWT or OAuth 2.0, depending on what you are building (see [Security overview](https://developer.atlassian.com/cloud/confluence/security-overview/)). Otherwise, if you are authenticating directly against the REST API, the REST API supports basic auth (see [Basic auth for REST APIs](https://developer.atlassian.com/cloud/confluence/basic-auth-for-rest-apis/)).
**Authorization:** If you are building a Cloud app, authorization can be implemented by [scopes](https://developer.atlassian.com/cloud/confluence/scopes/) or by [OAuth 2.0 user impersonation](https://developer.atlassian.com/cloud/confluence/oauth-2-jwt-bearer-tokens-for-apps). Otherwise, if you are making calls directly against the REST API, authorization is based on the user used in the authentication process.
See [Security overview](https://developer.atlassian.com/cloud/confluence/security-overview/) for more details on authentication and authorization.'
- title: Status codes
anchor: status-code
body: "The Confluence REST API uses the [standard HTTP status codes](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html).\n\nResponses that return an error status code will also return a response body, similar to the following:\n```json\n{\n \"statusCode\": 404,\n \"data\": {\n \"authorized\": false,\n \"valid\": false,\n \"errors\": [\n {\n \"message\": {\n \"translation\": \"This is an example error message.\",\n \"args\": []\n }\n }\n ],\n \"successful\": false\n },\n \"message\": \"This is an example error message.\"\n}\n```"
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/confluence/refs/heads/main/openapi/confluence-content-macro-body-api-openapi.yml