Confluence module

Complete API reference

The task-oriented sections below explain the most common workflows. These source-backed references list every public method and current signature for Server/Data Center, legacy Cloud, and the explicit Cloud V2 client.

class atlassian.confluence.server.Server(url, *args, **kwargs)

Confluence Server REST API wrapper

add_comment(page_id, text)

Add comment into page :param page_id :param text

add_content_labels(content_id, data, **kwargs)

Add labels to content.

add_space_permission_json_rpc(space_key, user, permission)

The JSON-RPC APIs for Confluence are provided here to help you browse and discover APIs you have access to. JSON-RPC APIs operate differently than REST APIs. To learn more about how to use these APIs, please refer to the Confluence JSON-RPC documentation on Atlassian Developers.

add_space_permissions(space_key, subject_type, subject_id, operation_key, operation_target)

Add permissions to a space

Parameters:

• space_key – str - key of space to add permissions to

• subject_type – str - type of subject to add permissions for

• subject_id – str - id of subject to add permissions for

• operation_key – str - key of operation to add permissions for

• operation_target – str - target of operation to add permissions for

Returns:

Current permissions of space

add_user(email, fullname, username, password)

That method related to creating user via json rpc for Confluence Server

add_user_in_restricted_page(user_name: str, page_id: str, restriction_type: Literal['View', 'Edit'])

add_user_to_group(group_name, username, **kwargs)

Add given user to a group :param group_name: str - name of group to add user to :param username: str - username of user to add to group :return: Current state of the group

anonymous()

Get information about how anonymous is represented in confluence :return:

append_page(page_id, title, append_body, parent_id=None, type='page', representation='storage', minor_edit=False)

Append content to an existing page.

append_body is normally a string of Confluence storage XHTML. A list or dict is supported with representation="storage" and is appended as pretty-printed JSON in a Confluence code block.

Parameters:

• parent_id – optional parent page ID

• page_id – page ID

• title – page title

• append_body – storage XHTML, or a list/dict to render as JSON

• type – content type; normally "page"

• representation – "storage" or legacy "wiki" markup

• minor_edit – whether to suppress watcher notifications

Returns:

the updated page response

archive_space(space_key)

Archive space :param space_key: :return:

attach_content(content, name, content_type='application/binary', page_id=None, title=None, space=None, comment=None)

Attach (upload) a file to a page, if it exists it will update automatically the version the new file and keep the old one. :param title: The page name :type title: str :param space: The space name :type space: str :param page_id: The page id to which we would like to upload the file :type page_id: str :param name: The name of the attachment :type name: str :param content: Contains the content which should be uploaded :type content: binary :param content_type: Specify the HTTP content type.

The default is “application/binary”

Parameters:

comment (str) – A comment describing this upload/file

Returns:

The attachment response.

Raises:

ApiNotFoundError – If no page ID is supplied and the title cannot be resolved in the requested space.

attach_file(filename, name=None, content_type=None, page_id=None, title=None, space=None, comment=None)

Attach (upload) a file to a page, if it exists it will update automatically the version the new file and keep the old one. :param title: The page name :type title: str :param space: The space name :type space: str :param page_id: The page id to which we would like to upload the file :type page_id: str :param filename: The file to upload (Specifies the content) :type filename: str :param name: Specifies name of the attachment. This parameter is optional.

Is no name give the file name is used as name

Parameters:

• content_type (str) – Specify the HTTP content type. The default is The default is “application/binary”

• comment (str) – A comment describing this upload/file

audit(start_date=None, end_date=None, start=None, limit=None, search_string=None)

Fetch a paginated list of AuditRecord instances dating back to a certain time :param start_date: :param end_date: :param start: :param limit: :param search_string: :return:

avatar_set_default_for_user(user_key)

Parameters:

user_key

Returns:

avatar_upload_for_user(user_key, data)

Parameters:

• user_key

• data – json like {“avatarDataURI”:”image in base64”}

Returns:

blog_post_exists(space_key, title, **kwargs)

Check if blog post exists.

change_my_password(oldpass, newpass)

That method related to changing calling user’s own password via json rpc for Confluence Server

change_user_password(username, password)

That method related to changing user password via json rpc for Confluence Server

check_access_mode()

check_long_task_result(task_id, expand=None)

Get result of long tasks :param task_id: task id :param expand: :return:

check_long_tasks_result(start=None, limit=None, expand=None)

Get result of long tasks :param start: OPTIONAL: The start point of the collection to return. Default: None (0). :param limit: OPTIONAL: The limit of the number of pages to return, this may be restricted by

fixed system limits. Default: 50

Parameters:

expand

Returns:

check_plugin_manager_status()

clean_all_caches()

Clean all caches from cache management

clean_jira_metadata_cache(global_id)

Clean cache for linked Jira app link PRIVATE method :param global_id: ID of Jira app link :return:

clean_package_cache(cache_name='com.gliffy.cache.gon')

Clean caches from cache management e.g. com.gliffy.cache.gon org.hibernate.cache.internal.StandardQueryCache_v5

collaborative_editing_disable()

Disable collaborative editing Related to the on-prem setup Confluence Data Center :return:

collaborative_editing_enable()

Disable collaborative editing Related to the on-prem setup Confluence Data Center :return:

collaborative_editing_get_configuration()

Get collaborative editing configuration Related to the on-prem setup Confluence Data Center :return:

collaborative_editing_restart()

Disable collaborative editing Related to the on-prem setup Confluence Data Center :return:

collaborative_editing_shared_draft_status()

Status of collaborative editing Related to the on-prem setup Confluence Data Center :return: false or true parameter in json

{

“sharedDraftsEnabled”: false

}

collaborative_editing_synchrony_status()

Status of collaborative editing Related to the on-prem setup Confluence Data Center :return: stopped or running parameter in json

{

“status”: “stopped”

}

content_types = {'.doc': 'application/msword', '.gif': 'image/gif', '.jpeg': 'image/jpeg', '.jpg': 'image/jpeg', '.pdf': 'application/pdf', '.png': 'image/png', '.svg': 'image/svg+xml', '.xls': 'application/vnd.ms-excel'}

convert_storage_to_view(storage)

Convert from Confluence XHTML format to view format :param storage: :return:

convert_wiki_to_storage(wiki)

Convert to Confluence XHTML format from wiki style :param wiki: :return:

cql(cql, start=0, limit=None, expand=None, include_archived_spaces=None, excerpt=None)

Get results from cql search result with all related fields Search for entities in Confluence using the Confluence Query Language (CQL) :param cql: :param start: OPTIONAL: The start point of the collection to return. Default: 0. :param limit: OPTIONAL: The limit of the number of issues to return, this may be restricted by

fixed system limits. Default by built-in method: 25

Parameters:

• excerpt – the excerpt strategy to apply to the result, one of : indexed, highlight, none. This defaults to highlight

• expand – OPTIONAL: the properties to expand on the search result, this may cause database requests for some properties

• include_archived_spaces – OPTIONAL: whether to include content in archived spaces in the result, this defaults to false

Returns:

cql_all(*args, **kwargs)

Return all paginated CQL results as a list.

Prefer iter_cql() for large result sets.

create_attachment(content_id, data, **kwargs)

Create new attachment.

create_comment(content_id, data, **kwargs)

Create new comment.

create_content(data, **kwargs)

Create new content.

create_content_property(content_id, data, **kwargs)

Create new content property.

create_group(name)

Create a group by given group parameter

Parameters:

name – str

Returns:

New group params

create_or_update_template(name, body, template_type='page', template_id=None, description=None, labels=None, space=None)

Creates a new or updates an existing content template.

Note, blueprint templates cannot be created or updated via the REST API.

If you provide a template_id then this method will update the template with the provided settings. If no template_id is provided, then this method assumes you are creating a new template.

Parameters:

• name (str) – If creating, the name of the new template. If updating, the name to change the template name to. Set to the current name if this field is not being updated.

• body (dict) –

  This object is used when creating or updating content. {

  ”storage”: {

  “value”: “<string>”, “representation”: “view”

  }

  }

• template_type (str) – OPTIONAL: The type of the new template. Default: “page”.

• template_id (str) – OPTIONAL: The ID of the template being updated. REQUIRED if updating a template.

• description (str) – OPTIONAL: A description of the new template. Max length 255.

• labels (list) –

  OPTIONAL: Labels for the new template. An array like: [

  {

  “prefix”: “<string>”, “name”: “<string>”, “id”: “<string>”, “label”: “<string>”,

  }

  ]

• space (dict) – OPTIONAL: The key for the space of the new template. Only applies to space templates. If not specified, the template will be created as a global template.

Returns:

create_page(space, title, body, parent_id=None, type='page', representation='storage', editor=None, full_width=False, status='current', version_comment=None)

Create page from scratch :param space: space key, not the display name. Personal-space keys

commonly look like ~<account-id>.

Parameters:

• title – page title

• body – page body in the selected representation

• parent_id – optional parent page ID

• type – content type; normally "page"

• representation – OPTIONAL: either Confluence ‘storage’ or ‘wiki’ markup format

• editor – OPTIONAL: v2 to be created in the new editor

• full_width – DEFAULT: False

• status – either ‘current’ or ‘draft’

• version_comment – optional message recorded with the first page version

Returns:

create_page_from_template(space, title, template_id, parent_id=None, replacements=None, **kwargs)

Create a page from a Server/Data Center content template.

Template bodies are read from the storage representation so that Confluence macros are retained. replacements maps literal template placeholders (for example {"{{REPORT_DATE}}": "2026-08-15"}) to their replacement values.

create_restricts_from_from_user(user_name: str, restriction_type: Literal['View', 'Edit'])

create_space(space_key, space_name=None, **kwargs)

Create space. Accepts either a full data dictionary or the legacy space_key/space_name pair.

delete_attachment(attachment_id, filename='', version=None, **kwargs)

Delete an attachment by content ID, or remove a legacy page attachment when filename/version is supplied.

delete_attachment_by_id(attachment_id, version)

Remove completely a file if version is None or delete version :param attachment_id: :param version: file version :return:

delete_comment(comment_id, **kwargs)

Delete comment.

delete_content(content_id, **kwargs)

Delete content.

delete_content_property(content_id, property_key, **kwargs)

Delete content property.

delete_page_property(page_id, page_property)

Delete the page (content) property e.g. delete key of hash :param page_id: content_id format :param page_property: key of property :return:

delete_plugin(plugin_key)

Delete plugin :param plugin_key: :return:

delete_space(space_key, **kwargs)

Delete a space by key.

Raises:

ApiNotFoundError: If Confluence responds with HTTP 404. Confluence

may use this status to avoid revealing an inaccessible space.

disable_plugin(plugin_key)

Disable a plugin :param plugin_key: :return:

download_attachment(attachment_id, **kwargs)

Download attachment.

download_attachments_from_page(page_id, path=None, start=0, limit=50, filename=None, to_memory=False, download_path=None)

Downloads attachments from a Confluence page. Supports downloading all files or a specific file. Files can either be saved to disk or returned as BytesIO objects for in-memory handling.

Parameters:

• page_id – str The ID of the Confluence page to fetch attachments from.

• path – str, optional Directory where attachments will be saved. If None, defaults to the current working directory. Ignored if to_memory is True.

• download_path – str, optional Deprecated alias for path retained for callers of older documentation. Do not pass both names with different values.

• start – int, optional The start point for paginated attachment fetching. Default is 0. Ignored if filename is specified.

• limit – int, optional The maximum number of attachments to fetch per request. Default is 50. Ignored if filename is specified.

• filename – str, optional The name of a specific file to download. If provided, only this file will be fetched.

• to_memory – bool, optional If True, attachments are returned as a dictionary of {filename: BytesIO object}. If False, files are written to the specified directory on disk.

Returns:

• If to_memory is True, returns a dictionary {filename: BytesIO object}.

• If to_memory is False, returns a summary dict: {“attachments_downloaded”: int, “path”: str}.

Raises:

• FileNotFoundError: If the specified path does not exist.

• PermissionError: If there are permission issues with the specified path.

• requests.HTTPError: If the HTTP request to fetch an attachment fails.

• Exception: For any unexpected errors.

enable_plugin(plugin_key)

Enable a plugin :param plugin_key: :return:

export_content(content_id, **kwargs)

Export content.

export_page(page_id)

Alias method for export page as pdf :param page_id: Page ID :return: PDF File

export_page_tree_as_pdf(page_id)

Return individual PDFs for a page subtree keyed by page ID.

Prefer iter_page_tree_as_pdf() for large hierarchies to avoid keeping every PDF in memory.

export_space(space_key, **kwargs)

Export space.

get_all_blog_posts_by_label(label, **kwargs)

Get all blog posts by label.

get_all_blog_posts_from_space(space_key, **kwargs)

Get all blog posts from space.

get_all_blog_posts_from_space_trash(space_key, **kwargs)

Get all blog posts from space trash.

get_all_blueprints_from_space(space, start=0, limit=None, expand=None)

Get all users blueprints from space. Experimental API :param space: Space Key :param start: OPTIONAL: The start point of the collection to return. Default: None (0). :param limit: OPTIONAL: The limit of the number of pages to return, this may be restricted by

fixed system limits. Default: 20

Parameters:

expand – OPTIONAL: expand e.g. body

get_all_draft_blog_posts_from_space(space_key, **kwargs)

Get all draft blog posts from space.

get_all_draft_pages_from_space(space_key, **kwargs)

Get all draft pages from space.

get_all_draft_pages_from_space_through_cql(space, start=0, limit=500, status='draft')

Search list of draft pages by space key Use case is cleanup old drafts from Confluence :param space: Space Key :param status: Can be changed :param start: OPTIONAL: The start point of the collection to return. Default: None (0). :param limit: OPTIONAL: The limit of the number of pages to return, this may be restricted by

fixed system limits. Default: 500

Returns:

get_all_groups(start=0, limit=1000)

Get all groups from Confluence User management :param start: OPTIONAL: The start point of the collection to return. Default: None (0). :param limit: OPTIONAL: The limit of the number of groups to return, this may be restricted by

fixed system limits. Default: 1000

Returns:

get_all_members(group_name='confluence-users', expand=None)

Get collection of all users in the given group :param group_name :param expand: OPTIONAL: A comma separated list of properties to expand on the content. status :return:

get_all_page_versions(page_id, limit=200, expand=None)

Return every version of a Server/Data Center page as a list.

get_all_pages_by_label(label, **kwargs)

Get all pages by label.

get_all_pages_from_space(space_key, **kwargs)

Get all pages from space.

get_all_pages_from_space_as_generator(space, start=0, limit=50, status=None, expand='history,space,version', content_type='page')

Retrieve all pages from a Confluence space using pagination.

Parameters:

• space – The space key to fetch pages from.

• start – OPTIONAL: The starting point of the collection. Default: 0.

