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.

NOTE: Personal data that is used to identify users, such as username and userKey, has been removed from the Confluence Cloud REST API. In addition, other personal data (for example, email) is now restricted by a user's profile settings (or in the case of managed accounts, the visibility settings decided by the site administrator). You must update your apps to accommodate these changes, if you have not done so already. This change was previously announced on 01 October 2018 and followed by a deprecation period (see the announcement).

Authentication: If you are building a Cloud app, authentication is implemented via JWT (see Authentication for apps). Otherwise, if you are authenticating directly against the REST API, the REST API supports basic auth (see Basic auth for REST APIs).

Authorization: If you are building a Cloud app, authorization can be implemented by scopes or by OAuth 2.0 user impersonation. 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 for more details on authentication and authorization.

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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

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

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

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

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.

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.