Atlassian Confluence Settings API
The Atlassian Confluence Settings API enables customization and configuration of Confluence instance settings including themes and system information.
OpenAPI Specification
openapi: 3.0.1
info:
title: 'Atlassian wiki/rest/api/settings/'
description: Needs description.
termsOfService: https://atlassian.com/terms/
version: 1.0.0
externalDocs:
description: The online and complete version of the Confluence Cloud REST API docs.
url: https://developer.atlassian.com/cloud/confluence/rest/
servers:
- url: //your-domain.atlassian.net
tags:
- name: Settings
- name: Themes
paths:
/wiki/rest/api/settings/lookandfeel:
get:
tags:
- Settings
summary: Atlassian Get Look And Feel Settings
description: >-
Returns the look and feel settings for the site or a single space.
This<br>includes attributes such as the color scheme, padding, and
border radius.<br><br>The look and feel settings for a space can be
inherited from the global<br>look and feel settings or provided by a
theme.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>None
operationId: atlassianGetlookandfeelsettings
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: Atlassian Select Look And Feel Settings
description: >-
Sets the look and feel settings to the default (global) settings,
the<br>custom settings, or the current theme's settings for a
space.<br>The custom and theme settings can only be selected if there is
already<br>a theme set for a space. Note, the default space settings are
inherited<br>from the current global
settings.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>'Admin' permission for the space.
operationId: atlassianUpdatelookandfeel
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: Atlassian Update Look And Feel Settings
description: >-
Updates the look and feel settings for the site or for a single
space.<br>If custom settings exist, they are updated. If no custom
settings exist,<br>then a set of custom settings is
created.<br><br>Note, if a theme is selected for a space, the space look
and feel settings<br>are provided by the theme and cannot be
overridden.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>'Admin' permission for the space.
operationId: atlassianUpdatelookandfeelsettings
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: Atlassian Reset Look And Feel Settings
description: >-
Resets the custom look and feel settings for the site or a single
space.<br>This changes the values of the custom settings to be the same
as the<br>default settings. It does not change which settings (default
or custom)<br>are selected. Note, the default space settings are
inherited from the<br>current global
settings.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>'Admin' permission for the space.
operationId: atlassianResetlookandfeelsettings
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/lookandfeel/selected:
put:
tags:
- Settings
summary: Atlassian Set Look And Feel Settings
description: >-
Sets the look and feel settings to either the default settings or
the<br>custom settings, for the site or a single space. Note, the
default<br>space settings are inherited from the current global
settings.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>'Admin' permission for the space.
operationId: atlassianSetlookandfeelsettings
parameters:
- name: spaceKey
in: query
description: |-
The key of the space for which the look and feel settings will be
set. If this is not set, the global look and feel settings will be
set.
schema:
type: string
requestBody:
description: The look and feel type to be set.
content:
application/json:
schema:
type: string
enum:
- global
- custom
- theme
required: true
responses:
'200':
description: Returned if the look and feel settings were set.
content:
application/json:
schema:
type: string
'400':
description: |-
Returned if;
- The `spaceKey` is invalid.
- The look and feel type is invalid.
content: {}
'403':
description: |-
Returned if the look and feel type is set to 'theme' but the
space/site doesn't have a theme assigned.
content: {}
'404':
description: Returned if there is no space with the given `spaceKey`.
content: {}
deprecated: true
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
/wiki/rest/api/settings/systemInfo:
get:
tags:
- Settings
summary: Atlassian Get System Info
description: >-
Returns the system information for the Confluence Cloud tenant.
This<br>information is used by
Atlassian.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>Permission to access the Confluence site ('Can use'
global permission).
operationId: atlassianGetsysteminfo
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
/wiki/rest/api/settings/theme:
get:
tags:
- Themes
summary: Atlassian Get Themes
description: >-
Returns all themes, not including the default
theme.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**: None
operationId: atlassianGetthemes
parameters:
- name: start
in: query
description: The starting index of the returned themes.
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: limit
in: query
description: |-
The maximum number of themes to return per page.
Note, this may be restricted by fixed system limits.
schema:
minimum: 0
type: integer
format: int32
default: 100
responses:
'200':
description: Returned if the requested themes are returned.
content:
application/json:
schema:
$ref: '#/components/schemas/ThemeArray'
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
/wiki/rest/api/settings/theme/selected:
get:
tags:
- Themes
summary: Atlassian Get Global Theme
description: >-
Returns the globally assigned
theme.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**: None
operationId: atlassianGetglobaltheme
responses:
'200':
description: Returned if the global theme is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/Theme'
'404':
description: |-
Returned if Confluence does not have a global theme assigned, i.e.
the default theme is used.
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
/wiki/rest/api/settings/theme/{themeKey}:
get:
tags:
- Themes
summary: Atlassian Get Theme
description: >-
Returns a theme. This includes information about the theme
name,<br>description, and
icon.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**: None
operationId: atlassianGettheme
parameters:
- name: themeKey
in: path
description: The key of the theme to be returned.
required: true
schema:
type: string
responses:
'200':
description: Returned if the requested theme is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/Theme'
'404':
description: Returned if there is no theme with the given key.
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:
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'
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
LookAndFeelWithLinks:
description: Look and feel settings returned after an update.
allOf:
- $ref: '#/components/schemas/LookAndFeel'
- type: object
properties:
_links:
$ref: '#/components/schemas/GenericLinks'
SystemInfoEntity:
required:
- cloudId
- commitHash
type: object
nullable: true
properties:
cloudId:
type: string
commitHash:
type: string
baseUrl:
type: string
edition:
type: string
siteTitle:
type: string
defaultLocale:
type: string
defaultTimeZone:
type: string
microsPerimeter:
type: string
ThemeArray:
required:
- _links
- limit
- results
- size
- start
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/ThemeNoLinks'
start:
type: integer
format: int32
limit:
type: integer
format: int32
size:
type: integer
format: int32
_links:
$ref: '#/components/schemas/GenericLinks'
Theme:
required:
- themeKey
type: object
properties:
themeKey:
type: string
name:
type: string
description:
type: string
icon:
$ref: '#/components/schemas/Icon'
_links:
$ref: '#/components/schemas/GenericLinks'
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).
Responses that return an error status code will also return a response
body, similar to the following:
```json
{
"statusCode": 404,
"data": {
"authorized": false,
"valid": false,
"errors": [
{
"message": {
"translation": "This is an example error message.",
"args": []
}
}
],
"successful": false
},
"message": "This is an example error message."
}
```
- 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
```
**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/).