• limit – OPTIONAL: The maximum number of pages per request. Default: 50.

• status – OPTIONAL: Filter pages by status (‘current’, ‘trashed’, ‘any’). Default: None.

• expand – OPTIONAL: Comma-separated list of properties to expand. Default: history,space,version.

• content_type – OPTIONAL: The content type to return (‘page’, ‘blogpost’). Default: page.

Returns:

Generator yielding pages one by one.

get_all_pages_from_space_raw(space, start=0, limit=50, status=None, expand=None, content_type='page')

Get all pages from space

Parameters:

• space

• start – OPTIONAL: The start point of the collection to return. Default: None (0).

• limit – OPTIONAL: The limit of the number of pages to return, this may be restricted by fixed system limits. Default: 50

• status – OPTIONAL: list of statuses the content to be found is in. Defaults to current is not specified. If set to ‘any’, content in ‘current’ and ‘trashed’ status will be fetched. Does not support ‘historical’ status for now.

• expand – OPTIONAL: a comma separated list of properties to expand on the content. Default value: history,space,version.

• content_type – the content type to return. Default value: page. Valid values: page, blogpost.

Returns:

get_all_pages_from_space_trash(space_key, **kwargs)

Get all pages from space trash.

get_all_restictions_for_content(content_id)

Let’s use the get_all_restrictions_for_content()

get_all_restrictions_for_content(content_id)

Returns info about all restrictions by operation. :param content_id: :return: Return the raw json response

get_all_restrictions_from_page_json_rpc(page_id)

The JSON-RPC APIs for Confluence are provided here to help you browse and discover APIs you have access to. JSON-RPC APIs operate differently than REST APIs. To learn more about how to use these APIs, please refer to the Confluence JSON-RPC documentation on Atlassian Developers.

get_all_space_permissions(space_key)

Returns list of permissions granted to users and groups in the particular space. :param space_key: :return:

get_all_spaces(start=0, limit=50, expand=None, space_type=None, space_status=None, label=None)

Get all spaces with provided limit :param start: OPTIONAL: The start point of the collection to return. Default: None (0). :param limit: OPTIONAL: The limit of the number of pages to return, this may be restricted by

fixed system limits. Default: 500

Parameters:

• space_type – OPTIONAL: Filter the list of spaces returned by type (global, personal)

• space_status – OPTIONAL: Filter the list of spaces returned by status (current, archived)

• label – OPTIONAL: Filter the list of spaces by a category label.

• expand – OPTIONAL: additional info, e.g. metadata, icon, description, homepage

get_all_templates_from_space(space, start=0, limit=None, expand=None)

Get all users templates from space. Experimental API ref: https://docs.atlassian.com/atlassian-confluence/1000.73.0/com/atlassian/confluence/plugins/restapi /resources/TemplateResource.html :param space: Space Key :param start: OPTIONAL: The start point of the collection to return. Default: None (0). :param limit: OPTIONAL: The limit of the number of pages to return, this may be restricted by

fixed system limits. Default: 20

Parameters:

expand – OPTIONAL: expand e.g. body

get_attachment(attachment_id, **kwargs)

Get attachment by ID.

get_attachment_history(attachment_id, limit=200, start=0)

Get attachment history :param attachment_id :param limit :param start :return

get_attachments(content_id, **kwargs)

Get content attachments.

get_attachments_from_content(page_id, start=0, limit=50, expand=None, filename=None, media_type=None)

Get attachments for page :param page_id: :param start: :param limit: :param expand: :param filename: :param media_type: :return:

get_blog_post_by_title(space_key, title, **kwargs)

Get blog post by title and space key.

get_blueprint_templates(space=None, start=0, limit=None, expand=None)

Gets all templates provided by blueprints.

Use this method to retrieve all global blueprint templates or all blueprint templates in a space. :param space: OPTIONAL: The key of the space to be queried for templates. If space is not

specified, global blueprint templates will be returned.

Parameters:

• start – OPTIONAL: The starting index of the returned templates. Default: None (0).

• limit – OPTIONAL: The limit of the number of pages to return, this may be restricted by fixed system limits. Default: 25

• expand – OPTIONAL: A multi-value parameter indicating which properties of the template to expand.

get_child_id_list(page_id, type='page', start=None, limit=None)

Find a list of Child id :param page_id: A string containing the id of the type content container. :param type: :param start: OPTIONAL: The start point of the collection to return. Default: None (0). :param limit: OPTIONAL: how many items should be returned after the start index. Default: Site limit 200. :return:

get_child_pages(page_id, **kwargs)

Get child pages for the provided page_id :param page_id: :return:

get_child_title_list(page_id, type='page', start=None, limit=None)

Find a list of Child title :param page_id: A string containing the id of the type content container. :param type: :param start: OPTIONAL: The start point of the collection to return. Default: None (0). :param limit: OPTIONAL: how many items should be returned after the start index. Default: Site limit 200. :return:

get_comment(comment_id, **kwargs)

Get comment by ID.

get_comments(content_id, **kwargs)

Get content comments.

get_content(content_id, **kwargs)

Get content by ID.

get_content_ancestors(content_id, **kwargs)

Get ancestor content.

get_content_by_id(content_id, **kwargs)

Get content by ID with expand options.

get_content_by_title(space_key, title, **kwargs)

Get content by title and space key.

get_content_by_type(content_type, **kwargs)

Get content by type (page, blogpost, etc.).

get_content_children(content_id, **kwargs)

Get child content.

get_content_descendants(content_id, **kwargs)

Get descendant content.

get_content_history(content_id)

get_content_history_by_version_number(content_id, version_number, expand=None)

Get content history by version number :param content_id: :param version_number: :return:

get_content_id(space_key, title, content_type='page')

Get content ID by title and space key.

get_content_labels(content_id, **kwargs)

Get content labels.

get_content_properties(content_id, **kwargs)

Get content properties.

get_content_property(content_id, property_key, **kwargs)

Get content property by key.

get_content_template(template_id)

Get a content template.

This includes information about the template, like the name, the space or blueprint

that the template is in, the body of the template, and more.

Parameters:

template_id (str) – The ID of the content template to be returned

Returns:

get_content_templates(space=None, start=0, limit=None, expand=None)

Get all content templates. Use this method to retrieve all global content templates or all content templates in a space. :param space: OPTIONAL: The key of the space to be queried for templates. If space is not

specified, global templates will be returned.

Parameters:

• start – OPTIONAL: The start point of the collection to return. Default: None (0).

• limit – OPTIONAL: The limit of the number of pages to return, this may be restricted by fixed system limits. Default: 25

• expand – OPTIONAL: A multi-value parameter indicating which properties of the template to expand. e.g. body

get_current_user(**kwargs)

Get current user.

get_descendant_page_id(space, parent_id, title)

Provide space, parent_id and title of the descendant page, it will return the descendant page_id :param space: str :param parent_id: int :param title: str :return: page_id of the page whose title is passed in argument

get_descendant_pages(content_id, **kwargs)

Get all descendant pages of a content item.

get_draft_content(content_id, **kwargs)

Get draft content.

get_draft_page_by_id(page_id, status='draft', expand=None)

Gets content by id with status = draft :param page_id: Content ID :param status: (str) list of content statuses to filter results on. Default value: [draft] :param expand: OPTIONAL: Default value: history,space,version

We can also specify some extensions such as extensions.inlineProperties (for getting inline comment-specific properties) or extensions. Resolution for the resolution status of each comment in the results

Returns:

get_group(group_name, **kwargs)

Get group by name.

get_group_members(group_name='confluence-users', start=None, limit=None, expand=None, **kwargs)

Get a paginated collection of users in the given group :param group_name :param start: OPTIONAL: The start point of the collection to return. :param limit: OPTIONAL: The limit of the number of users to return. :param expand: OPTIONAL: A comma separated list of properties to expand. :return:

get_groups(**kwargs)

Get all groups.

get_health(**kwargs)

Get API health status.

get_home_page_of_space(space_key)

Get information about a space through space key :param space_key: The unique space key name :return: Returns homepage

get_jira_metadata(page_id)

Get linked Jira ticket metadata PRIVATE method :param page_id: Page Id :return:

get_jira_metadata_aggregated(page_id)

Get linked Jira ticket aggregated metadata PRIVATE method :param page_id: Page Id :return:

get_labels(**kwargs)

Get all labels.

get_license_details()

Returns the license detailed information

get_license_max_users()

Returns the license max users

get_license_remaining()

Returns the available license seats remaining

get_license_user_count()

Returns the total used seats in the license

get_metadata(**kwargs)

Get API metadata.

get_mobile_parameters(username)

Get mobile paramaters :param username: :return:

get_page_ancestors(page_id)

Provide the ancestors from the page (content) id :param page_id: content_id format :return: get properties

get_page_as_pdf(page_id)

Export page as standard pdf exporter :param page_id: Page ID :return: PDF File

get_page_as_word(page_id)

Export a page through Confluence’s legacy Word exporter.

Returns the response bytes exactly as provided by Confluence. The exporter does not produce a DOCX file (nor necessarily a binary DOC file); its output is a Word-readable multipart HTML document. There is no supported Confluence REST endpoint for DOCX export.

Parameters:

page_id – Page ID

Returns:

Legacy Word-export bytes

get_page_by_id(page_id, expand=None, status=None, version=None)

Returns a piece of Content. Example request URI(s): http://example.com/confluence/rest/api/content/1234?expand=space,body.view,version,container http://example.com/confluence/rest/api/content/1234?status=any :param page_id: Content ID :param status: (str) list of Content statuses to filter results on. Default value: [current] :param version: (int) :param expand: OPTIONAL: Default value: history,space,version

We can also specify some extensions such as extensions.inlineProperties (for getting inline comment-specific properties) or extensions. Resolution for the resolution status of each comment in the results

Returns:

get_page_by_title(space_key, title, **kwargs)

Get page by title and space key.

get_page_child_by_type(page_id, type='page', start=None, limit=None, expand=None)

Provide content by type (page, blog, comment) :param page_id: A string containing the id of the type content container. :param type: :param start: OPTIONAL: The start point of the collection to return. Default: None (0). :param limit: OPTIONAL: how many items should be returned after the start index. Default: Site limit 200. :param expand: OPTIONAL: expand e.g. history :return:

get_page_child_count(page_id, type='page')

Return the number of direct children of type without listing them.

Confluence returns the collection size when the corresponding child collection is expanded, so this requires one content request rather than paginating all children.

get_page_comments(content_id, expand=None, parent_version=None, start=0, limit=25, location=None, depth=None)

Return a page’s comments through the separate comments endpoint.

Comments are not included in get_page_by_id(). To retrieve a rendered comment body and author metadata, use expand='body.view,history,version'. The initial author is available in history.createdBy and the latest editor in version.by.

Parameters:

• content_id – Page/content ID

• expand – Content expansions, for example body.view,history,version. Inline-comment metadata can use extensions.inlineProperties,extensions.resolution.

• parent_version – Filter comments for a parent version

• start – Page offset

• limit – Number of comments per response page

• location – inline to request inline comments

• depth – Nested comment depth

Returns:

Paginated Confluence comment response

get_page_id(space, title, type='page')

Provide content id from search result by title and space. :param space: SPACE key :param title: title :param type: type of content: Page or Blogpost. Defaults to page :return:

get_page_labels(page_id, prefix=None, start=None, limit=None)

Returns the list of labels on a piece of Content. :param page_id: A string containing the id of the labels content container. :param prefix: OPTIONAL: The prefixes to filter the labels with {@see Label.Prefix}.

Default: None.

Parameters:

• start – OPTIONAL: The start point of the collection to return. Default: None (0).

• limit – OPTIONAL: The limit of the number of labels to return, this may be restricted by fixed system limits. Default: 200.

Returns:

The JSON data returned from the content/{id}/label endpoint, or the results of the callback. Will raise requests.HTTPError on bad input, potentially.

get_page_properties(page_id, limit=100, expand=None)

Return every property attached to a page.

Confluence paginates this endpoint and otherwise returns only its small server-defined default page (commonly ten properties). Pagination is handled internally; limit controls the size of each HTTP request, not the number of properties returned.

Parameters:

• page_id – content ID

• limit – maximum properties requested per API call

• expand – optional property fields to expand

Returns:

list of page property objects

get_page_property(page_id, page_property_key)

Get the page (content) property e.g. get key of hash :param page_id: content_id format :param page_property_key: key of property :return:

get_page_space(page_id)

Get space key from page ID.

get_page_version_contributors(page_id, version_number)

Return every known contributor to a page revision.

Collaborative-editing revisions expose a collaborators collection. Older Confluence releases expose only by; in that case the saving author is returned as a one-item list.

get_pages_by_title(space, title, start=0, limit=200, expand=None)

Provide pages by title search :param space: Space key :param title: Title of the page :param start: OPTIONAL: The start point of the collection to return. Default: None (0). :param limit: OPTIONAL: The limit of the number of labels to return, this may be restricted by

fixed system limits. Default: 200.

Parameters:

expand – OPTIONAL: expand e.g. history

Returns:

The JSON data returned from searched results the content endpoint, or the results of the callback. Will raise requests.HTTPError on bad input, potentially. If it has IndexError then return the None.

get_parent_content_id(page_id)

Provide parent content id from page id :type page_id: str :return:

get_parent_content_title(page_id)

Provide parent content title from page id :type page_id: str :return:

get_permissions_granted_to_anonymous_for_space(space_key)

Get permissions granted to anonymous user for the given space :param space_key: :return:

get_permissions_granted_to_group_for_space(space_key, group_name)

Get permissions granted to group for the given space :param space_key: :param group_name: :return:

get_permissions_granted_to_user_for_space(space_key, user_key)

Get permissions granted to user for the given space :param space_key: :param user_key: :return:

get_plugin_info(plugin_key)

Provide plugin info :return a json of installed plugins

get_plugin_license_info(plugin_key)

Provide plugin license info :return a json specific License query

get_plugins_info()

Provide plugins info :return a json of installed plugins

get_reindex_progress(**kwargs)

Get reindex progress.

get_space(space_key, expand=None, params=None, **kwargs)

Get information about a space through space key :param space_key: The unique space key name :param expand: OPTIONAL: additional info from description, homepage :param params: OPTIONAL: dictionary of additional URL parameters :return: Returns the space along with its ID

get_space_content(space_key, depth=None, start=None, limit=None, content_type=None, expand=None, **kwargs)

Get space content. You can specify which type of content want to receive, or get all content types. Use expand to get specific content properties or page :param content_type: :param space_key: The unique space key name :param depth: OPTIONAL: all|root :param start: OPTIONAL: The start point of the collection to return. :param limit: OPTIONAL: The limit of the number of pages to return. :param expand: OPTIONAL: additional content properties to expand. :return: Returns the space content

get_space_export(space_key: str, export_type: str) → str

