openapi: 3.2.0
info:
  title: Confluence Cloud REST Content watches API
  description: This document describes the REST API and resources provided by Confluence.
  termsOfService: https://atlassian.com/terms/
  version: 1.0.0
servers:
- url: //your-domain.atlassian.net
tags:
- name: Content Watches
  description: ''
paths:
  /wiki/rest/api/content/{id}/notification/child-created:
    get:
      tags:
      - Content Watches
      summary: Get watches for page
      description: 'Returns the watches for a page. A user that watches a page will receive

        receive notifications when the page is updated.


        If you want to manage watches for a page, use the following `user` methods:


        - Get content watch status for user

        - Add content watch

        - Remove content watch


        **Permissions required**:

        Permission to access the Confluence site (''Can use'' global permission).'
      operationId: getWatchesForPage
      parameters:
      - name: id
        in: path
        description: The ID of the content to be queried for its watches.
        required: true
        schema:
          type: string
      - name: start
        in: query
        description: The starting index of the returned watches.
        schema:
          minimum: 0
          type: integer
          format: int32
          default: 0
      - name: limit
        in: query
        description: 'The maximum number of watches 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 watches are returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchArray'
        '401':
          description: 'Returned if the authentication credentials are incorrect or missing

            from the request.'
          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:watcher:confluence
        - read:user:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
      x-atlassian-connect-scope: READ
  /wiki/rest/api/content/{id}/notification/created:
    get:
      tags:
      - Content Watches
      summary: Get watches for space
      description: 'Returns all space watches for the space that the content is in. A user that

        watches a space will receive receive notifications when any content in the

        space is updated.


        If you want to manage watches for a space, use the following `user` methods:


        - Get space watch status for user

        - Add space watch

        - Remove space watch


        **Permissions required**:

        Permission to access the Confluence site (''Can use'' global permission).'
      operationId: getWatchesForSpace
      parameters:
      - name: id
        in: path
        description: The ID of the content to be queried for its watches.
        required: true
        schema:
          type: string
      - name: start
        in: query
        description: The starting index of the returned watches.
        schema:
          minimum: 0
          type: integer
          format: int32
          default: 0
      - name: limit
        in: query
        description: 'The maximum number of watches 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 watches are returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpaceWatchArray'
        '401':
          description: 'Returned if the authentication credentials are incorrect or missing

            from the request.'
          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:watcher:confluence
        - read:user:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-connect-scope: READ
  /wiki/rest/api/space/{spaceKey}/watch:
    get:
      tags:
      - Content Watches
      summary: Get space watchers
      description: Returns a list of watchers of a space
      operationId: getWatchersForSpace
      parameters:
      - name: spaceKey
        in: path
        description: The key of the space to get watchers.
        required: true
        schema:
          type: string
      - name: start
        in: query
        description: The start point of the collection to return.
        schema:
          type: string
      - name: limit
        in: query
        description: The limit of the number of items to return, this may be restricted by fixed system limits.
        schema:
          type: string
      responses:
        '200':
          description: Returned if watchers list is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpaceWatchArray'
        '404':
          description: Returned if there is no space with the given key
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - read:watcher:confluence
        - read:user:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - read:watcher:confluence
        - read:user:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-connect-scope: READ
  /wiki/rest/api/user/watch/content/{contentId}:
    get:
      tags:
      - Content Watches
      summary: Get content watch status
      description: 'Returns whether a user is watching a piece of content. Choose the user by

        doing one of the following:


        - Specify a user via a query parameter: Use the `accountId` to identify the user.

        - Do not specify a user: The currently logged-in user will be used.


        **Permissions required**:

        ''Confluence Administrator'' global permission or ''Space Administrator'' permission for the relevant space if specifying a user, otherwise

        permission to access the Confluence site (''Can use'' global permission).'
      operationId: getContentWatchStatus
      parameters:
      - name: contentId
        in: path
        description: 'The ID of the content to be queried for whether the specified user is

          watching it.'
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/userLookupKey'
      - $ref: '#/components/parameters/userLookupUsername'
      - $ref: '#/components/parameters/userLookupAccountId'
      responses:
        '200':
          description: Returned if the requested watch status is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserWatch'
        '403':
          description: 'Returned if;


            - The calling user does not have permission to view the

            content.

            - A user is specified via a query parameter and the calling user is

            not a Confluence administrator or space administrator.

            - No content exists for the specified `contentId`.'
          content: {}
        '404':
          description: Returned if no `contentId` is specified.
          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:watcher:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
      x-atlassian-connect-scope: READ
    post:
      tags:
      - Content Watches
      summary: Add content watcher
      description: 'Adds a user as a watcher to a piece of content. Choose the user by doing

        one of the following:


        - Specify a user via a query parameter: Use the `accountId` to identify the user.

        - Do not specify a user: The currently logged-in user will be used.


        Note, you must add the `X-Atlassian-Token: no-check` header when making a

        request, as this operation has XSRF protection.


        **Permissions required**:

        ''Confluence Administrator'' global permission or ''Space Administrator'' permission for the relevant space if specifying a user, otherwise

        permission to access the Confluence site (''Can use'' global permission).'
      operationId: addContentWatcher
      parameters:
      - name: contentId
        in: path
        description: The ID of the content to add the watcher to.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/userLookupKey'
      - $ref: '#/components/parameters/userLookupUsername'
      - $ref: '#/components/parameters/userLookupAccountId'
      responses:
        '204':
          description: 'Returned if the watcher was successfully created. No response body is

            returned.'
          content: {}
        '403':
          description: 'Returned if;


            - The `X-Atlassian-Token: no-check` header is not specified.

            - The calling user does not have permission to view the

            content.

            - A user is specified via a query parameter and the calling user is

            not a Confluence administrator or space administrator.

            - No content exists for the specified `contentId`.'
          content: {}
        '404':
          description: Returned if no `contentId` is specified.
          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:watcher:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
      x-atlassian-connect-scope: WRITE
    delete:
      tags:
      - Content Watches
      summary: Remove content watcher
      description: 'Removes a user as a watcher from a piece of content. Choose the user by

        doing one of the following:


        - Specify a user via a query parameter: Use the `accountId` to identify the user.

        - Do not specify a user: The currently logged-in user will be used.


        **Permissions required**:

        ''Confluence Administrator'' global permission or ''Space Administrator'' permission for the relevant space if specifying a user, otherwise

        permission to access the Confluence site (''Can use'' global permission).'
      operationId: removeContentWatcher
      parameters:
      - name: X-Atlassian-Token
        in: header
        description: 'Note, you must add header when making a

          request, as this operation has XSRF protection.'
        required: true
        schema:
          type: string
          default: no-check
      - name: contentId
        in: path
        description: The ID of the content to remove the watcher from.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/userLookupKey'
      - $ref: '#/components/parameters/userLookupUsername'
      - $ref: '#/components/parameters/userLookupAccountId'
      responses:
        '204':
          description: 'Returned if the watcher was successfully deleted. No response body is

            returned.'
          content: {}
        '403':
          description: 'Returned if;


            - The `X-Atlassian-Token: no-check` header is not specified.

            - The calling user does not have permission to view the

            content.

            - A user is specified via a query parameter and the calling user is

            not a Confluence administrator or space administrator.

            - No content exists for the specified `contentId`.'
          content: {}
        '404':
          description: Returned if no `contentId` is specified.
          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:watcher:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
      x-atlassian-connect-scope: WRITE
  /wiki/rest/api/user/watch/label/{labelName}:
    get:
      tags:
      - Content Watches
      summary: Get label watch status
      description: 'Returns whether a user is watching a label. Choose the user by doing one

        of the following:


        - Specify a user via a query parameter: Use the `accountId` to identify the user.

        - Do not specify a user: The currently logged-in user will be used.


        **Permissions required**:

        ''Confluence Administrator'' global permission if specifying a user, otherwise

        permission to access the Confluence site (''Can use'' global permission).'
      operationId: isWatchingLabel
      parameters:
      - name: labelName
        in: path
        description: 'The name of the label to be queried for whether the specified user is

          watching it.'
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/userLookupKey'
      - $ref: '#/components/parameters/userLookupUsername'
      - $ref: '#/components/parameters/userLookupAccountId'
      responses:
        '200':
          description: Returned if the requested watch status is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserWatch'
        '403':
          description: 'Returned if;


            - A user is specified via a query parameter and the calling user is

            not a Confluence administrator.

            - No label exists for the specified `labelName`.'
          content: {}
        '404':
          description: Returned if no `labelName` is specified.
          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:watcher:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-connect-scope: READ
    post:
      tags:
      - Content Watches
      summary: Add label watcher
      description: 'Adds a user as a watcher to a label. Choose the user by doing one of the

        following:


        - Specify a user via a query parameter: Use the `accountId` to identify the user.

        - Do not specify a user: The currently logged-in user will be used.


        Note, you must add the `X-Atlassian-Token: no-check` header when making a

        request, as this operation has XSRF protection.


        **Permissions required**:

        ''Confluence Administrator'' global permission if specifying a user, otherwise

        permission to access the Confluence site (''Can use'' global permission).'
      operationId: addLabelWatcher
      parameters:
      - name: X-Atlassian-Token
        in: header
        description: 'Note, you must add header when making a

          request, as this operation has XSRF protection.'
        required: true
        schema:
          type: string
          default: no-check
      - name: labelName
        in: path
        description: The name of the label to add the watcher to.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/userLookupKey'
      - $ref: '#/components/parameters/userLookupUsername'
      - $ref: '#/components/parameters/userLookupAccountId'
      responses:
        '204':
          description: 'Returned if the watcher was successfully created. No response body is

            returned.'
          content: {}
        '403':
          description: 'Returned if;


            - The `X-Atlassian-Token: no-check` header is not specified.

            - A user is specified via a query parameter and the calling user is

            not a Confluence administrator.

            - No label exists for the specified `labelName`.'
          content: {}
        '404':
          description: Returned if no `labelName` is specified.
          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:watcher:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-connect-scope: WRITE
    delete:
      tags:
      - Content Watches
      summary: Remove label watcher
      description: 'Removes a user as a watcher from a label. Choose the user by doing one of

        the following:


        - Specify a user via a query parameter: Use the `accountId` to identify the user.

        - Do not specify a user: The currently logged-in user will be used.


        **Permissions required**:

        ''Confluence Administrator'' global permission if specifying a user, otherwise

        permission to access the Confluence site (''Can use'' global permission).'
      operationId: removeLabelWatcher
      parameters:
      - name: labelName
        in: path
        description: The name of the label to remove the watcher from.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/userLookupKey'
      - $ref: '#/components/parameters/userLookupUsername'
      - $ref: '#/components/parameters/userLookupAccountId'
      responses:
        '204':
          description: 'Returned if the watcher was successfully deleted. No response body is

            returned.'
          content: {}
        '403':
          description: 'Returned if;


            - The `X-Atlassian-Token: no-check` header is not specified.

            - A user is specified via a query parameter and the calling user is

            not a Confluence administrator.

            - No label exists for the specified `labelName`.'
          content: {}
        '404':
          description: Returned if no `labelName` is specified.
          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:watcher:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-connect-scope: WRITE
  /wiki/rest/api/user/watch/space/{spaceKey}:
    get:
      tags:
      - Content Watches
      summary: Get space watch status
      description: 'Returns whether a user is watching a space. Choose the user by

        doing one of the following:


        - Specify a user via a query parameter: Use the `accountId` to identify the user.

        - Do not specify a user: The currently logged-in user will be used.


        **Permissions required**:

        ''Confluence Administrator'' global permission or ''Space Administrator'' permission for the relevant space if specifying a user, otherwise

        permission to access the Confluence site (''Can use'' global permission).'
      operationId: isWatchingSpace
      parameters:
      - name: spaceKey
        in: path
        description: 'The key of the space to be queried for whether the specified user is

          watching it.'
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/userLookupKey'
      - $ref: '#/components/parameters/userLookupUsername'
      - $ref: '#/components/parameters/userLookupAccountId'
      responses:
        '200':
          description: Returned if the requested watch status is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserWatch'
        '403':
          description: 'Returned if;


            - The calling user does not have permission to view the

            space.

            - A user is specified via a query parameter and the calling user is

            not a Confluence administrator or space administrator.

            - No space exists for the specified `spaceKey`.'
          content: {}
        '404':
          description: Returned if no `spaceKey` is specified.
          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:watcher:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-connect-scope: READ
    post:
      tags:
      - Content Watches
      summary: Add space watcher
      description: 'Adds a user as a watcher to a space. Choose the user by doing one of the

        following:


        - Specify a user via a query parameter: Use the `accountId` to identify the user.

        - Do not specify a user: The currently logged-in user will be used.


        Note, you must add the `X-Atlassian-Token: no-check` header when making a

        request, as this operation has XSRF protection.


        **Permissions required**:

        ''Confluence Administrator'' global permission or ''Space Administrator'' permission for the relevant space if specifying a user, otherwise

        permission to access the Confluence site (''Can use'' global permission).'
      operationId: addSpaceWatcher
      parameters:
      - name: X-Atlassian-Token
        in: header
        description: 'Note, you must add header when making a

          request, as this operation has XSRF protection.'
        required: true
        schema:
          type: string
          default: no-check
      - name: spaceKey
        in: path
        description: The key of the space to add the watcher to.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/userLookupKey'
      - $ref: '#/components/parameters/userLookupUsername'
      - $ref: '#/components/parameters/userLookupAccountId'
      responses:
        '204':
          description: 'Returned if the watcher was successfully created. No response body is

            returned.'
          content: {}
        '403':
          description: 'Returned if;


            - The `X-Atlassian-Token: no-check` header is not specified.

            - The calling user does not have permission to view the

            space.

            - A user is specified via a query parameter and the calling user is

            not a Confluence administrator or space administrator.

            - No space exists for the specified `spaceKey`.'
          content: {}
        '404':
          description: Returned if no `spaceKey` is specified.
          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:watcher:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-connect-scope: WRITE
    delete:
      tags:
      - Content Watches
      summary: Remove space watch
      description: 'Removes a user as a watcher from a space. Choose the user by doing one of

        the following:


        - Specify a user via a query parameter: Use the `accountId` to identify the user.

        - Do not specify a user: The currently logged-in user will be used.


        **Permissions required**:

        ''Confluence Administrator'' global permission or ''Space Administrator'' permission for the relevant space if specifying a user, otherwise

        permission to access the Confluence site (''Can use'' global permission).'
      operationId: removeSpaceWatch
      parameters:
      - name: spaceKey
        in: path
        description: The key of the space to remove the watcher from.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/userLookupKey'
      - $ref: '#/components/parameters/userLookupUsername'
      - $ref: '#/components/parameters/userLookupAccountId'
      responses:
        '204':
          description: Returned if the watcher was successfully deleted. No response body is returned.
          content: {}
        '403':
          description: 'Returned if;


            - The `X-Atlassian-Token: no-check` header is not specified.

            - The calling user does not have permission to view the space.

            - A user is specified via a query parameter and the calling user is

            not a Confluence administrator or space administrator.

            - No space exists for the specified `spaceKey`.'
          content: {}
        '404':
          description: Returned if no `spaceKey` is specified.
          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:watcher:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-connect-scope: WRITE
