The Confluence Cloud REST API

Content - children and descendants

Get content children

GET /wiki/rest/api/content/{id}/child

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 required: 'View' permission for the space, and permission to view the content if it is a page.

Connect app scope required: READ

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:confluence-content.summary

Granular:read:content-details:confluence

Request

Path parameters

id Required

string

The ID of the content to be queried for its children.

Query parameters

expand

Array<string>

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

parentVersion

integer

The version of the parent content to retrieve children for. Currently, this only works for the latest version.

Default: 0, Format: int32

Example

Forge

cURL

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asApp().requestConfluence(route`/wiki/rest/api/content/{id}/child`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

Responses

200

404

Returned if the requested content children are returned.

Content type	Value
application/json	ContentChildren

Move a page to a new location relative to a target page

PUT /wiki/rest/api/content/{pageId}/move/{position}/{targetId}

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.

Connect app scope required: WRITE

OAuth 2.0 scopes required:

ClassicRECOMMENDED:write:confluence-content

Granular:write:page:confluence

Request

Path parameters

pageId Required

string

The ID of the page to be moved

position Required

string

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

Valid values: before, after, append

targetId Required

string

The ID of the target page for this operation

Example

Forge

cURL

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asApp().requestConfluence(route`/wiki/rest/api/content/{pageId}/move/{position}/{targetId}`, {
  method: 'PUT',
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

Responses

200

400

403

404

Page was successfully moved

Content type	Value
application/json	object

Get content children by type

GET /wiki/rest/api/content/{id}/child/{type}

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.

Permissions required: 'View' permission for the space, and permission to view the content if it is a page.

Connect app scope required: READ

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:confluence-content.summary

Granular:read:content-details:confluence

Request

Path parameters

id Required

string

The ID of the content to be queried for its children.

type Required

string

The type of children to return.

Query parameters

expand

Array<string>

A multi-value parameter indicating which properties of the content to expand.

childTypes.all returns whether the content has attachments, comments, or child pages. Use this if you only need to check whether the content has children of a particular type.
childTypes.attachment returns whether the content has attachments.
childTypes.comment returns whether the content has comments.
childTypes.page returns whether the content has child pages.
container returns the space that the content is in. This is the same as the information returned by Get space.
metadata.currentuser returns information about the current user in relation to the content, including when they last viewed it, modified it, contributed to it, or added it as a favorite.
metadata.properties returns content properties that have been set via the Confluence REST API.
metadata.labels returns the labels that have been added to the content.
metadata.frontend this property is only used by Atlassian.
operations returns the operations for the content, which are used when setting permissions.
children.page returns pages that are descendants at the level immediately below the content.
children.attachment returns all attachments for the content.
children.comment returns all comments on the content.
restrictions.read.restrictions.user returns the users that have permission to read the content.
restrictions.read.restrictions.group returns the groups that have permission to read the content. Note that this may return deleted groups, because deleting a group doesn't remove associated restrictions.
restrictions.update.restrictions.user returns the users that have permission to update the content.
restrictions.update.restrictions.group returns the groups that have permission to update the content. Note that this may return deleted groups because deleting a group doesn't remove associated restrictions.
history returns the history of the content, including the date it was created.
history.lastUpdated returns information about the most recent update of the content, including who updated it and when it was updated.
history.previousVersion returns information about the update prior to the current content update.
history.contributors returns all of the users who have contributed to the content.
history.nextVersion returns information about the update after to the current content update.
ancestors returns the parent page, if the content is a page.
body returns the body of the content in different formats, including the editor format, view format, and export format.
body.storage returns the body of content in storage format.
body.view returns the body of content in view format.
version returns information about the most recent update of the content, including who updated it and when it was updated.
descendants.page returns pages that are descendants at any level below the content.
descendants.attachment returns all attachments for the content, same as children.attachment.
descendants.comment returns all comments on the content, same as children.comment.
space returns the space that the content is in. This is the same as the information returned by Get space.

In addition, the following comment-specific expansions can be used:

extensions.inlineProperties returns inline comment-specific properties.
extensions.resolution returns the resolution status of each comment.

Style: form

parentVersion

integer

The version of the parent content to retrieve children for. Currently, this only works for the latest version.

Default: 0, Minimum: 0, Format: int32

start

integer

The starting index of the returned content.

Format: int32

limit

integer

The maximum number of content to return per page. Note, this may be restricted by fixed system limits.

Default: 25, Minimum: 0, Format: int32

Example

Forge

cURL

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asApp().requestConfluence(route`/wiki/rest/api/content/{id}/child/{type}`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

Responses

200

400

404

Returned if the requested content is returned.

Content type	Value
application/json	ContentArray

Get content descendants

GET /wiki/rest/api/content/{id}/descendant

Returns a map of the descendants of a piece of content. This is similar to Get content children, 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 required: 'View' permission for the space, and permission to view the content if it is a page.

Connect app scope required: READ

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:confluence-content.summary

Granular:read:content-details:confluence

Request

Path parameters

id Required

string

The ID of the content to be queried for its descendants.

Query parameters

expand

Array<string>

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

Valid values: attachment, comment, page

Example

Forge

cURL

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asApp().requestConfluence(route`/wiki/rest/api/content/{id}/descendant`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

Responses

200

404

Returned if the requested descendants are returned.

Content type	Value
application/json	ContentChildren

Get content descendants by type

GET /wiki/rest/api/content/{id}/descendant/{type}

Returns all descendants of a given type, for a piece of content. This is similar to Get content children by type, 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 required: 'View' permission for the space, and permission to view the content if it is a page.

Connect app scope required: READ

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:confluence-content.summary

Granular:read:content-details:confluence

Request

Path parameters

id Required

string

The ID of the content to be queried for its descendants.

type Required

string

The type of descendants to return.

Valid values: page, comment, attachment

Query parameters

depth

string

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.

Default: all

Valid values: all, root, <any positive integer argument in the range of 1 and 100>

expand

Array<string>

A multi-value parameter indicating which properties of the content to expand.

childTypes.all returns whether the content has attachments, comments, or child pages. Use this if you only need to check whether the content has children of a particular type.
childTypes.attachment returns whether the content has attachments.
childTypes.comment returns whether the content has comments.
childTypes.page returns whether the content has child pages.
container returns the space that the content is in. This is the same as the information returned by Get space.
metadata.currentuser returns information about the current user in relation to the content, including when they last viewed it, modified it, contributed to it, or added it as a favorite.
metadata.properties returns content properties that have been set via the Confluence REST API.
metadata.labels returns the labels that have been added to the content.
metadata.frontend this property is only used by Atlassian.
operations returns the operations for the content, which are used when setting permissions.
children.page returns pages that are descendants at the level immediately below the content.
children.attachment returns all attachments for the content.
children.comment returns all comments on the content.
restrictions.read.restrictions.user returns the users that have permission to read the content.
restrictions.read.restrictions.group returns the groups that have permission to read the content. Note that this may return deleted groups, because deleting a group doesn't remove associated restrictions.
restrictions.update.restrictions.user returns the users that have permission to update the content.
restrictions.update.restrictions.group returns the groups that have permission to update the content. Note that this may return deleted groups because deleting a group doesn't remove associated restrictions.
history returns the history of the content, including the date it was created.
history.lastUpdated returns information about the most recent update of the content, including who updated it and when it was updated.
history.previousVersion returns information about the update prior to the current content update.
history.contributors returns all of the users who have contributed to the content.
history.nextVersion returns information about the update after to the current content update.
ancestors returns the parent page, if the content is a page.
body returns the body of the content in different formats, including the editor format, view format, and export format.
body.storage returns the body of content in storage format.
body.view returns the body of content in view format.
version returns information about the most recent update of the content, including who updated it and when it was updated.
descendants.page returns pages that are descendants at any level below the content.
descendants.attachment returns all attachments for the content, same as children.attachment.
descendants.comment returns all comments on the content, same as children.comment.
space returns the space that the content is in. This is the same as the information returned by Get space.

In addition, the following comment-specific expansions can be used:

extensions.inlineProperties returns inline comment-specific properties.
extensions.resolution returns the resolution status of each comment.

Style: form

start

integer

The starting index of the returned content.

Default: 0, Minimum: 0, Format: int32

limit

integer

The maximum number of content to return per page. Note, this may be restricted by fixed system limits.

Default: 25, Minimum: 0, Format: int32

Example

Forge

cURL

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asApp().requestConfluence(route`/wiki/rest/api/content/{id}/descendant/{type}`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

Responses

200

400

404

Returned if the requested content is returned.

Content type	Value
application/json	ContentArray

Copy page hierarchy

POST /wiki/rest/api/content/{id}/pagehierarchy/copy

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:

1
2

 {
      "id" : "1180606",
      "links" : {
           "status" : "/rest/api/longtask/1180606"
      }
 }

Use the /longtask/ REST API to get the copy task status.

Connect app scope required: WRITE

OAuth 2.0 scopes required:

ClassicRECOMMENDED:write:confluence-content

Granular:read:content.metadata:confluence, write:page:confluence

Request

Path parameters

id Required

string

Body parameters

copyAttachments

boolean

If set to true, attachments are copied to the destination page.

Default: false

copyPermissions

boolean

If set to true, page permissions are copied to the destination page.

Default: false

copyProperties

boolean

If set to true, content properties are copied to the destination page.

Default: false

copyLabels

boolean

If set to true, labels are copied to the destination page.

Default: false

copyCustomContents

boolean

If set to true, custom contents are copied to the destination page.

Default: false

copyDescendants

boolean

If set to true, descendants are copied to the destination page.

Default: true

destinationPageId Required

string

titleOptions

CopyPageHierarchyTitleOptions

Required for copying page in the same space.

Example

Forge

cURL

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

var bodyData = `{
  "copyAttachments": true,
  "copyPermissions": true,
  "copyProperties": true,
  "copyLabels": true,
  "copyCustomContents": true,
  "copyDescendants": true,
  "destinationPageId": "<string>",
  "titleOptions": {
    "prefix": "<string>",
    "replace": "<string>",
    "search": "<string>"
  }
}`;

const response = await api.asApp().requestConfluence(route`/wiki/rest/api/content/{id}/pagehierarchy/copy`, {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: bodyData
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

Responses

202

400

403

404

Returns a full JSON representation of a long running task

Content type	Value
application/json	LongTask

Copy single page

POST /wiki/rest/api/content/{id}/copy

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 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.

Connect app scope required: WRITE

OAuth 2.0 scopes required:

ClassicRECOMMENDED:write:confluence-content

Granular:read:content-details:confluence, write:page:confluence

Request

Path parameters

id Required

string

Query parameters

expand

Array<string>

A multi-value parameter indicating which properties of the content to expand. Maximum sub-expansions allowed is 8.

childTypes.all returns whether the content has attachments, comments, or child pages. Use this if you only need to check whether the content has children of a particular type.
childTypes.attachment returns whether the content has attachments.
childTypes.comment returns whether the content has comments.
childTypes.page returns whether the content has child pages.
container returns the space that the content is in. This is the same as the information returned by Get space.
metadata.currentuser returns information about the current user in relation to the content, including when they last viewed it, modified it, contributed to it, or added it as a favorite.
metadata.properties returns content properties that have been set via the Confluence REST API.
metadata.labels returns the labels that have been added to the content.
metadata.frontend this property is only used by Atlassian.
operations returns the operations for the content, which are used when setting permissions.
children.page returns pages that are descendants at the level immediately below the content.
children.attachment returns all attachments for the content.
children.comment returns all comments on the content.
restrictions.read.restrictions.user returns the users that have permission to read the content.
restrictions.read.restrictions.group returns the groups that have permission to read the content. Note that this may return deleted groups, because deleting a group doesn't remove associated restrictions.
restrictions.update.restrictions.user returns the users that have permission to update the content.
restrictions.update.restrictions.group returns the groups that have permission to update the content. Note that this may return deleted groups because deleting a group doesn't remove associated restrictions.
history returns the history of the content, including the date it was created.
history.lastUpdated returns information about the most recent update of the content, including who updated it and when it was updated.
history.previousVersion returns information about the update prior to the current content update.
history.contributors returns all of the users who have contributed to the content.
history.nextVersion returns information about the update after to the current content update.
ancestors returns the parent page, if the content is a page.
body returns the body of the content in different formats, including the editor format, view format, and export format.
body.storage returns the body of content in storage format.
body.view returns the body of content in view format.
version returns information about the most recent update of the content, including who updated it and when it was updated.
descendants.page returns pages that are descendants at any level below the content.
descendants.attachment returns all attachments for the content, same as children.attachment.
descendants.comment returns all comments on the content, same as children.comment.
space returns the space that the content is in. This is the same as the information returned by Get space.

In addition, the following comment-specific expansions can be used:

extensions.inlineProperties returns inline comment-specific properties.
extensions.resolution returns the resolution status of each comment.

Style: form

Body parameters

copyAttachments

boolean

If set to true, attachments are copied to the destination page.

Default: false

copyPermissions

boolean

If set to true, page permissions are copied to the destination page.

Default: false

copyProperties

boolean

If set to true, content properties are copied to the destination page.

Default: false

copyLabels

boolean

If set to true, labels are copied to the destination page.

Default: false

copyCustomContents

boolean

If set to true, custom contents are copied to the destination page.

Default: false

destination Required

CopyPageRequestDestination

Defines where the page will be copied to, and can be one of the following types.

parent_page: page will be copied as a child of the specified parent page
space: page will be copied to the specified space as a root page on the space
existing_page: page will be copied and replace the specified page

pageTitle

string

If defined, this will replace the title of the destination page.

body

object

If defined, this will replace the body of the destination page.

Example

Forge

cURL

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

var bodyData = `{
  "copyAttachments": true,
  "copyPermissions": true,
  "copyProperties": true,
  "copyLabels": true,
  "copyCustomContents": true,
  "destination": {
    "type": "space",
    "value": "<string>"
  },
  "pageTitle": "<string>",
  "body": {
    "storage": {
      "value": "<string>",
      "representation": "view"
    },
    "editor2": {
      "value": "<string>",
      "representation": "view"
    }
  }
}`;

const response = await api.asApp().requestConfluence(route`/wiki/rest/api/content/{id}/copy`, {
  method: 'POST',
  headers: {
    'Accept': 'application/json;charset=UTF-8',
    'Content-Type': 'application/json'
  },
  body: bodyData
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.text());

Responses

200

400

401

403

404

Returned if the content is copied.

Content type	Value
application/json;charset=UTF-8	Content