Export a Confluence space to a file of the specified type. (!) This method was developed for Confluence Cloud and may not work with Confluence on-prem. (!) This is an experimental method that does not trigger an officially supported REST endpoint. It may break if Atlassian changes the space export front-end logic.

Parameters:

• space_key – The key of the space to export.

• export_type – The type of export to perform. Valid values are: ‘html’, ‘csv’, ‘xml’, ‘pdf’.

Returns:

The URL to download the exported file.

get_space_names(start=0, limit=50, space_type=None, space_status=None, label=None)

Return every visible Server/Data Center space name.

Only the space directory metadata endpoint is requested; no page or space content is downloaded.

get_space_permissions(space_key, **kwargs)

Get space permissions.

get_space_property(space_key, expand=None)

get_space_settings(space_key, **kwargs)

Get space settings.

get_spaces(**kwargs)

Get all spaces.

get_subtree_of_content_ids(page_id)

Get subtree of page ids :param page_id: :return: Set of page ID

get_tables_from_page(page_id)

Return a consistent table summary for a page.

The returned dictionary always contains page_id, number_of_tables_in_page, and tables_content. Empty pages and pages without tables return a count of zero and an empty list.

get_template(template_id, **kwargs)

Get template by ID.

get_template_by_id(template_id)

Get user template by id. Experimental API Use case is get template body and create page from that

get_templates(**kwargs)

Get all templates.

get_trash_content(space_key, **kwargs)

Get trash content.

get_trashed_contents_by_space(space_key, cursor=None, expand=None, limit=100)

Get trashed contents by space :param space_key: :param cursor: :param expand: :param limit: :return:

get_user(username, **kwargs)

Get user by username.

get_user_by_key(user_key, **kwargs)

Get user by key.

get_user_details_by_accountid(accountid, expand=None)

Get information about a user through accountid :param accountid: The account id :param expand: OPTIONAL expand for get status of user.

Possible param is “status”. Results are “Active, Deactivated”

Returns:

Returns the user details

get_user_details_by_userkey(userkey, expand=None)

Get information about a user through user key :param userkey: The user key :param expand: OPTIONAL expand for get status of user.

Possible param is “status”. Results are “Active, Deactivated”

Returns:

Returns the user details

get_user_details_by_username(username, expand=None)

Get information about a user through username :param username: The username :param expand: OPTIONAL expand for get status of user.

Possible param is “status”. Results are “Active, Deactivated”

Returns:

Returns the user details

get_users(**kwargs)

Get all users.

get_users_from_restricts_in_page_by_type(page_id: str, restriction_type: Literal['View', 'Edit'])

has_unknown_attachment_error(page_id)

Check has unknown attachment error on page :param page_id: :return:

health_check()

Get health status https://confluence.atlassian.com/jirakb/how-to-retrieve-health-check-results-using-rest-api-867195158.html :return:

history(page_id)

is_page_content_is_already_updated(page_id, body, title=None)

Compare content and check is already updated or not :param page_id: Content ID for retrieve storage value :param body: Body for compare it :param title: Title to compare :return: True if the same

iter_cql(cql, start=0, limit=None, expand=None, include_archived_spaces=None, excerpt=None)

Yield every result of a CQL search, following Confluence pagination.

Unlike cql(), this does not materialize all results in memory.

iter_page_tree_as_pdf(page_id)

Yield (page_id, pdf_bytes) for a page and all descendant pages.

Confluence exposes single-page PDF export but does not provide a supported REST operation for one merged arbitrary subtree PDF. Results are yielded in depth-first page-tree order so callers can stream files to disk or merge them with their preferred PDF library.

iter_page_versions(page_id, limit=200, expand=None)

Yield every version of a Server/Data Center page.

The dedicated content/{id}/version endpoint is paginated. This method follows its links lazily, avoiding one request per version.

iter_space_exports(space_keys, export_type: str)

Yield exported-space download URLs one space at a time.

The underlying Confluence export is an asynchronous browser workflow. Confluence limits concurrent exports, so this iterator intentionally waits for each export to finish before starting the next one. It is a safer alternative to invoking get_space_export() concurrently from multiple threads.

Parameters:

• space_keys – Iterable of Confluence space keys.

• export_type – Export type accepted by get_space_export().

Returns:

Iterator of (space_key, download_url) tuples.

move_page(space_key, page_id, target_id=None, target_title=None, position='append')

Move page method :param space_key: :param page_id: :param target_title: :param target_id: :param position: topLevel or append , above, below :return:

page_exists(space_key, title, **kwargs)

Check if page exists.

page_has_children(page_id, type='page')

Return whether a page has at least one direct child of type.

prepend_page(page_id, title, prepend_body, parent_id=None, type='page', representation='storage', minor_edit=False)

Append body to page if already exist :param parent_id: :param page_id: :param title: :param prepend_body: :param type: :param representation: OPTIONAL: either Confluence ‘storage’ or ‘wiki’ markup format :param minor_edit: Indicates whether to notify watchers about changes.

If False then notifications will be sent.

Returns:

reindex()

Trigger reindexing of Confluence content It is not public method for reindex Confluence :return:

reindex_get_status()

Get reindex status of Confluence :return:

remove_content(content_id)

Remove any content :param content_id: :return:

remove_content_history(page_id, version_number)

Remove content history. It works as experimental method :param page_id: :param version_number: version number :return:

remove_content_history_in_cloud(page_id, version_id)

Remove content history. It works in CLOUD :param page_id: :param version_id: :return:

remove_content_label(content_id, label_name, **kwargs)

Remove label from content.

remove_group(name)

Delete a group by given group parameter If you delete a group and content is restricted to that group, the content will be hidden from all users

Parameters:

name – str

Returns:

remove_page(page_id, status=None, recursive=False)

Remove a page and optionally its child pages.

Parameters:

• page_id – page ID

• status – optional content status (for example "trashed")

• recursive – if True, remove child pages before this page

Returns:

the successful HTTP status code (normally 204). When the client has advanced_mode=True, return the raw response instead.

remove_page_as_draft(page_id)

This method removes a page from trash if it is a draft :param page_id: :return:

remove_page_attachment_keep_version(page_id, filename, keep_last_versions)

Keep last versions :param filename: :param page_id: :param keep_last_versions: :return:

remove_page_from_trash(page_id)

This method removes a page from trash :param page_id: :return:

remove_page_history(page_id, version_number)

Remove content history. It works as experimental method :param page_id: :param version_number: version number :return:

remove_page_history_keep_version(page_id, keep_last_versions)

Remove the oldest page versions while retaining the requested number of newest versions.

Confluence version numbers are immutable: deleting version 1 does not cause version 2 to become version 1. Delete each obsolete version number exactly once rather than repeatedly deleting version 1.

Parameters:

• page_id – Page whose history should be pruned.

• keep_last_versions – Number of latest versions to retain. Must be a positive integer.

remove_page_label(page_id: str, label: str)

Delete Confluence page label :param page_id: content_id format :param label: label name :return:

remove_permissions_from_anonymous_for_space(space_key, operations=None)

Revoke permissions from anonymous user in the given space. If anonymous user doesn’t have permissions that we are trying to revoke, those permissions will be silently skipped. Multiple permissions could be passed in one request. Supported targetType and operationKey pairs:

space read space administer space export space restrict space delete_own space delete_mail page create page delete blogpost create blogpost delete comment create comment delete attachment create attachment delete :param space_key: :param operations: :return:

remove_permissions_from_group_for_space(space_key, group_name, operations=None)

Revoke permissions from a group in the given space. If group doesn’t have permissions that we are trying to revoke, those permissions will be silently skipped. Multiple permissions could be passed in one request. Supported targetType and operationKey pairs:

space read space administer space export space restrict space delete_own space delete_mail page create page delete blogpost create blogpost delete comment create comment delete attachment create attachment delete :param space_key: :param group_name: :param operations: :return:

remove_permissions_from_user_for_space(space_key, user_key, operations=None)

Revoke permissions from a user in the given space. If user doesn’t have permissions that we are trying to revoke, those permissions will be silently skipped. Multiple permissions could be passed in one request. Supported targetType and operationKey pairs:

space read space administer space export space restrict space delete_own space delete_mail page create page delete blogpost create blogpost delete comment create comment delete attachment create attachment delete :param space_key: :param user_key: :param operations: :return:

remove_space_permission(space_key, user, permission)

The JSON-RPC APIs for Confluence are provided here to help you browse and discover APIs you have access to. JSON-RPC APIs operate differently than REST APIs. To learn more about how to use these APIs, please refer to the Confluence JSON-RPC documentation on Atlassian Developers.

remove_template(template_id)

Deletes a template.

This results in different actions depending on the type of template:

• If the template is a content template, it is deleted.

• If the template is a modified space-level blueprint template, it reverts to the template

  inherited from the global-level blueprint template.

• If the template is a modified global-level blueprint template, it reverts to the default

  global-level blueprint template.

Note: Unmodified blueprint templates cannot be deleted.

Parameters:

template_id (str) – The ID of the template to be deleted.

Returns:

remove_trashed_contents_by_space(space_key)

Remove all content from the trash in the given space, deleting them permanently.Example request URI: :param space_key: :return:

remove_user_from_group(group_name, username, **kwargs)

Remove the given {@link User} identified by username from the given {@link Group} identified by groupName. This method is idempotent i.e. if the membership is not present then no action will be taken.

Parameters:

• username – str - username of user to add to group

• group_name – str - name of group to add user to

Returns:

Current state of the group

request(method='GET', path='/', data=None, json=None, flags=None, params=None, headers=None, files=None, trailing=None, absolute=False, advanced_mode=False, allow_redirects=True)

Parameters:

• method

• path

• data

• json

• flags

• params

• headers

• files

• trailing – bool - OPTIONAL: Add trailing slash to url

• absolute – bool, OPTIONAL: Do not prefix url, url is absolute

• advanced_mode – bool, OPTIONAL: Return the raw response

Returns:

scrap_regex_from_page(page_id, regex)

Method scraps regex patterns from a Confluence page_id.

Parameters:

• page_id – The ID of the Confluence page.

• regex – The regex pattern to scrape.

Returns:

A list of regex matches.

search_content(query, **kwargs)

Search content using CQL.

search_spaces(query, **kwargs)

Search spaces.

set_inline_tasks_checkbox(page_id, task_id, status)

Set inline task element value status is CHECKED or UNCHECKED :return:

set_page_label(page_id, label)

Set a label on the page :param page_id: content_id format :param label: label to add :return:

set_page_property(page_id, data)

Set the page (content) property e.g. add hash parameters :param page_id: content_id format :param data: property dictionary, or a JSON string representing one :return:

set_permissions_to_anonymous_for_space(space_key, operations=None)

Grant permissions to anonymous user in the given space. Operation doesn’t override existing permissions, will only add those one that weren’t granted before. Multiple permissions could be passed in one request. Supported targetType and operationKey pairs:

space read space administer space export space restrict space delete_own space delete_mail page create page delete blogpost create blogpost delete comment create comment delete attachment create attachment delete :param space_key: :param operations: :return:

set_permissions_to_group_for_space(space_key, group_name, operations=None)

Grant permissions to group in the given space. Operation doesn’t override existing permissions, will only add those one that weren’t granted before. Multiple permissions could be passed in one request. Supported targetType and operationKey pairs:

space read space administer space export space restrict space delete_own space delete_mail page create page delete blogpost create blogpost delete comment create comment delete attachment create attachment delete :param space_key: :param group_name: :param operations: :return:

set_permissions_to_multiple_items_for_space(space_key, user_key=None, group_name=None, operations=None)

Sets permissions to multiple users/groups in the given space. Request should contain all permissions that user/group/anonymous user will have in a given space. If permission is absent in the request, but was granted before, it will be revoked. If empty list of permissions passed to user/group/anonymous user, then all their existing permissions will be revoked. If user/group/anonymous user not mentioned in the request, their permissions will not be revoked.

Maximum 40 different users/groups/anonymous user could be passed in the request. :param space_key: :param user_key: :param group_name: :param operations: :return:

set_permissions_to_user_for_space(space_key, user_key, operations=None)

Grant permissions to user in the given space. Operation doesn’t override existing permissions, will only add those one that weren’t granted before. Multiple permissions could be passed in one request. Supported targetType and operationKey pairs:

space read space administer space export space restrict space delete_own space delete_mail page create page delete blogpost create blogpost delete comment create comment delete attachment create attachment delete :param space_key: :param user_key: :param operations: :return:

set_restrictions_for_content(content_id, restrictions)

Set page or blog-post restrictions using the REST API.

restrictions is a list of ContentRestriction objects. Each supplied operation replaces its existing restrictions; operations not present in the list are unchanged. Supplying an empty user or group list clears that subject type for the operation.

Example:

[{
    "operation": "read",
    "restrictions": {
        "user": [{"type": "known", "username": "alice"}],
        "group": [{"type": "group", "name": "engineering"}],
    },
}]

set_space_homepage(space_key, homepage_id)

Set a Server/Data Center space’s homepage to an existing page.

homepage_id must identify a page in the target space. The caller needs permission to administer the space and view the chosen page.

share_with_others(page_id, group, message)

Notify members (currently only groups implemented) about something on that page link: https://jira.atlassian.com/browse/CONFSERVER-96030

synchrony_disable()

Disable Synchrony :return:

synchrony_enable()

Enable Synchrony :return:

synchrony_get_configuration()

Status of collaborative editing Related to the on-prem setup Confluence Data Center :return:

synchrony_remove_draft(page_id)

Status of collaborative editing Related to the on-prem setup Confluence Data Center :return:

team_calendar_events(sub_calendar_id, start, end, user_time_zone_id=None)

Get calendar event status :param sub_calendar_id: :param start: :param end: :param user_time_zone_id: :return:

team_calendars_get_sub_calendars(include=None, viewing_space_key=None, calendar_context=None)

Get subscribed calendars :param include: :param viewing_space_key: :param calendar_context: :return:

team_calendars_get_sub_calendars_watching_status(include=None)

update_attachment(attachment_id, data, **kwargs)

Update existing attachment.

update_comment(comment_id, data, **kwargs)

Update existing comment.

update_content(content_id, data, **kwargs)

Update existing content.

update_content_property(content_id, property_key, data, **kwargs)

Update existing content property.

update_existing_page(page_id, title, body, type='page', representation='storage', minor_edit=False, version_comment=None, full_width=False)

Backward-compatible alias for update_page().

body is sent unchanged. In particular, callers updating a table that contains Confluence image macros must retain the original storage markup. pandas.read_html cannot preserve those macros and its subsequent to_html output may replace image cells with NaN.

update_or_create(parent_id=None, title=None, body=None, representation='storage', minor_edit=False, version_comment=None, editor=None, full_width=False, space=None)

Update page or create a page if it is not exists :param parent_id: optional parent page ID. Omit for a top-level page. :param title: page title :param body: page body :param representation: OPTIONAL: either Confluence ‘storage’ or ‘wiki’ markup format :param minor_edit: Update page without notification :param version_comment: Version comment :param editor: OPTIONAL: v2 to be created in the new editor :param full_width: OPTIONAL: Default is False :param space: space key. Required when parent_id is omitted. :return:

Note:

Confluence does not update archived pages through this workflow. Restore the page to the current state before calling this method.

update_page(page_id, title, body=None, parent_id=None, type='page', representation='storage', minor_edit=False, version_comment=None, always_update=False, full_width=False)

Update an existing page.

body must be Confluence storage XHTML when representation is "storage" (the default), not arbitrary browser HTML. Escape only dynamic text or attribute values; do not escape the complete markup or Confluence macros. A literal & in text must be &. Existing entities such as " must not be escaped a second time.

Parameters:

• page_id – existing Confluence page ID

• title – page title

• body – storage XHTML or wiki markup matching representation

• parent_id – optional parent page ID; omit to retain the parent

• type – content type; normally "page"

• representation – "storage" for editable storage XHTML or "wiki" for legacy wiki markup

• minor_edit – Indicates whether to notify watchers about changes. If False then notifications will be sent.

• version_comment – Version comment

• always_update – Whether always to update (suppress content check)

• full_width – OPTIONAL: Default False

Returns:

The updated page response.

Raises:

ApiNotFoundError – If the page cannot be found while retrieving its current version.

update_page_property(page_id, data)

Update the page (content) property. Use json data or independent keys :param data: property dictionary, or a JSON string representing one :param page_id: content_id format :data: property data in json format :return:

update_plugin_license(plugin_key, raw_license)

Update license for plugin :param plugin_key: :param raw_license: :return:

update_restrictions_for_page_json_rpc(page_id, permission_type, content_permissions)

The JSON-RPC APIs for Confluence are provided here to help you browse and discover APIs you have access to. JSON-RPC APIs operate differently than REST APIs. To learn more about how to use these APIs, please refer to the Confluence JSON-RPC documentation on Atlassian Developers.

update_space(space_key, data, **kwargs)

Update an existing Server/Data Center space with a REST payload.

upload_plugin(plugin_path)

Provide plugin path for upload into Jira e.g. useful for auto deploy :param plugin_path: :return:

class atlassian.confluence.cloud.Cloud(url='https://api.atlassian.com/', *args, **kwargs)

Confluence Cloud REST API wrapper

add_content_labels(content_id, data, **kwargs)

Add labels to content.

blog_post_exists(space_key, title, **kwargs)

Check if blog post exists.

cql(cql, **kwargs)

Return one page of Cloud CQL search results.

cql_all(cql, **kwargs)

Return all paginated Cloud CQL results as a list.

Prefer iter_cql() for large result sets.

create_attachment(content_id, data, **kwargs)

Create new attachment.

create_comment(content_id, data, **kwargs)

Create new comment.

create_content(data, **kwargs)

Create new content.

create_content_property(content_id, data, **kwargs)

Create new content property.

create_or_update_template(name, body, template_type='page', template_id=None, description=None, labels=None, space=None)

Create or update a legacy Confluence Cloud content template.

The template API remains a V1 endpoint in Confluence Cloud. It is therefore addressed explicitly rather than through this client’s V2 root. body must be the body object returned by get_content_template(), or a storage body such as {"storage": {"value": "...", "representation": "storage"}}.

create_space(data, **kwargs)

Create new space.

delete_attachment(attachment_id, **kwargs)

Delete attachment.

delete_comment(comment_id, **kwargs)

Delete comment.

delete_content(content_id, **kwargs)

Delete content.

delete_content_property(content_id, property_key, **kwargs)

Delete content property.

delete_space(space_id, **kwargs)

Delete space.

export_content(content_id, **kwargs)

Export content.

export_page(page_id)

Alias for get_page_as_pdf().

export_space(space_id, **kwargs)

Export space.

get_all_blog_posts_from_space(space_key, **kwargs)

Get all blog posts from space.

get_all_groups(start=0, limit=1000)

Return the groups from a Cloud group result page.

This retains the legacy return shape while using the supported Cloud endpoint. Use each group’s id with get_group_members().

get_all_members(group_id, expand=None)

Return all members of a Cloud group identified by its ID.

get_all_page_versions(page_id, limit=200, expand=None)

Return every version of a legacy Confluence Cloud page as a list.

get_all_pages_from_space(space_key, **kwargs)

Get all pages from space.

get_all_spaces(**kwargs)

Get all spaces with full pagination.

Returns a generator yielding each space dict from the Confluence Cloud v2 endpoint /wiki/api/v2/spaces. Replaces the legacy v1 get_all_spaces (which hit /rest/api/space) — that endpoint is not available on the OAuth API gateway and returns GoneException: This deprecated endpoint has been removed.

get_attachment(attachment_id, **kwargs)

Get attachment by ID.

get_attachments(content_id, **kwargs)

Get content attachments.

get_blog_post_by_title(space_key, title, **kwargs)

Get blog post by title and space key.

get_child_id_list(page_id, type='page', start=None, limit=None)

Find a list of Child id :param page_id: A string containing the id of the type content container. :param type: :param start: OPTIONAL: The start point of the collection to return. Default: None (0). :param limit: OPTIONAL: how many items should be returned after the start index. Default: Site limit 200. :return:

get_child_pages(content_id, **kwargs)

Get child pages of a content item.

get_child_title_list(page_id, type='page', start=None, limit=None)

Find a list of Child title :param page_id: A string containing the id of the type content container. :param type: :param start: OPTIONAL: The start point of the collection to return. Default: None (0). :param limit: OPTIONAL: how many items should be returned after the start index. Default: Site limit 200. :return:

get_comment(comment_id, **kwargs)

Get comment by ID.

get_comments(content_id, **kwargs)

Get content comments.

get_content(content_id, **kwargs)

Get content by ID.

get_content_analytics(content_id, **kwargs)

Get content analytics.

get_content_ancestors(content_id, **kwargs)

Get ancestor content.

get_content_by_type(content_type, **kwargs)

Get content by type (page, blogpost, etc.).

get_content_children(content_id, **kwargs)

Get child content.

get_content_descendants(content_id, **kwargs)

Get descendant content.

get_content_labels(content_id, **kwargs)

Get content labels.

get_content_properties(content_id, **kwargs)

Get content properties.

get_content_property(content_id, property_key, **kwargs)

Get content property by key.

get_content_template(template_id)

Return a legacy Confluence Cloud content template by ID.

get_current_user(**kwargs)

Get current user.

get_descendant_pages(content_id, **kwargs)

Get all descendant pages of a content item.

get_group(group_id, **kwargs)

Get a Cloud group by its ID.

get_group_members(group_id, start=None, limit=None, expand=None, **kwargs)

Get a paginated collection of members for a Cloud group ID.

get_groups(start=0, limit=1000, **kwargs)

Get a page of Cloud groups from the supported V1 group API.

get_health(**kwargs)

Get API health status.

get_labels(**kwargs)

Get all labels.

get_metadata(**kwargs)

Get API metadata.

get_page_as_pdf(page_id)

Export a Cloud page as PDF using Confluence’s asynchronous exporter.

get_page_by_title(space_key, title, **kwargs)

Get page by title and space key.

get_page_child_by_type(page_id, type='page', start=None, limit=None, expand=None)

Provide content by type (page, blog, comment) :param page_id: A string containing the id of the type content container. :param type: :param start: OPTIONAL: The start point of the collection to return. Default: None (0). :param limit: OPTIONAL: how many items should be returned after the start index. Default: Site limit 200. :param expand: OPTIONAL: expand e.g. history :return:

get_page_child_count(page_id, type='page')

Return the number of direct children of type without listing them.

get_pdf_download_url_for_confluence_cloud(url)

Start a Cloud PDF export and return its signed download URL.

Confluence Cloud creates PDF exports asynchronously. The legacy task endpoint was removed; the current task state is available from the V2 pdfexporttask endpoint.

get_space(space_id, **kwargs)

Get space by ID.

get_space_analytics(space_id, **kwargs)

Get space analytics.

get_space_content(space_id, **kwargs)

Get space content.

get_space_names(**kwargs)

Return the names of every space without fetching page content.

get_spaces(**kwargs)

Get all spaces (single page).

Calls the Confluence Cloud v2 endpoint /wiki/api/v2/spaces. For paginated enumeration of every space, use get_all_spaces().

get_template(template_id, **kwargs)

Get template by ID.

get_templates(**kwargs)

Get all templates.

get_user(user_id, **kwargs)

Get user by ID.

get_users(**kwargs)

Get all users.

iter_cql(cql, **kwargs)

Yield every Cloud CQL result, following pagination links.

iter_page_versions(page_id, limit=200, expand=None)

Yield every version of a legacy Confluence Cloud page lazily.

page_exists(space_key, title, **kwargs)

Check whether a page exists using the Cloud V2 page endpoint.

The retired V1 content lookup accepted a space key directly. V2 page queries require a space ID, so resolve the key first and request only one matching page.

page_has_children(page_id, type='page')

Return whether a page has at least one direct child of type.

remove_content_history(page_id, version_number)

Remove one historical page version from Confluence Cloud.

The old implementation used the retired rest/experimental route. Cloud exposes the operation through the versioned v1 content endpoint.

remove_content_history_in_cloud(page_id, version_id)

Backward-compatible alias for removing a Cloud page version.

remove_content_label(content_id, label_id, **kwargs)

Remove label from content.

remove_page_history(page_id, version_number)

Alias for remove_content_history().

search_content(query, **kwargs)

Search content.

search_spaces(query, **kwargs)

Search spaces.

update_attachment(attachment_id, data, **kwargs)

Update existing attachment.

update_comment(comment_id, data, **kwargs)

Update existing comment.

update_content(content_id, data, **kwargs)

Update existing content.

update_content_property(content_id, property_key, data, **kwargs)

Update existing content property.

update_space(space_id, data, **kwargs)

Update existing space.

class atlassian.confluence.cloud.cloud.ConfluenceCloud(url: str, *args, **kwargs)

Confluence Cloud API implementation class

add_custom_content_label(custom_content_id: str, label: str, prefix: str = 'global') → Dict[str, Any]

Adds a label to custom content.

Args:

custom_content_id: The ID of the custom content label: The label to add prefix: (optional) The prefix of the label. Default is “global”

Returns:

The created label object

Raises:

HTTPError: If the API call fails ValueError: If the label is invalid

add_label(page_id: str, label: str) → Dict[str, Any]

Add a label to a page using the selected API version.

add_page_label(page_id: str, label: str) → Dict[str, Any]

Adds a label to a page.

Args:

page_id: The ID of the page label: The label to add

Returns:

The created label object

Raises:

HTTPError: If the API call fails ValueError: If the label is invalid

add_page_labels(page_id: str, labels: List[str]) → List[Dict[str, Any]]

Adds multiple labels to a page.

Args:

page_id: The ID of the page labels: List of labels to add

Returns:

List of created label objects

Raises:

HTTPError: If the API call fails ValueError: If any of the labels are invalid

add_space_label(space_id: str, label: str) → Dict[str, Any]

Adds a label to a space.

Args:

space_id: The ID of the space label: The label to add

Returns:

The created label object

Raises:

HTTPError: If the API call fails ValueError: If the label is invalid

add_space_labels(space_id: str, labels: List[str]) → List[Dict[str, Any]]

Adds multiple labels to a space.

Args:

space_id: The ID of the space labels: List of labels to add

Returns:

List of created label objects

Raises:

HTTPError: If the API call fails ValueError: If any of the labels are invalid

archive_space(space_key: str) → Dict[str, Any]

Archive a space.

Args:

space_key: The key of the space to archive

Returns:

Response from the API

Raises:

HTTPError: If the API call fails or the space doesn’t exist

create_attachment_comment(attachment_id: str, body: str, body_format: str = 'storage') → Dict[str, Any]

Create a comment on an attachment.

Args:

attachment_id: ID of the attachment body: Body of the comment body_format: (optional) Format of the comment body.

Valid values: ‘storage’, ‘atlas_doc_format’, ‘wiki’

Returns:

The created comment

Raises:

HTTPError: If the API call fails

create_blogpost_footer_comment(blogpost_id: str, body: str, body_format: str = 'storage') → Dict[str, Any]

Create a footer comment on a blog post.

Args:

blogpost_id: ID of the blog post body: Body of the comment body_format: (optional) Format of the comment body.

Valid values: ‘storage’, ‘atlas_doc_format’, ‘wiki’

Returns:

The created comment

Raises:

HTTPError: If the API call fails

create_comment_reply(parent_comment_id: str, body: str, body_format: str = 'storage') → Dict[str, Any]

Create a reply to an existing comment.

Args:

parent_comment_id: ID of the parent comment body: Body of the comment body_format: (optional) Format of the comment body.

Valid values: ‘storage’, ‘atlas_doc_format’, ‘wiki’

Returns:

The created comment

Raises:

HTTPError: If the API call fails

create_content(**kwargs)

create_custom_content(type: str, title: str, body: str, space_id: str | None = None, page_id: str | None = None, blog_post_id: str | None = None, custom_content_id: str | None = None, status: str = 'current', body_format: str = 'storage') → Dict[str, Any]

Creates a new custom content.

Args:

type: Type of custom content title: Title of the custom content body: Content body in the specified format space_id: (optional) ID of the containing space page_id: (optional) ID of the containing page blog_post_id: (optional) ID of the containing blog post custom_content_id: (optional) ID of the containing custom content status: (optional) Status of the custom content, default is “current”.

Valid values are “current” or “draft”

body_format: (optional) Format of the body. Default is “storage”.

Valid values are “storage”, “atlas_doc_format”, or “raw”

Returns:

Created custom content data

Raises:

HTTPError: If the API call fails ValueError: If invalid parameters are provided

create_custom_content_comment(custom_content_id: str, body: str, body_format: str = 'storage') → Dict[str, Any]

Create a comment on custom content.

Args:

custom_content_id: ID of the custom content body: Body of the comment body_format: (optional) Format of the comment body.

Valid values: ‘storage’, ‘atlas_doc_format’, ‘wiki’

Returns:

The created comment

Raises:

HTTPError: If the API call fails

create_custom_content_property(custom_content_id: str, key: str, value: Any) → Dict[str, Any]

Creates a new property for custom content.

Args:

custom_content_id: The ID of the custom content key: The key of the property to create. Must only contain alphanumeric

characters, periods, and hyphens

value: The value of the property. Can be any JSON-serializable value

Returns:

The created property object

Raises:

HTTPError: If the API call fails ValueError: If the key has invalid characters

