The Confluence Cloud REST API

Space

Get spaces

GET /wiki/rest/api/space

Returns all spaces. The returned spaces are ordered alphabetically in ascending order by space key.

Permissions required: Permission to access the Confluence site ('Can use' global permission). Note, the returned list will only contain spaces that the current user has permission to view.

Connect app scope required: READ

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:confluence-space.summary

Granular:read:content-details:confluence

Request

Query parameters

spaceKey

Array<string>

The key of the space to be returned. To return multiple spaces, specify this parameter multiple times with different values.

Style: form

spaceId

Array<integer>

The id of the space to be returned. To return multiple spaces, specify this parameter multiple times with different values.

Style: form

type

string

Filter the results to spaces based on their type.

Valid values: global, personal

status

string

Filter the results to spaces based on their status.

Valid values: current, archived

label

Array<string>

Filter the results to spaces based on their label.

Style: form

favourite

boolean

Filter the results to the favourite spaces of the user specified by favouriteUserKey. Note, 'favourite' spaces are also known as 'saved for later' spaces.

favouriteUserKey

string

The userKey of the user, whose favourite spaces are used to filter the results when using the favourite parameter.

Leave blank for the current user. Use Get user to get the userKey for a user.

expand

Array<string>

A multi-value parameter indicating which properties of the spaces to expand, where:

settings returns the settings for the space, similar to Get space settings.
metadata returns the space metadata.
metadata.labels returns the space labels, which are used to categorize the space.
operations returns the operations for a space, which are used when setting permissions.
lookAndFeel returns information about the look and feel of the space, including the color scheme.
permissions returns the permissions for the space. Note that this may return permissions for deleted groups, because deleting a group doesn't remove associated space permissions.
icon returns information about space icon.
description returns the description of the space.
description.plain returns the description of the space, the plain format.
description.view returns the description of the space, the view format.
theme returns information about the space theme.
homepage returns information about the space homepage.
history returns information about the history of the space.

Style: form

Valid values: settings, metadata, metadata.labels, operations, lookAndFeel, permissions, icon, description, description.plain, description.view ...(Show more)

start

integer

The starting index of the returned spaces.

Default: 0, Minimum: 0, Format: int32

limit

integer

