openapi: 3.2.0 info: title: Confluence Cloud REST Long-running task 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: Long-Running Task description: '' paths: /wiki/rest/api/longtask: get: tags: - Long-Running Task summary: Get long-running tasks description: 'Returns information about all active long-running tasks (e.g. space export), such as how long each task has been running and the percentage of each task that has completed. **Permissions required**: Permission to access the Confluence site (''Can use'' global permission).' operationId: getTasks parameters: - name: key in: query description: The key of the tasks. required: false schema: type: string - name: start in: query description: The starting index of the returned tasks. schema: minimum: 0 type: integer format: int32 default: 0 - name: limit in: query description: 'The maximum number of tasks 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 tasks are returned. content: application/json: schema: $ref: '#/components/schemas/LongTaskStatusArray' '401': description: Returned if the calling user is not logged in to Confluence. content: {} security: - basicAuth: [] - oAuthDefinitions: - read:content.metadata:confluence x-atlassian-oauth2-scopes: - scheme: oAuthDefinitions state: Current scopes: - read:content.metadata:confluence x-atlassian-data-security-policy: - app-access-rule-exempt: true x-atlassian-connect-scope: READ /wiki/rest/api/longtask/{id}: get: tags: - Long-Running Task summary: Get long-running task description: 'Returns information about an active long-running task (e.g. space export), such as how long it has been running and the percentage of the task that has completed. **Permissions required**: Permission to access the Confluence site (''Can use'' global permission).' operationId: getTask parameters: - name: id in: path description: The ID of the task. required: true schema: type: string responses: '200': description: Returned if the requested task is returned. content: application/json: schema: $ref: '#/components/schemas/LongTaskStatusWithLinks' '401': description: Returned if the calling user is not logged in to Confluence. content: {} '404': description: 'Returned if; - There is no task with the given ID. - The calling user does not have permission to view the task.' content: {} security: - basicAuth: [] - oAuthDefinitions: - read:confluence-space.summary x-atlassian-oauth2-scopes: - scheme: oAuthDefinitions state: Current scopes: - read:confluence-space.summary - scheme: oAuthDefinitions state: Beta scopes: - read:content.metadata:confluence x-atlassian-data-security-policy: - app-access-rule-exempt: true x-atlassian-connect-scope: READ components: schemas: LongTaskStatusWithLinks: required: - _links - elapsedTime - finished - id - messages - name - percentageComplete - successful type: object properties: ari: type: string description: the ARI for the long task, based on its ID id: type: string name: required: - args - key type: object properties: key: type: string args: type: array items: type: object properties: {} elapsedTime: type: integer format: int64 percentageComplete: type: integer format: int32 successful: type: boolean finished: type: boolean messages: type: array items: $ref: '#/components/schemas/Message' _links: $ref: '#/components/schemas/GenericLinks' status: type: string errors: type: array items: $ref: '#/components/schemas/Message' additionalDetails: type: object properties: destinationId: type: - string - 'null' destinationUrl: type: string totalPageNeedToCopy: type: integer additionalProperties: type: string description: 'Same as LongTaskStatus but with `_links` property. Status keys: - `ERROR_UNKNOWN` - Generic error - `ERROR_LOCK_FAILED` - Could not get the lock on destination space - `ERROR_RELINK` - Error when relink pages/attachments - `ERROR_COPY_PAGE` - Error while copying 1 page - `WARN_RENAME_PAGE` - Warning page is rename during copy - `WARN_IGNORE_COPY_PERMISSION` - Warning could not copy permission - `WARN_IGNORE_COPY_ATTACHMENT` - Warning could not copy attachment - `WARN_IGNORE_DELETE_PAGE` - Warning ignoring delete of a non agreed on page - `STATUS_COPIED_PAGES` - Message total pages are copied - `STATUS_COPYING_PAGES` - Message copy pages - `STATUS_RELINK_PAGES` - Message relink pages/attachments - `STATUS_DELETING_PAGES` - Message delete pages - `STATUS_DELETED_PAGES` - Message total pages are deleted - `STATUS_MOVING_PAGES` - Message move pages - `WARN_IGNORE_VIEW_RESTRICTED` - Permission changed - view restricted - `WARN_IGNORE_EDIT_RESTRICTED` - Permission changed - edit restricted - `INITIALIZING_TASK` - Message when initializing task - `UNKNOWN_STATUS` - Message when status is unknown' Message: required: - args type: object additionalProperties: true properties: translation: type: string args: type: array items: oneOf: - type: string - type: object additionalProperties: true GenericLinks: type: object additionalProperties: oneOf: - type: object additionalProperties: true - type: string LongTaskStatus: required: - elapsedTime - finished - id - messages - name - percentageComplete - successful type: object properties: ari: type: string description: the ARI for the long task, based on its ID id: type: string name: required: - args - key type: object properties: key: type: string args: type: array items: type: object properties: {} elapsedTime: type: integer format: int64 percentageComplete: type: integer format: int32 successful: type: boolean finished: type: boolean messages: type: array items: $ref: '#/components/schemas/Message' status: type: string errors: type: array items: $ref: '#/components/schemas/Message' additionalDetails: type: object properties: destinationId: type: string destinationUrl: type: string totalPageNeedToCopy: type: integer additionalProperties: type: string description: 'Current status of a long running task Status keys: - `ERROR_UNKNOWN` - Generic error - `ERROR_LOCK_FAILED` - Could not get the lock on destination space - `ERROR_RELINK` - Error when relink pages/attachments - `ERROR_COPY_PAGE` - Error while copying 1 page - `WARN_RENAME_PAGE` - Warning page is rename during copy - `WARN_IGNORE_COPY_PERMISSION` - Warning could not copy permission - `WARN_IGNORE_COPY_ATTACHMENT` - Warning could not copy attachment - `WARN_IGNORE_DELETE_PAGE` - Warning ignoring delete of a non agreed on page - `STATUS_COPIED_PAGES` - Message total pages are copied - `STATUS_COPYING_PAGES` - Message copy pages - `STATUS_RELINK_PAGES` - Message relink pages/attachments - `STATUS_DELETING_PAGES` - Message delete pages - `STATUS_DELETED_PAGES` - Message total pages are deleted - `STATUS_MOVING_PAGES` - Message move pages - `WARN_IGNORE_VIEW_RESTRICTED` - Permission changed - view restricted - `WARN_IGNORE_EDIT_RESTRICTED` - Permission changed - edit restricted - `INITIALIZING_TASK` - Message when initializing task - `UNKNOWN_STATUS` - Message when status is unknown' LongTaskStatusArray: required: - _links - limit - results - size - start type: object properties: results: type: array items: $ref: '#/components/schemas/LongTaskStatus' start: type: integer format: int32 limit: type: integer format: int32 size: type: integer format: int32 _links: $ref: '#/components/schemas/GenericLinks' 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/).'