create_page(space_id: str | None = None, title: str = '', body: str = '', parent_id: str | None = None, body_format: str = 'storage', status: str = 'current', representation: str | None = None, space: str | None = None) → Dict[str, Any]

Creates a new page in Confluence.

API Version: 2 (Cloud only)

Compatibility: This method is equivalent to create_page in v1, but with parameter differences: space_id instead of space, simplified body format, and no content type.

Args:

space_id: The ID of the space where the page will be created title: The title of the page body: The content of the page parent_id: (optional) The ID of the parent page body_format: (optional) The format of the body. Default is ‘storage’.

Valid values: ‘storage’, ‘atlas_doc_format’, ‘wiki’

status: (optional) The status of the page. Default is ‘current’.

Valid values: ‘current’, ‘draft’

representation: (optional) The content representation - used only for wiki format.

Valid value: ‘wiki’

Returns:

The created page object in v2 API format

Raises:

HTTPError: If the API call fails ValueError: If invalid parameters are provided

create_page_footer_comment(page_id: str, body: str, body_format: str = 'storage') → Dict[str, Any]

Create a footer comment on a page.

Args:

page_id: ID of the page body: Body of the comment body_format: (optional) Format of the comment body.

Valid values: ‘storage’, ‘atlas_doc_format’, ‘wiki’

Returns:

The created comment

Raises:

HTTPError: If the API call fails

create_page_inline_comment(page_id: str, body: str, inline_comment_properties: Dict[str, Any], body_format: str = 'storage') → Dict[str, Any]

Create an inline comment on a page.

Args:

page_id: ID of the page body: Body of the comment inline_comment_properties: Properties for inline comment, e.g.:

{

“textSelection”: “text to highlight”, “textSelectionMatchCount”: 3, “textSelectionMatchIndex”: 1

}

body_format: (optional) Format of the comment body.

Valid values: ‘storage’, ‘atlas_doc_format’, ‘wiki’

Returns:

The created comment

Raises:

HTTPError: If the API call fails

create_page_property(page_id: str, property_key: str, property_value: Any) → Dict[str, Any]

Creates a new property for a page.

Args:

page_id: The ID of the page key: The key of the property to create. Must only contain alphanumeric

characters and periods

value: The value of the property. Can be any JSON-serializable value

Returns:

The created property object

Raises:

HTTPError: If the API call fails ValueError: If the key has invalid characters

create_space(key: str, name: str, **kwargs) → Dict[str, Any]

Create a space; retained for callers migrating from the V1 API.

delete_comment(comment_id: str) → bool

Delete a comment.

Args:

comment_id: ID of the comment to delete

Returns:

True if successful

Raises:

HTTPError: If the API call fails

delete_content(content_id: str)

delete_custom_content(custom_content_id: str)

Delete a custom-content item.

delete_custom_content_label(custom_content_id: str, label: str, prefix: str = 'global') → bool

Delete a label from custom content.

Args:

custom_content_id: The ID of the custom content label: The label to delete prefix: (optional) The prefix of the label. Default is “global”

Returns:

True if the label was successfully deleted, False otherwise

Raises:

HTTPError: If the API call fails ValueError: If the label is invalid

delete_custom_content_property(custom_content_id: str, key: str) → bool

Deletes a property from custom content.

Args:

custom_content_id: The ID of the custom content key: The key of the property to delete

Returns:

True if the property was successfully deleted, False otherwise

Raises:

HTTPError: If the API call fails

delete_page(page_id: str) → bool

Deletes a page.

Args:

page_id: The ID of the page to delete

Returns:

True if the page was successfully deleted, False otherwise

Raises:

HTTPError: If the API call fails

delete_page_label(page_id: str, label: str) → bool

Deletes a label from a page.

Args:

page_id: The ID of the page label: The label to delete

Returns:

True if the label was successfully deleted, False otherwise

Raises:

HTTPError: If the API call fails

delete_page_property(page_id: str, property_key: str) → bool

Deletes a property from a page.

Args:

page_id: The ID of the page property_key: The key of the property to delete

Returns:

True if the property was successfully deleted, False otherwise

Raises:

HTTPError: If the API call fails

delete_space_label(space_id: str, label: str) → bool

Delete a label from a space.

Args:

space_id: The ID of the space label: The name of the label to delete

Returns:

True if successful

Raises:

HTTPError: If the API call fails

get_all_page_versions(page_id: str, body_format: str | None = None, limit: int = 25, sort: str | None = None) → List[Dict[str, Any]]

Return every version of a Confluence Cloud page as a list.

get_attachment_comments(attachment_id: str, body_format: str | None = None, cursor: str | None = None, limit: int = 25, sort: str | None = None) → List[Dict[str, Any]]

Get comments for an attachment.

Args:

attachment_id: ID of the attachment body_format: (optional) Format of the body to be returned.

Valid values: ‘storage’, ‘atlas_doc_format’, ‘view’

cursor: (optional) Cursor to use for pagination limit: (optional) Maximum number of comments to return per request. Default: 25 sort: (optional) Sort order for comments

Valid values: ‘created-date’, ‘-created-date’, ‘modified-date’, ‘-modified-date’

Returns:

List of comments

Raises:

HTTPError: If the API call fails

get_blogpost_footer_comments(blogpost_id: str, body_format: str | None = None, cursor: str | None = None, limit: int = 25, sort: str | None = None) → List[Dict[str, Any]]

Get footer comments for a blog post.

Args:

blogpost_id: ID of the blog post body_format: (optional) Format of the body to be returned.

Valid values: ‘storage’, ‘atlas_doc_format’, ‘view’

cursor: (optional) Cursor to use for pagination limit: (optional) Maximum number of comments to return per request. Default: 25 sort: (optional) Sort order for comments

Valid values: ‘created-date’, ‘-created-date’, ‘modified-date’, ‘-modified-date’

Returns:

List of footer comments

Raises:

HTTPError: If the API call fails

get_blogpost_inline_comments(blogpost_id: str, body_format: str | None = None, cursor: str | None = None, limit: int = 25, sort: str | None = None) → List[Dict[str, Any]]

Get inline comments for a blog post.

Args:

blogpost_id: ID of the blog post body_format: (optional) Format of the body to be returned.

Valid values: ‘storage’, ‘atlas_doc_format’, ‘view’

cursor: (optional) Cursor to use for pagination limit: (optional) Maximum number of comments to return per request. Default: 25 sort: (optional) Sort order for comments

Valid values: ‘created-date’, ‘-created-date’, ‘modified-date’, ‘-modified-date’

Returns:

List of inline comments

Raises:

HTTPError: If the API call fails

get_child_pages(parent_id: str, status: str | None = 'current', body_format: str | None = None, get_body: bool = False, expand: List[str] | None = None, limit: int = 25, sort: str | None = None) → List[Dict[str, Any]]

Returns a list of child pages for the specified parent page.

Args:

parent_id: The ID of the parent page status: (optional) Filter pages by status, default is ‘current’.

Valid values: ‘current’, ‘archived’, ‘any’

body_format: (optional) The format of the page body to be returned.

Valid values are ‘storage’, ‘atlas_doc_format’, or ‘view’

get_body: (optional) Whether to retrieve the page body. Default: False expand: (optional) A list of properties to expand in the response limit: (optional) Maximum number of pages to return per request. Default: 25 sort: (optional) Sorting of the results. Format: [field] or [-field] for descending order

Valid fields: ‘id’, ‘created-date’, ‘modified-date’, ‘child-position’

Returns:

List of child page objects in v2 API format

Raises:

HTTPError: If the API call fails

get_comment_by_id(comment_id: str, body_format: str | None = None, version: int | None = None) → Dict[str, Any]

Get a comment by ID.

Args:

comment_id: ID of the comment body_format: (optional) Format of the body to be returned.

Valid values: ‘storage’, ‘atlas_doc_format’, ‘view’

version: (optional) Version number to retrieve

Returns:

Comment details

Raises:

HTTPError: If the API call fails

get_comment_children(comment_id: str, body_format: str | None = None, cursor: str | None = None, limit: int = 25, sort: str | None = None) → List[Dict[str, Any]]

Get child comments for a comment.

Args:

comment_id: ID of the parent comment body_format: (optional) Format of the body to be returned.

Valid values: ‘storage’, ‘atlas_doc_format’, ‘view’

cursor: (optional) Cursor to use for pagination limit: (optional) Maximum number of comments to return per request. Default: 25 sort: (optional) Sort order for comments

Valid values: ‘created-date’, ‘-created-date’, ‘modified-date’, ‘-modified-date’

Returns:

List of child comments

Raises:

HTTPError: If the API call fails

get_content(**kwargs)

Deprecated v1-compatible alias for get_pages().

get_content_by_id(content_id: str, **kwargs) → Dict[str, Any]

Deprecated v1-compatible alias for get_page_by_id().

get_content_property(content_id: str, key: str) → Dict[str, Any]

Deprecated v1-compatible alias for a page property lookup.

get_custom_content(type: str | None = None, space_id: str | None = None, page_id: str | None = None, blog_post_id: str | None = None, custom_content_id: str | None = None, ids: List[str] | None = None, status: str | None = None, body_format: str | None = None, sort: str | None = None, cursor: str | None = None, limit: int | None = None) → List[Dict[str, Any]]

Get custom content with optional filtering.

Args:

_type: (optional) Filter by custom content type space_id: (optional) Filter by space ID page_id: (optional) Filter by page ID blog_post_id: (optional) Filter by blog post ID custom_content_id: (optional) Filter by parent custom content ID ids: (optional) List of custom content IDs to filter by status: (optional) Filter by status. Valid values: “current”, “draft”, “archived”, “trashed”, “deleted”, “any” body_format: (optional) Format to retrieve the body in.

Valid values: “storage”, “atlas_doc_format”, “raw”, “view”

sort: (optional) Sort order. Example: “id”, “-created-date” cursor: (optional) Cursor for pagination limit: (optional) Maximum number of results to return

Returns:

List of custom content

Raises:

HTTPError: If the API call fails

get_custom_content_ancestors(custom_content_id: str)

get_custom_content_by_id(custom_content_id: str, body_format: str | None = None) → Dict[str, Any]

Get custom content by its ID.

Args:

custom_content_id: ID of the custom content to retrieve body_format: (optional) Format to retrieve the body in.

Valid values: “storage”, “atlas_doc_format”, “raw”, “view”

Returns:

Custom content data

Raises:

HTTPError: If the API call fails

get_custom_content_children(custom_content_id: str, cursor: str | None = None, limit: int = 25)

get_custom_content_comments(custom_content_id: str, body_format: str | None = None, cursor: str | None = None, limit: int = 25, sort: str | None = None) → List[Dict[str, Any]]

Get comments for custom content.

Args:

custom_content_id: ID of the custom content body_format: (optional) Format of the body to be returned.

Valid values: ‘storage’, ‘atlas_doc_format’, ‘view’

cursor: (optional) Cursor to use for pagination limit: (optional) Maximum number of comments to return per request. Default: 25 sort: (optional) Sort order for comments

Valid values: ‘created-date’, ‘-created-date’, ‘modified-date’, ‘-modified-date’

Returns:

List of comments

Raises:

HTTPError: If the API call fails

get_custom_content_labels(custom_content_id: str, prefix: str | None = None, cursor: str | None = None, sort: str | None = None, limit: int = 25) → List[Dict[str, Any]]

Returns all labels for custom content.

Args:

custom_content_id: The ID of the custom content prefix: (optional) Filter the results to labels with a specific prefix cursor: (optional) Cursor for pagination sort: (optional) Sort order for the results. Valid values: ‘name’, ‘-name’ limit: (optional) Maximum number of labels to return per request. Default: 25

Returns:

List of label objects

Raises:

HTTPError: If the API call fails

get_custom_content_properties(custom_content_id: str, sort: str | None = None, limit: int = 25)

Return all properties attached to a custom-content item.

get_custom_content_property_by_key(custom_content_id: str, property_key: str)

Return a custom-content property by key.

get_page_by_id(page_id: str, body_format: str | None = None, get_body: bool = True, expand: List[str] | None = None) → Dict[str, Any]

Returns a page by ID in the v2 API format.

API Version: 2 (Cloud only)

Compatibility: This method provides similar functionality to the v1 get_page_by_id but with a different parameter set and response structure.

Args:

page_id: The ID of the page to be returned body_format: (optional) The format of the page body to be returned.

Valid values are ‘storage’, ‘atlas_doc_format’, or ‘view’

get_body: (optional) Whether to retrieve the page body. Default: True expand: (optional) A list of properties to expand in the response

Valid values: ‘childTypes’, ‘children.page.metadata’, ‘children.attachment.metadata’, ‘children.comment.metadata’, ‘children’, ‘history’, ‘ancestors’, ‘body.atlas_doc_format’, ‘body.storage’, ‘body.view’, ‘version’

Returns:

The page object in v2 API format

Raises:

HTTPError: If the API call fails ApiError: If the page does not exist or the user doesn’t have permission to view it

get_page_footer_comments(page_id: str, body_format: str | None = None, cursor: str | None = None, limit: int = 25, sort: str | None = None) → List[Dict[str, Any]]

Get footer comments for a page.

Args:

page_id: ID of the page body_format: (optional) Format of the body to be returned.

Valid values: ‘storage’, ‘atlas_doc_format’, ‘view’

cursor: (optional) Cursor to use for pagination limit: (optional) Maximum number of comments to return per request. Default: 25 sort: (optional) Sort order for comments

Valid values: ‘created-date’, ‘-created-date’, ‘modified-date’, ‘-modified-date’

Returns:

List of footer comments

Raises:

HTTPError: If the API call fails

get_page_inline_comments(page_id: str, body_format: str | None = None, cursor: str | None = None, limit: int = 25, sort: str | None = None) → List[Dict[str, Any]]

Get inline comments for a page.

Args:

page_id: ID of the page body_format: (optional) Format of the body to be returned.

Valid values: ‘storage’, ‘atlas_doc_format’, ‘view’

cursor: (optional) Cursor to use for pagination limit: (optional) Maximum number of comments to return per request. Default: 25 sort: (optional) Sort order for comments

Valid values: ‘created-date’, ‘-created-date’, ‘modified-date’, ‘-modified-date’

Returns:

List of inline comments

Raises:

HTTPError: If the API call fails

get_page_labels(page_id: str, prefix: str | None = None, cursor: str | None = None, limit: int = 25) → List[Dict[str, Any]]

Returns all labels for a page.

Args:

page_id: The ID of the page prefix: (optional) Filter the results to labels with a specific prefix cursor: (optional) Cursor for pagination limit: (optional) Maximum number of labels to return per request. Default: 25

Returns:

List of label objects

Raises:

HTTPError: If the API call fails

get_page_properties(page_id: str, cursor: str | None = None, limit: int = 25) → List[Dict[str, Any]]

Returns all properties for a page.

Args:

