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:

Experimental

APIs in this section can change without any prior deprecation notice.

Delete page tree

DELETE /wiki/rest/api/content/{id}/pageTree

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:

1
2

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

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

Permissions required: 'Delete' permission for the space that the content is in.

Connect app scope required: DELETE

OAuth 2.0 scopes required:
ClassicRECOMMENDED:write:confluence-content
Granular:delete:content:confluence

Request

Path parameters
id Required

string

The ID of the content which forms root of the page tree, to be deleted.

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

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

Responses

Returned if the request to trash content and all its current page descendants, is successfully accepted.

Content typeValue
application/json

LongTask

Get Space Labels

Experimental

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

Returns a list of labels associated with a space. Can provide a prefix as well as other filters to select different types of labels.

Connect app scope required: READ

OAuth 2.0 scopes required:
ClassicRECOMMENDED:read:confluence-space.summary
Granular:read:label:confluence

Request

Path parameters
spaceKey Required

string

The key of the space to get labels for.

Query parameters
prefix

string

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 labels that are on content within the provided space.
  • my prefix can be explicitly added by a user when adding a label via the UI, e.g. 'my:example-label'.
  • team prefix is used for labels applied to the space.

Valid values: global, my, team

start

integer

The starting index of the returned labels.

Default: 0, Minimum: 0, Format: int32
limit

integer

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

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

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

Responses

Returned if the list of labels is returned.

Content typeValue
application/json

LabelArray

Add labels to a space

Experimental

POST /wiki/rest/api/space/{spaceKey}/label

Adds labels to a piece of content. Does not modify the existing labels.

Notes:

  • Labels can also be added when creating content (Create content).
  • Labels can be updated when updating content (Update content). This will delete the existing labels and replace them with the labels in the request.

Permissions required: Permission to update the content.

Connect app scope required: WRITE

OAuth 2.0 scopes required:
ClassicRECOMMENDED:write:confluence-space
Granular:read:label:confluence, write:label:confluence

Request

Path parameters
spaceKey Required

string

The key of the space to add labels to.

Body parameters
Content typeValue
application/json

Array<LabelCreate>

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

var bodyData = `[
  {
    "prefix": "<string>",
    "name": "<string>"
  }
]`;

const response = await api.asApp().requestConfluence(route`/wiki/rest/api/space/{spaceKey}/label`, {
  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 labels are added to the content.

Content typeValue
application/json

LabelArray

Remove label from a space

Experimental

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

Connect app scope required: WRITE

OAuth 2.0 scopes required:
ClassicRECOMMENDED:write:confluence-space
Granular:write:label:confluence

Request

Path parameters
spaceKey Required

string

The key of the space to remove a labels from.

Query parameters
name Required

string

The name of the label to remove

prefix

string

The prefix of the label to remove. If not provided defaults to global.

Example

1
2
3
4
5
6
7
8
9
10
// 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}/label?name={name}`, {
  method: 'DELETE'
});

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

Responses

Returned if the label was successfully deleted.

A schema has not been defined for this response code.

Get user properties

Experimental

GET /wiki/rest/api/user/{userId}/property

Returns the properties for a user as list of property keys. For more information about user properties, see Confluence entity properties. Note, these properties stored against a user are on a Confluence site level and not space/content level.

Permissions required: Permission to access the Confluence site ('Can use' global permission).

Connect app scope required: READ

OAuth 2.0 scopes required:
read:user.property:confluence

Request

Path parameters
userId Required

string

The account ID of the user to be queried for its properties.

Query parameters
start

integer

The starting index of the returned properties.

Default: 0, Minimum: 0, Format: int32
limit

integer

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

Default: 5, Minimum: 0, Maximum: 25, 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/user/{userId}/property`, {
  headers: {
    'Accept': 'application/json'
  }
});

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

Responses

Returned if the requested properties are returned.

Content typeValue
application/json

UserPropertyKeyArray

Get user property

Experimental

GET /wiki/rest/api/user/{userId}/property/{key}

Returns the property corresponding to key for a user. For more information about user properties, see Confluence entity properties. Note, these properties stored against a user are on a Confluence site level and not space/content level.

Permissions required: Permission to access the Confluence site ('Can use' global permission).

Connect app scope required: READ

OAuth 2.0 scopes required:
read:user.property:confluence

Request

Path parameters
userId Required

string

The account ID of the user to be queried for its properties.

key Required

string

The key of the user property.

Pattern: ^[-_a-zA-Z0-9]+$

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/user/{userId}/property/{key}`, {
  headers: {
    'Accept': 'application/json'
  }
});

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

Responses

Returned if the requested properties are returned.

Content typeValue
application/json

UserProperty

Update user property

Experimental

PUT /wiki/rest/api/user/{userId}/property/{key}

Updates a property for the given user. Note, you cannot update the key of a user property, only the value. For more information about user properties, see Confluence entity properties. Note, these properties stored against a user are on a Confluence site level and not space/content level.

Permissions required: Permission to access the Confluence site ('Can use' global permission).

Connect app scope required: WRITE

OAuth 2.0 scopes required:
write:user.property:confluence

Request

Path parameters
userId Required

string

The account ID of the user. The accountId uniquely identifies the user across all Atlassian products. For example, 384093:32b4d9w0-f6a5-3535-11a3-9c8c88d10192

key Required

string

The key of the user property.

Pattern: ^[-_a-zA-Z0-9]+$
Body parameters
value Required

object

The value of the user property.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

var bodyData = `{
  "value": {}
}`;

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

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

Responses

Returned if the user property is updated.

Create user property by key

Experimental

POST /wiki/rest/api/user/{userId}/property/{key}

Creates a property for a user. For more information about user properties, see [Confluence entity properties] (https://developer.atlassian.com/cloud/confluence/confluence-entity-properties/). Note, these properties stored against a user are on a Confluence site level and not space/content level.

Note: the number of properties which could be created per app in a tenant for each user might be restricted by fixed system limits. Permissions required: Permission to access the Confluence site ('Can use' global permission).

Connect app scope required: WRITE

OAuth 2.0 scopes required:
write:user.property:confluence

Request

Path parameters
userId Required

string

The account ID of the user. The accountId uniquely identifies the user across all Atlassian products. For example, 384093:32b4d9w0-f6a5-3535-11a3-9c8c88d10192

key Required

string

The key of the user property.

Pattern: ^[-_a-zA-Z0-9]+$
Body parameters
value Required

object

The value of the user property.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

var bodyData = `{
  "value": {}
}`;

const response = await api.asApp().requestConfluence(route`/wiki/rest/api/user/{userId}/property/{key}`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: bodyData
});

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

Responses

Returned if the user property is created.

A schema has not been defined for this response code.

Delete user property

Experimental

DELETE /wiki/rest/api/user/{userId}/property/{key}

Deletes a property for the given user. For more information about user properties, see Confluence entity properties. Note, these properties stored against a user are on a Confluence site level and not space/content level.

Permissions required: Permission to access the Confluence site ('Can use' global permission).

Connect app scope required: WRITE

OAuth 2.0 scopes required:
write:user.property:confluence

Request

Path parameters
userId Required

string

The account ID of the user. The accountId uniquely identifies the user across all Atlassian products. For example, 384093:32b4d9w0-f6a5-3535-11a3-9c8c88d10192

key Required

string

The key of the user property.

Pattern: ^[-_a-zA-Z0-9]+$

Example

1
2
3
4
5
6
7
8
9
10
// 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/user/{userId}/property/{key}`, {
  method: 'DELETE'
});

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

Responses

Returned if the user property is deleted.

Rate this page: