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.

When accessing the API, you may need to provide some Authentication or Authorization. You can do this byauthenticating with your user credentials or, depending on what platform you are using, you may be able to authorize an App.

Scopes

Scopes enable an app to request a level of access to an Atlassian product. It is important to note that Confluence permissions control access to data and aren't overridden by scopes.

For example, if a user does not have permission to update content then the update won't be able to access content even if the app has the write:confluence-content scope.

Scopes for OAuth 2.0 (3LO) and Forge apps differ from scopes for Connect Apps. See below for information about each platform.

Forge apps

For Forge apps, REST API scopes are used when authenticating with Confluence Cloud. These are defined in the apps Manifest. See Add scopes to call an Atlassian REST API for more details.

The URIs for Forge app REST API calls have this structure:

/wiki/rest/api/<resource-name>

For example, /wiki/rest/api/content

Connect apps

For Connect apps, authentication (JWT-based) is built into the Connect libraries. Authorization is implemented using either scopes (shown as App scope required for operations on this page) or user impersonation. See Security for Connect apps for details.

Connect Apps use their own Scopes, rather than the REST API scopes used for Forge and 3LO Apps, see Scopes for Connect Apps for a list of scopes.

The URIs for Connect app REST API calls have this structure:

https://<site-url>/wiki/rest/api/<resource-name>

For example, https://your-domain.atlassian.net/wiki/rest/api/content

Other integrations

For integrations that are not Forge or Connect apps, use OAuth 2.0 authorization code grants (3LO) for security (3LO scopes are shown as for operations OAuth scopes required).

In OAuth Apps, REST API scopes are used when authenticating with Confluence Cloud, and are defined in the Developer Console. See OAuth 2.0 (3LO) apps for details.

The URIs for OAuth 2.0 (3LO) app REST API calls have this structure:

https://api.atlassian.com/ex/confluence/<cloudid>/rest/api/<resource-name>

For example, https://api.atlassian.com/ex/confluence/35273b54-3f06-40d2-880f-dd28cf8daafa/rest/api/content

Ad-hoc API calls

For personal scripts, bots, and ad-hoc execution of the REST APIs use basic authentication. See Basic auth for REST APIs for details.

The URIs for basic authentication REST API calls have this structure:

https://<site-url>/wiki/rest/api/<resource-name>

For example, https://your-domain.atlassian.net/wiki/rest/api/content

See Security overview for more details on authentication and authorization.

Many operations in this API will either require permission, or will limit the results based on permissions. These will either be the permissions of the user calling the API, or the app users permissions (and Scopes) depending on how the API is called.

Permissions in confluence can be granted at three levels: Global, Space and Page.

It is important to note that Confluence permissions control access to data and aren't overridden by scopes. For example, if a user does not have permission to update content then the update won't be able to access content even if the app has the write:confluence-content scope.

Global Permissions

Global permissions are site-wide permissions, and are assigned by Confluence administrators.

Space Permissions

Every space has its own independent set of permissions, managed by the space admin(s) that determine access settings for different users and groups. These can be applied to groups, users and even anonymous users if need be.

Page Restrictions

Page restrictions function a little differently to Global and Space permissions. Pages are open to viewing or editing by default but can be restricted to certain users or groups.

See What are Confluence Cloud permissions and restrictions? for more details on Confluence cloud permissions, including how permissions and restrictions interact.

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:

1
2
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.

1
2
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.

The Confluence REST API uses the standard HTTP status codes.

Responses that return an error status code will also return a response body, similar to the following:

1
2
{
  "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."
}

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.

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.

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.