page_id: The ID of the page cursor: (optional) Cursor for pagination limit: (optional) Maximum number of properties to return per request. Default: 25

Returns:

List of page property objects

Raises:

HTTPError: If the API call fails

get_page_property_by_key(page_id: str, property_key: str) → Dict[str, Any]

Returns a page property by key.

Args:

page_id: The ID of the page property_key: The key of the property to retrieve

Returns:

The page property object

Raises:

HTTPError: If the API call fails or the property doesn’t exist

get_page_space(page_id: str) → Dict[str, Any]

Return the space associated with a page (V1 compatibility helper).

get_page_version(page_id: str, version_number: int) → Dict[str, Any]

Return details for one Confluence Cloud page version.

get_page_versions(page_id: str, body_format: str | None = None, limit: int = 25, sort: str | None = None, cursor: str | None = None) → Dict[str, Any]

Return the version history for a Confluence Cloud page.

This uses the Cloud V2 version endpoint. Cloud V2 exposes version retrieval only; deletion remains unavailable in that API.

get_pages(space_id: str | None = None, title: str | None = None, status: str | None = 'current', body_format: str | None = None, get_body: bool = False, expand: List[str] | None = None, limit: int = 25, sort: str | None = None, cursor: str | None = None) → Dict[str, Any]

Returns a list of pages based on the provided filters.

API Version: 2 (Cloud only)

Compatibility: This method is equivalent to get_all_pages_from_space in v1, but uses cursor-based pagination and supports more filtering options.

Args:

space_id: (optional) The ID of the space to get pages from title: (optional) Filter pages by title status: (optional) Filter pages by status, default is ‘current’.

Valid values: ‘current’, ‘archived’, ‘draft’, ‘trashed’, ‘deleted’, ‘any’

body_format: (optional) The format of the page body to be returned.

Valid values are ‘storage’, ‘atlas_doc_format’, or ‘view’

get_body: (optional) Whether to retrieve the page body. Default: False expand: (optional) A list of properties to expand in the response limit: (optional) Maximum number of pages to return per request. Default: 25 sort: (optional) Sorting of the results. Format: [field] or [-field] for descending order

Valid fields: ‘id’, ‘created-date’, ‘modified-date’, ‘title’

cursor: (optional) Cursor for pagination. Use the cursor from _links.next in previous response

Returns:

Dictionary containing results list and pagination information in v2 API format

Raises:

HTTPError: If the API call fails

get_space(space_id: str) → Dict[str, Any]

Returns a specific space by ID.

Args:

space_id: The ID of the space to retrieve

Returns:

Space object with details

Raises:

HTTPError: If the API call fails or the space doesn’t exist

get_space_by_key(space_key: str) → Dict[str, Any]

Returns a specific space by key. This uses the get_spaces method with a key filter and returns the first match.

Args:

space_key: The key of the space to retrieve

Returns:

Space object with details

Raises:

HTTPError: If the API call fails ValueError: If no space with the specified key exists

get_space_content(space_id: str, depth: str | None = None, sort: str | None = None, limit: int = 25) → List[Dict[str, Any]]

Returns the content of a space using the search method. This is a convenience method that builds a CQL query.

Args:

space_id: The ID of the space depth: (optional) Depth of the search. Valid values: ‘root’, ‘all’ sort: (optional) Sort order. Format: [field] or [-field] for descending

Valid fields: ‘created’, ‘modified’

limit: (optional) Maximum number of items to return. Default: 25

Returns:

List of content items in the space

Raises:

HTTPError: If the API call fails

get_space_labels(space_id: str, prefix: str | None = None, cursor: str | None = None, limit: int = 25) → List[Dict[str, Any]]

Returns all labels for a space.

Args:

space_id: The ID of the space prefix: (optional) Filter the results to labels with a specific prefix cursor: (optional) Cursor for pagination limit: (optional) Maximum number of labels to return per request. Default: 25

Returns:

List of label objects

Raises:

HTTPError: If the API call fails

get_space_names(**kwargs) → List[str]

Return every visible space name without retrieving page content.

get_spaces(ids: List[str] | None = None, keys: List[str] | None = None, type: str | None = None, status: str | None = None, labels: List[str] | None = None, sort: str | None = None, cursor: str | None = None, limit: int = 25) → List[Dict[str, Any]]

Returns all spaces, optionally filtered by provided parameters.

Args:

ids: (optional) List of space IDs to filter by keys: (optional) List of space keys to filter by type: (optional) Type of spaces to filter by. Valid values: ‘global’, ‘personal’ status: (optional) Status of spaces to filter by. Valid values: ‘current’, ‘archived’ labels: (optional) List of labels to filter by (matches any) sort: (optional) Sort order. Format: [field] or [-field] for descending

Valid fields: ‘id’, ‘key’, ‘name’, ‘type’, ‘status’

cursor: (optional) Cursor for pagination limit: (optional) Maximum number of spaces to return per request. Default: 25

Returns:

List of space objects

Raises:

HTTPError: If the API call fails ValueError: If invalid parameters are provided

get_trashed_contents_by_space(space_key: str, cursor: str | None = None, expand: List[str] | None = None, limit: int = 100) → Dict[str, Any]

Get trashed contents by space.

Args:

space_key: The key of the space cursor: (optional) Cursor for pagination expand: (optional) List of properties to expand limit: (optional) Maximum number of results to return. Default: 100

Returns:

Response containing trashed content items

Raises:

HTTPError: If the API call fails

iter_page_versions(page_id: str, body_format: str | None = None, limit: int = 25, sort: str | None = None)

Yield every version of a Confluence Cloud page lazily.

search(query: str, cql: str | None = None, cursor: str | None = None, limit: int = 25, excerpt: bool = True, body_format: str | None = None) → Dict[str, Any]

Search for content in Confluence.

Args:

query: Text to search for cql: (optional) Confluence Query Language (CQL) expression to filter by cursor: (optional) Cursor to start searching from for pagination limit: (optional) Maximum number of results to return per request. Default: 25 excerpt: (optional) Whether to include excerpts in the response. Default: True body_format: (optional) The format for the excerpt if excerpts are included.

Valid values: ‘view’, ‘storage’, or ‘atlas_doc_format’

Returns:

Dictionary with search results

Raises:

HTTPError: If the API call fails ValueError: If invalid parameters are provided

search_content(query: str, type: str | None = None, space_id: str | None = None, status: str | None = 'current', limit: int = 25) → List[Dict[str, Any]]

Search for content with specific filters. This is a convenience method that builds a CQL query and calls the search method.

Args:

query: Text to search for _type: (optional) Content type to filter by. Valid values: ‘page’, ‘blogpost’, ‘comment’ space_id: (optional) Space ID to restrict search to status: (optional) Content status. Valid values: ‘current’, ‘archived’, ‘draft’, ‘any’ limit: (optional) Maximum number of results to return per request. Default: 25

Returns:

List of content items matching the search criteria

Raises:

HTTPError: If the API call fails ValueError: If invalid parameters are provided

update_comment(comment_id: str, body: str, version: int, body_format: str = 'storage', resolved: bool | None = None) → Dict[str, Any]

Update an existing comment.

Args:

comment_id: ID of the comment body: Updated body of the comment version: Current version number of the comment (will increment by 1) body_format: (optional) Format of the comment body.

Valid values: ‘storage’, ‘atlas_doc_format’, ‘wiki’

resolved: (optional) For inline comments - whether to mark as resolved

Returns:

The updated comment

Raises:

HTTPError: If the API call fails

update_content(content_id: str | None = None, **kwargs)

update_custom_content(custom_content_id: str, type: str, title: str, body: str, status: str, version_number: int, space_id: str, version_message: str | None = None) → Dict[str, Any]

Update a custom-content item.

update_custom_content_property(custom_content_id: str, key: str, value: Any, version_number: int, version_message: str = '') → Dict[str, Any]

Updates an existing property for custom content.

Args:

custom_content_id: The ID of the custom content key: The key of the property to update value: The new value of the property. Can be any JSON-serializable value version_number: The version number for concurrency control version_message: (optional) A message describing the change

Returns:

The updated property object

Raises:

HTTPError: If the API call fails

update_page(page_id: str, title: str | None = None, body: str | None = None, body_format: str = 'storage', status: str | None = None, version: int | None = None, representation: str | None = None) → Dict[str, Any]

Updates an existing page.

API Version: 2 (Cloud only)

Compatibility: This method is equivalent to update_page in v1, but requires the version number and uses a simplified body format. The v2 update requires at least one field (title, body, or status) to be provided.

Args:

page_id: The ID of the page to update title: (optional) The new title of the page body: (optional) The new content of the page body_format: (optional) The format of the body. Default is ‘storage’.

Valid values: ‘storage’, ‘atlas_doc_format’, ‘wiki’

status: (optional) The new status of the page.

Valid values: ‘current’, ‘draft’, ‘archived’

version: (optional) The version number for concurrency control

If not provided, the current version will be incremented

representation: (optional) The content representation - used only for wiki format.

Valid value: ‘wiki’

Returns:

The updated page object in v2 API format

Raises:

HTTPError: If the API call fails ValueError: If invalid parameters are provided

update_page_property(page_id: str, property_key: str, property_value: Any, version: int | None = None) → Dict[str, Any]

Updates an existing property for a page.

Args:

page_id: The ID of the page property_key: The key of the property to update property_value: The new value of the property. Can be any JSON-serializable value version: (optional) The version number of the property for concurrency control.

If not provided, the current version will be retrieved and incremented

Returns:

The updated page property object

Raises:

HTTPError: If the API call fails ValueError: If the property doesn’t exist

The Confluence module now provides both Cloud and Server implementations with dedicated APIs for each platform.

New Implementation

The new Confluence implementation follows the same pattern as other modules with dedicated Cloud and Server classes:

from atlassian.confluence import ConfluenceCloud, ConfluenceServer

# For Confluence Cloud
confluence_cloud = ConfluenceCloud(
    url="https://your-domain.atlassian.net",
    username="you@example.com",
    password="your-cloud-api-token",
)

# Cloud API tokens use HTTP Basic auth. Do not pass them as ``token=``:
# that creates a Bearer header for Server/Data Center personal access tokens.
# The client constructs the Basic header; do not base64-encode credentials.
with open("CONFLUENCE_TOKEN", encoding="utf-8") as token_file:
    api_token = token_file.read().strip()
confluence_cloud = ConfluenceCloud(
    url="https://your-domain.atlassian.net",
    username="you@example.com",
    password=api_token,
)

# For Confluence Server
confluence_server = ConfluenceServer(
    url="https://your-confluence-server.com",
    username="your-username",
    password="your-password"
)

Cloud vs Server Differences

Feature | Cloud | Server |

Authentication | API Token | Username/Password |

API Version | v2 | v1.0 |

API Root | wiki/api/v2 | rest/api/1.0 |

Content IDs | UUID strings | Numeric IDs |

Space IDs | UUID strings | Space keys |

Choosing a Cloud client

ConfluenceCloud is the established Cloud client and keeps compatibility methods for older Cloud REST endpoints. Use ConfluenceV2 for the versioned Cloud V2 interface and new V2-only resources such as whiteboards, folders, databases, data classification, and V2 content properties. Both use the Cloud /wiki/api/v2 root for V2 operations; legacy operations retain their documented /wiki/rest/api paths.

from atlassian import ConfluenceV2

confluence = ConfluenceV2(
    "https://your-domain.atlassian.net",
    username="you@example.com",
    password="your-api-token",
)

For scoped Cloud API tokens through https://api.atlassian.com/ex/confluence/<cloud-id>, use ConfluenceV2. This preserves the gateway URL and targets the V2 endpoints supported by scoped tokens.

Space endpoint versions

The endpoint is selected by API version, not by the method name:

• Server/Data Center REST V1 uses /rest/api/space (or /wiki/rest/api/space when the instance uses the /wiki context).

• Cloud REST V2 uses /wiki/api/v2/spaces.

For Server/Data Center (and legacy Cloud V1 installations), filter by one space category label with get_all_spaces(label="service"). Cloud V2 uses the plural list filter: get_spaces(labels=["service"]).

The Cloud V1 Postman collection does not define a public Get spaces operation; use Cloud V2 for space enumeration. ConfluenceV2 and ConfluenceCloud use the V2 plural endpoint. Their get_spaces(ids=[...], keys=[...], labels=[...]) filters are encoded as repeated V2 query parameters. ConfluenceCloud.get_spaces() returns one V2 response page and get_all_spaces() lazily follows its cursor pages; ConfluenceV2.get_spaces() returns the fully paginated list.

Set a space homepage (Server/Data Center)

Set an existing page as a space homepage with set_space_homepage. The calling user needs space-administration permission and access to the page.

confluence.set_space_homepage("TEAM", "123456789")

For other space metadata, use update_space(space_key, data) with the corresponding Confluence REST space payload.

Common Operations

Both implementations support:

• Content management (create, read, update, delete)

• Space management

• User and group management

• Label management

• Attachment handling

• Comment management

• Search functionality

• Page properties

• Export capabilities

Server-Specific Features

The Server implementation includes additional features:

• Draft content management

• Trash content management

• Reindex operations

• Space permissions

• Space settings

Legacy Implementation

The original Confluence implementation is still available for backward compatibility.

Get page info

# Check page exists
# type of the page, 'page' or 'blogpost'. Defaults to 'page'
# Cloud uses V2 space/page lookups; Server/Data Center keeps its REST API.
confluence.page_exists(space, title, type=None)

# Resolve direct, display, and shared short page URLs to a page ID.
page_id = confluence.get_page_id_by_url("https://confluence.example.com/x/-_Z3")

# For Server/Data Center, use this paginated helper for all group members.
members = confluence.get_all_members("confluence-users")

# Returns only space names and follows the space-directory pagination.
space_names = confluence.get_space_names()

# Provide content by type (page, blog, comment)
confluence.get_page_child_by_type(page_id, type='page', start=None, limit=None, expand=None)

# Get child information without listing or paginating every child.
child_count = confluence.get_page_child_count(page_id)
has_children = confluence.page_has_children(page_id)

# Stream all CQL matches without accumulating them in memory.
for result in confluence.iter_cql('type=page', limit=250):
    process(result)

# Use this only when a complete in-memory list is required.
all_results = confluence.cql_all('type=page', limit=250)

# Provide content id from search result by title and space
confluence.get_page_id(space, title)

# Provide space key from content id
confluence.get_page_space(page_id)

# Returns the list of labels on a piece of Content
confluence.get_page_by_title(space, title, start=None, limit=None)

