Atlassian Confluence Content Body API
The Atlassian Confluence Content Body API enables programmatic manipulation of Confluence page content bodies and format conversion.
OpenAPI Specification
openapi: 3.0.1
info:
title: 'Atlassian wiki/rest/api/contentbody/'
description: Needs description.
termsOfService: https://atlassian.com/terms/
version: 1.0.0
externalDocs:
description: The online and complete version of the Confluence Cloud REST API docs.
url: https://developer.atlassian.com/cloud/confluence/rest/
servers:
- url: //your-domain.atlassian.net
tags:
- name: Content Body
paths:
/wiki/rest/api/contentbody/convert/{to}:
post:
tags:
- Content Body
summary: Atlassian Convert Content Body
description: >-
Converts a content body from one format to another
format.<br><br>Supported conversions:<br><br>- storage: view,
export_view, styled_view, editor<br>- editor: storage<br>- view:
none<br>- export_view: none<br>- styled_view:
none<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>If request specifies 'contentIdContext', 'View'
permission for the space, and permission to view the content.
operationId: atlassianConvertcontentbody
parameters:
- name: to
in: path
description: The name of the target format for the content body.
required: true
schema:
type: string
- 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: contentIdContext
in: query
description: >-
The content ID used to find the space 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 `contentIdContext=123` parameter is provided, then the link
will be converted to a link to the "Example page" page in the same
space
that has the content with ID=123. Note, `spaceKeyContext` will be
ignored
if this parameter is provided.
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
- $ref: '#/components/parameters/bodyConversionExpand'
requestBody:
description: The content body to convert.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentBodyCreate'
required: true
responses:
'200':
description: Returned if the content is converted.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentBody'
'400':
description: >-
Returned if the content body is invalid or if the value is
improperly formed.
content: {}
'404':
description: Returned if content cannot be found with the provided context.
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-codegen-request-body-name: body
x-atlassian-connect-scope: READ
/wiki/rest/api/contentbody/convert/async/{to}:
post:
tags:
- Content Body
summary: Atlassian Asynchronously Convert Content Body
description: >-
Converts a content body from one format to another format
asynchronously.<br>Returns the asyncId for the asynchronous
task.<br><br>Supported conversions:<br><br>- storage:
export_view<br><br>No other conversions are supported at the
moment.<br>Once a conversion is completed, it will be available for 5
minutes at the result
endpoint.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>If request specifies 'contentIdContext', 'View'
permission for the space, and permission to view the content.
operationId: atlassianAsyncconvertcontentbodyrequest
parameters:
- name: to
in: path
description: The name of the target format for the content body.
required: true
schema:
type: string
enum:
- export_view
- $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: contentIdContext
in: query
description: >-
The content ID used to find the space 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 `contentIdContext=123` parameter is provided, then the link
will be converted to a link to the "Example page" page in the same
space
that has the content with ID=123. Note, `spaceKeyContext` will be
ignored
if this parameter is provided.
schema:
type: string
- name: allowCache
in: query
description: >-
If this field is false, the cache will erase its current value and
begin a new conversion.
If this field is true, the cache will not erase its current value,
and will set the status of the
async conversion to RERUNNING. Once the data is updated, the status
will change to COMPLETED.
Large macros that take long to convert, and whose data need not
immediately up to date (same as previous conversion's result within
last 5 minutes)
should set this fields to true. Cache values are stored per user per
content body and expansions.
schema:
type: boolean
default: false
- 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
requestBody:
description: The content body to convert.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentBodyCreate'
required: true
responses:
'200':
description: >-
Returned if the content is added to the messaging queue for
conversion. This id will be available for 5 minutes after the
conversion is complete.
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncId'
'400':
description: |-
Returned
- if the content body or conversion context is invalid or null
- if the value is improperly formed
- any conversion type other than export_view
content: {}
'404':
description: Returned if content cannot be found with the provided context.
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: true
x-codegen-request-body-name: body
x-atlassian-connect-scope: READ
/wiki/rest/api/contentbody/convert/async/{id}:
get:
tags:
- Content Body
summary: >-
Atlassian Get Asynchronously Converted Content Body From The Id Or The Current Status Of The Task
description: >-
Returns the asynchronous content body for the corresponding id if the
task is complete <br>or returns the status of the task.<br><br>After the
task is completed, the result can be obtained for 5 minutes, or until an
identical conversion request is made again,<br>with allowCache query
param set to
false.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>If request specifies 'contentIdContext', 'View'
permission for the space, and permission to view the content.
operationId: atlassianAsyncconvertcontentbodyresponse
parameters:
- name: id
in: path
description: The asyncId of the macro task to get the converted body.
required: true
schema:
type: string
responses:
'200':
description: >-
Returned if successfully found an async conversion task associated
with the id.
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncContentBody'
'400':
description: Returned if the async id is invalid.
content: {}
'401':
description: >-
Returned if the request was not made by an anonymous user and user
is not authenticated.
content: {}
'403':
description: >-
Returned if the requesting user is not the user who made the
conversion request.
content: {}
'404':
description: >-
Returned if async macro conversion task cannot be found with the
provided id.
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: true
x-codegen-request-body-name: body
x-atlassian-connect-scope: READ
components:
schemas:
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'
AsyncId:
required:
- asyncId
type: object
properties:
asyncId:
type: string
AsyncContentBody:
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
renderTaskId:
type: string
error:
type: string
status:
description: >-
Rerunning is reserved for when the job is working, but there is a
previous run's value in the cache. You may choose to continue
polling, or use the cached value.
type: string
enum:
- WORKING
- QUEUED
- FAILED
- COMPLETED
- RERUNNING
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'
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).
Responses that return an error status code will also return a response
body, similar to the following:
```json
{
"statusCode": 404,
"data": {
"authorized": false,
"valid": false,
"errors": [
{
"message": {
"translation": "This is an example error message.",
"args": []
}
}
],
"successful": false
},
"message": "This is an example error message."
}
```
- title: Using the REST API
anchor: using
body: >-
**Expansion:** The Confluence REST API uses resource expansion: some
parts of a resource are not returned unless explicitly specified. This
simplifies responses and minimizes network traffic.
To expand part of a resource in a request, use the `expand` query
parameter and specify the entities to be expanded. If you need to expand
nested entities, use the `.` dot notation. For example, the following
request will expand information about the requested content's space and
labels:
```
GET /wiki/rest/api/content/{id}?expand=space,metadata.labels
```
**Pagination:** The Confluence REST API uses pagination: a method that
returns a response with multiple objects can only return a limited
number at one time. This limits the size of responses and conserves
server resources.
Use the 'limit' and 'start' query parameters to specify pagination:
- `limit` is the number of objects to return per page. This may be
restricted by system limits.
- `start` is the index of the first item returned in the page of
results. The base index is 0.
For example, the following request will return ten content objects,
starting from the fifth object.
```
GET /wiki/rest/api/content?start=4&limit=10
```
**Special headers:**
- `X-Atlassian-Token: no-check` request header must be specified for
methods
that are protected from Cross Site Request Forgery (XSRF/CSRF) attacks.
This is
stated in the method description, if required. For more information, see
this
[KB
article](https://confluence.atlassian.com/cloudkb/xsrf-check-failed-when-calling-cloud-apis-826874382.html).
- title: Capabilities
anchor: capabilities
body: >-
**Webhooks:** A webhook is a user-defined callback over HTTP. You can
use Confluence webhooks to notify your app or web application when
certain events occur in Confluence. For example, when a page is created
or updated. To learn more, see
[Webhooks](https://developer.atlassian.com/cloud/confluence/modules/webhook/).
**Content properties:** Content properties are a key-value storage
associated with a piece of Confluence content. If you are building an
app, this is one form of persistence that you can use. You can use the
Confluence REST API to get, update, and delete content properties. To
learn more, see [Content properties in the REST
API](https://developer.atlassian.com/cloud/confluence/content-properties/).
**CQL:** The Confluence Query Language (CQL) allows you to perform
complex searches for content using an SQL-like syntax in the `search`
resource. To learn more, see [Advanced searching using
CQL](https://developer.atlassian.com/cloud/confluence/advanced-searching-using-cql/).