openapi: 3.2.0 info: title: Confluence Cloud REST API v2 Space Permission Transition 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: Space Permission Transition description: '' paths: /space-permissions/transition/combinations: get: tags: - Space Permission Transition operationId: listSpacePermissionCombinations summary: List unassigned space permission combinations description: 'Lists the unique unassigned space permission combinations currently present on the tenant. Combinations that already map to a space role are filtered out server-side. Each row carries the decoded set of space permissions and the principal types that currently hold the combination — these inform which `principalType` values are valid to include in the matching bulk role-assignments request. Results are always sorted by `principalCount` descending. Sort field and sort order are not configurable; page size is controlled by the `limit` query parameter (default 25, min 1, max 250). Use the `cursor` field to page through additional results. The `generatedAt` field reflects the last audit run that populated the combinations table — call the generate-combinations endpoint to refresh stale data. **Permissions required**: User must be a Confluence administrator.' parameters: - name: cursor in: query required: false description: Opaque cursor returned from a previous page in the `cursor` field of the response. Omit for the first page. schema: type: string - name: limit in: query required: false description: The maximum number of combinations to return per page. Requests outside the supported range return `400`. schema: type: integer format: int32 default: 25 minimum: 1 maximum: 250 responses: '200': description: 'Returned with the page of unassigned combinations (possibly an empty `results` array if no combinations exist or if combinations have not yet been generated for this tenant).' content: application/json: schema: $ref: '#/components/schemas/ListSpacePermissionCombinationsResponse' '400': description: 'Returned if the `cursor` query parameter is malformed, or if `limit` is not an integer in the range `1`–`250`.' 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 or the resource is not found. content: {} security: - basicAuth: [] - oAuthDefinitions: - read:configuration:confluence x-atlassian-oauth2-scopes: - scheme: oAuthDefinitions state: Current scopes: - read:configuration:confluence x-atlassian-connect-scope: ADMIN x-atlassian-data-security-policy: - app-access-rule-exempt: true x-experimental: true post: tags: - Space Permission Transition operationId: generateSpacePermissionCombinations summary: Generate space permission combinations description: 'Submits a task to refresh the space permission combinations in the database, which identifies all unique permission combinations across the site. This provides permission combination IDs that can be used with the assign-roles and remove-access endpoints. **Permissions required**: User must be a Confluence administrator.' responses: '202': description: Returned if the generation task is successfully submitted. content: application/json: schema: $ref: '#/components/schemas/BulkTransitionTaskResponse' '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 or the resource is not found. content: {} security: - basicAuth: [] - oAuthDefinitions: - write:configuration:confluence x-atlassian-oauth2-scopes: - scheme: oAuthDefinitions state: Current scopes: - write:configuration:confluence x-atlassian-connect-scope: ADMIN x-atlassian-data-security-policy: - app-access-rule-exempt: true x-experimental: true /space-permissions/transition/role-assignments: post: tags: - Space Permission Transition operationId: bulkAssignSpacePermissionRoles summary: Bulk assign space permission roles description: 'Bulk assigns roles for one or more permission combination IDs obtained from the space permission combinations. Supports targeting all spaces, specific spaces, or excluding specific spaces. **Permissions required**: User must be a Confluence administrator.' requestBody: content: application/json: schema: $ref: '#/components/schemas/BulkAssignRolesRequest' required: true responses: '202': description: Returned if the bulk assign roles task is successfully submitted. content: application/json: schema: $ref: '#/components/schemas/BulkTransitionTaskResponse' '400': description: Returned if the request is invalid (e.g., empty assignments, missing space selection). 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 or the resource is not found. content: {} security: - basicAuth: [] - oAuthDefinitions: - write:configuration:confluence x-atlassian-oauth2-scopes: - scheme: oAuthDefinitions state: Current scopes: - write:configuration:confluence x-atlassian-connect-scope: ADMIN x-atlassian-data-security-policy: - app-access-rule-exempt: true x-experimental: true /space-permissions/transition/access-removals: post: tags: - Space Permission Transition operationId: bulkRemoveSpacePermissionAccess summary: Bulk remove space permission access description: 'Bulk removes access for one or more permission combination IDs obtained from the space permission combinations. This removes all space permissions for the specified combinations across the targeted spaces. **Permissions required**: User must be a Confluence administrator.' requestBody: content: application/json: schema: $ref: '#/components/schemas/BulkRemoveAccessRequest' required: true responses: '202': description: Returned if the bulk remove access task is successfully submitted. content: application/json: schema: $ref: '#/components/schemas/BulkTransitionTaskResponse' '400': description: Returned if the request is invalid (e.g., empty permission combination IDs, missing space selection). 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 or the resource is not found. content: {} security: - basicAuth: [] - oAuthDefinitions: - write:configuration:confluence x-atlassian-oauth2-scopes: - scheme: oAuthDefinitions state: Current scopes: - write:configuration:confluence x-atlassian-connect-scope: ADMIN x-atlassian-data-security-policy: - app-access-rule-exempt: true x-experimental: true /space-permissions/transition/tasks/{taskId}: get: tags: - Space Permission Transition operationId: getSpacePermissionTransitionTaskStatus summary: Get space permission transition task status description: 'Retrieves the status of an async space permission transition task. Use the taskId returned from the generate-combinations, assign-roles, or remove-access endpoints to poll for progress and completion. **Permissions required**: User must be a Confluence administrator.' parameters: - name: taskId in: path required: true description: The ID of the async task, as returned by the generate-combinations, assign-roles, or remove-access endpoints. schema: type: string responses: '200': description: Returned if the task is found and the status is successfully retrieved. content: application/json: schema: $ref: '#/components/schemas/BulkTransitionTaskStatusResponse' '401': description: Returned if the authentication credentials are incorrect or missing from the request. content: {} '404': description: Returned if the task does not exist or the calling user does not have permission to view it. content: {} security: - basicAuth: [] - oAuthDefinitions: - read:configuration:confluence x-atlassian-oauth2-scopes: - scheme: oAuthDefinitions state: Current scopes: - read:configuration:confluence x-atlassian-connect-scope: ADMIN x-atlassian-data-security-policy: - app-access-rule-exempt: true x-experimental: true components: schemas: BulkTransitionTaskResponse: type: object required: - taskId - status - statusUrl properties: taskId: type: string description: The ID of the async task. status: type: string description: The current status of the task. enum: - IN_PROGRESS - COMPLETED - FAILED statusUrl: type: string description: URL to poll for task progress. BulkTransitionSpaceSelection: type: object required: - spaceType properties: spaceType: type: string description: The space selection type. enum: - ALL - ALL_EXCEPT_PERSONAL - ALL_EXCEPT_SPECIFIC - PERSONAL - SPECIFIC selectedSpaces: type: array description: List of specific spaces. Required when spaceType is SPECIFIC or ALL_EXCEPT_SPECIFIC. items: $ref: '#/components/schemas/BulkTransitionSpaceTarget' BulkTransitionSpaceTarget: type: object required: - id - key properties: id: type: string description: The space ID. key: type: string description: The space key. BulkRemoveAccessRequest: type: object required: - permissionCombinationIds - spaceSelection properties: permissionCombinationIds: type: array description: List of permission combination IDs to remove access for. items: type: string spaceSelection: $ref: '#/components/schemas/BulkTransitionSpaceSelection' BulkTransitionPrincipalTypeAssignment: type: object required: - principalType - removeAccess properties: principalType: type: string description: The type of principal. enum: - USER - GROUP - GUEST - ANONYMOUS - ALL_LICENSED_USERS_USER_CLASS - ALL_PRODUCT_ADMINS_USER_CLASS - APP removeAccess: type: boolean description: Whether to remove access for this principal type instead of assigning a role. roleId: type: - string - 'null' description: The UUID of the space role to assign. Required when removeAccess is false. BulkAssignRolesRequest: type: object required: - assignments - spaceSelection properties: assignments: type: array description: List of role assignments to apply. items: $ref: '#/components/schemas/BulkTransitionRoleAssignment' spaceSelection: $ref: '#/components/schemas/BulkTransitionSpaceSelection' ListSpacePermissionCombinationsResponse: type: object required: - results properties: results: type: array description: One page of unassigned permission combinations, sorted by principalCount descending. items: $ref: '#/components/schemas/BulkTransitionCombinationEntry' generatedAt: type: - string - 'null' description: 'ISO-8601 timestamp of the last audit run that populated the combinations table. Absent if the audit task has never run on this tenant.' cursor: type: - string - 'null' description: Opaque cursor for the next page. Absent when no further results exist. BulkTransitionTaskStatusResponse: type: object required: - taskId - status properties: taskId: type: string description: The ID of the task. status: type: string description: The current status of the task. enum: - IN_PROGRESS - COMPLETED - FAILED errorMessage: type: - string - 'null' description: Human-readable error message describing why the task failed. Only present when status is FAILED. BulkTransitionCombinationEntry: type: object required: - combinationId - spaceCount - principalCount - permissions - principalTypes properties: combinationId: type: string description: The opaque id identifying this unique combination of space permissions. Pass directly to the bulk role-assignments or access-removals endpoints. spaceCount: type: integer format: int64 description: Number of spaces that currently have this combination. principalCount: type: integer format: int64 description: Number of principals (users / groups / etc.) that currently have this combination. permissions: type: array description: The decoded space permissions that make up this combination. items: $ref: '#/components/schemas/BulkTransitionDecodedPermission' principalTypes: type: array description: 'The principal types that currently hold this combination and can be reassigned via the bulk role-assignments endpoint. Use this to know which `principalType` entries are valid to include in the bulk-assign request for this combination.' items: type: string enum: - USER - GROUP - GUEST - ANONYMOUS - ALL_LICENSED_USERS_USER_CLASS - ALL_PRODUCT_ADMINS_USER_CLASS - APP - TEAM BulkTransitionRoleAssignment: type: object required: - permissionCombinationId - principalTypeAssignments properties: permissionCombinationId: type: string description: The ID of the permission combination. principalTypeAssignments: type: array description: List of principal type assignments. items: $ref: '#/components/schemas/BulkTransitionPrincipalTypeAssignment' BulkTransitionDecodedPermission: type: object required: - id - displayName properties: id: type: string description: The platform id of the permission (e.g. `VIEW_CONTENT`). displayName: type: string description: Human-readable name of the permission. 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."