The Confluence Cloud REST API

Content labels

Get labels for content

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

Returns the labels on a piece of content.

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

Connect app scope required: READ

OAuth scopes required:

read:confluence-content.summary

Request

Path parameters

id Required

string

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

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 default when a user adds a label via the UI.
my prefix can be explicitly added by a user when adding a label via the UI, e.g. 'my:example-label'. Also, when a page is selected as a favourite, the 'my:favourite' label is automatically added.
team can used when adding labels via Add labels to content but is not used in the UI.

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

cURL

Node.js

Java

Python

PHP

Forge

Connect

curl --request GET \
  --url 'https://api.atlassian.com/ex/confluence/:cloudId:/wiki/rest/api/content/{id}/label' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

200

404

Returned if the requested labels are returned.

Content type	Value
application/json	LabelArray

Add labels to content

POST /wiki/rest/api/content/{id}/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 scopes required:

write:confluence-content

Request

Path parameters

id Required

string

The ID of the content that will have labels added to it.

Query parameters

use-400-error-response

boolean

If true, return the new 400 error response on invalid requests. Otherwise return a server error response on invalid requests.

Why does this parameter exist? Previously, our API was returning a 500 status code with a difficult-to-consume response body. We've fixed the response to have a 400 status code and a more useful body. This parameter enables a smooth transition without a breaking change; eventually, we'll completely remove the 500 response and this parameter won't be needed.

Body parameters

Content type	Value
application/json	Array<LabelCreate>

Example

cURL

Node.js

Java

Python

PHP

Forge

Connect

curl --request POST \
  --url 'https://api.atlassian.com/ex/confluence/:cloudId:/wiki/rest/api/content/{id}/label' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "prefix": "global",
    "name": "<string>"
  }
]'

Responses

200

400

404

Returned if the labels are added to the content.

Content type	Value
application/json	LabelArray

Remove label from content using query parameter

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

Removes a label from a piece of content. This is similar to Remove label from content except that the label name is specified via a query parameter.

Use this method if the label name has "/" characters, as Remove label from content using query parameter does not accept "/" characters for the label name.

Permissions required: Permission to update the content.

Connect app scope required: DELETE

OAuth scopes required:

write:confluence-content

Request

Path parameters

id Required

string

The ID of the content that the label will be removed from.

Query parameters

name Required

string

The name of the label to be removed.

Example

cURL

Node.js

Java

Python

PHP

Forge

Connect

1
2
3

curl --request DELETE \
  --url 'https://api.atlassian.com/ex/confluence/:cloudId:/wiki/rest/api/content/{id}/label?name={name}' \
  --header 'Authorization: Bearer <access_token>'

Responses

204

403

404

Returned if the label is removed. The response body will be empty.

A schema has not been defined for this response code.

Remove label from content

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

Removes a label from a piece of content. This is similar to Remove label from content using query parameter except that the label name is specified via a path parameter.

Use this method if the label name does not have "/" characters, as the path parameter does not accept "/" characters for security reasons. Otherwise, use Remove label from content using query parameter.

Permissions required: Permission to update the content.

Connect app scope required: DELETE

OAuth scopes required:

write:confluence-content

Request

Path parameters

id Required

string

The ID of the content that the label will be removed from.

label Required

string

The name of the label to be removed.

Example

cURL

Node.js

Java

Python

PHP

Forge

Connect

1
2
3

curl --request DELETE \
  --url 'https://api.atlassian.com/ex/confluence/:cloudId:/wiki/rest/api/content/{id}/label/{label}' \
  --header 'Authorization: Bearer <access_token>'

Responses

204

400

403

404

Returned if the label is removed. The response body will be empty.

A schema has not been defined for this response code.