components:
  schemas:
    GenericAccountId:
      type:
      - string
      - 'null'
      description: 'The account ID of the user, which uniquely identifies the user across all Atlassian products.

        For example, `384093:32b4d9w0-f6a5-3535-11a3-9c8c88d10192`.'
    SpaceWatchArray:
      required:
      - limit
      - results
      - size
      - start
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/SpaceWatch'
        start:
          type: integer
          format: int32
        limit:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        _links:
          $ref: '#/components/schemas/GenericLinks'
    UserWatch:
      required:
      - watching
      type: object
      properties:
        watching:
          type: boolean
    SpaceWatch:
      required:
      - type
      - watcher
      type: object
      properties:
        type:
          type: string
        watcher:
          $ref: '#/components/schemas/WatchUser'
        spaceKey:
          type: string
        labelName:
          type: string
        prefix:
          type: string
    Watch:
      required:
      - contentId
      - type
      - watcher
      type: object
      properties:
        type:
          type: string
        watcher:
          $ref: '#/components/schemas/WatchUser'
        contentId:
          type: integer
          format: int64
    WatchArray:
      required:
      - _links
      - limit
      - results
      - size
      - start
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Watch'
        start:
          type: integer
          format: int32
        limit:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        _links:
          $ref: '#/components/schemas/GenericLinks'
    WatchUser:
      required:
      - type
      - accountId
      - profilePicture
      - displayName
      - operations
      - isExternalCollaborator
      - isGuest
      - accountType
      - email
      - publicName
      - personalSpace
      - externalCollaborator
      type: object
      properties:
        type:
          type: string
        username:
          $ref: '#/components/schemas/GenericUserName'
        userKey:
          $ref: '#/components/schemas/GenericUserKey'
        accountId:
          $ref: '#/components/schemas/GenericAccountId'
        profilePicture:
          $ref: '#/components/schemas/Icon'
        displayName:
          type: string
        timeZone:
          type:
          - string
          - 'null'
        operations:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/OperationCheckResult'
        externalCollaborator:
          type: boolean
        isGuest:
          type:
          - boolean
          - 'null'
        isExternalCollaborator:
          type: boolean
        details:
          $ref: '#/components/schemas/UserDetails'
        accountType:
          type: string
        email:
          type: string
        publicName:
          type: string
        personalSpace:
          type:
          - object
          - 'null'
      description: 'This essentially the same as the `User` object, but no `_links` property and

        no `_expandable` property (therefore, different required fields).'
    GenericUserName:
      type:
      - string
      - 'null'
      description: 'This property is no longer available and will be removed from the documentation soon.

        Use `accountId` instead.

        See the [deprecation notice](/cloud/confluence/deprecation-notice-user-privacy-api-migration-guide/) for details.'
    GenericLinks:
      type: object
      additionalProperties:
        oneOf:
        - type: object
          additionalProperties: true
        - type: string
    UserDetails:
      type: object
      properties:
        business:
          type: object
          properties:
            position:
              type: string
              description: 'This property has been deprecated due to privacy changes. There is no replacement. See the

                [migration guide](https://developer.atlassian.com/cloud/confluence/deprecation-notice-user-privacy-api-migration-guide/)

                for details.'
            department:
              type: string
              description: 'This property has been deprecated due to privacy changes. There is no replacement. See the

                [migration guide](https://developer.atlassian.com/cloud/confluence/deprecation-notice-user-privacy-api-migration-guide/)

                for details.'
            location:
              type: string
              description: 'This property has been deprecated due to privacy changes. There is no replacement. See the

                [migration guide](https://developer.atlassian.com/cloud/confluence/deprecation-notice-user-privacy-api-migration-guide/)

                for details.'
        personal:
          type: object
          properties:
            phone:
              type: string
              description: 'This property has been deprecated due to privacy changes. There is no replacement. See the

                [migration guide](https://developer.atlassian.com/cloud/confluence/deprecation-notice-user-privacy-api-migration-guide/)

                for details.'
            im:
              type: string
              description: 'This property has been deprecated due to privacy changes. There is no replacement. See the

                [migration guide](https://developer.atlassian.com/cloud/confluence/deprecation-notice-user-privacy-api-migration-guide/)

                for details.'
            website:
              type: string
              description: 'This property has been deprecated due to privacy changes. There is no replacement. See the

                [migration guide](https://developer.atlassian.com/cloud/confluence/deprecation-notice-user-privacy-api-migration-guide/)

                for details.'
            email:
              type: string
              description: 'This property has been deprecated due to privacy changes. Use the `User.email` property instead. See the

                [migration guide](https://developer.atlassian.com/cloud/confluence/deprecation-notice-user-privacy-api-migration-guide/)

                for details.'
    GenericUserKey:
      type:
      - string
      - 'null'
      description: 'This property is no longer available and will be removed from the documentation soon.

        Use `accountId` instead.

        See the [deprecation notice](/cloud/confluence/deprecation-notice-user-privacy-api-migration-guide/) for details.'
    Icon:
      required:
      - height
      - isDefault
      - path
      - width
      type:
      - object
      - 'null'
      properties:
        path:
          type: string
        width:
          type: integer
          format: int32
        height:
          type: integer
          format: int32
        isDefault:
          type: boolean
      description: This object represents an icon. If used as a profilePicture, this may be returned as null, depending on the user's privacy setting.
    OperationCheckResult:
      required:
      - operation
      - targetType
      type: object
      properties:
        operation:
          type: string
          description: The operation itself.
          enum:
          - administer
          - archive
          - clear_permissions
          - copy
          - create
          - create_space
          - delete
          - export
          - move
          - purge
          - purge_version
          - read
          - restore
          - restrict_content
          - update
          - use
        targetType:
          type: string
          description: The space or content type that the operation applies to. Could be one of- - application - page - blogpost - comment - attachment - space
      description: An operation and the target entity that it applies to, e.g. create page.
  parameters:
    userLookupAccountId:
      name: accountId
      in: query
      description: 'The account ID of the user. The accountId uniquely identifies the user across all Atlassian products.

        For example, `384093:32b4d9w0-f6a5-3535-11a3-9c8c88d10192`.'
      schema:
        type: string
    userLookupUsername:
      name: username
      in: query
      deprecated: true
      description: 'This parameter is no longer available and will be removed from the documentation soon.

        Use `accountId` instead.

        See the [deprecation notice](/cloud/confluence/deprecation-notice-user-privacy-api-migration-guide/) for details.'
      schema:
        type: string
    userLookupKey:
      name: key
      in: query
      deprecated: true
      description: 'This parameter is no longer available and will be removed from the documentation soon.

        Use `accountId` instead.

        See the [deprecation notice](/cloud/confluence/deprecation-notice-user-privacy-api-migration-guide/) for details.'
      schema:
        type: string
  securitySchemes:
    basicAuth:
      type: http
      description: You can access this resource via basic auth.
      scheme: basic
    oAuthDefinitions:
      type: oauth2
      description: This API uses OAuth 2 with the authorizationCode grant flow.
      flows:
        authorizationCode:
          authorizationUrl: https://auth.atlassian.com/authorize
          tokenUrl: https://auth.atlassian.com/oauth/token
          scopes:
            read:confluence-content.all: Read all content, including content body (expansions permitted). Note, APIs using this scope may also return data allowed by read:confluence-space.summary. However, this scope is not a substitute for read:confluence-space.summary.
            read:confluence-content.permission: Read content permissions.
            read:confluence-content.summary: Read a summary of the content, which is the content without expansions. Note, APIs using this scope may also return data allowed by read:confluence-space.summary. However, this scope is not a substitute for read:confluence-space.summary.
            write:confluence-content: Permits the creation of pages, blogs, comments and questions.
            read:confluence-space.summary: Read a summary of space information without expansions.
            write:confluence-space: Create, update and delete space information.
            write:confluence-file: Upload attachments.
            read:confluence-props: Read content properties.
            write:confluence-props: Write content properties.
            search:confluence: Search Confluence. Note, APIs using this scope may also return data allowed by read:confluence-space.summary and read:confluence-content.summary. However, this scope is not a substitute for read:confluence-space.summary or read:confluence-content.summary.
            manage:confluence-configuration: Manage global settings.
            read:confluence-groups: Read user groups.
            write:confluence-groups: Create, remove and update user groups.
            read:confluence-user: Read users.
            readonly:content.attachment:confluence: Download attachments of a Confluence page or blogpost that you have access to.
            read:content:confluence: View content.
            read:content-details:confluence: View content details.
            write:content:confluence: Create and update content.
            delete:content:confluence: Delete content.
            read:space-details:confluence: View space details.
            read:analytics.content:confluence: View analytics for content.
            read:audit-log:confluence: View audit records.
            write:audit-log:confluence: Create audit records.
            read:configuration:confluence: View Confluence settings.
            write:configuration:confluence: Update Confluence settings.
            read:page:confluence: View pages.
            write:page:confluence: Create and update pages.
            delete:page:confluence: Delete pages.
            read:blogpost:confluence: View blogposts.
            write:blogpost:confluence: Create and update blogposts.
            delete:blogpost:confluence: Delete blogposts.
            read:whiteboard:confluence: View whiteboards.
            write:whiteboard:confluence: Create and update whiteboards.
            delete:whiteboard:confluence: Delete whiteboards.
            read:custom-content:confluence: View custom content.
            write:custom-content:confluence: Create and update custom content.
            delete:custom-content:confluence: Delete custom content.
            read:attachment:confluence: View and download content attachments.
            write:attachment:confluence: Create and update attachments.
            delete:attachment:confluence: Delete attachments.
            read:comment:confluence: View comments.
            write:comment:confluence: Create and update comments.
            delete:comment:confluence: Delete comments.
            read:template:confluence: View content templates.
            write:template:confluence: Create, update and delete content templates.
            read:label:confluence: View labels.
            write:label:confluence: Add and remove labels.
            read:content.permission:confluence: Check content permissions.
            read:content.property:confluence: View content properties.
            write:content.property:confluence: Create, update and delete content properties.
            read:content.restriction:confluence: View content restrictions.
            write:content.restriction:confluence: Update content restrictions.
            read:content.metadata:confluence: View content summaries.
            read:watcher:confluence: View content watchers.
            write:watcher:confluence: Add and remove content watchers.
            read:group:confluence: View groups.
            write:group:confluence: Create and delete groups.
            read:inlinetask:confluence: View tasks.
            write:inlinetask:confluence: Update tasks.
            read:relation:confluence: View entity relationships.
            write:relation:confluence: Create and update entity relationships.
            read:space:confluence: View spaces.
            write:space:confluence: Create and update spaces.
            delete:space:confluence: Delete spaces.
            read:space.permission:confluence: View space permissions.
            write:space.permission:confluence: Update space permissions.
            read:space.property:confluence: View space properties.
            write:space.property:confluence: Create, update and delete space properties.
            read:user.property:confluence: View user properties.
            write:user.property:confluence: Create, update and delete user properties.
            read:space.setting:confluence: View space settings.
            write:space.setting:confluence: Update space settings.
            read:user:confluence: View user details.
            moderate:core-content:confluence: Moderate core contents
            moderate:comment:confluence: Moderate comments
            read:email-address:confluence: View email addresses of all users regardless of the user’s profile visibility settings.
externalDocs:
  description: The online and complete version of the Confluence Cloud REST API docs.
  url: https://developer.atlassian.com/cloud/confluence/rest/
x-atlassian-narrative:
  documents:
  - title: About
    anchor: about
    body: 'This is the reference for the Confluence Cloud REST API. This API is the primary way to get and

      modify data in Confluence Cloud, whether you are developing an app or any other integration.

      Use it to interact with Confluence entities, like pages and blog posts, spaces, users, groups,

      and more.'
  - title: Authentication and authorization
    anchor: auth
    body: '**Authentication:** If you are building a Cloud app, authentication is implemented via JWT or OAuth 2.0, depending on what you are building (see [Security overview](https://developer.atlassian.com/cloud/confluence/security-overview/)). Otherwise, if you are authenticating directly against the REST API, the REST API supports basic auth (see [Basic auth for REST APIs](https://developer.atlassian.com/cloud/confluence/basic-auth-for-rest-apis/)).


      **Authorization:** If you are building a Cloud app, authorization can be implemented by [scopes](https://developer.atlassian.com/cloud/confluence/scopes/) or by [OAuth 2.0 user impersonation](https://developer.atlassian.com/cloud/confluence/oauth-2-jwt-bearer-tokens-for-apps). Otherwise, if you are making calls directly against the REST API, authorization is based on the user used in the authentication process.


      See [Security overview](https://developer.atlassian.com/cloud/confluence/security-overview/) for more details on authentication and authorization.'
  - title: Status codes
    anchor: status-code
    body: "The Confluence REST API uses the [standard HTTP status codes](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html).\n\nResponses that return an error status code will also return a response body, similar to the following:\n```json\n{\n  \"statusCode\": 404,\n  \"data\": {\n    \"authorized\": false,\n    \"valid\": false,\n    \"errors\": [\n      {\n        \"message\": {\n          \"translation\": \"This is an example error message.\",\n          \"args\": []\n        }\n      }\n    ],\n    \"successful\": false\n  },\n  \"message\": \"This is an example error message.\"\n}\n```"
  - title: Using the REST API
    anchor: using
    body: '**Expansion:** The Confluence REST API uses resource expansion: some parts of a resource are not returned unless explicitly specified. This simplifies responses and minimizes network traffic.


      To expand part of a resource in a request, use the `expand` query parameter and specify the entities to be expanded. If you need to expand nested entities, use the `.` dot notation. For example, the following request will expand information about the requested content''s space and labels:

      ```

      GET /wiki/rest/api/content/{id}?expand=space,metadata.labels

      ```


      For bulk endpoints, when using the expand query parameter to request `body.export_view` and/or `body.styled_view` content representations, the response will be limited to a maximum of 25 results. If you require more than 25 results, use pagination to retrieve additional results.


      **Pagination:** The Confluence REST API uses pagination: a method that returns a response with multiple objects can only return a limited number at one time. This limits the size of responses and conserves server resources.


      Use the ''limit'' and ''start'' query parameters to specify pagination:


      - `limit` is the number of objects to return per page. This may be restricted by system limits.

      - `start` is the index of the first item returned in the page of results. The base index is 0.


      For example, the following request will return ten content objects, starting from the fifth object.

      ```

      GET /wiki/rest/api/content?start=4&limit=10

      ```

      **Special headers:**


      - `X-Atlassian-Token: no-check` request header must be specified for methods

      that are protected from Cross Site Request Forgery (XSRF/CSRF) attacks. This is

      stated in the method description, if required. For more information, see this

      [KB article](https://confluence.atlassian.com/cloudkb/xsrf-check-failed-when-calling-cloud-apis-826874382.html).'
  - title: Capabilities
    anchor: capabilities
    body: '**Webhooks:** A webhook is a user-defined callback over HTTP. You can use Confluence webhooks to notify your app or web application when certain events occur in Confluence. For example, when a page is created or updated. To learn more, see [Webhooks](https://developer.atlassian.com/cloud/confluence/modules/webhook/).


      **Content properties:** Content properties are a key-value storage associated with a piece of Confluence content. If you are building an app, this is one form of persistence that you can use. You can use the Confluence REST API to get, update, and delete content properties. To learn more, see [Content properties in the REST API](https://developer.atlassian.com/cloud/confluence/content-properties/).


      **CQL:** The Confluence Query Language (CQL) allows you to perform complex searches for content using an SQL-like syntax in the `search` resource. To learn more, see [Advanced searching using CQL](https://developer.atlassian.com/cloud/confluence/advanced-searching-using-cql/).'