Confluence Cloud Developer

Confluence Cloud Developer

Rate this page:

About

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.

Authentication and authorization

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.

Status codes

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

Using the REST API

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.

Capabilities

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.

Rate this page: