Atlassian Content Labels API

openapi: 3.1.0
info:
  title: Atlassian Admin Account Content Labels API
  description: The Atlassian Admin API provides programmatic access to manage Atlassian organizations, users, domains, policies, and events. It enables administrators to automate organization management tasks, integrate with identity providers, and ensure appropriate access to Atlassian products.
  version: 1.0.0
  contact:
    name: Atlassian Developer
    url: https://developer.atlassian.com/cloud/admin/
  license:
    name: Atlassian Developer Terms
    url: https://developer.atlassian.com/platform/marketplace/atlassian-developer-terms/
  x-logo:
    url: https://wac-cdn.atlassian.com/assets/img/favicons/atlassian/favicon.png
servers:
- url: https://api.atlassian.com
  description: Atlassian Cloud API
security:
- bearerAuth: []
- oauth2: []
tags:
- name: Content Labels
paths:
  /wiki/rest/api/content/{id}/label:
    get:
      tags:
      - Content Labels
      summary: Atlassian Get Labels For Content
      deprecated: true
      description: Deprecated, use [Confluence's v2 API](https://developer.atlassian.com/cloud/confluence/rest/v2/intro/).<br><br>Returns the labels on a piece of content.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw) required**:<br>'View' permission for the space and permission to view the content if it is a page.
      operationId: atlassianGetlabelsforcontent
      parameters:
      - name: id
        in: path
        description: The ID of the content to be queried for its labels.
        required: true
        schema:
          type: string
      - name: prefix
        in: query
        description: '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](#api-content-id-label-post)

          but is not used in the UI.'
        schema:
          type: string
          enum:
          - global
          - my
          - team
      - name: start
        in: query
        description: The starting index of the returned labels.
        schema:
          minimum: 0
          type: integer
          format: int32
          default: 0
      - name: limit
        in: query
        description: 'The maximum number of labels to return per page. Note,

          this may be restricted by fixed system limits.'
        schema:
          minimum: 0
          type: integer
          format: int32
          default: 200
      responses:
        '200':
          description: Returned if the requested labels are returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelArray'
        '403':
          description: Returned if the calling user can view but not edit the content.
          content: {}
        '404':
          description: 'Returned if;


            - There is no content with the given ID.

            - The calling user does not have permission to view the content.'
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - read:confluence-content.summary
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - read:confluence-content.summary
      - scheme: oAuthDefinitions
        state: Beta
        scopes:
        - read:label:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
      x-atlassian-connect-scope: READ
    post:
      tags:
      - Content Labels
      summary: Atlassian Add Labels To Content
      description: Adds labels to a piece of content. Does not modify the existing labels.<br><br>Notes:<br><br>- Labels can also be added when creating content ([Create content](#api-content-post)).<br>- Labels can be updated when updating content ([Update content](#api-content-id-put)).<br>This will delete the existing labels and replace them with the labels in<br>the request.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw) required**:<br>Permission to update the content.
      operationId: atlassianAddlabelstocontent
      parameters:
      - name: id
        in: path
        description: The ID of the content that will have labels added to it.
        required: true
        schema:
          type: string
      requestBody:
        description: The labels to add to the content.
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/LabelCreateArray'
              - $ref: '#/components/schemas/LabelCreate'
        required: true
      responses:
        '200':
          description: Returned if the labels are added to the content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelArray'
        '400':
          description: 'Returned if;


            - The body contains labels with invalid characters or too many characters.

            - The body contains too many labels.

            - The target content would contain too many labels after the operation.

            - The calling user does not have permission to edit labels.'
          content: {}
        '403':
          description: Returned if the calling user can view but not edit the content.
          content: {}
        '404':
          description: 'Returned if;


            - There is no content with the given ID.

            - The calling user does not have permission to view the content.'
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - write:confluence-content
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - write:confluence-content
      - scheme: oAuthDefinitions
        state: Beta
        scopes:
        - read:label:confluence
        - write:label:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
      x-codegen-request-body-name: body
      x-atlassian-connect-scope: WRITE
    delete:
      tags:
      - Content Labels
      summary: Atlassian Remove Label From Content Using Query Parameter
      description: Removes a label from a piece of content. Labels can't be deleted from archived content.<br>This is similar to [Remove label from content](#api-content-id-label-label-delete)<br>except that the label name is specified via a query parameter.<br><br>Use this method if the label name has "/" characters, as<br>[Remove label from content using query parameter](#api-content-id-label-delete)<br>does not accept "/" characters for the label name.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw) required**:<br>Permission to update the content.
      operationId: atlassianRemovelabelfromcontentusingqueryparameter
      parameters:
      - name: id
        in: path
        description: The ID of the content that the label will be removed from.
        required: true
        schema:
          type: string
      - name: name
        in: query
        description: The name of the label to be removed.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Returned if the label is removed. The response body will be empty.
          content: {}
        '403':
          description: Returned if the calling user can view but not edit the content.
          content: {}
        '404':
          description: 'Returned if;


            - There is no content with the given ID.

            - The calling user does not have permission to view the content.'
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - write:confluence-content
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - write:confluence-content
      - scheme: oAuthDefinitions
        state: Beta
        scopes:
        - write:label:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
      x-atlassian-connect-scope: WRITE
  /wiki/rest/api/content/{id}/label/{label}:
    delete:
      tags:
      - Content Labels
      summary: Atlassian Remove Label From Content
      description: Removes a label from a piece of content. Labels can't be deleted from archived content.<br>This is similar to [Remove label from content using query parameter](#api-content-id-label-delete)<br>except that the label name is specified via a path parameter.<br><br>Use this method if the label name does not have "/" characters, as the path<br>parameter does not accept "/" characters for security reasons. Otherwise,<br>use [Remove label from content using query parameter](#api-content-id-label-delete).<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw) required**:<br>Permission to update the content.
      operationId: atlassianRemovelabelfromcontent
      parameters:
      - name: id
        in: path
        description: The ID of the content that the label will be removed from.
        required: true
        schema:
          type: string
      - name: label
        in: path
        description: The name of the label to be removed.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Returned if the label is removed. The response body will be empty.
          content: {}
        '400':
          description: Returned if the label name has a "/" character.
          content: {}
        '403':
          description: Returned if the calling user can view but not edit the content.
          content: {}
        '404':
          description: 'Returned if;


            - There is no content with the given ID.

            - The calling user does not have permission to view the content.'
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - write:confluence-content
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - write:confluence-content
      - scheme: oAuthDefinitions
        state: Beta
        scopes:
        - write:label:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
      x-atlassian-connect-scope: WRITE
components:
  schemas:
    LabelArray:
      required:
      - results
      - size
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Label'
        start:
          type: integer
          format: int32
        limit:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        _links:
          $ref: '#/components/schemas/GenericLinks'
    GenericLinks:
      type: object
      additionalProperties:
        oneOf:
        - type: object
          additionalProperties: true
        - type: string
    LabelCreate:
      required:
      - name
      - prefix
      type: object
      additionalProperties: true
      properties:
        prefix:
          type: string
          description: The prefix for the label. `global`, `my` `team`, etc.
        name:
          type: string
          description: The name of the label, which will be shown in the UI.
    Label:
      required:
      - id
      - label
      - name
      - prefix
      type: object
      properties:
        prefix:
          type: string
        name:
          type: string
        id:
          type: string
        label:
          type: string
    LabelCreateArray:
      type: array
      items:
        $ref: '#/components/schemas/LabelCreate'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Use an Atlassian API key as a Bearer token. Create API keys at https://admin.atlassian.com.
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization for Atlassian Cloud APIs.
      flows:
        authorizationCode:
          authorizationUrl: https://auth.atlassian.com/authorize
          tokenUrl: https://auth.atlassian.com/oauth/token
          scopes:
            read:org:admin: Read organization information.
            write:org:admin: Modify organization settings.
            read:user:admin: Read user information.
            write:user:admin: Modify user accounts.
            read:policy:admin: Read organization policies.
            write:policy:admin: Modify organization policies.
            read:event:admin: Read organization events.
externalDocs:
  description: Atlassian Admin REST API Documentation
  url: https://developer.atlassian.com/cloud/admin/organization/rest/intro/