The maximum number of spaces 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/space`, {
  headers: {
    'Accept': 'application/json'
  }
});

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

Responses

200

400

401

Returned if the requested spaces are returned.

Content type	Value
application/json	SpaceArray

Create space

POST /wiki/rest/api/space

Creates a new space. Note, currently you cannot set space labels when creating a space.

Permissions required: 'Create Space(s)' global permission.

Connect app scope required: WRITE

OAuth 2.0 scopes required:

ClassicRECOMMENDED:write:confluence-space

Granular:read:space-details:confluence, write:space:confluence, write:space.permission:confluence

Request

Body parameters

This is the request object used when creating a new space.

key Required

string

The key for the new space. Format: See Space keys.

name Required

string

The name of the new space.

Max length: 200

description

SpaceDescriptionCreate

The description of the new/updated space. Note, only the 'plain' representation can be used for the description when creating or updating a space.

Nullable: true

permissions

Array<SpacePermissionCreate>

The permissions for the new space. If no permissions are provided, the Confluence default space permissions are applied. Note that if permissions are provided, the space is created with only the provided set of permissions, not including the default space permissions. Space permissions can be modified after creation using the space permissions endpoints, and a private space can be created using the create private space endpoint.

Nullable: true

Additional Properties

anything

Extra properties of any type may be provided to this object.

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 = `{
  "key": "<string>",
  "name": "<string>",
  "description": {
    "plain": {
      "value": "<string>",
      "representation": "<string>"
    }
  },
  "permissions": [
    {
      "subjects": {
        "user": {
          "results": [
            {
              "type": "known",
              "username": "<string>",
              "userKey": "<string>",
              "accountId": "<string>",
              "accountType": "atlassian",
              "email": "<string>",
              "publicName": "<string>",
              "profilePicture": {
                "path": "<string>",
                "width": 2154,
                "height": 2154,
                "isDefault": true
              },
              "displayName": "<string>",
              "timeZone": "<string>",
              "isExternalCollaborator": true,
              "externalCollaborator": true,
              "operations": [
                {
                  "operation": "administer",
                  "targetType": "<string>"
                }
              ],
              "details": {},
              "personalSpace": {
                "key": "<string>",
                "name": "<string>",
                "type": "<string>",
                "status": "<string>",
                "_expandable": {},
                "_links": {}
              },
              "_expandable": {
                "operations": "<string>",
                "details": "<string>",
                "personalSpace": "<string>"
              },
              "_links": {}
            }
          ],
          "size": 2154
        },
        "group": {
          "results": [
            {
              "type": "group",
              "name": "<string>"
            }
          ],
          "size": 2154
        }
      },
      "operation": {
        "operation": "administer",
        "targetType": "<string>"
      },
      "anonymousAccess": true,
      "unlicensedAccess": true
    }
  ]
}`;

const response = await api.asApp().requestConfluence(route`/wiki/rest/api/space`, {
  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

200

400

401

403

Returned if the space is created.

Content type	Value
application/json	Space

Create private space

POST /wiki/rest/api/space/_private

Creates a new space that is only visible to the creator. This method is the same as the Create space method with permissions set to the current user only. Note, currently you cannot set space labels when creating a space.

Permissions required: 'Create Space(s)' global permission.

Connect app scope required: WRITE

OAuth 2.0 scopes required:

ClassicRECOMMENDED:write:confluence-space

Granular:read:space-details:confluence, write:space:confluence, write:space.permission:confluence

Request

Body parameters

This is the request object used when creating a new space.

key Required

string

The key for the new space. Format: See Space keys.

name Required

string

The name of the new space.

Max length: 200

description

SpaceDescriptionCreate

The description of the new/updated space. Note, only the 'plain' representation can be used for the description when creating or updating a space.

Nullable: true

permissions

Array<SpacePermissionCreate>

Nullable: true

Additional Properties

anything

Extra properties of any type may be provided to this object.

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 = `{
  "key": "<string>",
  "name": "<string>",
  "description": {
    "plain": {
      "value": "<string>",
      "representation": "<string>"
    }
  },
  "permissions": [
    {
      "subjects": {
        "user": {
          "results": [
            {
              "type": "known",
              "username": "<string>",
              "userKey": "<string>",
              "accountId": "<string>",
              "accountType": "atlassian",
              "email": "<string>",
              "publicName": "<string>",
              "profilePicture": {
                "path": "<string>",
                "width": 2154,
                "height": 2154,
                "isDefault": true
              },
              "displayName": "<string>",
              "timeZone": "<string>",
              "isExternalCollaborator": true,
              "externalCollaborator": true,
              "operations": [
                {
                  "operation": "administer",
                  "targetType": "<string>"
                }
              ],
              "details": {},
              "personalSpace": {
                "key": "<string>",
                "name": "<string>",
                "type": "<string>",
                "status": "<string>",
                "_expandable": {},
                "_links": {}
              },
              "_expandable": {
                "operations": "<string>",
                "details": "<string>",
                "personalSpace": "<string>"
              },
              "_links": {}
            }
          ],
          "size": 2154
        },
        "group": {
          "results": [
            {
              "type": "group",
              "name": "<string>"
            }
          ],
          "size": 2154
        }
      },
      "operation": {
        "operation": "administer",
        "targetType": "<string>"
      },
      "anonymousAccess": true,
      "unlicensedAccess": true
    }
  ]
}`;

const response = await api.asApp().requestConfluence(route`/wiki/rest/api/space/_private`, {
  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

200

400

401

403

Returned if the space is created.

Content type	Value
application/json	Space

Get space

GET /wiki/rest/api/space/{spaceKey}

Returns a space. This includes information like the name, description, and permissions, but not the content in the space.

Permissions required: 'View' permission for the space.

Connect app scope required: READ

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:confluence-space.summary

Granular:read:content-details:confluence

Request

Path parameters

spaceKey Required

string

The key of the space to be returned.

Query parameters

expand

Array<string>

A multi-value parameter indicating which properties of the spaces to expand, where:

settings returns the settings for the space, similar to Get space settings.
metadata returns the space metadata.
metadata.labels returns the space labels, which are used to categorize the space.
operations returns the operations for a space, which are used when setting permissions.
lookAndFeel returns information about the look and feel of the space, including the color scheme.
permissions returns the permissions for the space. Note that this may return permissions for deleted groups, because deleting a group doesn't remove associated space permissions.
icon returns information about space icon.
description returns the description of the space.
description.plain returns the description of the space, the plain format.
description.view returns the description of the space, the view format.
theme returns information about the space theme.
homepage returns information about the space homepage.
history returns information about the history of the space.

Style: form

Valid values: settings, metadata, metadata.labels, operations, lookAndFeel, permissions, icon, description, description.plain, description.view ...(Show more)

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/space/{spaceKey}`, {
  headers: {
    'Accept': 'application/json'
  }
});

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

