Confluence Settings API

openapi: 3.2.0
info:
  title: Confluence Cloud REST Settings 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: Settings
  description: ''
paths:
  /wiki/rest/api/settings/lookandfeel:
    get:
      tags:
      - Settings
      summary: Get look and feel settings
      description: 'Returns the look and feel settings for the site or a single space. This

        includes attributes such as the color scheme, padding, and border radius.


        The look and feel settings for a space can be inherited from the global

        look and feel settings or provided by a theme.


        **Permissions required**:

        None'
      operationId: getLookAndFeelSettings
      parameters:
      - name: spaceKey
        in: query
        description: 'The key of the space for which the look and feel settings will be

          returned. If this is not set, only the global look and feel settings

          are returned.'
        schema:
          type: string
      responses:
        '200':
          description: Returned if the requested look and feel settings are returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookAndFeelSettings'
        '400':
          description: Returned if `spaceKey` is invalid.
          content: {}
        '404':
          description: Returned if there is no space with the given `spaceKey`.
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - manage:confluence-configuration
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - manage:confluence-configuration
      - scheme: oAuthDefinitions
        state: Beta
        scopes:
        - read:configuration:confluence
        - read:space.setting:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-connect-scope: READ
    put:
      tags:
      - Settings
      summary: Select look and feel settings
      description: 'Sets the look and feel settings to the default (global) settings, the

        custom settings, or the current theme''s settings for a space.

        The custom and theme settings can only be selected if there is already

        a theme set for a space. Note, the default space settings are inherited

        from the current global settings.


        **Permissions required**:

        ''Admin'' permission for the space.'
      operationId: updateLookAndFeel
      requestBody:
        description: The look and feel type to be set.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LookAndFeelSelection'
        required: true
      responses:
        '200':
          description: Returned if the look and feel settings were set.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookAndFeelSelection'
        '400':
          description: 'Returned if;


            - `spaceKey` is invalid.

            - `lookAndFeelType` is invalid.'
          content: {}
        '403':
          description: 'Returned if the calling user doesn''t have permission to edit the

            look and feel settings.'
          content: {}
        '404':
          description: Returned if there is no space with the given `spaceKey`.
          content: {}
        '409':
          description: 'Returned if `lookAndFeelType` is set to ''custom'' or ''theme'',

            and a theme is not currently set for the space.'
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - manage:confluence-configuration
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - manage:confluence-configuration
      - scheme: oAuthDefinitions
        state: Beta
        scopes:
        - read:space.setting:confluence
        - write:space.setting:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-codegen-request-body-name: body
      x-atlassian-connect-scope: WRITE
  /wiki/rest/api/settings/lookandfeel/custom:
    post:
      tags:
      - Settings
      summary: Update look and feel settings
      description: 'Updates the look and feel settings for the site or for a single space.

        If custom settings exist, they are updated. If no custom settings exist,

        then a set of custom settings is created.


        Note, if a theme is selected for a space, the space look and feel settings

        are provided by the theme and cannot be overridden.


        **Permissions required**:

        ''Admin'' permission for the space.'
      operationId: updateLookAndFeelSettings
      parameters:
      - name: spaceKey
        in: query
        description: 'The key of the space for which the look and feel settings will be

          updated. If this is not set, the global look and feel settings will

          be updated.'
        schema:
          type: string
      requestBody:
        description: 'The updated settings. All values for the settings must be included,

          regardless of whether they are being changed.


          One way to create the request body is to copy the settings from the

          response body of [Get look and feel settings](#api-settings-lookandfeel-get)

          and modify it as needed.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LookAndFeel'
        required: true
      responses:
        '200':
          description: Returned if the look and feel settings are updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookAndFeelWithLinks'
        '400':
          description: 'Returned if;


            - The `spaceKey` is invalid

            - The request body contains invalid data.'
          content: {}
        '403':
          description: 'Returned if the calling user doesn''t have permission to edit the

            look and feel settings.'
          content: {}
        '404':
          description: Returned if there is no space with the given `spaceKey`.
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - manage:confluence-configuration
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - manage:confluence-configuration
      - scheme: oAuthDefinitions
        state: Beta
        scopes:
        - read:configuration:confluence
        - read:space.setting:confluence
        - write:configuration:confluence
        - write:space.setting:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-codegen-request-body-name: body
      x-atlassian-connect-scope: WRITE
    delete:
      tags:
      - Settings
      summary: Reset look and feel settings
      description: 'Resets the custom look and feel settings for the site or a single space.

        This changes the values of the custom settings to be the same as the

        default settings. It does not change which settings (default or custom)

        are selected. Note, the default space settings are inherited from the

        current global settings.


        **Permissions required**:

        ''Admin'' permission for the space.'
      operationId: resetLookAndFeelSettings
      parameters:
      - name: spaceKey
        in: query
        description: 'The key of the space for which the look and feel settings will be

          reset. If this is not set, the global look and feel settings will

          be reset.'
        schema:
          type: string
      responses:
        '204':
          description: Returned if the look and feel settings have been reset.
          content: {}
        '400':
          description: Returned if `spaceKey` is invalid.
          content: {}
        '403':
          description: 'Returned if the calling user doesn''t have permission to reset the

            look and feel.'
          content: {}
        '404':
          description: Returned if there is no space with the given `spaceKey`.
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - manage:confluence-configuration
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - manage:confluence-configuration
      - scheme: oAuthDefinitions
        state: Beta
        scopes:
        - write:configuration:confluence
        - write:space.setting:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-connect-scope: DELETE
  /wiki/rest/api/settings/systemInfo:
    get:
      tags:
      - Settings
      summary: Get system info
      description: 'Returns the system information for the Confluence Cloud tenant. This

        information is used by Atlassian.


        **Permissions required**:

        Permission to access the Confluence site (''Can use'' global permission).'
      operationId: getSystemInfo
      responses:
        '200':
          description: 'Returned if the system information for the Confluence Cloud tenant

            is returned.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemInfoEntity'
        '403':
          description: 'Returned when the user does not have permission to view the system

            information.'
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - manage:confluence-configuration
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - manage:confluence-configuration
      - scheme: oAuthDefinitions
        state: Beta
        scopes:
        - read:configuration:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-connect-scope: READ
components:
  schemas:
    HorizontalHeaderLookAndFeel:
      required:
      - backgroundColor
      - primaryNavigation
      type: object
      properties:
        backgroundColor:
          type: string
        button:
          $ref: '#/components/schemas/ButtonLookAndFeel'
        primaryNavigation:
          $ref: '#/components/schemas/TopNavigationLookAndFeel'
        secondaryNavigation:
          $ref: '#/components/schemas/NavigationLookAndFeel'
        search:
          $ref: '#/components/schemas/SearchFieldLookAndFeel'
    ScreenLookAndFeel:
      required:
      - background
      type: object
      properties:
        background:
          type: string
        backgroundAttachment:
          type:
          - string
          - 'null'
        backgroundBlendMode:
          type:
          - string
          - 'null'
        backgroundClip:
          type:
          - string
          - 'null'
        backgroundColor:
          type:
          - string
          - 'null'
        backgroundImage:
          type:
          - string
          - 'null'
        backgroundOrigin:
          type:
          - string
          - 'null'
        backgroundPosition:
          type:
          - string
          - 'null'
        backgroundRepeat:
          type:
          - string
          - 'null'
        backgroundSize:
          type:
          - string
          - 'null'
        layer:
          type:
          - object
          - 'null'
          properties:
            width:
              type: string
            height:
              type: string
        gutterTop:
          type:
          - string
          - 'null'
        gutterRight:
          type:
          - string
          - 'null'
        gutterBottom:
          type:
          - string
          - 'null'
        gutterLeft:
          type:
          - string
          - 'null'
    HeaderLookAndFeel:
      required:
      - backgroundColor
      - button
      - primaryNavigation
      - search
      - secondaryNavigation
      type: object
      properties:
        backgroundColor:
          type: string
        button:
          $ref: '#/components/schemas/ButtonLookAndFeel'
        primaryNavigation:
          $ref: '#/components/schemas/NavigationLookAndFeel'
        secondaryNavigation:
          $ref: '#/components/schemas/NavigationLookAndFeel'
        search:
          $ref: '#/components/schemas/SearchFieldLookAndFeel'
    LookAndFeel:
      required:
      - bordersAndDividers
      - content
      - header
      - headings
      - links
      - menus
      type: object
      properties:
        headings:
          required:
          - color
          type: object
          properties:
            color:
              type: string
        links:
          required:
          - color
          type: object
          properties:
            color:
              type: string
        menus:
          $ref: '#/components/schemas/MenusLookAndFeel'
        header:
          $ref: '#/components/schemas/HeaderLookAndFeel'
        horizontalHeader:
          $ref: '#/components/schemas/HorizontalHeaderLookAndFeel'
        content:
          $ref: '#/components/schemas/ContentLookAndFeel'
        bordersAndDividers:
          required:
          - color
          type: object
          properties:
            color:
              type: string
        spaceReference:
          type:
          - object
          - 'null'
    LookAndFeelSelection:
      required:
      - lookAndFeelType
      - spaceKey
      type: object
      properties:
        spaceKey:
          type: string
          description: 'The key of the space for which the look and feel settings will be

            set.'
        lookAndFeelType:
          type: string
          enum:
          - global
          - custom
          - theme
      description: Look and feel selection
    MenusLookAndFeel:
      required:
      - color
      - hoverOrFocus
      type: object
      properties:
        hoverOrFocus:
          required:
          - backgroundColor
          type: object
          properties:
            backgroundColor:
              type: string
        color:
          type: string
    TopNavigationLookAndFeel:
      required:
      - highlightColor
      type: object
      properties:
        color:
          type:
          - string
          - 'null'
        highlightColor:
          type: string
        hoverOrFocus:
          type: object
          properties:
            backgroundColor:
              type: string
            color:
              type: string
    ContainerLookAndFeel:
      required:
      - background
      - backgroundColor
      - backgroundImage
      - backgroundSize
      - borderRadius
      - padding
      type:
      - object
      - 'null'
      properties:
        background:
          type: string
        backgroundAttachment:
          type:
          - string
          - 'null'
        backgroundBlendMode:
          type:
          - string
          - 'null'
        backgroundClip:
          type:
          - string
          - 'null'
        backgroundColor:
          type:
          - string
          - 'null'
        backgroundImage:
          type:
          - string
          - 'null'
        backgroundOrigin:
          type:
          - string
          - 'null'
        backgroundPosition:
          type:
          - string
          - 'null'
        backgroundRepeat:
          type:
          - string
          - 'null'
        backgroundSize:
          type:
          - string
          - 'null'
        padding:
          type: string
        borderRadius:
          type: string
    NavigationLookAndFeel:
      required:
      - color
      - hoverOrFocus
      type:
      - object
      - 'null'
      properties:
        color:
          type: string
        highlightColor:
          type:
          - string
          - 'null'
        hoverOrFocus:
          required:
          - backgroundColor
          - color
          type: object
          properties:
            backgroundColor:
              type: string
            color:
              type: string
    LookAndFeelWithLinks:
      description: Look and feel settings returned after an update.
      allOf:
      - $ref: '#/components/schemas/LookAndFeel'
      - type: object
        properties:
          _links:
            $ref: '#/components/schemas/GenericLinks'
    ButtonLookAndFeel:
      required:
      - backgroundColor
      - color
      type:
      - object
      - 'null'
      properties:
        backgroundColor:
          type: string
        color:
          type: string
    SystemInfoEntity:
      required:
      - cloudId
      - commitHash
      type:
      - object
      - 'null'
      properties:
        cloudId:
          type: string
        commitHash:
          type: string
        baseUrl:
          type: string
        fallbackBaseUrl:
          type: string
        edition:
          type: string
        siteTitle:
          type: string
        defaultLocale:
          type: string
        defaultTimeZone:
          type: string
        microsPerimeter:
          type: string
    LookAndFeelSettings:
      required:
      - custom
      - global
      - selected
      type: object
      properties:
        selected:
          type: string
          enum:
          - global
          - custom
        global:
          $ref: '#/components/schemas/LookAndFeel'
        theme:
          $ref: '#/components/schemas/LookAndFeel'
        custom:
          $ref: '#/components/schemas/LookAndFeel'
    SearchFieldLookAndFeel:
      required:
      - backgroundColor
      - color
      type:
      - object
      - 'null'
      properties:
        backgroundColor:
          type: string
        color:
          type: string
    GenericLinks:
      type: object
      additionalProperties:
        oneOf:
        - type: object
          additionalProperties: true
        - type: string
    ContentLookAndFeel:
      type: object
      properties:
        screen:
          $ref: '#/components/schemas/ScreenLookAndFeel'
        container:
          $ref: '#/components/schemas/ContainerLookAndFeel'
        header:
          $ref: '#/components/schemas/ContainerLookAndFeel'
        body:
          $ref: '#/components/schemas/ContainerLookAndFeel'
  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/).'