Atlassian Confluence Content API
The Atlassian Confluence Content API enables access and manipulation of content within Confluence including pages, blog posts, comments, and attachments.
OpenAPI Specification
openapi: 3.0.1
info:
title: 'Atlassian wiki/rest/api/content/'
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
- name: Content - Attachments
- name: Content - Children and Descendants
- name: Content - Macro Body
- name: Content Comments
- name: Content Labels
- name: Content Permissions
- name: Content Properties
- name: Content Restrictions
- name: Content States
- name: Content Versions
- name: Content Watches
- name: Experimental
paths:
/wiki/rest/api/content/archive:
post:
tags:
- Content
summary: Atlassian Archive Pages
description: >-
Archives a list of pages. The pages to be archived are specified as a
list of content IDs.<br>This API accepts the archival request and
returns a task ID.<br>The archival process happens
asynchronously.<br>Use the /longtask/ REST API to get the copy task
status.<br><br>Each content ID needs to resolve to page objects that are
not already in an archived state.<br>The content IDs need not belong to
the same
space.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>'Archive' permission for each of the pages in the
corresponding space it belongs to.
operationId: atlassianArchivepages
requestBody:
description: The pages to be archived.
content:
application/json:
schema:
type: object
properties:
pages:
type: array
items:
type: object
required:
- id
properties:
id:
type: integer
format: int64
description: The `id` of the page to be archived.
responses:
'202':
description: Returned if the archive request has been submitted.
content:
application/json:
schema:
$ref: '#/components/schemas/LongTask'
'400':
description: >-
Returned if:
- there is an archival job already running for the tenant.
- the number of pages to archive is larger than the limit of 300.
- any of the content IDs specified in the array do not resolve to
pages.
- any of the specified pages are already archived.
- the request is coming from a free edition tenant.
- the request is coming from a non premium edition tenant with more
than 1 page ID
in the archive request.
content: {}
'401':
description: |-
Returned if the authentication credentials are incorrect or missing
from the request.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-content
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-content
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:content.metadata:confluence
- write:page:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-experimental: true
x-atlassian-connect-scope: WRITE
/wiki/rest/api/content/blueprint/instance/{draftId}:
put:
tags:
- Content
summary: Atlassian Publish Shared Draft
description: >-
Publishes a shared draft of a page created from a blueprint.<br><br>By
default, the following objects are expanded: `body.storage`, `history`,
`space`, `version`,
`ancestors`.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>Permission to view the draft and 'Add' permission for the
space that<br>the content will be created in.
operationId: atlassianPublishshareddraft
parameters:
- name: draftId
in: path
description: |-
The ID of the draft page that was created from a blueprint.
You can find the `draftId` in the Confluence application by
opening the draft page and checking the page URL.
required: true
schema:
type: string
- name: status
in: query
description: |-
The status of the content to be updated, i.e. the draft. This is set
to 'draft' by default, so you shouldn't need to specify it.
schema:
type: string
default: draft
- $ref: '#/components/parameters/contentExpand'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContentBlueprintDraft'
required: true
responses:
'200':
description: Returned if the draft was successfully published.
content:
application/json:
schema:
$ref: '#/components/schemas/Content'
'400':
description: |-
Returned if a title is not specified or a page with the
title already exists.
content: {}
'409':
description: Returned if the version is not set to 1.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-content
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-content
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:content-details:confluence
- write:content:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-codegen-request-body-name: body
x-atlassian-connect-scope: WRITE
post:
tags:
- Content
summary: Atlassian Publish Legacy Draft
description: >-
Publishes a legacy draft of a page created from a blueprint. Legacy
drafts<br>will eventually be removed in favor of shared drafts. For now,
this method<br>works the same as [Publish shared
draft](#api-content-blueprint-instance-draftId-put).<br><br>By default,
the following objects are expanded: `body.storage`, `history`, `space`,
`version`,
`ancestors`.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>Permission to view the draft and 'Add' permission for the
space that<br>the content will be created in.
operationId: atlassianPublishlegacydraft
parameters:
- name: draftId
in: path
description: |-
The ID of the draft page that was created from a blueprint.
You can find the `draftId` in the Confluence application by
opening the draft page and checking the page URL.
required: true
schema:
type: string
- name: status
in: query
description: |-
The status of the content to be updated, i.e. the draft. This is set
to 'draft' by default, so you shouldn't need to specify it.
schema:
type: string
default: draft
- $ref: '#/components/parameters/contentExpand'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContentBlueprintDraft'
required: true
responses:
'200':
description: Returned if the draft was successfully published.
content:
application/json:
schema:
$ref: '#/components/schemas/Content'
'400':
description: |-
Returned if a title is not specified or a page with the
title already exists.
content: {}
'409':
description: Returned if the version is not set to 1.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-content
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-content
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:content-details:confluence
- write:content:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-codegen-request-body-name: body
x-atlassian-connect-scope: WRITE
/wiki/rest/api/content/search:
get:
tags:
- Content
summary: Atlassian Search Content By Cql
description: >-
Returns the list of content that matches a Confluence Query
Language<br>(CQL) query. For information on CQL, see:<br>[Advanced
searching using
CQL](https://developer.atlassian.com/cloud/confluence/advanced-searching-using-cql/).<br><br>Example
initial
call:<br>```<br>/wiki/rest/api/content/search?cql=type=page&limit=25<br>```<br><br>Example
response:<br>```<br>{<br> "results": [<br> { ... },<br> { ...
},<br> ...<br> { ... }<br> ],<br> "limit": 25,<br> "size":
25,<br> ...<br> "_links": {<br> "base": "",<br> "context":
"",<br> "next":
"/rest/api/content/search?cql=type=page&limit=25&cursor=raNDoMsTRiNg",<br> "self": ""<br> }<br>}<br>```<br><br>When additional results are
available, returns `next` and `prev` URLs to retrieve them in subsequent
calls. The URLs each contain a cursor that points to the appropriate set
of results. Use `limit` to specify the number of results returned in
each call.<br>Example subsequent call (taken from example
response):<br>```<br>/wiki/rest/api/content/search?cql=type=page&limit=25&cursor=raNDoMsTRiNg<br>```<br>The
response to this will have a `prev` URL similar to the `next` in the
example
response.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>Permission to access the Confluence site ('Can use'
global permission).<br>Only content that the user has permission to view
will be returned.
operationId: atlassianSearchcontentbycql
parameters:
- name: cql
in: query
description: The CQL string that is used to find the requested content.
required: true
schema:
type: string
- name: cqlcontext
in: query
description: >-
The space, content, and content status to execute the search
against.
Specify this as an object with the following properties:
- `spaceKey` Key of the space to search against. Optional.
- `contentId` ID of the content to search against. Optional. Must
be in the space spacified by `spaceKey`.
- `contentStatuses` Content statuses to search against. Optional.
schema:
type: string
- $ref: '#/components/parameters/contentExpand'
- name: cursor
in: query
description: >-
Pointer to a set of search results, returned as part of the `next`
or `prev` URL from the previous search call.
schema:
type: string
- name: limit
in: query
description: |-
The maximum number of content objects to return per page.
Note, this may be restricted by fixed system limits.
schema:
minimum: 0
type: integer
format: int32
default: 25
responses:
'200':
description: Returned if the requested list of content is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentArray'
'400':
description: Returned if the CQL is invalid or missing.
content: {}
'401':
description: |-
Returned if the authentication credentials are incorrect or missing
from the request.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- search:confluence
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- search:confluence
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:content-details:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: READ
/wiki/rest/api/content/{id}:
get:
tags:
- Content
summary: Atlassian Get Content By Id
deprecated: true
description: >-
Deprecated, use [Confluence's v2
API](https://developer.atlassian.com/cloud/confluence/rest/v2/intro/).<br><br>Returns
a single piece of content, like a page or a blog post.<br><br>By
default, the following objects are expanded: `space`, `history`,
`version`.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>Permission to view the content. If the content is a blog
post, 'View' permission<br>for the space is required.
operationId: atlassianGetcontentbyid
parameters:
- name: id
in: path
description: >-
The ID of the content to be returned. If you don't know the content
ID,
use [Get content](#api-content-get) and filter the results.
required: true
schema:
type: string
- name: status
in: query
description: |-
Filter the results to a set of content based on their status.
If set to `any`, content with any status is returned. Note, the
`historical` status is currently not supported.
style: form
explode: true
schema:
type: array
items:
type: string
default:
- current
enum:
- current
- trashed
- deleted
- historical
- draft
- any
- name: version
in: query
description: The version number of the content to be returned.
schema:
type: integer
format: int32
- name: embeddedContentRender
in: query
description: >-
The version of embedded content (e.g. attachments) to render.
- <code>current</code> renders the latest version of the embedded
content.
- <code>version-at-save</code> renders the version of the embedded
content
at the time of save.
schema:
type: string
default: current
enum:
- current
- version-at-save
- $ref: '#/components/parameters/contentExpandWithSubExpandLimit'
- name: trigger
in: query
description: >-
If set to `viewed`, the request will trigger a 'viewed' event for
the content.
When this event is triggered, the page/blogpost will appear on the
'Recently visited'
tab of the user's Confluence dashboard.
schema:
type: string
enum:
- viewed
responses:
'200':
description: Returned if the requested content is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/Content'
'400':
description: |-
Returned if;
- The content id is invalid.
- The sub-expansions limit exceeds.
content: {}
'401':
description: >-
Returned if the authentication credentials are incorrect or missing
from the request.
content: {}
'403':
description: Returned if the calling user can not view the content.
content: {}
'404':
description: |-
Returned if;
- There is no content with the given ID.
- The requesting user does not have permission to view the content.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- read:confluence-content.summary
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- read:confluence-content.summary
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:content-details:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: READ
put:
tags:
- Content
summary: Atlassian Update Content
deprecated: true
description: >-
Deprecated, use [Confluence's v2
API](https://developer.atlassian.com/cloud/confluence/rest/v2/intro/).<br><br>Updates
a piece of content. Use this method to update the title or body<br>of a
piece of content, change the status, change the parent page, and
more.<br><br>Note, updating draft content is currently not
supported.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>Permission to update the content.
operationId: atlassianUpdatecontent
parameters:
- name: id
in: path
description: The ID of the content to be updated.
required: true
schema:
type: string
- name: status
in: query
description: >-
The updated status of the content. Use this parameter to change the
status of a piece of content without passing the entire request
body.
schema:
type: string
default: current
enum:
- current
- trashed
- deleted
- historical
- draft
- name: conflictPolicy
in: query
description: |-
The action that should be taken when conflicts are discovered.
Only used when publishing a draft page.
schema:
type: string
default: abort
enum:
- abort
requestBody:
description: The updated content.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentUpdate'
required: true
responses:
'200':
description: Returned if the content is updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Content'
'400':
description: >-
Returned if;
- The request body is missing required parameters (version, type,
title).
- The type property has been set incorrectly.
content: {}
'401':
description: |-
Returned if the authentication credentials are incorrect or missing
from the request.
content: {}
'403':
description: >-
Returned if the calling user can not update the content with
specified id.
content: {}
'404':
description: >-
Returned if a draft with current content cannot be found when
setting the status
parameter to draft and the content status is current.
content: {}
'409':
description: |-
Returned if;
- The page is a draft (draft pages cannot be updated).
- The version property has not been set correctly for the content
type.
content: {}
'501':
description: >-
Indicates that the server does not support the functionality needed
to serve the request.
For example,
- trying to publish edit draft and passing content status as
historical.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-content
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-content
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:content-details:confluence
- write:content:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-codegen-request-body-name: content
x-atlassian-connect-scope: WRITE
delete:
tags:
- Content
summary: Atlassian Delete Content
deprecated: true
description: >-
Deprecated, use [Confluence's v2
API](https://developer.atlassian.com/cloud/confluence/rest/v2/intro/).<br><br>Moves
a piece of content to the space's trash or purges it from the
trash,<br>depending on the content's type and status:<br><br>- If the
content's type is `page`,`blogpost`, or `attachment` and its status is
`current`,<br>it will be trashed.<br>- If the content's type is
`page`,`blogpost`, or `attachment` and its status is `trashed`,<br>the
content will be purged from the trash and deleted permanently.
Note,<br>you must also set the `status` query parameter to `trashed` in
your request.<br>- If the content's type is `comment`, it will be
deleted<br>permanently without being
trashed.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>'Delete' permission for the space that the content is in.
operationId: atlassianDeletecontent
parameters:
- name: id
in: path
description: The ID of the content to be deleted.
required: true
schema:
type: string
- name: status
in: query
description: >-
Set this to `trashed`, if the content's status is `trashed` and you
want to purge it.
schema:
type: string
responses:
'204':
description: Returned if the content is successfully trashed or purged.
content: {}
'400':
description: Returned if the content id is invalid.
content: {}
'401':
description: |-
Returned if the authentication credentials are incorrect or missing
from the request.
content: {}
'403':
description: >-
Returned if the calling user can not delete the content with
specified id.
content: {}
'404':
description: |-
Returned if;
- There is no content with the given ID.
- The requesting user does not have permission to trash or purge the
content.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-content
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-content
- scheme: oAuthDefinitions
state: Beta
scopes:
- delete:content:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: DELETE
/wiki/rest/api/content/{id}/pageTree:
delete:
tags:
- Experimental
summary: Atlassian Delete Page Tree
description: >-
Moves a pagetree rooted at a page to the space's trash:<br><br>- If the
content's type is `page` and its status is `current`, it will be trashed
including<br>all its descendants.<br>- For every other combination of
content type and status, this API is not supported.<br><br>This API
accepts the pageTree delete request and returns a task ID.<br>The delete
process happens asynchronously.<br><br> Response example:<br> <br>
{<br> "id" : "1180606",<br> "links" : {<br> "status"
: "/rest/api/longtask/1180606"<br> }<br> }<br> <br> Use the
`/longtask/` REST API to get the copy task
status.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>'Delete' permission for the space that the content is in.
operationId: atlassianDeletepagetree
parameters:
- name: id
in: path
description: >-
The ID of the content which forms root of the page tree, to be
deleted.
required: true
schema:
type: string
responses:
'202':
description: >-
Returned if the request to trash content and all its current page
descendants, is successfully accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/LongTask'
'400':
description: >-
Returned if the content id is invalid or id does not represents a
'CURRENT' page.
content: {}
'401':
description: |-
Returned if the authentication credentials are incorrect or missing
from the request.
content: {}
'403':
description: >-
Returned if the calling user can not delete the content with
specified id.
content: {}
'404':
description: >-
Returned if;
- There is no content with the given ID.
- The requesting user does not have permission to trash the content
or any of it's descendant pages.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-content
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-content
- scheme: oAuthDefinitions
state: Beta
scopes:
- delete:content:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: DELETE
/wiki/rest/api/content/{id}/child:
get:
tags:
- Content - Children and Descendants
summary: Atlassian Get Content Children
deprecated: true
description: >-
Deprecated, use [Confluence's v2
API](https://developer.atlassian.com/cloud/confluence/rest/v2/intro/).<br><br>Returns
a map of the direct children of a piece of content. A piece of
content<br>has different types of child content, depending on its type.
These are<br>the default parent-child content type
relationships:<br><br>- `page`: child content is `page`, `comment`,
`attachment`<br>- `blogpost`: child content is `comment`,
`attachment`<br>- `attachment`: child content is `comment`<br>-
`comment`: child content is `attachment`<br><br>Apps can override these
default relationships. Apps can also introduce<br>new content types that
create new parent-child content relationships.<br><br>Note, the map will
always include all child content types that are valid<br>for the
content. However, if the content has no instances of a child
content<br>type, the map will contain an empty array for that child
content
type.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**: 'View' permission for the space,<br>and permission to view
the content if it is a page.
operationId: atlassianGetcontentchildren
parameters:
- name: id
in: path
description: The ID of the content to be queried for its children.
required: true
schema:
type: string
- name: expand
in: query
description: >-
A multi-value parameter indicating which properties of the children
to expand, where:
- `attachment` returns all attachments for the content.
- `comments` returns all comments for the content.
- `page` returns all child pages of the content.
- Custom content types that are provided by apps are also supported.
style: form
explode: false
schema:
type: array
items:
type: string
- name: parentVersion
in: query
description: |-
The version of the parent content to retrieve children for.
Currently, this only works for the latest version.
schema:
type: integer
format: int32
default: 0
responses:
'200':
description: Returned if the requested content children are returned.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentChildren'
'404':
description: |-
Returned if;
- There is no content with the given ID.
- The calling user does not have permission to view the content.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- read:confluence-content.summary
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- read:confluence-content.summary
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:content-details:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: READ
/wiki/rest/api/content/{pageId}/move/{position}/{targetId}:
put:
tags:
- Content - Children and Descendants
summary: Atlassian Move A Page To A New Location Relative To A Target Page
description: >-
Move a page to a new location relative to a target page:<br><br>*
`before` - move the page under the same parent as the target, before the
target in the list of children<br>* `after` - move the page under the
same parent as the target, after the target in the list of children<br>*
`append` - move the page to be a child of the target<br><br>Caution:
This API can move pages to the top level of a space. Top-level pages are
difficult to find in the UI<br>because they do not show up in the page
tree display. To avoid this, never use `before` or `after`
positions<br>when the `targetId` is a top-level page.
operationId: atlassianMovepage
parameters:
- name: pageId
in: path
description: The ID of the page to be moved
required: true
schema:
type: string
- name: position
in: path
description: >-
The position to move the page to relative to the target page:
* `before` - move the page under the same parent as the target,
before the target in the list of children
* `after` - move the page under the same parent as the target, after
the target in the list of children
* `append` - move the page to be a child of the target
required: true
schema:
type: string
enum:
- before
- after
- append
- name: targetId
in: path
description: The ID of the target page for this operation
required: true
schema:
type: string
responses:
'200':
description: Page was successfully moved
content:
application/json:
schema
# --- truncated at 32 KB (212 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-wiki-rest-api-content--openapi-original.yml