{ "openapi": "3.0.3", "info": { "title": "The Confluence Cloud REST API v2", "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" }, "externalDocs": { "description": "The online and complete version of the Confluence Cloud REST API docs.", "url": "https://developer.atlassian.com/cloud/confluence/rest/v2" }, "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": "Admin Key", "description": "The [Admin Key feature](https://support.atlassian.com/confluence-cloud/docs/bypass-access-restrictions-on-a-page-with-admin-key/) is only offered with Confluence Cloud Premium and Enterprise to organization or site admins.\n\n**NOTE:** Users can only make calls to our public REST APIs using a valid Admin Key by adding the following HTTP header on their requests: `Atl-Confluence-With-Admin-Key: true`. Visit the [Confluence Cloud Changelog](https://developer.atlassian.com/cloud/confluence/changelog/#CHANGE-2480) for more details." }, { "name": "Attachment", "description": "" }, { "name": "App Properties", "description": "" }, { "name": "Ancestors", "description": "" }, { "name": "Blog Post", "description": "" }, { "name": "Children", "description": "" }, { "name": "Classification Level", "description": "" }, { "name": "Comment", "description": "" }, { "name": "Content", "description": "" }, { "name": "Content Properties", "description": "" }, { "name": "Custom Content", "description": "" }, { "name": "Database", "description": "" }, { "name": "Data Policies", "description": "" }, { "name": "Descendants", "description": "" }, { "name": "Folder", "description": "" }, { "name": "Label", "description": "" }, { "name": "Like", "description": "" }, { "name": "Operation", "description": "" }, { "name": "Page", "description": "" }, { "name": "Redactions", "description": "" }, { "name": "Smart Link", "description": "" }, { "name": "Space", "description": "" }, { "name": "Space Permissions", "description": "" }, { "name": "Space Properties", "description": "" }, { "name": "Space Roles", "description": "" }, { "name": "Task", "description": "" }, { "name": "User", "description": "" }, { "name": "Version", "description": "" }, { "name": "Whiteboard", "description": "" } ], "paths": { "/admin-key": { "get": { "tags": [ "Admin Key" ], "operationId": "getAdminKey", "summary": "Get Admin Key", "description": "Returns information about the admin key if one is currently enabled for the calling user within the site.\n\n**[Permissions](https://support.atlassian.com/user-management/docs/give-users-admin-permissions/#Centralized-user-management-content) required**:\nUser must be an organization or site admin.", "responses": { "200": { "description": "Returned if an admin key is currently enabled for the calling user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminKeyResponse" } } } }, "401": { "description": "Returned if the authentication credentials are incorrect or missing from the request.", "content": {} }, "404": { "description": "Returned if the calling user does not currently have an admin key, if the calling user does not have permission to use admin keys, or if the site is not a Confluence Cloud Premium or Enterprise instance.", "content": {} } }, "x-atlassian-connect-scope": "INACCESSIBLE" }, "post": { "tags": [ "Admin Key" ], "operationId": "enableAdminKey", "summary": "Enable Admin Key", "description": "Enables admin key access for the calling user within the site. If an admin key already exists for the user, a new one will be issued with an updated expiration time.\n\n**Note:** The `durationInMinutes` field within the request body is optional. If the request body is empty or if the `durationInMinutes` is set to 0 minutes, a new admin key will be issued to the calling user with a default duration of 10 minutes.\n\n**[Permissions](https://support.atlassian.com/user-management/docs/give-users-admin-permissions/#Centralized-user-management-content) required**:\nUser must be an organization or site admin.", "requestBody": { "$ref": "#/components/requestBodies/AdminKeyRequest" }, "responses": { "200": { "description": "Returned if a new admin key is successfully issued for the calling user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminKeyResponse" } } } }, "400": { "description": "Returned if the request body contains an invalid `durationInMinutes`.", "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 use admin keys or if the site is not a Confluence Cloud Premium or Enterprise instance.", "content": {} } }, "x-atlassian-connect-scope": "INACCESSIBLE" }, "delete": { "tags": [ "Admin Key" ], "operationId": "disableAdminKey", "summary": "Disable Admin Key", "description": "Disables admin key access for the calling user within the site.\n\n**[Permissions](https://support.atlassian.com/user-management/docs/give-users-admin-permissions/#Centralized-user-management-content) required**:\nUser must be an organization or site admin.", "responses": { "204": { "description": "Returned if admin key access was successfully disabled for the calling user or if the user did not have an admin key in the first place.", "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 use admin keys or if the site is not a Confluence Cloud Premium or Enterprise instance.", "content": {} } }, "x-atlassian-connect-scope": "INACCESSIBLE" } }, "/attachments": { "get": { "tags": [ "Attachment" ], "operationId": "getAttachments", "summary": "Get attachments", "description": "Returns all attachments. The number of results is limited by the `limit` parameter and additional results (if available)\nwill be available through the `next` URL present in the `Link` response header.\n\n**[Permissions](https://confluence.atlassian.com/x/_AozKw) required**:\nPermission to view the container of the attachment.", "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "Used to sort the result by a particular field.", "schema": { "$ref": "#/components/schemas/AttachmentSortOrder" } }, { "name": "cursor", "in": "query", "required": false, "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": "status", "in": "query", "required": false, "description": "Filter the results to attachments based on their status. By default, `current` and `archived` are used.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "current", "archived", "trashed" ] } } }, { "name": "mediaType", "in": "query", "required": false, "description": "Filters on the mediaType of attachments. Only one may be specified.", "schema": { "type": "string" } }, { "name": "filename", "in": "query", "required": false, "description": "Filters on the file-name of attachments. Only one may be specified.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of attachments 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": 50, "minimum": 1, "maximum": 250, "type": "integer" } } ], "responses": { "200": { "description": "Returned if the requested attachments are returned.", "content": { "application/json": { "schema": { "title": "MultiEntityResult", "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/AttachmentBulk" } }, "_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\"`\n" } } }, "400": { "description": "Returned if an invalid request is provided.", "content": {} }, "401": { "description": "Returned if the authentication credentials are incorrect or missing\nfrom the request.", "content": {} } }, "security": [ { "basicAuth": [] }, { "oAuthDefinitions": [ "read:attachment:confluence" ] } ], "x-atlassian-oauth2-scopes": [ { "scheme": "oAuthDefinitions", "state": "Current", "scopes": [ "read:attachment:confluence" ] } ], "x-atlassian-connect-scope": "READ", "x-atlassian-data-security-policy": [ { "app-access-rule-exempt": false } ] } }, "/attachments/{id}": { "get": { "tags": [ "Attachment" ], "operationId": "getAttachmentById", "summary": "Get attachment by id", "description": "Returns a specific attachment.\n\n**[Permissions](https://confluence.atlassian.com/x/_AozKw) required**:\nPermission to view the attachment's container.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the attachment to be returned. If you don't know the attachment's ID, use Get attachments for page/blogpost/custom content.", "schema": { "type": "string", "pattern": "(att)?[0-9]+" } }, { "name": "version", "in": "query", "description": "Allows you to retrieve a previously published version. Specify the previous version's number to retrieve its details.", "schema": { "type": "integer" } }, { "name": "include-labels", "in": "query", "description": "Includes labels associated with this attachment in the response.\nThe number of results will be limited to 50 and sorted in the default sort order. \nA `meta` and `_links` property will be present to indicate if more results are available and a link to retrieve the rest of the results.", "schema": { "type": "boolean", "default": false } }, { "name": "include-properties", "in": "query", "description": "Includes content properties associated with this attachment in the response.\nThe number of results will be limited to 50 and sorted in the default sort order. \nA `meta` and `_links` property will be present to indicate if more results are available and a link to retrieve the rest of the results.", "schema": { "type": "boolean", "default": false } }, { "name": "include-operations", "in": "query", "description": "Includes operations associated with this attachment in the response, as defined in the `Operation` object.\nThe number of results will be limited to 50 and sorted in the default sort order. \nA `meta` and `_links` property will be present to indicate if more results are available and a link to retrieve the rest of the results.", "schema": { "type": "boolean", "default": false } }, { "name": "include-versions", "in": "query", "description": "Includes versions associated with this attachment in the response.\nThe number of results will be limited to 50 and sorted in the default sort order. \nA `meta` and `_links` property will be present to indicate if more results are available and a link to retrieve the rest of the results.", "schema": { "type": "boolean", "default": false } }, { "name": "include-version", "in": "query", "description": "Includes the current version associated with this attachment in the response.\nBy default this is included and can be omitted by setting the value to `false`.", "schema": { "type": "boolean", "default": true } }, { "name": "include-collaborators", "in": "query", "description": "Includes collaborators on the attachment.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Returned if the requested attachment is returned.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/AttachmentSingle" }, { "type": "object", "properties": { "_links": { "type": "object", "properties": { "base": { "type": "string", "description": "Base url of the Confluence site." } } } } } ] } } } }, "400": { "description": "Returned if an invalid request is provided.", "content": {} }, "401": { "description": "Returned if the authentication credentials are incorrect or missing\nfrom the request.", "content": {} }, "404": { "description": "Returned if the calling user does not have permission to view the\nrequested attachment or the attachment was not found.", "content": {} } }, "security": [ { "basicAuth": [] }, { "oAuthDefinitions": [ "read:attachment:confluence" ] } ], "x-atlassian-oauth2-scopes": [ { "scheme": "oAuthDefinitions", "state": "Current", "scopes": [ "read:attachment:confluence" ] } ], "x-atlassian-connect-scope": "READ", "x-atlassian-data-security-policy": [ { "app-access-rule-exempt": false } ] }, "delete": { "tags": [ "Attachment" ], "operationId": "deleteAttachment", "summary": "Delete attachment", "description": "Delete an attachment by id.\n\nDeleting an attachment moves the attachment to the trash, where it can be restored later. To permanently delete an attachment (or \"purge\" it),\nthe endpoint must be called on a **trashed** attachment with the following param `purge=true`.\n\n**[Permissions](https://confluence.atlassian.com/x/_AozKw) required**:\nPermission to view the container of the attachment.\nPermission to delete attachments in the space.\nPermission to administer the space (if attempting to purge).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the attachment to be deleted.", "schema": { "format": "int64", "type": "integer" } }, { "name": "purge", "in": "query", "required": false, "description": "If attempting to purge the attachment.", "schema": { "type": "boolean", "default": false } } ], "responses": { "204": { "description": "Returned if the attachment was successfully deleted.", "content": {} }, "400": { "description": "Returned if an invalid request is provided.", "content": {} }, "401": { "description": "Returned if the authentication credentials are incorrect or missing\nfrom the request.", "content": {} }, "404": { "description": "Returned if:\n- The provided attachment does not exist\n- The user does not have permissions to view the container of the attachment\n- The user does not have the needed permissions to delete an attachment in the space" } }, "security": [ { "basicAuth": [] }, { "oAuthDefinitions": [ "delete:attachment:confluence" ] } ], "x-atlassian-oauth2-scopes": [ { "scheme": "oAuthDefinitions", "state": "Current", "scopes": [ "delete:attachment:confluence" ] } ], "x-atlassian-connect-scope": "DELETE", "x-atlassian-data-security-policy": [ { "app-access-rule-exempt": false } ] } }, "/attachments/{id}/labels": { "get": { "tags": [ "Label" ], "operationId": "getAttachmentLabels", "summary": "Get labels for attachment", "description": "Returns the labels of specific attachment. The number of results is limited by the `limit` parameter and additional results (if available)\nwill be available through the `next` URL present in the `Link` response header.\n\n**[Permissions](https://confluence.atlassian.com/x/_AozKw) required**:\nPermission to view the parent content of the attachment and its corresponding space.\nOnly labels that the user has permission to view will be returned.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the attachment for which labels should be returned.", "schema": { "format": "int64", "type": "integer" } }, { "name": "prefix", "in": "query", "required": false, "description": "Filter the results to labels based on their prefix.", "schema": { "type": "string", "enum": [ "my", "team", "global", "system" ] } }, { "name": "sort", "in": "query", "required": false, "description": "Used to sort the result by a particular field.", "schema": { "type": "string", "items": { "$ref": "#/components/schemas/LabelSortOrder" } } }, { "name": "cursor", "in": "query", "required": false, "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 labels 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 labels are returned.", "content": { "application/json": { "schema": { "title": "MultiEntityResult