openapi: 3.2.0 info: title: Confluence Cloud REST API v2 Task API description: This document describes Confluence's v2 APIs. This is intended to be an iteration on the existing Confluence Cloud REST API with improvements in both endpoint definitions and performance. termsOfService: https://developer.atlassian.com/platform/marketplace/atlassian-developer-terms/ version: 2.0.0 servers: - url: https://{your-domain}/wiki/api/v2 variables: your-domain: default: no-default description: Specific domain of the Confluence site being used. Must be provided. tags: - name: Task description: '' paths: /tasks: get: tags: - Task operationId: getTasks summary: Get tasks description: 'Returns all tasks. The number of results is limited by the `limit` parameter and additional results (if available) will be available through the `next` URL present in the `Link` response header. **Permissions required**: Permission to access the Confluence site (''Can use'' global permission). Only tasks that the user has permission to view will be returned.' parameters: - name: body-format in: query description: The content format types to be returned in the `body` field of the response. If available, the representation will be available under a response field of the same name under the `body` field. schema: $ref: '#/components/schemas/PrimaryBodyRepresentation' - name: include-blank-tasks in: query description: Specifies whether to include blank tasks in the response. Defaults to `true`. schema: type: boolean - name: status in: query description: Filters on the status of the task. schema: type: string enum: - complete - incomplete - name: task-id in: query required: false description: Filters on task ID. Multiple IDs can be specified. schema: type: array maxItems: 250 items: type: integer format: int64 - name: space-id in: query description: Filters on the space ID of the task. Multiple IDs can be specified. schema: type: array maxItems: 250 items: type: integer format: int64 - name: page-id in: query description: Filters on the page ID of the task. Multiple IDs can be specified. Note - page and blog post filters can be used in conjunction. schema: type: array maxItems: 250 items: type: integer format: int64 - name: blogpost-id in: query description: Filters on the blog post ID of the task. Multiple IDs can be specified. Note - page and blog post filters can be used in conjunction. schema: type: array maxItems: 250 items: type: integer format: int64 - name: created-by in: query description: Filters on the Account ID of the user who created this task. Multiple IDs can be specified. schema: type: array maxItems: 250 items: type: string - name: assigned-to in: query description: Filters on the Account ID of the user to whom this task is assigned. Multiple IDs can be specified. schema: type: array maxItems: 250 items: type: string - name: completed-by in: query description: Filters on the Account ID of the user who completed this task. Multiple IDs can be specified. schema: type: array maxItems: 250 items: type: string - name: created-at-from in: query description: Filters on start of date-time range of task based on creation date (inclusive). Input is epoch time in milliseconds. schema: type: integer format: int64 - name: created-at-to in: query description: Filters on end of date-time range of task based on creation date (inclusive). Input is epoch time in milliseconds. schema: type: integer format: int64 - name: due-at-from in: query description: Filters on start of date-time range of task based on due date (inclusive). Input is epoch time in milliseconds. schema: type: integer format: int64 - name: due-at-to in: query description: Filters on end of date-time range of task based on due date (inclusive). Input is epoch time in milliseconds. schema: type: integer format: int64 - name: completed-at-from in: query description: Filters on start of date-time range of task based on completion date (inclusive). Input is epoch time in milliseconds. schema: type: integer format: int64 - name: completed-at-to in: query description: Filters on end of date-time range of task based on completion date (inclusive). Input is epoch time in milliseconds. schema: type: integer format: int64 - name: cursor in: query description: Used for pagination, this opaque cursor will be returned in the `next` URL in the `Link` response header. Use the relative URL in the `Link` header to retrieve the `next` set of results. schema: type: string - name: limit in: query description: Maximum number of tasks per result to return. If more results exist, use the `Link` header to retrieve a relative URL that will return the next set of results. schema: format: int32 default: 25 minimum: 1 maximum: 250 type: integer responses: '200': description: Returned if the requested tasks are returned. content: application/json: schema: title: MultiEntityResult type: object properties: results: type: array items: $ref: '#/components/schemas/Task' _links: $ref: '#/components/schemas/MultiEntityLinks' headers: Link: schema: type: string description: 'This header contains URL(s) within angle brackets and a relation description for each URL, describing how the provided URL relates to the incoming request''s URL. For example, rel="next" would be the URL necessary to get the next page of information. Example response header format: `Link: >; rel="next", ; rel="base"` ' '400': description: Returned if an invalid request is provided. content: {} '401': description: 'Returned if the authentication credentials are incorrect or missing from the request.' content: {} security: - basicAuth: [] - oAuthDefinitions: - read:task:confluence x-atlassian-oauth2-scopes: - scheme: oAuthDefinitions state: Current scopes: - read:task:confluence x-atlassian-connect-scope: READ x-atlassian-data-security-policy: - app-access-rule-exempt: false /tasks/{id}: get: tags: - Task operationId: getTaskById summary: Get task by id description: 'Returns a specific task. **Permissions required**: Permission to view the containing page or blog post and its corresponding space.' parameters: - name: id in: path required: true description: The ID of the task to be returned. If you don't know the task ID, use Get tasks and filter the results. schema: format: int64 type: integer - name: body-format in: query description: The content format types to be returned in the `body` field of the response. If available, the representation will be available under a response field of the same name under the `body` field. schema: $ref: '#/components/schemas/PrimaryBodyRepresentation' responses: '200': description: Returned if the requested task is returned. content: application/json: schema: $ref: '#/components/schemas/Task' '400': description: Returned if an invalid request is provided. content: {} '401': description: 'Returned if the authentication credentials are incorrect or missing from the request.' content: {} '404': description: 'Returned if the calling user does not have permission to view the requested task or the task was not found.' content: {} security: - basicAuth: [] - oAuthDefinitions: - read:task:confluence x-atlassian-oauth2-scopes: - scheme: oAuthDefinitions state: Current scopes: - read:task:confluence x-atlassian-connect-scope: READ x-atlassian-data-security-policy: - app-access-rule-exempt: false put: tags: - Task operationId: updateTask summary: Update task description: 'Update a task by id. This endpoint currently only supports updating task status. **Permissions required**: Permission to edit the containing page or blog post and view its corresponding space.' parameters: - name: id in: path required: true description: The ID of the task to be updated. If you don't know the task ID, use Get tasks and filter the results. schema: format: int64 type: integer - name: body-format in: query description: The content format types to be returned in the `body` field of the response. If available, the representation will be available under a response field of the same name under the `body` field. schema: $ref: '#/components/schemas/PrimaryBodyRepresentation' requestBody: $ref: '#/components/requestBodies/TaskUpdateRequest' responses: '200': description: Returned if the requested task is updated. content: application/json: schema: $ref: '#/components/schemas/Task' '400': description: Returned if an invalid request is provided. content: {} '401': description: Returned if the authentication credentials are incorrect or missing from the request. content: {} '404': description: 'Returned if: - The provided task does not exist - The user does not have permissions to view the task - The user does not have the needed permissions to update the containing page or blog post in the corresponding space' content: {} security: - basicAuth: [] - oAuthDefinitions: - write:task:confluence x-atlassian-oauth2-scopes: - scheme: oAuthDefinitions state: Current scopes: - write:task:confluence x-atlassian-connect-scope: WRITE x-atlassian-data-security-policy: - app-access-rule-exempt: false components: schemas: PrimaryBodyRepresentation: enum: - storage - atlas_doc_format type: string description: The primary formats a body can be represented as. A subset of BodyRepresentation. These formats are the only allowed formats in certain use cases. Task: type: object properties: id: type: string description: ID of the task. localId: type: string description: Local ID of the task. This ID is local to the corresponding page or blog post. spaceId: type: string description: ID of the space the task is in. pageId: type: string description: ID of the page the task is in. blogPostId: type: string description: ID of the blog post the task is in. status: enum: - complete - incomplete type: string description: Status of the task. body: $ref: '#/components/schemas/TaskBodySingle' createdBy: type: string description: Account ID of the user who created this task. assignedTo: type: string description: Account ID of the user to whom this task is assigned. completedBy: type: string description: Account ID of the user who completed this task. createdAt: type: string format: date-time description: Date and time when the task was created. In format "YYYY-MM-DDTHH:mm:ss.sssZ". updatedAt: type: string format: date-time description: Date and time when the task was updated. In format "YYYY-MM-DDTHH:mm:ss.sssZ". dueAt: type: string format: date-time description: Date and time when the task is due. In format "YYYY-MM-DDTHH:mm:ss.sssZ". completedAt: type: string format: date-time description: Date and time when the task was completed. In format "YYYY-MM-DDTHH:mm:ss.sssZ". MultiEntityLinks: type: object properties: next: type: string description: 'Used for pagination. Contains the relative URL for the next set of results, using a cursor query parameter. This property will not be present if there is no additional data available.' base: type: string description: Base url of the Confluence site. BodyType: type: object properties: representation: type: string description: Type of content representation used for the value field. value: type: string description: Body of the content, in the format found in the representation field. TaskBodySingle: type: object description: Contains fields for each representation type requested. properties: storage: $ref: '#/components/schemas/BodyType' atlas_doc_format: $ref: '#/components/schemas/BodyType' requestBodies: TaskUpdateRequest: required: true content: application/json: schema: type: object required: - status properties: id: type: string description: ID of the task. localId: type: string description: Local ID of the task. This ID is local to the corresponding page or blog post. spaceId: type: string description: ID of the space the task is in. pageId: type: string description: ID of the page the task is in. blogPostId: type: string description: ID of the blog post the task is in. status: enum: - complete - incomplete type: string description: Status of the task. createdBy: type: string description: Account ID of the user who created this task. assignedTo: type: string description: Account ID of the user to whom this task is assigned. completedBy: type: string description: Account ID of the user who completed this task. createdAt: type: string format: date-time description: Date and time when the task was created. In format "YYYY-MM-DDTHH:mm:ss.sssZ". updatedAt: type: string format: date-time description: Date and time when the task was updated. In format "YYYY-MM-DDTHH:mm:ss.sssZ". dueAt: type: string format: date-time description: Date and time when the task is due. In format "YYYY-MM-DDTHH:mm:ss.sssZ". completedAt: type: string format: date-time description: Date and time when the task was completed. In format "YYYY-MM-DDTHH:mm:ss.sssZ". 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:page:confluence: View pages and blogposts and their properties. read:space:confluence: View spaces and their properties. read:attachment:confluence: View attachments and their properties. read:comment:confluence: View comments and their properties. read:custom-content:confluence: View custom content and their properties. read:task:confluence: View tasks. read:whiteboard:confluence: View whiteboards and their properties. read:database:confluence: View databases and their properties. read:embed:confluence: View Smart Links in the content tree and their properties. read:folder:confluence: View folders and their properties. read:hierarchical-content:confluence: View children and descendants in the content tree. write:space:confluence: Create and update spaces and their properties. write:page:confluence: Create and update pages and blog posts and their properties. write:comment:confluence: Create and update comments and their properties. write:custom-content:confluence: Create and update custom content and their properties. write:whiteboard:confluence: Create and update whiteboards and their properties. write:database:confluence: Create and update databases and their properties. write:embed:confluence: Create and update Smart Links in the content tree and their properties. write:folder:confluence: Create and update folders and their properties. write:app-data:confluence: Create, update and delete app properties. delete:custom-content:confluence: Delete custom content. delete:page:confluence: Delete pages and blog posts. delete:comment:confluence: Delete comments. delete:whiteboard:confluence: Delete whiteboards. delete:database:confluence: Delete databases. delete:embed:confluence: Delete Smart Links in the content tree. delete:folder:confluence: Delete folders. externalDocs: description: The online and complete version of the Confluence Cloud REST API docs. url: https://developer.atlassian.com/cloud/confluence/rest/v2 x-atlassian-narrative: documents: - title: About anchor: about body: This is the reference for the Confluence Cloud REST API v2, with definitions and performance intended to be an improvement over v1. You can click on the meatball menu in the upper right to download the spec or Postman collection. - 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''re building (see [Authentication for apps](https://developer.atlassian.com/cloud/confluence/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](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: Using the REST API anchor: using body: "**Pagination:** The Confluence REST API v2 uses cursor-based 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.\n\nUse the 'limit' and 'cursor' parameters on endpoints that return multiple objects to work with pagination. First, make a request with your desired limit in the 'limit' parameter, then observe the `Link` header in the response. If there are additional entities to be retrieved, the `next` URL in the `Link` header will allow you to retrieve the next set of results. This relative URL will also be available under the `_links.next` property of paginated responses. \n\nFor example, the following request will return 5 page objects (if there are 5 present in the target site).\n```\nGET /wiki/api/v2/pages?limit=5\n```\n\nIf there are additional pages available, the `Link` header will look like:\n```\n>; rel=\"next\"\n```\nThe URL within the `Link` header will allow you to access the next 5 pages, while the `rel=\"next\"` denotes that the URL refers to the \"next\" set of pages. Relations for a single URL are separated by semicolons (;) and URLs are separated by commas (,)\nIf there are no related URLs, the `Link` header will not be present in the response and neither will the `next` property for `_links` in the response body."