Rate this page:

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.

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

1
2
3
curl --request GET \
  --url 'https://your-domain.atlassian.net/wiki/rest/api/content/{id}/label' \
  --header 'Accept: application/json'

Responses

Returned if the requested labels are returned.

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

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 typeValue
application/json

Array<LabelCreate>

Example

1
2
3
4
5
6
7
8
9
10
curl --request POST \
  --url 'https://your-domain.atlassian.net/wiki/rest/api/content/{id}/label' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "prefix": "global",
    "name": "<string>"
  }
]'

Responses

Returned if the labels are added to the content.

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

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

1
2
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/wiki/rest/api/content/{id}/label?name={name}'

Responses

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

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.

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

1
2
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/wiki/rest/api/content/{id}/label/{label}'

Responses

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

Rate this page: