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.
This API accepts the archival request and
returns a task ID.
The archival process happens
asynchronously.
Use the /longtask/ REST API to get the copy task
status.
Each content ID needs to resolve to page objects that are
not already in an archived state.
The content IDs need not belong to
the same
space.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
'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.
By
default, the following objects are expanded: `body.storage`, `history`,
`space`, `version`,
`ancestors`.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to view the draft and 'Add' permission for the
space that
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
will eventually be removed in favor of shared drafts. For now,
this method
works the same as [Publish shared
draft](#api-content-blueprint-instance-draftId-put).
By default,
the following objects are expanded: `body.storage`, `history`, `space`,
`version`,
`ancestors`.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to view the draft and 'Add' permission for the
space that
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
(CQL) query. For information on CQL, see:
[Advanced
searching using
CQL](https://developer.atlassian.com/cloud/confluence/advanced-searching-using-cql/).
Example
initial
call:
```
/wiki/rest/api/content/search?cql=type=page&limit=25
```
Example
response:
```
{
"results": [
{ ... },
{ ...
},
...
{ ... }
],
"limit": 25,
"size":
25,
...
"_links": {
"base": "",
"context":
"",
"next":
"/rest/api/content/search?cql=type=page&limit=25&cursor=raNDoMsTRiNg",
"self": ""
}
}
```
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.
Example subsequent call (taken from example
response):
```
/wiki/rest/api/content/search?cql=type=page&limit=25&cursor=raNDoMsTRiNg
```
The
response to this will have a `prev` URL similar to the `next` in the
example
response.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to access the Confluence site ('Can use'
global permission).
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/).
Returns
a single piece of content, like a page or a blog post.
By
default, the following objects are expanded: `space`, `history`,
`version`.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to view the content. If the content is a blog
post, 'View' permission
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.
- current renders the latest version of the embedded
content.
- version-at-save 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/).
Updates
a piece of content. Use this method to update the title or body
of a
piece of content, change the status, change the parent page, and
more.
Note, updating draft content is currently not
supported.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
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/).
Moves
a piece of content to the space's trash or purges it from the
trash,
depending on the content's type and status:
- If the
content's type is `page`,`blogpost`, or `attachment` and its status is
`current`,
it will be trashed.
- If the content's type is
`page`,`blogpost`, or `attachment` and its status is `trashed`,
the
content will be purged from the trash and deleted permanently.
Note,
you must also set the `status` query parameter to `trashed` in
your request.
- If the content's type is `comment`, it will be
deleted
permanently without being
trashed.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
'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:
- If the
content's type is `page` and its status is `current`, it will be trashed
including
all its descendants.
- For every other combination of
content type and status, this API is not supported.
This API
accepts the pageTree delete request and returns a task ID.
The delete
process happens asynchronously.
Response example:
{
"id" : "1180606",
"links" : {
"status"
: "/rest/api/longtask/1180606"
}
}
Use the
`/longtask/` REST API to get the copy task
status.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
'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/).
Returns
a map of the direct children of a piece of content. A piece of
content
has different types of child content, depending on its type.
These are
the default parent-child content type
relationships:
- `page`: child content is `page`, `comment`,
`attachment`
- `blogpost`: child content is `comment`,
`attachment`
- `attachment`: child content is `comment`
-
`comment`: child content is `attachment`
Apps can override these
default relationships. Apps can also introduce
new content types that
create new parent-child content relationships.
Note, the map will
always include all child content types that are valid
for the
content. However, if the content has no instances of a child
content
type, the map will contain an empty array for that child
content
type.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**: 'View' permission for the space,
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:
*
`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
Caution:
This API can move pages to the top level of a space. Top-level pages are
difficult to find in the UI
because they do not show up in the page
tree display. To avoid this, never use `before` or `after`
positions
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:
type: object
properties:
pageId:
$ref: '#/components/schemas/ContentId'
'400':
description: >-
Returned if;
- A page already exists in the target space with the same name.
User is advised to rename page before moving.
- The move would create a parent-child loop (page becomes a
descendant and ancestor of itself)
- The page has permission restrictions that the user does not have
permission to create in the target space.
User is advised to remove restrictions before moving.
content: {}
'403':
description: |-
Returned if;
- User does not have permission to remove page from current space
- User does not have permission to create a page in target space
content: {}
'404':
description: |-
Returned if;
- The id or targetId refer to non-existent 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:
- write:page:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: WRITE
/wiki/rest/api/content/{id}/child/attachment:
get:
tags:
- Content - Attachments
summary: Atlassian Get Attachments
deprecated: true
description: >-
Deprecated, use [Confluence's v2
API](https://developer.atlassian.com/cloud/confluence/rest/v2/intro/).
Returns
the attachments for a piece of content.
By default, the following
objects are expanded:
`metadata`.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to view the content. If the content is a blog
post, 'View' permission
for the space is required.
operationId: atlassianGetattachments
parameters:
- name: id
in: path
description: The ID of the content to be queried for its attachments.
required: true
schema:
type: string
- $ref: '#/components/parameters/contentExpand'
- name: start
in: query
description: The starting index of the returned attachments.
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: limit
in: query
description: |-
The maximum number of attachments to return per page.
Note, this may be restricted by fixed system limits.
schema:
minimum: 0
type: integer
format: int32
default: 25
- name: filename
in: query
description: Filter the results to attachments that match the filename.
schema:
type: string
- name: mediaType
in: query
description: Filter the results to attachments that match the media type.
schema:
type: string
responses:
'200':
description: Returned if the requested attachments are returned.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentArray'
'404':
description: >-
Returned if;
- There is no parent content with the given ID.
- The calling user does not have permission to view the parent
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 - Attachments
summary: Atlassian Create Or Update Attachment
description: >-
Adds an attachment to a piece of content. If the attachment already
exists
for the content, then the attachment is updated (i.e. a new
version of the
attachment is created).
Note, you must set a
`X-Atlassian-Token: nocheck` header on the request
for this method,
otherwise it will be blocked. This protects against XSRF
attacks,
which is necessary as this method accepts
multipart/form-data.
The media type 'multipart/form-data' is
defined in [RFC 7578](https://www.ietf.org/rfc/rfc7578.txt).
Most
client libraries have classes that make it easier to
implement
multipart posts, like the
[MultipartEntityBuilder](https://hc.apache.org/httpcomponents-client-5.1.x/current/httpclient5/apidocs/)
Java
class provided by Apache HTTP Components.
Note, according to [RFC
7578](https://tools.ietf.org/html/rfc7578#section-4.5),
in the case
where the form data is text,
the charset parameter for the
"text/plain" Content-Type may be used to
indicate the character
encoding used in that part. In the case of this
API endpoint, the
`comment` body parameter should be sent with `type=text/plain`
and
`charset=utf-8` values. This will force the charset to be
UTF-8.
Example: This curl command attaches a file ('example.txt')
to a piece of
content (id='123') with a comment and
`minorEdits`=true. If the 'example.txt'
file already exists, it will
update it with a new version of the attachment.
``` bash
curl
-D- \
-u admin:admin \
-X PUT \
-H 'X-Atlassian-Token:
nocheck' \
-F 'file=@"example.txt"' \
-F 'minorEdit="true"'
\
-F 'comment="Example attachment comment"; type=text/plain;
charset=utf-8' \
http://myhost/rest/api/content/123/child/attachment
```
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to update the content.
operationId: atlassianCreateorupdateattachments
parameters:
- name: id
in: path
description: The ID of the content to add the attachment to.
required: true
schema:
type: string
- name: status
in: query
description: |-
The status of the content that the attachment is being added to.
This should always be set to 'current'.
schema:
type: string
default: current
enum:
- current
- draft
requestBody:
content:
multipart/form-data:
schema:
required:
- file
- minorEdit
properties:
file:
type: string
description: >-
The relative location and name of the attachment to be added
to
the content.
format: binary
comment:
type: string
description: >-
The comment for the attachment that is being added.
If you specify a comment, then every file must have a
comment and
the comments must be in the same order as the files.
Alternatively,
don't specify any comments.
format: binary
minorEdit:
type: string
description: >-
If `minorEdits` is set to 'true', no notification email or
activity stream
will be generated when the attachment is added to the
content.
format: binary
required: true
responses:
'200':
description: Returned if the attachments were added to the content.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentArray'
'403':
description: >-
Returned if;
- Attachments are disabled.
- The calling user does not have permission to add attachments to
the
content.
content: {}
'404':
description: |-
Returned if;
- The requested content is not found.
- The user does not have permission to view it.
- The attachment exceeds the maximum configured attachment size.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-file
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-file
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:content-details:confluence
- write:attachment:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: WRITE
post:
tags:
- Content - Attachments
summary: Atlassian Create Attachment
description: >-
Adds an attachment to a piece of content. This method only adds a
new
attachment. If you want to update an existing attachment,
use
[Create or update
attachments](#api-content-id-child-attachment-put).
Note, you
must set a `X-Atlassian-Token: nocheck` header on the request
for
this method, otherwise it will be blocked. This protects against
XSRF
attacks, which is necessary as this method accepts
multipart/form-data.
The media type 'multipart/form-data' is
defined in [RFC 7578](https://www.ietf.org/rfc/rfc7578.txt).
Most
client libraries have classes that make it easier to
implement
multipart posts, like the
[MultipartEntityBuilder](https://hc.apache.org/httpcomponents-client-5.1.x/current/httpclient5/apidocs/)
Java
class provided by Apache HTTP Components.
Note, according to [RFC
7578](https://tools.ietf.org/html/rfc7578#section-4.5),
in the case
where the form data is text,
the charset parameter for the
"text/plain" Content-Type may be used to
indicate the character
encoding used in that part. In the case of this
API endpoint, the
`comment` body parameter should be sent with `type=text/plain`
and
`charset=utf-8` values. This will force the charset to be
UTF-8.
Example: This curl command attaches a file ('example.txt')
to a container
(id='123') with a comment and
`minorEdits`=true.
``` bash
curl -D- \
-u admin:admin
\
-X POST \
-H 'X-Atlassian-Token: nocheck' \
-F
'file=@"example.txt"' \
-F 'minorEdit="true"' \
-F
'comment="Example attachment comment"; type=text/plain; charset=utf-8'
\
http://myhost/rest/api/content/123/child/attachment
```
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to update the content.
operationId: atlassianCreateattachment
parameters:
- name: id
in: path
description: The ID of the content to add the attachment to.
required: true
schema:
type: string
- name: status
in: query
description: The status of the content that the attachment is being added to.
schema:
type: string
default: current
enum:
- current
- draft
requestBody:
content:
multipart/form-data:
schema:
required:
- file
- minorEdit
properties:
file:
type: string
description: >-
The relative location and name of the attachment to be added
to
the content.
format: binary
comment:
type: string
description: >-
The comment for the attachment that is being added.
If you specify a comment, then every file must have a
comment and
the comments must be in the same order as the files.
Alternatively,
don't specify any comments.
format: binary
minorEdit:
type: string
description: >-
If `minorEdits` is set to 'true', no notification email or
activity stream
will be generated when the attachment is added to the
content.
format: binary
required: true
responses:
'200':
description: Returned if the attachments were added to the content.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentArray'
'400':
description: >-
Returned if the content already has an attachment with the same
filename.
content: {}
'403':
description: >-
Returned if;
- Attachments are disabled in Confluence.
- The calling user does not have permission to add attachments to
the
content.
content: {}
'404':
description: |-
Returned if;
- The requested content is not found.
- The user does not have permission to view it
- The attachment exceeds the maximum configured attachment size.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-file
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-file
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:content-details:confluence
- write:attachment:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: WRITE
/wiki/rest/api/content/{id}/child/attachment/{attachmentId}:
put:
tags:
- Content - Attachments
summary: Atlassian Update Attachment Properties
description: >-
Updates the attachment properties, i.e. the non-binary data of an
attachment
like the filename, media-type, comment, and parent
container.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to update the content.
operationId: atlassianUpdateattachmentproperties
parameters:
- name: id
in: path
description: The ID of the content that the attachment is attached to.
required: true
schema:
type: string
- name: attachmentId
in: path
description: The ID of the attachment to update.
required: true
schema:
type: string
requestBody:
description: The details of the attachment to be updated.
content:
application/json:
schema:
$ref: '#/components/schemas/AttachmentPropertiesUpdateBody'
required: true
responses:
'200':
description: Returned if the attachment is updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Content'
'400':
description: |-
Returned if;
- The attachment id is invalid.
- The attachment version number is invalid.
content: {}
'403':
description: >-
Returned if;
- The calling user is not permitted to update or move the
attachment.
- The attachment is being moved to an invalid content type.
content: {}
'404':
description: Returned if no attachment is found for the attachment ID.
content: {}
'409':
description: |-
Returned if the version of the supplied attachment does not match
the version of the attachment stored in the database.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-file
- write:confluence-props
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-file
- write:confluence-props
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:content-details:confluence
- write:attachment: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/{id}/child/attachment/{attachmentId}/data:
post:
tags:
- Content - Attachments
summary: Atlassian Update Attachment Data
description: >-
Updates the binary data of an attachment, given the attachment ID,
and
optionally the comment and the minor edit field.
This
method is essentially the same as [Create or update
attachments](#api-content-id-child-attachment-put),
except that it
matches the attachment ID rather than the name.
Note, you must
set a `X-Atlassian-Token: nocheck` header on the request
for this
method, otherwise it will be blocked. This protects against
XSRF
attacks, which is necessary as this method accepts
multipart/form-data.
The media type 'multipart/form-data' is
defined in [RFC 7578](https://www.ietf.org/rfc/rfc7578.txt).
Most
client libraries have classes that make it easier to
implement
multipart posts, like the
[MultipartEntityBuilder](https://hc.apache.org/httpcomponents-client-5.1.x/current/httpclient5/apidocs/)
Java
class provided by Apache HTTP Components.
Note, according to [RFC
7578](https://tools.ietf.org/html/rfc7578#section-4.5),
in the case
where the form data is text,
the charset parameter for the
"text/plain" Content-Type may be used to
indicate the character
encoding used in that part. In the case of this
API endpoint, the
`comment` body parameter should be sent with `type=text/plain`
and
`charset=utf-8` values. This will force the charset to be
UTF-8.
Example: This curl command updates an attachment
(id='att456') that is attached
to a piece of content (id='123') with
a comment and `minorEdits`=true.
``` bash
curl -D- \
-u
admin:admin \
-X POST \
-H 'X-Atlassian-Token: nocheck' \
-F 'file=@"example.txt"' \
-F 'minorEdit="true"' \
-F
'comment="Example attachment comment"; type=text/plain; charset=utf-8'
\
http://myhost/rest/api/content/123/child/attachment/att456/data
```
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to update the content.
operationId: atlassianUpdateattachmentdata
parameters:
- name: id
in: path
description: The ID of the content that the attachment is attached to.
required: true
schema:
type: string
- name: attachmentId
in: path
description: The ID of the attachment to update.
required: true
schema:
type: string
requestBody:
content:
multipart/form-data:
schema:
required:
- file
- minorEdit
properties:
file:
type: string
description: >-
The relative location and name of the attachment to be added
to
the content.
format: binary
comment:
type: string
description: >-
The comment for the attachment that is being added.
If you specify a comment, then every file must have a
comment and
the comments must be in the same order as the files.
Alternatively,
don't specify any comments.
format: binary
minorEdit:
type: string
description: >-
If `minorEdits` is set to 'true', no notification email or
activity stream
will be generated when the attachment is added to the
content.
format: binary
required: true
responses:
'200':
description: Returned if the attachment is updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Content'
'400':
description: Returned if the attachment id is invalid.
content: {}
'404':
description: Returned if no attachment is found for the attachment ID.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-file
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-file
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:content-details:confluence
- write:attachment:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: WRITE
/wiki/rest/api/content/{id}/child/attachment/{attachmentId}/download:
get:
tags:
- Content - Attachments
summary: Atlassian Get Uri To Download Attachment
description: Redirects the client to a URL that serves an attachment's binary data.
operationId: atlassianDownloadattatchment
parameters:
- name: id
in: path
description: The ID of the content that the attachment is attached to.
required: true
schema:
type: string
- name: attachmentId
in: path
description: The ID of the attachment to download.
required: true
schema:
type: string
- name: version
in: query
description: >-
The version of the attachment. If this parameter is absent, the
redirect URI will download the latest version of the attachment.
schema:
type: integer
responses:
'302':
description: Returned if download URL is found.
'400':
description: >-
Returned if version number is greater than attachment's latest
version number or an invalid value.
'401':
description: Returned if there are authentication issues in request.
'404':
description: >-
Returned if;
- No content is found with the specified content ID.
- The specified content does not contain an attachment with the
specified attachment ID.
- The calling user does not have permission to view the attachment.
security:
- basicAuth: []
- oAuthDefinitions:
- readonly:content.attachment:confluence
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- readonly:content.attachment:confluence
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:attachment:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: READ
/wiki/rest/api/content/{id}/child/comment:
get:
tags:
- Content Comments
summary: Atlassian Get Content Comments
deprecated: true
description: >-
Deprecated, use [Confluence's v2
API](https://developer.atlassian.com/cloud/confluence/rest/v2/intro/).
Returns
the comments on a piece of
content.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**: 'View' permission for the space,
and permission to view
the content if it is a page.
operationId: atlassianGetcontentcomments
parameters:
- name: id
in: path
description: The ID of the content to be queried for its comments.
required: true
schema:
type: string
- $ref: '#/components/parameters/contentExpand'
- name: parentVersion
in: query
description: |-
The version of the parent content to retrieve children for.
Currently, this only works for the latest version.
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: start
in: query
description: The starting index of the returned comments.
schema:
type: integer
format: int32
- name: limit
in: query
description: |-
The maximum number of comments to return per page. Note,
this may be restricted by fixed system limits.
schema:
minimum: 0
type: integer
format: int32
default: 25
- name: location
in: query
description: >-
The location of the comments in the page. Multiple locations can be
specified.
If no location is specified, comments from all locations are
returned.
style: form
explode: true
schema:
type: array
items:
type: string
enum:
- inline
- footer
- resolved
- name: depth
in: query
description: |-
Currently, this parameter is not used.
Comments are returned at the root level only.
schema:
type: string
responses:
'200':
description: Returned if the requested comments are returned.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentArray'
'404':
description: >-
Returned if;
- There is no parent content with the given ID.
- The calling user does not have permission to view the parent
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/{id}/child/{type}:
get:
tags:
- Content - Children and Descendants
summary: Atlassian Get Content Children By Type
deprecated: true
description: >-
Deprecated, use [Confluence's v2
API](https://developer.atlassian.com/cloud/confluence/rest/v2/intro/).
Returns
all children of a given type, for a piece of content.
A piece of
content has different types of child content, depending on its
type:
- `page`: child content is `page`, `comment`,
`attachment`
- `blogpost`: child content is `comment`,
`attachment`
- `attachment`: child content is `comment`
-
`comment`: child content is `attachment`
Custom content types
that are provided by apps can also be returned.
Note, this method
only returns direct children. To return children at all
levels, use
[Get descendants by
type](#api-content-id-descendant-type-get).
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**: 'View' permission for the space,
and permission to view
the content if it is a page.
operationId: atlassianGetcontentchildrenbytype
parameters:
- name: id
in: path
description: The ID of the content to be queried for its children.
required: true
schema:
type: string
- name: type
in: path
description: The type of children to return.
required: true
schema:
type: string
- $ref: '#/components/parameters/contentExpand'
- name: parentVersion
in: query
description: |-
The version of the parent content to retrieve children for.
Currently, this only works for the latest version.
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: start
in: query
description: The starting index of the returned content.
schema:
type: integer
format: int32
- name: limit
in: query
description: |-
The maximum number of content 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 content is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentArray'
'400':
description: >-
Returned if the parent type and desired child content type are not
compatible.
Eg: Cannot find `page` children of a `blogpost`.
content: {}
'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/{id}/descendant:
get:
tags:
- Content - Children and Descendants
summary: Atlassian Get Content Descendants
description: >-
Returns a map of the descendants of a piece of content. This is
similar
to [Get content children](#api-content-id-child-get), except
that this
method returns child pages at all levels, rather than just
the direct
child pages.
A piece of content has different types
of descendants, depending on its type:
- `page`: descendant is
`page`, `comment`, `attachment`
- `blogpost`: descendant is
`comment`, `attachment`
- `attachment`: descendant is `comment`
-
`comment`: descendant is `attachment`
The map will always include
all descendant types that are valid for the content.
However, if the
content has no instances of a descendant type, the map will
contain
an empty array for that descendant
type.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
'View' permission for the space, and permission to view
the content if it
is a page.
operationId: atlassianGetcontentdescendants
parameters:
- name: id
in: path
description: The ID of the content to be queried for its descendants.
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.
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- attachment
- comment
- page
responses:
'200':
description: Returned if the requested descendants 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/{id}/descendant/{type}:
get:
tags:
- Content - Children and Descendants
summary: Atlassian Get Content Descendants By Type
description: >-
Returns all descendants of a given type, for a piece of content. This
is
similar to [Get content children by
type](#api-content-id-child-type-get),
except that this method
returns child pages at all levels, rather than just
the direct child
pages.
A piece of content has different types of descendants,
depending on its type:
- `page`: descendant is `page`, `comment`,
`attachment`
- `blogpost`: descendant is `comment`, `attachment`
-
`attachment`: descendant is `comment`
- `comment`: descendant is
`attachment`
Custom content types that are provided by apps can
also be
returned.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
'View' permission for the space, and permission to view
the content if it
is a page.
operationId: atlassianGetdescendantsoftype
parameters:
- name: id
in: path
description: The ID of the content to be queried for its descendants.
required: true
schema:
type: string
- name: type
in: path
description: The type of descendants to return.
required: true
schema:
type: string
enum:
- page
- comment
- attachment
- name: depth
in: query
description: >-
Filter the results to descendants upto a desired level of the
content. Note, the maximum value supported is 100. root level of the
content means immediate (level 1) descendants of the type requested.
all represents returning all descendants of the type requested.
schema:
type: string
default: all
enum:
- all
- root
-
- $ref: '#/components/parameters/contentExpand'
- name: start
in: query
description: The starting index of the returned content.
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: limit
in: query
description: |-
The maximum number of content 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 content is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentArray'
'400':
description: >-
Returned if;
- Any of the required request params are missing.
- The request is invalid such as negative start param, a format
besides int32 for limit etc.
content: {}
'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/{id}/history:
get:
tags:
- Content
summary: Atlassian Get Content History
deprecated: true
description: >-
Deprecated, use [Confluence's v2
API](https://developer.atlassian.com/cloud/confluence/rest/v2/intro/).
Returns
the most recent update for a piece of
content.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**: Permission to view the content.
operationId: atlassianGethistoryforcontent
parameters:
- name: id
in: path
description: The ID of the content to be queried for its history.
required: true
schema:
type: string
- name: expand
in: query
description: >-
A multi-value parameter indicating which properties of the content
history to expand.
Maximum sub-expansions allowed is `8`.
- `lastUpdated` returns information about the most recent update of
the content,
including who updated it and when it was updated.
- `previousVersion` returns information about the update prior to
the current content
update. For this method, it contains the same information as
`lastUpdated`.
- `contributors` returns all of the users who have contributed to
the content.
- `nextVersion` This parameter is not used for this method.
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- lastUpdated
- previousVersion
- contributors
- nextVersion
responses:
'200':
description: Returned if the requested content history is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentHistory'
'400':
description: Returned if sub-expansions limit exceeds.
content: {}
'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.
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.metadata:confluence
- read:user: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}:
get:
tags:
- Content - Macro Body
summary: Atlassian 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.
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](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to view the content that the macro is in.
operationId: atlassianGetmacrobodybymacroid
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: Atlassian 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.
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](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to view the content that the macro is in.
operationId: atlassianGetandconvertmacrobodybymacroid
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 ``
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: Atlassian 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.
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](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to view the content that the macro is in.
operationId: atlassianGetandasyncconvertmacrobodybymacroid
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: >-
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.
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 ``
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
/wiki/rest/api/content/{id}/label:
get:
tags:
- Content Labels
summary: Atlassian Get Labels For Content
deprecated: true
description: >-
Deprecated, use [Confluence's v2
API](https://developer.atlassian.com/cloud/confluence/rest/v2/intro/).
Returns
the labels on a piece of
content.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
'View' permission for the space and permission to view
the content if it is a page.
operationId: atlassianGetlabelsforcontent
parameters:
- name: id
in: path
description: The ID of the content to be queried for its labels.
required: true
schema:
type: string
- name: prefix
in: query
description: >-
Filters the results to labels with the specified prefix. If this
parameter
is not specified, then labels with any prefix will be returned.
- `global` prefix is used by default when a user adds a label
via the UI.
- `my` prefix can be explicitly added by a user when adding a label
via the UI, e.g. 'my:example-label'. Also, when a page is selected
as
a favourite, the 'my:favourite' label is automatically added.
- `team` can used when adding labels via [Add labels to
content](#api-content-id-label-post)
but is not used in the UI.
schema:
type: string
enum:
- global
- my
- team
- name: start
in: query
description: The starting index of the returned labels.
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: limit
in: query
description: |-
The maximum number of labels to return per page. Note,
this may be restricted by fixed system limits.
schema:
minimum: 0
type: integer
format: int32
default: 200
responses:
'200':
description: Returned if the requested labels are returned.
content:
application/json:
schema:
$ref: '#/components/schemas/LabelArray'
'403':
description: Returned if the calling user can view but not edit the content.
content: {}
'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:label:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: READ
post:
tags:
- Content Labels
summary: Atlassian Add Labels To Content
description: >-
Adds labels to a piece of content. Does not modify the existing
labels.
Notes:
- Labels can also be added when creating
content ([Create content](#api-content-post)).
- Labels can be
updated when updating content ([Update
content](#api-content-id-put)).
This will delete the existing labels
and replace them with the labels in
the
request.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to update the content.
operationId: atlassianAddlabelstocontent
parameters:
- name: id
in: path
description: The ID of the content that will have labels added to it.
required: true
schema:
type: string
requestBody:
description: The labels to add to the content.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/LabelCreateArray'
- $ref: '#/components/schemas/LabelCreate'
required: true
responses:
'200':
description: Returned if the labels are added to the content.
content:
application/json:
schema:
$ref: '#/components/schemas/LabelArray'
'400':
description: >-
Returned if;
- The body contains labels with invalid characters or too many
characters.
- The body contains too many labels.
- The target content would contain too many labels after the
operation.
- The calling user does not have permission to edit labels.
content: {}
'403':
description: Returned if the calling user can view but not edit the content.
content: {}
'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:
- write:confluence-content
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-content
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:label:confluence
- write:label:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-codegen-request-body-name: body
x-atlassian-connect-scope: WRITE
delete:
tags:
- Content Labels
summary: Atlassian Remove Label From Content Using Query Parameter
description: >-
Removes a label from a piece of content. Labels can't be deleted from
archived content.
This is similar to [Remove label from
content](#api-content-id-label-label-delete)
except that the label
name is specified via a query parameter.
Use this method if the
label name has "/" characters, as
[Remove label from content using
query parameter](#api-content-id-label-delete)
does not accept "/"
characters for the label
name.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to update the content.
operationId: atlassianRemovelabelfromcontentusingqueryparameter
parameters:
- name: id
in: path
description: The ID of the content that the label will be removed from.
required: true
schema:
type: string
- name: name
in: query
description: The name of the label to be removed.
required: true
schema:
type: string
responses:
'204':
description: Returned if the label is removed. The response body will be empty.
content: {}
'403':
description: Returned if the calling user can view but not edit the content.
content: {}
'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:
- write:confluence-content
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-content
- scheme: oAuthDefinitions
state: Beta
scopes:
- write:label:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: WRITE
/wiki/rest/api/content/{id}/label/{label}:
delete:
tags:
- Content Labels
summary: Atlassian Remove Label From Content
description: >-
Removes a label from a piece of content. Labels can't be deleted from
archived content.
This is similar to [Remove label from content using
query parameter](#api-content-id-label-delete)
except that the label
name is specified via a path parameter.
Use this method if the
label name does not have "/" characters, as the path
parameter does
not accept "/" characters for security reasons. Otherwise,
use
[Remove label from content using query
parameter](#api-content-id-label-delete).
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to update the content.
operationId: atlassianRemovelabelfromcontent
parameters:
- name: id
in: path
description: The ID of the content that the label will be removed from.
required: true
schema:
type: string
- name: label
in: path
description: The name of the label to be removed.
required: true
schema:
type: string
responses:
'204':
description: Returned if the label is removed. The response body will be empty.
content: {}
'400':
description: Returned if the label name has a "/" character.
content: {}
'403':
description: Returned if the calling user can view but not edit the content.
content: {}
'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:
- write:confluence-content
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-content
- scheme: oAuthDefinitions
state: Beta
scopes:
- write:label:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: WRITE
/wiki/rest/api/content/{id}/notification/child-created:
get:
tags:
- Content Watches
summary: Atlassian Get Watches For Page
description: >-
Returns the watches for a page. A user that watches a page will
receive
receive notifications when the page is updated.
If you
want to manage watches for a page, use the following `user`
methods:
- [Get content watch status for
user](#api-user-watch-content-contentId-get)
- [Add content
watch](#api-user-watch-content-contentId-post)
- [Remove content
watch](#api-user-watch-content-contentId-delete)
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to access the Confluence site ('Can use'
global permission).
operationId: atlassianGetwatchesforpage
parameters:
- name: id
in: path
description: The ID of the content to be queried for its watches.
required: true
schema:
type: string
- name: start
in: query
description: The starting index of the returned watches.
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: limit
in: query
description: |-
The maximum number of watches to return per page.
Note, this may be restricted by fixed system limits.
schema:
minimum: 0
type: integer
format: int32
default: 200
responses:
'200':
description: Returned if the requested watches are returned.
content:
application/json:
schema:
$ref: '#/components/schemas/WatchArray'
'401':
description: |-
Returned if the authentication credentials are incorrect or missing
from the request.
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:watcher:confluence
- read:user:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: READ
/wiki/rest/api/content/{id}/notification/created:
get:
tags:
- Content Watches
summary: Atlassian Get Watches For Space
description: >-
Returns all space watches for the space that the content is in. A user
that
watches a space will receive receive notifications when any
content in the
space is updated.
If you want to manage watches
for a space, use the following `user` methods:
- [Get space watch
status for user](#api-user-watch-space-spaceKey-get)
- [Add space
watch](#api-user-watch-space-spaceKey-post)
- [Remove space
watch](#api-user-watch-space-spaceKey-delete)
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to access the Confluence site ('Can use'
global permission).
operationId: atlassianGetwatchesforspace
parameters:
- name: id
in: path
description: The ID of the content to be queried for its watches.
required: true
schema:
type: string
- name: start
in: query
description: The starting index of the returned watches.
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: limit
in: query
description: |-
The maximum number of watches to return per page.
Note, this may be restricted by fixed system limits.
schema:
minimum: 0
type: integer
format: int32
default: 200
responses:
'200':
description: Returned if the requested watches are returned.
content:
application/json:
schema:
$ref: '#/components/schemas/SpaceWatchArray'
'401':
description: |-
Returned if the authentication credentials are incorrect or missing
from the request.
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:watcher:confluence
- read:user:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-connect-scope: READ
/wiki/rest/api/content/{id}/pagehierarchy/copy:
post:
tags:
- Content - Children and Descendants
summary: Atlassian Copy Page Hierarchy
description: >-
Copy page hierarchy allows the copying of an entire hierarchy of pages
and their associated properties, permissions and attachments.
The id
path parameter refers to the content id of the page to copy, and the new
parent of this copied page is defined using the destinationPageId in the
request body.
The titleOptions object defines the rules of renaming
page titles during the copy;
for example, search and replace can be
used in conjunction to rewrite the copied page titles.
Response
example:
{
"id" : "1180606",
"links" :
{
"status" : "/rest/api/longtask/1180606"
}
}
Use the /longtask/ REST API to get the copy task status.
operationId: atlassianCopypagehierarchy
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
description: Request object from json post body
content:
application/json:
schema:
$ref: '#/components/schemas/CopyPageHierarchyRequest'
required: true
responses:
'202':
description: Returns a full JSON representation of a long running task
content:
application/json:
schema:
$ref: '#/components/schemas/LongTask'
'400':
description: >-
Returned if the title prefix is invalid (e.g. is empty, creates a
conflict)
content: {}
'403':
description: >-
Returned if the user does not have permission to create content at
destination
content: {}
'404':
description: Returned if original page or destination page does not exist.
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-codegen-request-body-name: request
x-atlassian-connect-scope: WRITE
/wiki/rest/api/content/{id}/copy:
post:
tags:
- Content - Children and Descendants
summary: Atlassian Copy Single Page
description: >-
Copies a single page and its associated properties, permissions,
attachments, and custom contents.
The `id` path parameter refers to
the content ID of the page to copy. The target of the page to be
copied
is defined using the `destination` in the request body and
can be one of the following types.
- `space`: page will be
copied to the specified space as a root page on the space
-
`parent_page`: page will be copied as a child of the specified parent
page
- `existing_page`: page will be copied and replace the
specified page
By default, the following objects are expanded:
`space`, `history`,
`version`.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**: 'Add' permission for the space that the content will be
copied in and permission to update the content if copying to an
`existing_page`.
operationId: atlassianCopypage
parameters:
- name: id
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/contentExpandWithSubExpandLimit'
requestBody:
description: Request object from json post body
content:
application/json:
schema:
$ref: '#/components/schemas/CopyPageRequest'
required: true
responses:
'200':
description: Returned if the content is copied.
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/Content'
'400':
description: |-
Returned if;
- destination or any of its fields are not specified.
- destination.type is invalid.
- 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 user does not have permission to create content at
destination.
content: {}
'404':
description: |-
Returned if;
- the original page doesn't exist.
- the destination page doesn’t exist.
- the destination space doesn’t exist.
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:page:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-codegen-request-body-name: request
x-atlassian-connect-scope: WRITE
/wiki/rest/api/content/{id}/permission/check:
post:
tags:
- Content Permissions
summary: Atlassian Check Content Permissions
description: >-
Check if a user or a group can perform an operation to the specified
content. The `operation` to check
must be provided. The user’s
account ID or the ID of the group can be provided in the `subject` to
check
permissions against a specified user or group. The following
permission checks are done to make sure that the
user or group has
the proper access:
- site permissions
- space permissions
-
content
restrictions
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to access the Confluence site ('Can use'
global permission) if checking permission for self,
otherwise
'Confluence Administrator' global permission is required.
operationId: atlassianCheckcontentpermission
parameters:
- name: id
in: path
description: The ID of the content to check permissions against.
required: true
schema:
type: string
requestBody:
description: The content permission request.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentPermissionRequest'
required: true
responses:
'200':
description: Returned if the permission check completed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/PermissionCheckResponse'
'400':
description: |-
Returned if;
- If any of the required fields are missing.
- If specified `subject` or `operation` is invalid.
content: {}
'401':
description: |-
Returned if the authentication credentials are incorrect or missing
from the request.
content: {}
'403':
description: Returned if the user does not have permission perform the check.
content: {}
'404':
description: Returned if there is no content with the given ID.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- read:confluence-content.permission
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- read:confluence-content.permission
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:content.permission: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/content/{id}/property:
get:
tags:
- Content Properties
summary: Atlassian Get Content Properties
deprecated: true
description: >-
Returns the properties for a piece of content. For more
information
about content properties, see [Confluence entity
properties](https://developer.atlassian.com/cloud/confluence/confluence-entity-properties/).
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
'View' permission for the space, and permission to view
the content if it is a page.
operationId: atlassianGetcontentproperties
parameters:
- name: id
in: path
description: The ID of the content to be queried for its properties.
required: true
schema:
type: string
- name: key
in: query
description: The key of the content property.
explode: true
schema:
type: array
items:
type: string
- name: expand
in: query
description: >-
A multi-value parameter indicating which properties of the content
to
expand. By default, the `version` object is expanded.
- `content` returns the content that the property is stored against.
- `version` returns information about the version of the property,
such
as the version number, when it was created, etc.
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- content
- version
- name: start
in: query
description: The starting index of the returned properties.
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: limit
in: query
description: |-
The maximum number of properties to return per page.
Note, this may be restricted by fixed system limits.
schema:
minimum: 0
type: integer
format: int32
default: 10
responses:
'200':
description: Returned if the requested properties are returned.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentPropertyArray'
'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-props
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- read:confluence-props
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:content-details:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: READ
post:
tags:
- Content Properties
summary: Atlassian Create Content Property
deprecated: true
description: >-
Creates a property for an existing piece of content. For more
information
about content properties, see [Confluence entity
properties](https://developer.atlassian.com/cloud/confluence/confluence-entity-properties/).
This
is the same as [Create content property for
key](#api-content-id-property-key-post)
except that the key is
specified in the request body instead of as a
path
parameter.
Content properties can also be added when creating a
new piece of content
by including them in the `metadata.properties`
of the
request.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to update the content.
operationId: atlassianCreatecontentproperty
parameters:
- name: id
in: path
description: The ID of the content to add the property to.
required: true
schema:
type: string
requestBody:
description: The content property to be created.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentPropertyCreate'
required: true
responses:
'200':
description: Returned if the content property is created.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentProperty'
'400':
description: |-
Returned if;
- The content already has a property with the given key.
- The key is too long.
- The key is empty.
content: {}
'403':
description: |-
Returned if the user does not have permission to edit the content
with the given ID.
content: {}
'413':
description: Returned if the value is too long.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-props
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-props
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:content.property:confluence
- write:content.property: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/{id}/property/{key}:
get:
tags:
- Content Properties
summary: Atlassian Get Content Property
deprecated: true
description: >-
Returns a content property for a piece of content. For more information,
see
[Confluence entity
properties](https://developer.atlassian.com/cloud/confluence/confluence-entity-properties/).
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
'View' permission for the space, and permission to view
the content if it is a page.
operationId: atlassianGetcontentproperty
parameters:
- name: id
in: path
description: The ID of the content to be queried for the property.
required: true
schema:
type: string
- name: key
in: path
description: The key of the content property.
required: true
schema:
type: string
- name: expand
in: query
description: >-
A multi-value parameter indicating which properties of the content
to
expand. By default, the `version` object is expanded.
- `content` returns the content that the property is stored against.
- `version` returns information about the version of the property,
such
as the version number, when it was created, etc.
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- content
- version
- 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. By default it will fetch
current and archived statuses `?status=current&status=archived`.
All supported statuses
- any
- archived
- current
- deleted
- draft
- trashed
style: form
explode: true
schema:
type: array
items:
type: string
default:
- current
- archived
enum:
- any
- archived
- current
- deleted
- draft
- trashed
responses:
'200':
description: Returned if the content property is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentProperty'
'404':
description: |-
Returned if;
- The calling user does not have permission to view the content.
- There is no content with the given ID.
- There is no property with the given key.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- read:confluence-props
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- read:confluence-props
- 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 Properties
summary: Atlassian Update Content Property
deprecated: true
description: >-
Updates an existing content property. This method will also create a
new
property for a piece of content, if the property key does not
exist and
the property version is 1. For more information about
content properties, see
[Confluence entity
properties](https://developer.atlassian.com/cloud/confluence/confluence-entity-properties/).
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to update the content.
operationId: atlassianUpdatecontentproperty
parameters:
- name: id
in: path
description: The ID of the content that the property belongs to.
required: true
schema:
type: string
- name: key
in: path
description: The key of the property.
required: true
schema:
type: string
requestBody:
description: The content property being updated.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentPropertyUpdate'
required: true
responses:
'200':
description: Returned if the content property is created.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentProperty'
'400':
description: |-
Returned if;
- The content already a property with the given key.
- The key is too long.
- The key is empty.
content: {}
'403':
description: |-
Returned if the user does not have permission to edit the content
with the given ID.
content: {}
'404':
description: >-
Returned if;
- There is no content with the given ID.
- The calling user does not have permission to view the content.
- There is no property with the given key and the version number is
not 1.
content: {}
'409':
description: Returned if the property version is not correctly incremented.
content: {}
'413':
description: Returned if the value is too long.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-props
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-props
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:content.property:confluence
- write:content.property: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 Properties
summary: Atlassian Create Content Property For Key
deprecated: true
description: >-
Creates a property for an existing piece of content. For more
information
about content properties, see [Confluence entity
properties](https://developer.atlassian.com/cloud/confluence/confluence-entity-properties/).
This
is the same as [Create content
property](#api-content-id-property-post)
except that the key is
specified as a path parameter instead of in the
request
body.
Content properties can also be added when creating a new
piece of content
by including them in the `metadata.properties` of
the
request.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to update the content.
operationId: atlassianCreatecontentpropertyforkey
parameters:
- name: id
in: path
description: The ID of the content to add the property to.
required: true
schema:
type: string
- name: key
in: path
description: The key of the content property. Required.
required: true
schema:
type: string
requestBody:
description: The content property to be created.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentPropertyCreateNoKey'
required: true
responses:
'200':
description: Returned if the content property is created.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentProperty'
'400':
description: |-
Returned if;
- The content already has a property with the given key.
- The key is too long.
- The key is empty.
content: {}
'403':
description: |-
Returned if the user does not have permission to edit the content
with the given ID.
content: {}
'413':
description: Returned if the value is too long.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-props
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-props
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:content.property:confluence
- write:content.property:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-codegen-request-body-name: body
x-atlassian-connect-scope: WRITE
delete:
tags:
- Content Properties
summary: Atlassian Delete Content Property
deprecated: true
description: >-
Deletes a content property. For more information about content
properties, see
[Confluence entity
properties](https://developer.atlassian.com/cloud/confluence/confluence-entity-properties/).
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to update the content.
operationId: atlassianDeletecontentproperty
parameters:
- name: id
in: path
description: The ID of the content that the property belongs to.
required: true
schema:
type: string
- name: key
in: path
description: The key of the property.
required: true
schema:
type: string
responses:
'204':
description: Returned if the content property is deleted.
content: {}
'403':
description: |-
Returned if the user does not have permission to delete content
with the given ID.
content: {}
'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:
- write:confluence-props
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-props
- scheme: oAuthDefinitions
state: Beta
scopes:
- write:content.property:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: WRITE
/wiki/rest/api/content/{id}/restriction:
get:
tags:
- Content Restrictions
summary: Atlassian Get Restrictions
description: >-
Returns the restrictions on a piece of
content.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to view the content.
operationId: atlassianGetrestrictions
parameters:
- name: id
in: path
description: The ID of the content to be queried for its restrictions.
required: true
schema:
type: string
- name: expand
in: query
description: >-
A multi-value parameter indicating which properties of the content
restrictions to expand. By default, the following objects are
expanded:
`restrictions.user`, `restrictions.group`.
- `restrictions.user` returns the piece of content that the
restrictions are
applied to.
- `restrictions.group` returns the piece of content that the
restrictions are
applied to.
- `content` returns the piece of content that the restrictions are
applied to.
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- restrictions.user
- read.restrictions.user
- update.restrictions.user
- restrictions.group
- read.restrictions.group
- update.restrictions.group
- content
- name: start
in: query
description: >-
The starting index of the users and groups in the returned
restrictions.
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: limit
in: query
description: >-
The maximum number of users and the maximum number of groups, in the
returned restrictions, to return per page. Note, this may be
restricted
by fixed system limits.
schema:
minimum: 0
type: integer
format: int32
default: 100
responses:
'200':
description: Returned if the requested restrictions are returned.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentRestrictionArray'
'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.all
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- read:confluence-content.all
- 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 Restrictions
summary: Atlassian Update Restrictions
description: >-
Updates restrictions for a piece of content. For each operation
specified in the request, it removes
any existing restrictions on the
content for that operation, and replaces them with the restrictions in
the request.
Note: Not specifying an operation will ignore
restrictions of that type, and passing an empty list for an
operation
will remove all existing restrictions of that
type.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to edit the content.
operationId: atlassianUpdaterestrictions
parameters:
- name: id
in: path
description: The ID of the content to update restrictions for.
required: true
schema:
type: string
- name: expand
in: query
description: >-
A multi-value parameter indicating which properties of the content
restrictions (returned in response) to expand.
- `restrictions.user` returns the piece of content that the
restrictions are
applied to. Expanded by default.
- `restrictions.group` returns the piece of content that the
restrictions are
applied to. Expanded by default.
- `content` returns the piece of content that the restrictions are
applied to.
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- restrictions.user
- read.restrictions.user
- update.restrictions.user
- restrictions.group
- read.restrictions.group
- update.restrictions.group
- content
requestBody:
description: The updated restrictions for the content.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentRestrictionAddOrUpdateArray'
required: true
responses:
'200':
description: Returned if the requested restrictions are updated.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentRestrictionArray'
'404':
description: |-
Returned if;
- There is no content with the given ID.
- The calling user does not have permission to update restrictions
for 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:
- read:content-details:confluence
- write:content.restriction: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 Restrictions
summary: Atlassian Add Restrictions
description: >-
Adds restrictions to a piece of content. Note, this does not change
any
existing restrictions on the
content.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to edit the content.
operationId: atlassianAddrestrictions
parameters:
- name: id
in: path
description: The ID of the content to add restrictions to.
required: true
schema:
type: string
- name: expand
in: query
description: >-
A multi-value parameter indicating which properties of the content
restrictions (returned in response) to expand.
- `restrictions.user` returns the piece of content that the
restrictions are
applied to. Expanded by default.
- `restrictions.group` returns the piece of content that the
restrictions are
applied to. Expanded by default.
- `content` returns the piece of content that the restrictions are
applied to.
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- restrictions.user
- read.restrictions.user
- update.restrictions.user
- restrictions.group
- read.restrictions.group
- update.restrictions.group
- content
requestBody:
description: The restrictions to be added to the content.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentRestrictionAddOrUpdateArray'
required: true
responses:
'200':
description: Returned if the requested restrictions are added.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentRestrictionArray'
'404':
description: |-
Returned if;
- There is no content with the given ID.
- The calling user does not have permission to add restrictions to
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:
- read:content-details:confluence
- write:content.restriction:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-codegen-request-body-name: body
x-atlassian-connect-scope: WRITE
delete:
tags:
- Content Restrictions
summary: Atlassian Delete Restrictions
description: >-
Removes all restrictions (read and update) on a piece of
content.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to edit the content.
operationId: atlassianDeleterestrictions
parameters:
- name: id
in: path
description: The ID of the content to remove restrictions from.
required: true
schema:
type: string
- name: expand
in: query
description: >-
A multi-value parameter indicating which properties of the content
restrictions (returned in response) to expand.
- `restrictions.user` returns the piece of content that the
restrictions are
applied to. Expanded by default.
- `restrictions.group` returns the piece of content that the
restrictions are
applied to. Expanded by default.
- `content` returns the piece of content that the restrictions are
applied to.
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- restrictions.user
- read.restrictions.user
- update.restrictions.user
- restrictions.group
- read.restrictions.group
- update.restrictions.group
- content
responses:
'200':
description: Returned if the restrictions are removed.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentRestrictionArray'
'400':
description: Returned if any of the above validation rules are violated
content: {}
'403':
description: |-
Returned if the calling user does not have permission to alter the
restrictions on the content.
content: {}
'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:
- 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.restriction:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: DELETE
/wiki/rest/api/content/{id}/restriction/byOperation:
get:
tags:
- Content Restrictions
summary: Atlassian Get Restrictions By Operation
description: >-
Returns restrictions on a piece of content by operation. This method
is
similar to [Get restrictions](#api-content-id-restriction-get)
except that
the operations are properties of the return object,
rather than items in
a results
array.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to view the content.
operationId: atlassianGetrestrictionsbyoperation
parameters:
- name: id
in: path
description: The ID of the content to be queried for its restrictions.
required: true
schema:
type: string
- name: expand
in: query
description: >-
A multi-value parameter indicating which properties of the content
restrictions to expand.
- `restrictions.user` returns the piece of content that the
restrictions are
applied to. Expanded by default.
- `restrictions.group` returns the piece of content that the
restrictions are
applied to. Expanded by default.
- `content` returns the piece of content that the restrictions are
applied to.
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- restrictions.user
- restrictions.group
- content
responses:
'200':
description: Returned if the requested restrictions are returned.
content:
application/json:
schema:
type: object
additionalProperties:
properties:
operationType:
$ref: '#/components/schemas/ContentRestriction'
_links:
$ref: '#/components/schemas/GenericLinks'
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-details:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: READ
/wiki/rest/api/content/{id}/restriction/byOperation/{operationKey}:
get:
tags:
- Content Restrictions
summary: Atlassian Get Restrictions For Operation
description: >-
Returns the restictions on a piece of content for a given operation
(read
or
update).
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to view the content.
operationId: atlassianGetrestrictionsforoperation
parameters:
- name: id
in: path
description: The ID of the content to be queried for its restrictions.
required: true
schema:
type: string
- name: operationKey
in: path
description: The operation type of the restrictions to be returned.
required: true
schema:
type: string
enum:
- read
- update
- name: expand
in: query
description: >-
A multi-value parameter indicating which properties of the content
restrictions to expand.
- `restrictions.user` returns the piece of content that the
restrictions are
applied to. Expanded by default.
- `restrictions.group` returns the piece of content that the
restrictions are
applied to. Expanded by default.
- `content` returns the piece of content that the restrictions are
applied to.
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- restrictions.user
- restrictions.group
- content
- name: start
in: query
description: >-
The starting index of the users and groups in the returned
restrictions.
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: limit
in: query
description: >-
The maximum number of users and the maximum number of groups, in the
returned restrictions, to return per page. Note, this may be
restricted
by fixed system limits.
schema:
minimum: 0
type: integer
format: int32
default: 100
responses:
'200':
description: Returned if the requested restrictions are returned.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentRestriction'
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-details:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: READ
/wiki/rest/api/content/{id}/restriction/byOperation/{operationKey}/group/{groupName}:
get:
tags:
- Content Restrictions
summary: Atlassian Get Content Restriction Status For Group
deprecated: true
description: >-
Deprecated, use [Get content restriction status for group via
groupId](https://developer.atlassian.com/cloud/confluence/rest/v1/api-group-content-restrictions/#api-wiki-rest-api-content-id-restriction-byoperation-operationkey-bygroupid-groupid-get).
Returns
whether the specified content restriction applies to a group.
For
example, if a page with `id=123` has a `read` restriction for the
`admins` group,
the following request will return
`true`:
`/wiki/rest/api/content/123/restriction/byOperation/read/group/admins`
Note
that a response of `true` does not guarantee that the group can view the
page, as it does not account for
account-inherited restrictions,
space permissions, or even product access. For more
information, see
[Confluence
permissions](https://confluence.atlassian.com/x/_AozKw).
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to view the content.
operationId: atlassianGetcontentrestrictionstatusforgroup
parameters:
- name: id
in: path
description: The ID of the content that the restriction applies to.
required: true
schema:
type: string
- name: operationKey
in: path
description: The operation that the restriction applies to.
required: true
schema:
type: string
enum:
- read
- update
- name: groupName
in: path
description: >-
The name of the group to be queried for whether the content
restriction
applies to it.
required: true
schema:
type: string
responses:
'200':
description: >-
Returns true if the content restriction applies to the group. The
response
will not return a response body.
content: {}
'400':
description: |-
Returned if;
- Group name is missing
content: {}
'404':
description: |-
Returned if;
- There is no content with the given ID.
- The calling user does not have permission to view the content.
- An invalid operation or group is specified.
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.restriction:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: READ
put:
tags:
- Content Restrictions
summary: Atlassian Add Group To Content Restriction
deprecated: true
description: >-
Deprecated, use [Add group to content restriction via
groupId](https://developer.atlassian.com/cloud/confluence/rest/v1/api-group-content-restrictions/#api-wiki-rest-api-content-id-restriction-byoperation-operationkey-bygroupid-groupid-put).
Adds
a group to a content restriction. That is, grant read or
update
permission to the group for a piece of
content.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to edit the content.
operationId: atlassianAddgrouptocontentrestriction
parameters:
- name: id
in: path
description: The ID of the content that the restriction applies to.
required: true
schema:
type: string
- name: operationKey
in: path
description: The operation that the restriction applies to.
required: true
schema:
type: string
enum:
- read
- update
- name: groupName
in: path
description: The name of the group to add to the content restriction.
required: true
schema:
type: string
responses:
'200':
description: >-
Returned if the group is added to the content restriction. The
response
body will be empty.
content: {}
'404':
description: |-
Returned if;
- There is no content with the given ID.
- The calling user does not have permission to view the content.
- An invalid operation or group is specified.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-content
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-content
- scheme: oAuthDefinitions
state: Beta
scopes:
- write:content.restriction:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: WRITE
delete:
tags:
- Content Restrictions
summary: Atlassian Remove Group From Content Restriction
deprecated: true
description: >-
Deprecated, use [Remove group from content restriction by
groupId](https://developer.atlassian.com/cloud/confluence/rest/v1/api-group-content-restrictions/#api-wiki-rest-api-content-id-restriction-byoperation-operationkey-user-delete).
Removes
a group from a content restriction. That is, remove read or
update
permission for the group for a piece of
content.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to edit the content.
operationId: atlassianRemovegroupfromcontentrestrictionbyid
parameters:
- name: id
in: path
description: The ID of the content that the restriction applies to.
required: true
schema:
type: string
- name: operationKey
in: path
description: The operation that the restriction applies to.
required: true
schema:
type: string
enum:
- read
- update
- name: groupName
in: path
description: The name of the group to remove from the content restriction.
required: true
schema:
type: string
responses:
'200':
description: >-
Returned if the group is removed from the content restriction. The
response
body will be empty.
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 restriction to be deleted does not exist.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-content
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-content
- scheme: oAuthDefinitions
state: Beta
scopes:
- write:content.restriction:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: WRITE
/wiki/rest/api/content/{id}/restriction/byOperation/{operationKey}/byGroupId/{groupId}:
get:
tags:
- Content Restrictions
summary: Atlassian Get Content Restriction Status For Group
description: >-
Returns whether the specified content restriction applies to a
group.
For example, if a page with `id=123` has a `read` restriction
for the `123456` group id,
the following request will return
`true`:
`/wiki/rest/api/content/123/restriction/byOperation/read/byGroupId/123456`
Note
that a response of `true` does not guarantee that the group can view the
page, as it does not account for
account-inherited restrictions,
space permissions, or even product access. For more
information, see
[Confluence
permissions](https://confluence.atlassian.com/x/_AozKw).
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to view the content.
operationId: atlassianGetindividualgrouprestrictionstatusbygroupid
parameters:
- name: id
in: path
description: The ID of the content that the restriction applies to.
required: true
schema:
type: string
- name: operationKey
in: path
description: The operation that the restriction applies to.
required: true
schema:
type: string
enum:
- read
- update
- name: groupId
in: path
description: >-
The id of the group to be queried for whether the content
restriction
applies to it.
required: true
schema:
type: string
responses:
'200':
description: >-
Returns true if the content restriction applies to the group. The
response
will not return a response body.
content: {}
'403':
description: |-
Returned if the calling user does not have permission to view the
content.
content: {}
'404':
description: |-
Returned if
- There is no content with the given ID.
- An invalid operation or group is specified.
- Given groupId is blank or has invalid characters
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.restriction:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: READ
put:
tags:
- Content Restrictions
summary: Atlassian Add Group To Content Restriction
description: >-
Adds a group to a content restriction by Group Id. That is, grant read
or update
permission to the group for a piece of
content.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to edit the content.
operationId: atlassianAddgrouptocontentrestrictionbygroupid
parameters:
- name: id
in: path
description: The ID of the content that the restriction applies to.
required: true
schema:
type: string
- name: operationKey
in: path
description: The operation that the restriction applies to.
required: true
schema:
type: string
enum:
- read
- update
- name: groupId
in: path
description: The groupId of the group to add to the content restriction.
required: true
schema:
type: string
responses:
'200':
description: >-
Returned if the group is added to the content restriction by Group
Id. The response
body will be empty.
content: {}
'400':
description: |-
Returned if;
- Group Id is not valid
content: {}
'403':
description: |-
Returned if the calling user does not have permission to update the
content.
content: {}
'404':
description: |-
Returned if;
- There is no content with the given ID.
- The calling user does not have permission to view the content.
- An invalid operation or group id is specified.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-content
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-content
- scheme: oAuthDefinitions
state: Beta
scopes:
- write:content.restriction:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: WRITE
delete:
tags:
- Content Restrictions
summary: Atlassian Remove Group From Content Restriction
description: >-
Removes a group from a content restriction. That is, remove read or
update
permission for the group for a piece of
content.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to edit the content.
operationId: atlassianRemovegroupfromcontentrestriction
parameters:
- name: id
in: path
description: The ID of the content that the restriction applies to.
required: true
schema:
type: string
- name: operationKey
in: path
description: The operation that the restriction applies to.
required: true
schema:
type: string
enum:
- read
- update
- name: groupId
in: path
description: The id of the group to remove from the content restriction.
required: true
schema:
type: string
responses:
'200':
description: >-
Returned if the group is removed from the content restriction. The
response
body will be empty.
content: {}
'400':
description: Returned if given group id is blank
content: {}
'403':
description: >-
Returned if the calling user does not have permission to view the
content.
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 restriction to be deleted does not exist.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-content
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-content
- scheme: oAuthDefinitions
state: Beta
scopes:
- write:content.restriction:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: WRITE
/wiki/rest/api/content/{id}/restriction/byOperation/{operationKey}/user:
get:
tags:
- Content Restrictions
summary: Atlassian Get Content Restriction Status For User
description: >-
Returns whether the specified content restriction applies to a
user.
For example, if a page with `id=123` has a `read` restriction
for a user with an account ID
of
`384093:32b4d9w0-f6a5-3535-11a3-9c8c88d10192`, the following
request will return
`true`:
`/wiki/rest/api/content/123/restriction/byOperation/read/user?accountId=384093:32b4d9w0-f6a5-3535-11a3-9c8c88d10192`
Note
that a response of `true` does not guarantee that the user can view the
page, as it does not account for
account-inherited restrictions,
space permissions, or even product access. For more
information, see
[Confluence
permissions](https://confluence.atlassian.com/x/_AozKw).
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to view the content.
operationId: atlassianGetcontentrestrictionstatusforuser
parameters:
- name: id
in: path
description: The ID of the content that the restriction applies to.
required: true
schema:
type: string
- name: operationKey
in: path
description: The operation that is restricted.
required: true
schema:
type: string
- $ref: '#/components/parameters/userLookupKey'
- $ref: '#/components/parameters/userLookupUsername'
- $ref: '#/components/parameters/userLookupAccountId'
responses:
'200':
description: >-
Return true if the content restriction applies to the user. The
response
body will be empty.
content: {}
'404':
description: |-
Returned if;
- There is no content with the given ID.
- The calling user does not have permission to view the content.
- An invalid operation or user is specified.
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.restriction:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: READ
put:
tags:
- Content Restrictions
summary: Atlassian Add User To Content Restriction
description: >-
Adds a user to a content restriction. That is, grant read or
update
permission to the user for a piece of
content.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to edit the content.
operationId: atlassianAddusertocontentrestriction
parameters:
- name: id
in: path
description: The ID of the content that the restriction applies to.
required: true
schema:
type: string
- name: operationKey
in: path
description: The operation that the restriction applies to.
required: true
schema:
type: string
- $ref: '#/components/parameters/userLookupKey'
- $ref: '#/components/parameters/userLookupUsername'
- $ref: '#/components/parameters/userLookupAccountId'
responses:
'200':
description: >-
Returned if the user is added to the content restriction. The
response
body will be empty.
content: {}
'400':
description: |-
Returned if;
- Provided restrictions are invalid
content: {}
'404':
description: |-
Returned if;
- There is no content with the given ID.
- The calling user does not have permission to view the content.
- An invalid operation or group is specified.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-content
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-content
- scheme: oAuthDefinitions
state: Beta
scopes:
- write:content.restriction:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: WRITE
delete:
tags:
- Content Restrictions
summary: Atlassian Remove User From Content Restriction
description: >-
Removes a group from a content restriction. That is, remove read or
update
permission for the group for a piece of
content.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to edit the content.
operationId: atlassianRemoveuserfromcontentrestriction
parameters:
- name: id
in: path
description: The ID of the content that the restriction applies to.
required: true
schema:
type: string
- name: operationKey
in: path
description: The operation that the restriction applies to.
required: true
schema:
type: string
enum:
- read
- update
- $ref: '#/components/parameters/userLookupKey'
- $ref: '#/components/parameters/userLookupUsername'
- $ref: '#/components/parameters/userLookupAccountId'
responses:
'200':
description: >-
Returned if the user is removed from the content restriction. The
response
body will be empty.
content: {}
'404':
description: |-
Returned if;
- There is no content with the given ID.
- The calling user does not have permission to view the content.
- An invalid operation or group is specified.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-content
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-content
- scheme: oAuthDefinitions
state: Beta
scopes:
- write:content.restriction:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: WRITE
/wiki/rest/api/content/{id}/state:
get:
tags:
- Content States
summary: Atlassian Get Content State
description: >-
Gets the current content state of the draft or current version of
content. To specify the draft version, set
the parameter status to
draft, otherwise archived or current will get the relevant published
state.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to view the content.
operationId: atlassianGetcontentstate
parameters:
- name: id
in: path
description: The id of the content whose content state is of interest.
required: true
schema:
type: string
- name: status
in: query
description: >-
Set status to one of [current,draft,archived]. Default value is
current.
schema:
type: string
default: current
enum:
- current
- draft
- archived
responses:
'200':
description: Returned if permission allows viewing of content.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentStateResponse'
'401':
description: >-
Returned if the authentication credentials are incorrect or missing
from the request.
'403':
description: Returned if user does not have content view permission.
'404':
description: Returned if the content with given id can not be found.
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 States
summary: >-
Atlassian Set The Content State Of A Content And Publishes A New Version Of The Content
description: >-
Sets the content state of the content specified and creates a new
version
(publishes the content without changing the body) of the
content with the new state.
You may pass in either an id of a
state, or the name and color of a desired new state.
If all 3 are
passed in, id will be used.
If the name and color passed in already
exist under the current user's existing custom states, the existing
state will be reused.
If custom states are disabled in the space of
the content (which can be determined by getting the content state space
settings of the content's space)
then this set will fail.
You
may not remove a content state via this PUT request. You must use the
DELETE method. A specified state is required in the body of this
request.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to edit the content.
operationId: atlassianSetcontentstate
requestBody:
description: >-
Content state fields for state. Pass in id for an existing state, or
new name and color for best matching existing state, or new state if
allowed in space.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentStateRestInput'
required: true
parameters:
- name: id
in: path
description: The Id of the content whose content state is to be set.
required: true
schema:
type: string
- name: status
in: query
description: >-
Status of content onto which state will be placed. If draft, then
draft state will change.
If current, state will be placed onto a new version of the content
with same body as previous version.
schema:
type: string
enum:
- current
- draft
responses:
'200':
description: Returned if content state is set successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentStateResponse'
'400':
description: >-
Invalid Name/Color, non-existent id of content state, or type of
state desired is not allowed.
Name must be less than or exactly 20 characters. Color must be a
valid hex string.
Status must be in [draft,current].
'401':
description: >-
Returned if the authentication credentials are incorrect or missing
from the request.
'403':
description: Returned if user does not have content edit permission.
'404':
description: Returned if the content with given id can not be found.
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-content
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-content
- scheme: oAuthDefinitions
state: Beta
scopes:
- write:content:confluence
- read:content-details:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: WRITE
delete:
tags:
- Content States
summary: 'Atlassian Removes The Content State Of A Content And Publishes A New Version'
description: >-
Removes the content state of the content specified and creates a new
version
(publishes the content without changing the body) of the
content with the new
status.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to edit the content.
operationId: atlassianRemovecontentstate
parameters:
- name: id
in: path
description: The Id of the content whose content state is to be set.
required: true
schema:
type: string
- name: status
in: query
description: >-
status of content state from which to delete state. Can be draft or
archived
schema:
type: string
enum:
- current
- draft
responses:
'200':
description: Returned if content state is removed from content.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentStateResponse'
'401':
description: >-
Returned if the authentication credentials are incorrect or missing
from the request.
'403':
description: Returned if user does not have content edit permission.
'404':
description: Returned if the content with given id can not be found.
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-content
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-content
- scheme: oAuthDefinitions
state: Beta
scopes:
- write:content:confluence
- read:content-details:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: WRITE
/wiki/rest/api/content/{id}/state/available:
get:
tags:
- Content States
summary: 'Atlassian Gets Available Content States For Content'
description: >-
Gets content states that are available for the content to be set
as.
Will return all enabled Space Content States.
Will only return
most the 3 most recently published custom content states to match UI
editor list.
To get all custom content states, use the
/content-states
endpoint.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to edit the content.
operationId: atlassianGetavailablecontentstates
parameters:
- name: id
in: path
description: id of content to get available states for
required: true
schema:
type: string
responses:
'200':
description: Returned if the content is found and permission is valid.
content:
application/json:
schema:
$ref: '#/components/schemas/AvailableContentStates'
'400':
description: Invalid status for content. Must be in [current,draft,archived].
'401':
description: >-
Returned if the authentication credentials are incorrect or missing
from the request.
'403':
description: Returned if user does not have content edit permission.
'404':
description: Returned if the content with given id can not be found.
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-content
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-content
- scheme: oAuthDefinitions
state: Beta
scopes:
- write:content:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: READ
/wiki/rest/api/content/{id}/version:
get:
tags:
- Content Versions
summary: Atlassian Get Content Versions
deprecated: true
description: >-
Deprecated, use [Confluence's v2
API](https://developer.atlassian.com/cloud/confluence/rest/v2/intro/).
Returns
the versions for a piece of content in descending
order.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to view the content. If the content is a blog
post, 'View' permission
for the space is required.
operationId: atlassianGetcontentversions
parameters:
- name: id
in: path
description: The ID of the content to be queried for its versions.
required: true
schema:
type: string
- name: start
in: query
description: The starting index of the returned versions.
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: limit
in: query
description: |-
The maximum number of versions to return per page.
Note, this may be restricted by fixed system limits.
schema:
minimum: 0
type: integer
format: int32
default: 200
- name: expand
in: query
description: >-
A multi-value parameter indicating which properties of the content
to expand. By default, the `content`
object is expanded.
- `collaborators` returns the users that collaborated on the
version.
- `content` returns the content for the version.
style: form
explode: false
schema:
type: array
items:
type: string
responses:
'200':
description: Returned if the requested versions are returned.
content:
application/json:
schema:
$ref: '#/components/schemas/VersionArray'
'403':
description: |-
Returned if 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
post:
tags:
- Content Versions
summary: Atlassian Restore Content Version
description: >-
Restores a historical version to be the latest version. That is, a new
version
is created with the content of the historical
version.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to update the content.
operationId: atlassianRestorecontentversion
parameters:
- name: id
in: path
description: The ID of the content for which the history will be restored.
required: true
schema:
type: string
- name: expand
in: query
description: >-
A multi-value parameter indicating which properties of the content
to expand. By default, the `content`
object is expanded.
- `collaborators` returns the users that collaborated on the
version.
- `content` returns the content for the version.
style: form
explode: false
schema:
type: array
items:
type: string
requestBody:
description: The content version to be restored.
content:
application/json:
schema:
$ref: '#/components/schemas/VersionRestore'
required: true
responses:
'200':
description: Returned if the version is restored.
content:
application/json:
schema:
$ref: '#/components/schemas/Version'
'400':
description: |-
Returned if;
- There is no content with the given ID.
- There is no version with the given version number.
- The version number is the current version.
content: {}
'403':
description: |-
Returned if the calling user doesn't have permission to edit 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:
- 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/{id}/version/{versionNumber}:
get:
tags:
- Content Versions
summary: Atlassian Get Content Version
deprecated: true
description: >-
Deprecated, use [Confluence's v2
API](https://developer.atlassian.com/cloud/confluence/rest/v2/intro/).
Returns
a version for a piece of
content.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to view the content. If the content is a blog
post, 'View' permission
for the space is required.
operationId: atlassianGetcontentversion
parameters:
- name: id
in: path
description: The ID of the content to be queried for its version.
required: true
schema:
type: string
- name: versionNumber
in: path
description: The number of the version to be retrieved.
required: true
schema:
type: integer
format: int32
- name: expand
in: query
description: >-
A multi-value parameter indicating which properties of the content
to expand. By default, the `content`
object is expanded.
- `collaborators` returns the users that collaborated on the
version.
- `content` returns the content for the version.
style: form
explode: false
schema:
type: array
items:
type: string
responses:
'200':
description: Returned if the version is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/Version'
'403':
description: |-
Returned if the calling user does not have permission to view the
content.
content: {}
'404':
description: Returned if the content or version cannot be found.
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
delete:
tags:
- Content Versions
summary: Atlassian Delete Content Version
description: >-
Delete a historical version. This does not delete the changes made to
the
content in that version, rather the changes for the deleted
version are
rolled up into the next version. Note, you cannot delete
the current
version.
**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:
Permission to update the content.
operationId: atlassianDeletecontentversion
parameters:
- name: id
in: path
description: The ID of the content that the version will be deleted from.
required: true
schema:
type: string
- name: versionNumber
in: path
description: |-
The number of the version to be deleted. The version number starts
from 1 up to current version.
required: true
schema:
type: integer
format: int32
responses:
'204':
description: Returned if the version is deleted.
content: {}
'400':
description: |-
Returned if;
- The content or version cannot be found.
- The current version is specified.
content: {}
'403':
description: |-
Returned if the calling user doesn't have permission to edit 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
components:
schemas:
Content:
required:
- status
- type
nullable: true
type: object
additionalProperties: true
properties:
id:
type: string
type:
type: string
description: Can be "page", "blogpost", "attachment" or "content"
status:
type: string
title:
type: string
space:
$ref: '#/components/schemas/Space'
history:
$ref: '#/components/schemas/ContentHistory'
version:
$ref: '#/components/schemas/Version'
ancestors:
nullable: true
type: array
items:
$ref: '#/components/schemas/Content'
operations:
type: array
items:
$ref: '#/components/schemas/OperationCheckResult'
children:
$ref: '#/components/schemas/ContentChildren'
childTypes:
$ref: '#/components/schemas/ContentChildType'
descendants:
$ref: '#/components/schemas/ContentChildren'
container:
$ref: '#/components/schemas/Container'
body:
type: object
properties:
view:
$ref: '#/components/schemas/ContentBody'
export_view:
$ref: '#/components/schemas/ContentBody'
styled_view:
$ref: '#/components/schemas/ContentBody'
storage:
$ref: '#/components/schemas/ContentBody'
wiki:
$ref: '#/components/schemas/ContentBody'
editor:
$ref: '#/components/schemas/ContentBody'
editor2:
$ref: '#/components/schemas/ContentBody'
anonymous_export_view:
$ref: '#/components/schemas/ContentBody'
atlas_doc_format:
$ref: '#/components/schemas/ContentBody'
dynamic:
$ref: '#/components/schemas/ContentBody'
raw:
$ref: '#/components/schemas/ContentBody'
_expandable:
type: object
properties:
editor:
type: string
view:
type: string
export_view:
type: string
styled_view:
type: string
storage:
type: string
editor2:
type: string
anonymous_export_view:
type: string
atlas_doc_format:
type: string
wiki:
type: string
dynamic:
type: string
raw:
type: string
restrictions:
type: object
properties:
read:
$ref: '#/components/schemas/ContentRestriction'
update:
$ref: '#/components/schemas/ContentRestriction'
_expandable:
type: object
properties:
read:
type: string
update:
type: string
_links:
$ref: '#/components/schemas/GenericLinks'
metadata:
$ref: '#/components/schemas/ContentMetadata'
macroRenderedOutput:
type: object
additionalProperties:
type: object
extensions:
type: object
_expandable:
type: object
properties:
childTypes:
type: string
container:
type: string
metadata:
type: string
operations:
type: string
children:
type: string
restrictions:
type: string
history:
type: string
ancestors:
type: string
body:
type: string
version:
type: string
descendants:
type: string
space:
type: string
extensions:
type: string
schedulePublishDate:
type: string
schedulePublishInfo:
type: string
macroRenderedOutput:
type: string
_links:
$ref: '#/components/schemas/GenericLinks'
description: Base object for all content types.
ContentArray:
required:
- _links
- results
- size
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Content'
start:
type: integer
format: int32
limit:
type: integer
format: int32
size:
type: integer
format: int32
_links:
$ref: '#/components/schemas/GenericLinks'
ContentChildren:
type: object
additionalProperties: true
properties:
attachment:
$ref: '#/components/schemas/ContentArray'
comment:
$ref: '#/components/schemas/ContentArray'
page:
$ref: '#/components/schemas/ContentArray'
_expandable:
type: object
additionalProperties: true
properties:
attachment:
type: string
comment:
type: string
page:
type: string
_links:
$ref: '#/components/schemas/GenericLinks'
ContentHistory:
required:
- latest
type: object
nullable: true
properties:
latest:
type: boolean
createdBy:
$ref: '#/components/schemas/User'
ownedBy:
$ref: '#/components/schemas/User'
lastOwnedBy:
$ref: '#/components/schemas/User'
createdDate:
type: string
format: date-time
lastUpdated:
$ref: '#/components/schemas/Version'
previousVersion:
$ref: '#/components/schemas/Version'
contributors:
type: object
properties:
publishers:
$ref: '#/components/schemas/UsersUserKeys'
nextVersion:
$ref: '#/components/schemas/Version'
_expandable:
type: object
properties:
lastUpdated:
type: string
previousVersion:
type: string
contributors:
type: string
nextVersion:
type: string
ownedBy:
type: string
lastOwnedBy:
type: string
_links:
$ref: '#/components/schemas/GenericLinks'
MacroInstance:
type: object
properties:
name:
type: string
body:
type: string
parameters:
type: object
_links:
$ref: '#/components/schemas/GenericLinks'
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
LabelArray:
required:
- results
- size
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Label'
start:
type: integer
format: int32
limit:
type: integer
format: int32
size:
type: integer
format: int32
_links:
$ref: '#/components/schemas/GenericLinks'
WatchArray:
required:
- _links
- limit
- results
- size
- start
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Watch'
start:
type: integer
format: int32
limit:
type: integer
format: int32
size:
type: integer
format: int32
_links:
$ref: '#/components/schemas/GenericLinks'
SpaceWatchArray:
required:
- limit
- results
- size
- start
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/SpaceWatch'
start:
type: integer
format: int32
limit:
type: integer
format: int32
size:
type: integer
format: int32
_links:
$ref: '#/components/schemas/GenericLinks'
PermissionCheckResponse:
required:
- hasPermission
type: object
properties:
hasPermission:
type: boolean
errors:
type: array
items:
$ref: '#/components/schemas/Message'
_links:
$ref: '#/components/schemas/GenericLinks'
description: >-
This object represents the response for the content permission check
API. If the user or group does not have
permissions, the following errors may be returned:
- Group does not have permission to the space
- Group does not have permission to the content
- User is not allowed to use Confluence
- User does not have permission to the space
- User does not have permission to the content
- Anonymous users are not allowed to use Confluence
- Anonymous user does not have permission to the space
- Anonymous user does not have permission to the content
ContentPropertyArray:
required:
- _links
- limit
- results
- size
- start
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/ContentProperty'
start:
type: integer
format: int32
limit:
type: integer
format: int32
size:
type: integer
format: int32
_links:
$ref: '#/components/schemas/GenericLinks'
ContentProperty:
required:
- _links
- id
- key
- value
type: object
additionalProperties: true
properties:
id:
type: string
key:
type: string
value:
oneOf:
- type: array
items:
type: string
- type: boolean
- type: object
additionalProperties: true
properties: {}
- type: string
description: >-
The value of the content property. This can be empty or a complex
object.
version:
required:
- message
- minorEdit
- number
- when
type: object
additionalProperties: true
properties:
when:
type: string
format: date-time
message:
type: string
number:
type: integer
format: int32
minorEdit:
type: boolean
contentTypeModified:
type: boolean
description: >-
True if content type is modifed in this version (e.g. page to
blog)
_links:
$ref: '#/components/schemas/GenericLinks'
_expandable:
type: object
properties:
content:
type: string
additionalProperties:
type: string
ContentRestrictionArray:
required:
- _links
- limit
- restrictionsHash
- results
- size
- start
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/ContentRestriction'
start:
type: integer
format: int32
limit:
type: integer
format: int32
size:
type: integer
format: int32
restrictionsHash:
type: string
description: >-
This property is used by the UI to figure out whether a set of
restrictions
has changed.
_links:
$ref: '#/components/schemas/GenericLinks'
ContentRestriction:
required:
- _expandable
- _links
- operation
type: object
properties:
operation:
type: string
enum:
- administer
- copy
- create
- delete
- export
- move
- purge
- purge_version
- read
- restore
- update
- use
restrictions:
type: object
properties:
user:
$ref: '#/components/schemas/UserArray'
group:
$ref: '#/components/schemas/GroupArray'
_expandable:
type: object
properties:
user:
type: string
group:
type: string
content:
$ref: '#/components/schemas/Content'
_expandable:
type: object
properties:
restrictions:
type: string
content:
type: string
_links:
$ref: '#/components/schemas/GenericLinks'
ContentStateResponse:
type: object
properties:
contentState:
$ref: '#/components/schemas/ContentState'
description: Null or content state
lastUpdated:
type: string
description: Timestamp of last publish event where content state changed
AvailableContentStates:
required:
- spaceContentStates
- customContentStates
type: object
properties:
spaceContentStates:
type: array
items:
type: object
$ref: '#/components/schemas/ContentState'
description: >-
Space suggested content states that can be used in the space. This
can be null if space content states are disabled in the space.
This list can be empty if there are no space content states defined
in the space.
All spaces start with 3 default space content states, and this can
be modified in the UI under space settings.
customContentStates:
type: array
items:
type: object
$ref: '#/components/schemas/ContentState'
description: >-
Custom content states that can be used by the user on the content of
this call.
This can be null if custom content states are disabled in the space
of the content.
This list can be empty if there are no custom content states defined
by the user.
This will at most have 3 of the most recently published content
states.
Only the calling user has access to place these states on content,
but all users can see these states once they are placed.
VersionArray:
required:
- _links
- limit
- results
- size
- start
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Version'
start:
type: integer
format: int32
limit:
type: integer
format: int32
size:
type: integer
format: int32
_links:
$ref: '#/components/schemas/GenericLinks'
Version:
required:
- minorEdit
- number
- when
type: object
nullable: true
additionalProperties: true
properties:
by:
$ref: '#/components/schemas/User'
when:
type: string
format: date-time
nullable: true
friendlyWhen:
type: string
nullable: true
message:
type: string
nullable: true
number:
type: integer
format: int32
description: Set this to the current version number incremented by one
minorEdit:
description: |-
If `minorEdit` is set to 'true', no notification email or activity
stream will be generated for the change.
type: boolean
content:
$ref: '#/components/schemas/Content'
collaborators:
$ref: '#/components/schemas/UsersUserKeys'
_expandable:
type: object
properties:
content:
type: string
collaborators:
type: string
_links:
$ref: '#/components/schemas/GenericLinks'
contentTypeModified:
type: boolean
description: True if content type is modifed in this version (e.g. page to blog)
confRev:
type: string
nullable: true
description: >-
The revision id provided by confluence to be used as a revision in
Synchrony
syncRev:
type: string
nullable: true
description: The revision id provided by Synchrony
syncRevSource:
type: string
nullable: true
description: Source of the synchrony revision
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/).