Responses

200

401

404

Returned if the requested space is returned.

Content type	Value
application/json	Space

Update space

PUT /wiki/rest/api/space/{spaceKey}

Updates the name, description, or homepage of a space.

For security reasons, permissions cannot be updated via the API and must be changed via the user interface instead.
Currently you cannot set space labels when updating a space.

Permissions required: 'Admin' permission for the space.

Connect app scope required: WRITE

OAuth 2.0 scopes required:

ClassicRECOMMENDED:write:confluence-space

Granular:read:space-details:confluence, write:space:confluence, write:space.permission:confluence

Request

Path parameters

spaceKey Required

string

The key of the space to update.

Body parameters

The properties of a space that can be updated.

name

string

The updated name of the space.

Nullable: true, Max length: 200

description

SpaceDescriptionCreate

The description of the new/updated space. Note, only the 'plain' representation can be used for the description when creating or updating a space.

Nullable: true

homepage

object

The updated homepage for this space

Nullable: true

type

string

The updated type for this space.

status

string

The updated status for this space.

Nullable: true

Additional Properties

anything

Extra properties of any type may be provided to this object.

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 = `{
  "name": "<string>",
  "description": {
    "plain": {
      "value": "<string>",
      "representation": "<string>"
    }
  },
  "homepage": {},
  "type": "<string>",
  "status": "<string>"
}`;

const response = await api.asApp().requestConfluence(route`/wiki/rest/api/space/{spaceKey}`, {
  method: 'PUT',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: bodyData
});

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

Responses

200

401

404

Returned if the space is updated.

Content type	Value
application/json	Space

Delete space

DELETE /wiki/rest/api/space/{spaceKey}

Deletes a space. Note, the space will be deleted in a long running task. Therefore, the space may not be deleted yet when this method has returned. Clients should poll the status link that is returned in the response until the task completes.

Permissions required: 'Admin' permission for the space.

Connect app scope required: DELETE

OAuth 2.0 scopes required:

ClassicRECOMMENDED:write:confluence-space

Granular:read:content.metadata:confluence, delete:space:confluence

Request

Path parameters

spaceKey Required

string

The key of the space to delete.

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/space/{spaceKey}`, {
  method: 'DELETE',
  headers: {
    'Accept': 'application/json'
  }
});

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

Responses

202

401

404

Returns a pointer to the status of the space deletion task.

Content type	Value
application/json	LongTask

Get content for space

GET /wiki/rest/api/space/{spaceKey}/content

Returns all content in a space. The returned content is grouped by type (pages then blogposts), then ordered by content ID in ascending order.

Permissions required: 'View' permission for the space. Note, the returned list will only contain content that the current user has permission to view.

Connect app scope required: READ

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:confluence-content.summary

Granular:read:content-details:confluence

Request

Path parameters

spaceKey Required

string

The key of the space to be queried for its content.

Query parameters

depth

string

Filter the results to content at the root level of the space or all content.

Default: all

Valid values: all, root

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 objects 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/space/{spaceKey}/content`, {
  headers: {
    'Accept': 'application/json'
  }
});

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

Responses

200

401

404

Returned if the requested content is returned.

Content type	Value
application/json	object

Get content by type for space

GET /wiki/rest/api/space/{spaceKey}/content/{type}

Returns all content of a given type, in a space. The returned content is ordered by content ID in ascending order.

Permissions required: 'View' permission for the space. Note, the returned list will only contain content that the current user has permission to view.

Connect app scope required: READ

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:confluence-content.summary

Granular:read:content-details:confluence

Request

Path parameters

spaceKey Required

string

The key of the space to be queried for its content.

type Required

string

The type of content to return. page, blogpost, <some_customContentType>.

Query parameters

depth

string

Filter the results to content at the root level of the space or all content.

Default: all

Valid values: all, root

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 objects 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/space/{spaceKey}/content/{type}`, {
  headers: {
    'Accept': 'application/json'
  }
});

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

Responses

200

401

404

Returned if the requested content is returned.

Content type	Value
application/json	ContentArray