Audit
Analytics
Content
Content - attachments
Content body
Content - children and descendants
Content - macro body
Content comments
Content labels
Content permissions
Content properties
Content restrictions
Content states
Content versions
Content watches
Dynamic modules
Experimental
Group
Inline tasks
Label info
Long-running task
Relation
Search
Settings
Space
Space permissions
Space properties
Space settings
Template
Themes
Users

Rate this page:

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 requiredREAD

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

1
2
3
4
5
6
7
8
9
10
11
12
// 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

Returned if the requested spaces are returned.

Content typeValue
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 requiredWRITE

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
// 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

Returned if the space is created.

Content typeValue
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 requiredWRITE

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
// 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

Returned if the space is created.

Content typeValue
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 requiredREAD

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

1
2
3
4
5
6
7
8
9
10
11
12
// 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

Returned if the requested space is returned.

Content typeValue
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 requiredWRITE

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
// 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

Returned if the space is updated.

Content typeValue
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 requiredDELETE

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

1
2
3
4
5
6
7
8
9
10
11
12
13
// 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

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

Content typeValue
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 requiredREAD

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

1
2
3
4
5
6
7
8
9
10
11
12
// 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

Returned if the requested content is returned.

Content typeValue
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 requiredREAD

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

1
2
3
4
5
6
7
8
9
10
11
12
// 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

Returned if the requested content is returned.

Content typeValue
application/json

ContentArray

Rate this page: