Confluence Experimental API

openapi: 3.2.0
info:
  title: Confluence Cloud REST Experimental 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: Experimental
  description: APIs in this section can change without any prior deprecation notice.
paths:
  /wiki/rest/api/content/{id}/pageTree:
    delete:
      tags:
      - Experimental
      summary: Delete page tree
      description: '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:


        {

        "id" : "1180606",

        "links" : {

        "status" : "/rest/api/longtask/1180606"

        }

        }


        Use the `/longtask/` REST API to get the copy task status.


        **Permissions required**:

        ''Delete'' permission for the space that the content is in.'
      operationId: deletePageTree
      parameters:
      - name: id
        in: path
        description: The ID of the content which forms root of the page tree, to be deleted.
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Returned if the request to trash content and all its current page descendants, is successfully accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LongTask'
        '400':
          description: Returned if the content id is invalid or id does not represents a 'CURRENT' page.
          content: {}
        '401':
          description: 'Returned if the authentication credentials are incorrect or missing

            from the request.'
          content: {}
        '403':
          description: Returned if the calling user can not delete the content with specified id.
          content: {}
        '404':
          description: 'Returned if;


            - There is no content with the given ID.

            - The requesting user does not have permission to trash the content or any of it''s descendant pages.'
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - write:confluence-content
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - write:confluence-content
      - scheme: oAuthDefinitions
        state: Beta
        scopes:
        - delete:content:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
      x-atlassian-connect-scope: DELETE
  /wiki/rest/api/space/{spaceKey}/label:
    get:
      tags:
      - Experimental
      summary: Get Space Labels
      description: 'Returns a list of labels associated with a space. Can provide a prefix as well as other filters to

        select different types of labels.'
      operationId: getLabelsForSpace
      parameters:
      - name: spaceKey
        in: path
        description: The key of the space to get labels for.
        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 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.'
        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 list of labels is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelArray'
        '404':
          description: 'Returned if;

            - There is no space with the given space key.

            - The calling user does not have permission to view the space.'
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - read:confluence-space.summary
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - read:confluence-space.summary
      - scheme: oAuthDefinitions
        state: Beta
        scopes:
        - read:label:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-experimental: true
      x-atlassian-connect-scope: READ
    post:
      tags:
      - Experimental
      summary: Add labels to a space
      description: '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.'
      operationId: addLabelsToSpace
      parameters:
      - name: spaceKey
        in: path
        description: The key of the space to add labels to.
        required: true
        schema:
          type: string
      requestBody:
        description: The labels to add to the content.
        content:
          application/json:
            schema:
              type: array
              items:
                $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 space with the given space key.

            - The calling user does not have permission to view the space.'
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - write:confluence-space
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - write:confluence-space
      - scheme: oAuthDefinitions
        state: Beta
        scopes:
        - read:label:confluence
        - write:label:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-experimental: true
      x-atlassian-connect-scope: WRITE
    delete:
      tags:
      - Experimental
      summary: Remove label from a space
      description: ''
      operationId: deleteLabelFromSpace
      parameters:
      - name: spaceKey
        in: path
        description: The key of the space to remove a labels from.
        required: true
        schema:
          type: string
      - name: name
        in: query
        description: The name of the label to remove
        required: true
        schema:
          type: string
      - name: prefix
        in: query
        description: The prefix of the label to remove. If not provided defaults to global.
        required: false
        schema:
          type: string
      responses:
        '204':
          description: Returned if the label was successfully deleted.
          content: {}
        '400':
          description: 'Returned if;

            - The user does not provide a label name'
          content: {}
        '404':
          description: 'Returned if;

            - There is no space with the given space key.

            - The calling user does not have permission to view the space.'
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - write:confluence-space
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - write:confluence-space
      - scheme: oAuthDefinitions
        state: Beta
        scopes:
        - write:label:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-experimental: true
      x-atlassian-connect-scope: WRITE
components:
  schemas:
    Label:
      required:
      - id
      - label
      - name
      - prefix
      type: object
      properties:
        prefix:
          type: string
        name:
          type: string
        id:
          type: string
        label:
          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.
    LongTask:
      required:
      - id
      - links
      type: object
      properties:
        ari:
          type: string
          description: the ARI for the long task, based on its ID
        id:
          type: string
          description: a unique identifier for the long task
        links:
          type: object
          additionalProperties: true
          properties:
            status:
              type: string
              description: The URL to retrive status of long task.
    GenericLinks:
      type: object
      additionalProperties:
        oneOf:
        - type: object
          additionalProperties: true
        - type: string
    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'
  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/).'