# Get page by ID
# Example request URI(s):
#    http://example.com/confluence/rest/api/content/1234?expand=space,body.view,version,container
#    http://example.com/confluence/rest/api/content/1234?status=any
#    page_id: Content ID
#    status: (str) list of Content statuses to filter results on. Default value: [current]
#    version: (int)
#    expand: OPTIONAL: A comma separated list of properties to expand on the content.
#                   Default value: history,space,version
#                   We can also specify some extensions such as extensions.inlineProperties
#                   (for getting inline comment-specific properties) or extensions.resolution
#                   for the resolution status of each comment in the results
confluence.get_page_by_id(page_id, expand=None, status=None, version=None)

# The list of labels on a piece of Content
confluence.get_page_labels(page_id, prefix=None, start=None, limit=None)

# Get draft page by ID
confluence.get_draft_page_by_id(page_id, status='draft')

# Get all page by label
confluence.get_all_pages_by_label(label, start=0, limit=50, expand=None)

# Get all pages from Space
# content_type can be 'page' or 'blogpost'. Defaults to 'page'
# expand is a comma separated list of properties to expand on the content.
# max limit is 100. For more you have to loop over start values.
confluence.get_all_pages_from_space(space, start=0, limit=100, status=None, expand=None, content_type='page')

# Get all pages from space as Generator
confluence.get_all_pages_from_space_as_generator(space, start=0, limit=100, status=None, expand=None, content_type='page')

# Get list of pages from trash
confluence.get_all_pages_from_space_trash(space, start=0, limit=500, status='trashed', content_type='page')

# Get list of draft pages from space
# Use case is cleanup old drafts from Confluence
confluence.get_all_draft_pages_from_space(space, start=0, limit=500, status='draft')

# Search list of draft pages by space key
# Use case is cleanup old drafts from Confluence
confluence.get_all_draft_pages_from_space_through_cql(space, start=0, limit=500, status='draft')

# Info about all restrictions by operation
confluence.get_all_restrictions_for_content(content_id)

Page actions

# Create page from scratch
# Server/Data Center: ``space`` is the space KEY, not its display name.
# Personal-space keys commonly look like ``~<account-id>``.
confluence.create_page(space, title, body, parent_id=None, type='page', representation='storage', editor='v2', full_width=False)

# Check that the supplied credentials are accepted. This does not by itself
# grant create permission in a particular space.
confluence.get_current_user()

# Cloud V2 uses a space ID rather than a key. Resolve it first, then create.
from atlassian import ConfluenceV2
cloud = ConfluenceV2(url, username=email, password=api_token)
space_id = cloud.get_space_by_key('SPACEKEY')['id']
cloud.create_page(space_id=space_id, title=title, body=body)

# Server/Data Center: retain template macros and replace explicit placeholders.
confluence.create_page_from_template(
    space, title, template_id, replacements={"{{REPORT_MONTH}}": "August"}
)

# With recursive=True, all descendants are listed before deletion so
# server-side pagination cannot leave later child pages behind.
confluence.remove_page(page_id, status=None, recursive=False)

# Remove any content
confluence.remove_content(content_id):

# Remove page from trash
delete_status = confluence.remove_page_from_trash(page_id)  # normally 204

# Remove page as draft
confluence.remove_page_as_draft(page_id)

# Update page if already exist
confluence.update_page(page_id, title, body, parent_id=None, type='page', representation='storage', minor_edit=False, full_width=False)

# Server/Data Center updates use the configured REST API root and send a JSON body.

# Get every contributor for a collaboratively edited page revision.
contributors = confluence.get_page_version_contributors(page_id, version_number)

# Update the page only when the title exists under parent_id; a same-titled
# page elsewhere in the space is left untouched. parent_id is optional;
# use a space key to create or update a top-level page.
confluence.update_or_create(parent_id, title, body, representation='storage', full_width=False)
confluence.update_or_create(title=title, body=body, space='SPACEKEY')

# Server/Data Center: annotate the first page revision on creation.
confluence.create_page('SPACEKEY', title, body, version_comment='Initial import')

# Preserve Confluence storage macros when updating tables. Do not round-trip
# a page containing images through pandas.read_html(...).to_html(), because
# pandas represents embedded image cells as missing values and serializes
# them as ``NaN``. Fetch body.storage, update only the intended markup, and
# pass the resulting storage XHTML to update_page/update_existing_page.

# Archived pages must be restored/unarchived before update_or_create() can update them.

# Append body to page if already exist
confluence.append_page(page_id, title, append_body, parent_id=None, type='page', representation='storage', minor_edit=False)

# A list or dictionary is rendered as formatted JSON in a storage code block.
confluence.append_page(page_id, title, {"users": ["Ada", "Linus"]})

# Uploading the same attachment name creates a new attachment revision.
confluence.attach_file("images/diagram.png", page_id=page_id)

# Attachment names are filenames, not paths. Path-like values are reduced
# to their basename (for example, ``reports/diagram.png`` becomes
# ``diagram.png``).

# Attachments are files, not executable page markup. Link an HTML report
# from the page; replacing the attachment keeps this link current.
confluence.attach_file("reports/status.html", page_id=page_id)
html_attachment_link = """
    <ac:link>
      <ri:attachment ri:filename="status.html" />
      <ac:plain-text-link-body><![CDATA[Open the HTML status report]]></ac:plain-text-link-body>
    </ac:link>
"""
confluence.append_page(page_id, title, html_attachment_link)

# ``download_path=...`` remains an alias for historical examples; use
# ``path=...`` for new code.
confluence.download_attachments_from_page(page_id, path="/tmp/downloads")

# Attachments belong to the page that uploaded them. Including ``source_page``
# in another page does not copy its attachments, so query the source directly.
source_attachments = confluence.get_attachments_from_content(source_page_id)

# Server/Data Center: set all read restrictions listed below. This replaces
# the existing read restriction set, so include every allowed user/group.
confluence.set_restrictions_for_content(page_id, [{
    "operation": "read",
    "restrictions": {"user": [{"type": "known", "username": "alice"}]},
}])

# Confluence Cloud does not render attached HTML inline. Server/Data Center
# HTML/HTML Include macros are administrator-controlled and disabled by
# default because embedding arbitrary HTML can introduce XSS vulnerabilities.

# Fetch every historic revision without querying version numbers one by one.
# Use iter_page_versions(...) instead when processing a large history.
versions = confluence.get_all_page_versions(page_id, limit=200)

# Server/Data Center: export each page in a hierarchy. Confluence has no
# supported REST endpoint for one merged arbitrary-subtree PDF.
page_pdfs = confluence.export_page_tree_as_pdf(page_id)
for exported_page_id, pdf_bytes in confluence.iter_page_tree_as_pdf(page_id):
    save_pdf(exported_page_id, pdf_bytes)

# Invalid storage XHTML raises HTTPError with Confluence's ``message``,
# ``detail``, and field-level validation errors when the server supplies them.

# Set a page property. Pass a dictionary; JSON strings are accepted for
# backwards compatibility and are converted before the request is sent.
confluence.set_page_property(page_id, {"key": "myprop", "value": {"hash": "1111"}})

# Delete the page (content) property e.g. delete key of hash
confluence.delete_page_property(page_id, page_property)

# Move page
confluence.move_page(space_key, page_id, target_title, position="append")

# Get the page (content) property e.g. get key of hash
confluence.get_page_property(page_id, page_property_key)

# Get every page (content) property. Pagination is handled automatically;
# limit controls the size of each request, not the final result size.
confluence.get_page_properties(page_id)

# Get page ancestors
confluence.get_page_ancestors(page_id)

# Attach (upload) a file to a page, if it exists it will update the
# automatically version the new file and keep the old one
# content_type is default to "application/binary"
confluence.attach_file(filename, name=None, content_type=None, page_id=None, title=None, space=None, comment=None)

# Attach (upload) a content to a page, if it exists it will update the
# automatically version the new file and keep the old one
# content_type is default to "application/binary"
confluence.attach_content(content, name=None, content_type=None, page_id=None, title=None, space=None, comment=None)

# Download attachments from a page to local system. If path is None, current working directory will be used.
# Downloads every attachment, following Confluence pagination automatically.
confluence.download_attachments_from_page(page_id, path=None)

# Remove completely a file if version is None or delete version
confluence.delete_attachment(page_id, filename, version=None)

# Remove completely a file if version is None or delete version
confluence.delete_attachment_by_id(attachment_id, version)

# Keep last versions
confluence.remove_page_attachment_keep_version(page_id, filename, keep_last_versions)

# Get attachment history
confluence.get_attachment_history(attachment_id, limit=200, start=0)

# Get attachment for content
confluence.get_attachments_from_content(page_id, start=0, limit=50, expand=None, filename=None, media_type=None)

# Check has unknown attachment error on page
confluence.has_unknown_attachment_error(page_id)

# Export page as PDF
# Use ConfluenceCloud (or Confluence(..., cloud=True)) for Cloud exports.
# ``api_version='cloud'`` is deprecated; use ConfluenceV2 for Cloud V2 APIs.
confluence.export_page(page_id)

# Server/Data Center only: legacy Word exporter. The returned bytes are a
# Word-readable multipart HTML export, not a .docx document.
word_export = confluence.get_page_as_word(page_id)

# Set a label on the page
confluence.set_page_label(page_id, label)

# Delete Confluence page label
confluence.remove_page_label(page_id, label)

# Add comment into page
confluence.add_comment(page_id, text)

# Comments are a separate paginated resource; they are not included by
# get_page_by_id(). Expand the rendered body and creator/editor metadata.
comment_page = confluence.get_page_comments(
    page_id, expand='body.view,history,version', start=0, limit=100
)
for comment in comment_page['results']:
    body = comment['body']['view']['value']
    author = comment.get('history', {}).get('createdBy')
    latest_editor = comment.get('version', {}).get('by')

# Cloud V2 has separate methods for footer and inline comments. Their
# result items include authorId; request body_format for comment bodies.
footer_comments = cloud.get_page_footer_comments(page_id, body_format='view')
inline_comments = cloud.get_page_inline_comments(page_id, body_format='view')

 # Fetch tables from Confluence page
confluence.get_tables_from_page(page_id)

# Get regex matches from Confluence page
confluence.scrap_regex_from_page(page_id, regex)

Reading large page bodies

get_page_by_id(..., expand='body.storage') returns the complete body sent by Confluence; the client does not paginate or truncate an individual page body. IDE debuggers and interactive-variable viewers may abbreviate large strings, which can look like a partial API result. Check the string length or write it to a file before concluding that content is missing.

page = confluence.get_page_by_id(page_id, expand='body.storage')
storage = page['body']['storage']['value']

print(f'Received {len(storage)} characters')
with open('page-storage.xhtml', 'w', encoding='utf-8') as output:
    output.write(storage)

If the request itself times out, set a larger timeout when creating the client. This controls the HTTP request duration; it does not change the amount of content returned by Confluence.

confluence = Confluence(url=url, username=username, password=password, timeout=150)

Storage-format updates

representation='storage' expects Confluence storage XHTML, including ac: and ri: macros already present in the page. It is not generic browser HTML. Fetch body.storage, preserve macros, and replace only the dynamic values you own.

from xml.sax.saxutils import escape

page = confluence.get_page_by_id(page_id, expand='body.storage')
storage = page['body']['storage']['value']

# Escape dynamic text only. Do not escape the complete document: that
# would turn <ac:...> macros into literal text.
storage = storage.replace('{{SUMMARY}}', escape('Revenue & growth'))
confluence.update_page(page_id, page['title'], storage, representation='storage')

A literal & must be &. Existing entities such as " are already valid storage XML and must not be escaped a second time. Parentheses do not require XML escaping. representation='wiki' is legacy wiki markup; prefer storage XHTML for pages users will edit in the browser.

JSON in a code-block macro

Confluence code blocks are storage-format macros. Serialize structured output with the standard library, place it in an ac:plain-text-body CDATA section, and set the code language to json. This preserves indentation and enables JSON syntax highlighting in the Confluence editor.

import json

def confluence_json_code_block(server_output):
    json_text = json.dumps(server_output, indent=2, sort_keys=True, ensure_ascii=False)

    # CDATA cannot contain ``]]>``. Split that sequence so arbitrary JSON
    # string values remain valid Confluence storage XML.
    json_text = json_text.replace("]]>", "]]]]><![CDATA[>")

    return (
        '<ac:structured-macro ac:name="code" ac:schema-version="1">'
        '<ac:parameter ac:name="language">json</ac:parameter>'
        f'<ac:plain-text-body><![CDATA[{json_text}]]></ac:plain-text-body>'
        '</ac:structured-macro>'
    )

page = confluence.get_page_by_id(page_id, expand='body.storage')
body = page['body']['storage']['value']
body = body.replace('{{SERVER_OUTPUT}}', confluence_json_code_block(server_output))
confluence.update_page(page_id, page['title'], body, representation='storage')

The placeholder must be part of an existing storage-format page template. Do not use html.escape on the returned macro: doing so would display the macro as literal text instead of rendering a code block.

Word document imports

Confluence Server/Data Center’s Import Word document action is provided by the Office Connector user interface. It is not exposed as a supported REST API, and Confluence Cloud’s REST APIs likewise do not accept a .doc or .docx file as a page body. Consequently, this package intentionally has no import_word_document() method: using an internal browser endpoint would be fragile and could lose document content.

For a faithful, one-off import (including the UI options to replace a page or split a document by headings), use the Confluence web interface. For automated workflows, convert the document with a tool chosen and controlled by your application, validate the resulting storage XHTML, and then use the normal page methods. Conversion of Word styles, images, tables, and macros is outside the scope of the REST API and must be validated for the documents you support.

# ``storage_xhtml`` is produced and validated by your own DOCX conversion
# step. It is Confluence storage XHTML, not the original DOCX bytes.
page = confluence.create_page(space_key, title, storage_xhtml,
                              representation='storage')

# Optionally retain the original source document as an attachment. This
# uploads the file; it does not convert it into page content.
confluence.attach_file('report.docx', page_id=page['id'])

Confluence Whiteboards

Whiteboards are available through Confluence Cloud REST API V2 only. Use ConfluenceV2 (or ConfluenceCloud) and a token with the relevant read:whiteboard:confluence, write:whiteboard:confluence, and delete:whiteboard:confluence scopes.

from atlassian import ConfluenceV2

confluence = ConfluenceV2(url, username=email, password=api_token)

# Create a whiteboard in a space. ``private`` is an optional API query
# parameter; parent_id, template_key, and locale are optional body fields.
whiteboard = confluence.create_whiteboard(
    space_id, title='Planning', parent_id=page_id, private=True
)

# Fetch it, optionally expanding related information.
whiteboard = confluence.get_whiteboard(
    whiteboard['id'], include_collaborators=True,
    include_direct_children=True, include_operations=True,
    include_properties=True,
)

# Deletion moves the whiteboard to trash, where Confluence can restore it.
confluence.delete_whiteboard(whiteboard['id'])

get_whiteboard_by_id() remains as a compatible alias for get_whiteboard(). Whiteboards are not supported by Confluence Server or Data Center.

Confluence Cloud GraphQL search

ConfluenceV2 also supports the Atlassian GraphQL Gateway for Cloud-only use cases such as advanced search. GraphQL has a continuously evolving schema, so REST/CQL search() remains unchanged and GraphQL responses are returned without translation. Use a tenanted *.atlassian.net URL with an API token; the GraphQL gateway is not available on Confluence Server or Data Center.

from atlassian import ConfluenceV2

confluence = ConfluenceV2(url, username=email, password=api_token)

# Find this once from https://your-site.atlassian.net/_edge/tenant_info.
cloud_id = "your-confluence-cloud-id"
response = confluence.search_graphql("deployment guide", cloud_id)

# GraphQL may return HTTP 200 with an errors field, so inspect it first.
if response.get("errors"):
    raise RuntimeError(response["errors"])
search = response["data"]["search"]["search"]
for edge in search["edges"]:
    print(edge["node"]["title"], edge["node"]["url"])

For custom queries or mutations, call confluence.graphql(query, variables). The GraphQL Gateway has its own query-cost rate limit, separate from REST API limits.

Confluence Cloud V2 content properties

Cloud V2 property endpoints share the same lifecycle across pages, blog posts, attachments, comments, custom content, folders, whiteboards, databases, and embeds. content_type selects the documented V2 resource name; pagination is handled automatically when listing properties.

properties = confluence.get_v2_content_properties("page", page_id)
created = confluence.create_v2_content_property(
    "page", page_id, {"key": "report", "value": {"published": True}}
)
property_data = confluence.get_v2_content_property("page", page_id, created["id"])
confluence.update_v2_content_property("page", page_id, created["id"], property_data)
confluence.delete_v2_content_property("page", page_id, created["id"])

The *_v2 names distinguish these helpers from the legacy V1 key-based content-property API. Supported content types are attachment, blogpost, comment, custom_content, database, embed, folder, page, and whiteboard.

Confluence Cloud V2 data classification

Data classification is available only to eligible Confluence Cloud sites. The site administrator defines the available levels; the caller needs the relevant content or space permissions.

levels = confluence.get_classification_levels()
confluence.update_content_classification_level("page", page_id, levels[0]["id"])
current_level = confluence.get_content_classification_level("page", page_id)

# Make a level the default for a space, or reset a page to that default.
confluence.update_space_default_classification_level(space_id, levels[0]["id"])
confluence.reset_content_classification_level("page", page_id)

Supported content types are page, blogpost, whiteboard, and database. Content-level updates accept only the current and draft statuses required by the V2 API.

Confluence Cloud tasks

from atlassian import ConfluenceV2

confluence = ConfluenceV2(url, username=email, password=api_token)

# Retrieves every result page.  Filters accept account IDs, content IDs,
# and Unix epoch milliseconds for the date-range arguments.
tasks = confluence.get_tasks(status="incomplete", page_ids=[page_id])

task = confluence.get_task(task_id, body_format="storage")
confluence.update_task(task_id, "complete")

# Scoped tokens require read:task:confluence or write:task:confluence.

Template actions

The methods below use Confluence’s supported template endpoints. They apply to Server/Data Center and to the legacy Cloud V1 template API; they are not part of ConfluenceV2.

Migration from experimental template methods

The older experimental methods remain available for compatibility but emit a DeprecationWarning. Use their supported replacements in new code:

• get_template_by_id(template_id) -> get_content_template(template_id)

• get_all_templates_from_space(space) -> get_content_templates(space)

• get_all_blueprints_from_space(space) -> get_blueprint_templates(space)

# Read a content template. Requesting this supported method rather than
# get_template_by_id() avoids the experimental endpoint.
template = confluence.get_content_template(template_id)
storage_body = template['body']['storage']

# Create a space template. Omit space to create a global template.
created = confluence.create_or_update_template(
    name='Monthly report',
    body={'storage': {'value': '<p>{{SUMMARY}}</p>', 'representation': 'storage'}},
    description='Starting point for monthly reports',
    labels=[{'prefix': 'global', 'name': 'report'}],
    space='TEAM',
)

# Update an existing template. Use keyword arguments so template_id is
# never confused with template_type or description.
updated = confluence.create_or_update_template(
    name=template['name'],
    body={'storage': storage_body},
    template_id=template_id,
    description=template.get('description'),
)

# Get all global content templates
confluence.get_content_templates()

# Get content templates in a space
confluence.get_content_templates(space)

# Get all global blueprint templates
confluence.get_blueprint_templates()

# Get all blueprint templates in a space
confluence.get_blueprint_templates(space)

# Removing a template
confluence.remove_template(template_id)

create_or_update_template supports content templates only. Confluence does not allow blueprint templates to be created or updated through this REST API. Use get_blueprint_templates to inspect blueprint templates; removing a modified blueprint resets it to its inherited/default version.

Get spaces info

# Get all spaces with provided limit
# additional info, e.g. metadata, icon, description, homepage
confluence.get_all_spaces(start=0, limit=500, expand=None)

# Get information about a space through space key
confluence.get_space(space_key, expand='description.plain,homepage')

# Get space content (configuring by the expand property)
confluence.get_space_content(space_key, depth="all", start=0, limit=500, content_type=None, expand="body.storage")

# Get Space permissions set based on json-rpc call
confluence.get_space_permissions(space_key)

# Experimental UI export: returns a temporary download URL for HTML, CSV,
# or XML. This is not a supported REST API and can change.
download_url = confluence.get_space_export(space_key, export_type='html')

# Export several spaces sequentially. Do not parallelize UI exports: the
# Confluence export service limits concurrent jobs.
for space_key, download_url in confluence.iter_space_exports(
    ["ENG", "HR", "SUPPORT"], export_type="html"
):
    print(space_key, download_url)

get_space_export and iter_space_exports use Confluence’s browser export workflow because there is no supported REST endpoint for this task. Confluence can reject concurrent export jobs, so process spaces sequentially and download each returned temporary URL before it expires. For Data Center PDF exports, an administrator can tune the server-side concurrency limit; the client cannot safely override it.

Space

# Archive the given Space identified by spaceKey.
# This method is idempotent i.e.,
# if the Space is already archived then no action will be taken.
confluence.archive_space(space_key)

# Get trash contents of space
confluence.get_trashed_contents_by_space(space_key, cursor=None, expand=None, limit=100)

# Remove all trash contents of space
confluence.remove_trashed_contents_by_space(space_key)

Get space permissions

# Returns list of permissions granted to users and groups in the particular space.
confluence.get_all_space_permissions(space_key)

# Sets permissions to multiple users/groups in the given space.
confluence.set_permissions_to_multiple_items_for_space(self, space_key, user_key=None, group_name=None, operations=None)

# Get permissions granted to anonymous user for the given space
confluence.get_permissions_granted_to_anonymous_for_space(space_key)

# Grant permissions to anonymous user in the given space.
# Operation doesn't override existing permissions
# will only add those one that weren't granted before.
# Multiple permissions could be passed in one request.
# Supported targetType and operationKey pairs:
#    space read
#    space administer
#    space export
#    space restrict
#    space delete_own
#    space delete_mail
#    page create
#    page delete
#    blogpost create
#    blogpost delete
#    comment create
#    comment delete
#    attachment create
#    attachment delete
confluence.set_permissions_to_anonymous_for_space(space_key, operations=None)

# Remove permissions granted to anonymous user for the given space
confluence.remove_permissions_granted_to_anonymous_for_space(space_key)

# Get permissions granted to group for the given space
confluence.get_permissions_granted_to_group_for_space(space_key, user_key)

# Grant permissions to group in the given space.
# Operation doesn't override existing permissions
# will only add those one that weren't granted before.
# Multiple permissions could be passed in one request.
# Supported targetType and operationKey pairs:
#    space read
#    space administer
#    space export
#    space restrict
#    space delete_own
#    space delete_mail
#    page create
#    page delete
#    blogpost create
#    blogpost delete
#    comment create
#    comment delete
#    attachment create
#    attachment delete
confluence.set_permissions_to_group_for_space(space_key, user_key, operations=None)

# Remove permissions granted to group for the given space
confluence.remove_permissions_from_group_for_space(space_key, group_name)

# Get permissions granted to user for the given space
confluence.get_permissions_granted_to_user_for_space(space_key, user_key)

# Grant permissions to user in the given space.
confluence.set_permissions_to_user_for_space(space_key, user_key, operations=None)

# Remove permissions granted to user for the given space
confluence.remove_permissions_from_user_for_space(space_key, user_key)

# Add permissions to a space
confluence.add_space_permissions(space_key, user_key, group_name, operations)

# Remove permissions from a space
confluence.remove_space_permissions(space_key, user_key, group_name, permission)

Users and Groups

# Get all groups from Confluence User management
confluence.get_all_groups(start=0, limit=1000)

# Get information about a user through username
confluence.get_user_details_by_username(username, expand=None)

# Get information about a user through user key
confluence.get_user_details_by_userkey(userkey, expand=None)

# Change a user's password
confluence.change_user_password(username, password)

# Change calling user's password
confluence.change_my_password(oldpass, newpass)

# Add given user to a group
confluence.add_user_to_group(username, group_name)

# Remove given user from a group
confluence.remove_user_from_group(username, group_name)

CQL

# ``cql()`` returns one result page. CQL search results wrap a page in
# ``result["content"]``, so expand the nested path, not ``body.storage``.
response = confluence.cql(
    'space = "TEAM" and type = page',
    limit=25,
    expand="content.body.storage",
)
for result in response.get("results", []):
    storage = result["content"]["body"]["storage"]["value"]

# Cloud pagination is cursor-based. This iterator follows ``_links.next``
# for every page; do not increment ``start`` yourself.
for result in confluence.iter_cql(
    'space = "TEAM" and type = page', limit=25, expand="content.body.storage"
):
    storage = result["content"]["body"]["storage"]["value"]

# Materialize every matching result only when an in-memory list is needed.
all_results = confluence.cql_all('space = "TEAM" and type = page', limit=25)

iter_cql() and cql_all() work for Cloud and Server/Data Center. Cloud follows its cursor link, while Server/Data Center retains its offset-based pagination semantics.

Other actions

# Clean all caches from cache management
confluence.clean_all_caches()

# Clean caches from cache management
# e.g.
# com.gliffy.cache.gon
# org.hibernate.cache.internal.StandardQueryCache_v5
confluence.clean_package_cache(cache_name='com.gliffy.cache.gon')

# Convert to Confluence XHTML format from wiki style
confluence.convert_wiki_to_storage(wiki)

# Get page history
confluence.history(page_id)

# Get content history by version number
confluence.get_content_history_by_version_number(content_id, version_number)

# Remove content history. It works as experimental method
confluence.remove_content_history(page_id, version_number)

# Compare content and check is already updated or not
confluence.is_page_content_is_already_updated(page_id, body)

# Add inline task setting checkbox method
confluence.set_inline_tasks_checkbox(page_id, task_id, status)

Consistent return values

For Server and Data Center, get_tables_from_page always returns a dictionary with page_id, number_of_tables_in_page, and tables_content. Pages without tables use a count of zero and an empty list. download_attachments_from_page likewise returns an empty dictionary in memory mode, or {"attachments_downloaded": 0, "path": ...} on disk when no attachments match.

attach_content and update_page raise ApiNotFoundError when the target page cannot be resolved instead of returning None. Title lookups remain search-result responses; an empty results collection means that no matching page exists.

Content history

get_content_history_by_version_number and the Server/Data Center history-removal methods use the supported /rest/api/content/{id}/version/{number} endpoint. Cloud history removal uses the equivalent V1 content endpoint under /wiki; the retired /rest/experimental route is not used. remove_page_history_keep_version also tolerates historical gaps, so rerunning it after a partial cleanup does not fail on an already-deleted version.

For Confluence Cloud V2, use get_page_versions or get_page_version to read page history. The published V2 API does not provide a delete-version operation, so deletion requires the compatible V1 endpoint and appropriate permission.

Scoped Cloud API tokens

Scoped Confluence Cloud API tokens use the Atlassian API gateway and the v2 API. Pass the gateway URL containing the cloud ID; Confluence selects the v2 Cloud client automatically and does not append /wiki.

confluence = Confluence(
    url="https://api.atlassian.com/ex/confluence/<cloud-id>",
    username="user@example.com",
    password="scoped-api-token",
    cloud=True,
)

page = confluence.get_page_by_id("<page-id>")

Confluence Cloud databases

Confluence Cloud v2 supports database lifecycle metadata: create, retrieve by ID, and move to trash. Use ConfluenceV2 (or a gateway URL as above) for these endpoints. The public API does not currently expose database records, fields, views, or queries.

from atlassian import ConfluenceV2

confluence = ConfluenceV2(
    url="https://your-domain.atlassian.net/wiki",
    username="user@example.com",
    password="api-token",
)

database = confluence.create_database(
    space_id="<space-id>",
    title="Release tracker",
    parent_id="<parent-page-or-folder-id>",
    private=False,
)
details = confluence.get_database(database["id"], include_properties=True)
confluence.delete_database(database["id"])

Scoped tokens require the corresponding write:database:confluence, read:database:confluence, or delete:database:confluence scope.

Confluence Cloud folders

Confluence Cloud v2 supports creating, retrieving, and moving folders to trash. A folder may have a page or another folder as its parent. Use ConfluenceV2 (or a gateway URL as above).

folder = confluence.create_folder(
    space_id="<space-id>",
    title="Release assets",
    parent_id="<parent-page-or-folder-id>",
)
details = confluence.get_folder(folder["id"], include_direct_children=True)
confluence.delete_folder(folder["id"])

Scoped tokens require the corresponding write:folder:confluence, read:folder:confluence, or delete:folder:confluence scope.

Additional Cloud v2 resources

The Cloud v2 client also exposes administrative and workspace operations from the current OpenAPI contract:

admin_key = confluence.get_admin_key()
permissions = confluence.get_space_permissions(limit=25)
roles = confluence.get_space_roles(space_id="<space-id>", limit=25)
users = confluence.bulk_get_users({"accountIds": ["<account-id>"]})
policies = confluence.get_data_policy_spaces(ids=["<space-id>"])

Global comments are available through get_global_footer_comments and get_global_inline_comments. Their child, likes, operations, and version resources are exposed by the corresponding *_v2 helpers.

Cloud group members

Confluence Cloud group membership uses the group ID, not its display name. The API returns group IDs from get_all_groups. The legacy Server/Data Center methods continue to use group names.

for group in confluence.get_all_groups(start=0, limit=1000):
    members = confluence.get_all_members(group["id"])

License endpoints

get_license_details and the related license-seat methods are available for Confluence Server and Data Center only. Confluence Cloud does not expose an equivalent license REST API; Cloud clients receive ApiNotAcceptable instead of an HTTP 404.