Confluence Cloud Integration#

Confluence Cloud REST API v2 integration for wiki/documentation management, including spaces, pages, attachments, comments, and labels.

Authentication#

Confluence Cloud uses API token authentication. Required environment variables:

• CONFLUENCE_BASE_URL - Your Confluence instance (e.g., https://yourcompany.atlassian.net)
• CONFLUENCE_USER_EMAIL - Atlassian account email
• CONFLUENCE_API_TOKEN - API token from https://id.atlassian.com/manage-profile/security/api-tokens

Test connection:

bash

curl -s -u "$CONFLUENCE_USER_EMAIL:$CONFLUENCE_API_TOKEN" "$CONFLUENCE_BASE_URL/wiki/api/v2/spaces?limit=1" | jq .

Quick Reference#

All operations use the scripts/confluence.py script:

OperationCommandSpacesList spacesconfluence.py spacesGet space by IDconfluence.py space SPACE_IDGet space by keyconfluence.py space-by-key PROJCreate spaceconfluence.py create-space --name "My Space" --key MYSPPagesList pagesconfluence.py pages --space-id SPACE_IDGet pageconfluence.py page PAGE_IDCreate pageconfluence.py create-page --space-id ID --title "Title" --body "<p>Content</p>"Update pageconfluence.py update-page PAGE_ID --body "<p>New content</p>"Delete pageconfluence.py delete-page PAGE_IDPage TreeGet childrenconfluence.py children PAGE_IDGet ancestorsconfluence.py ancestors PAGE_IDSearchCQL searchconfluence.py search "type=page AND space=PROJ"AttachmentsList attachmentsconfluence.py attachments PAGE_IDGet attachmentconfluence.py attachment ATT_IDUpload fileconfluence.py upload PAGE_ID /path/to/file.pdfDownloadconfluence.py download ATT_ID -o output.pdfDelete attachmentconfluence.py delete-attachment ATT_IDCommentsList commentsconfluence.py comments PAGE_IDGet commentconfluence.py comment COMMENT_IDCreate commentconfluence.py create-comment PAGE_ID "Comment text"Update commentconfluence.py update-comment COMMENT_ID "New text"Delete commentconfluence.py delete-comment COMMENT_IDLabelsGet labelsconfluence.py labels PAGE_IDAdd labelsconfluence.py add-labels PAGE_ID "label1,label2"Remove labelconfluence.py remove-label PAGE_ID labelnameUserCurrent userconfluence.py me

Common Workflows#

Space Management#

bash

# List all spaces
confluence.py spaces

# List global spaces only
confluence.py spaces --type global

# Get space by key
confluence.py space-by-key PROJ

# Create a new space
confluence.py create-space --name "Project Documentation" --key DOCS --description "Team docs"

# Create a private space
confluence.py create-space --name "Private Notes" --key PRIV --private

Page Operations#

bash

# List pages in a space (need space ID, not key)
# First get the space ID:
confluence.py space-by-key PROJ
# Then list pages:
confluence.py pages --space-id 12345678

# Filter pages by title
confluence.py pages --title "Meeting Notes"

# Get page with body content
confluence.py page 98765432 --body-format storage

# Get page with labels
confluence.py page 98765432 --include-labels

# Get specific version
confluence.py page 98765432 --version 5

Creating Pages#

Pages use Confluence Storage Format (XHTML-based):

bash

# Simple page
confluence.py create-page --space-id 12345678 --title "New Page" \
  --body "<p>Hello World</p>"

# Page with formatting
confluence.py create-page --space-id 12345678 --title "Formatted Page" \
  --body "<h1>Heading</h1><p>Paragraph with <strong>bold</strong> text.</p><ul><li>Item 1</li><li>Item 2</li></ul>"

# Child page (under a parent)
confluence.py create-page --space-id 12345678 --title "Child Page" \
  --parent-id 98765432 --body "<p>This is a child page</p>"

# Draft page
confluence.py create-page --space-id 12345678 --title "Draft" \
  --status draft --body "<p>Work in progress</p>"

Updating Pages#

bash

# Update page content
confluence.py update-page 98765432 --body "<p>Updated content</p>"

# Update with new title
confluence.py update-page 98765432 --title "New Title" --body "<p>Content</p>"

# Update with version message
confluence.py update-page 98765432 --body "<p>Fixed typo</p>" \
  --message "Corrected spelling errors"

Deleting Pages#

bash

# Move to trash (recoverable)
confluence.py delete-page 98765432

# Permanently delete (purge)
confluence.py delete-page 98765432 --purge

Page Tree Navigation#

bash

# Get child pages
confluence.py children 98765432

# Get parent chain (ancestors)
confluence.py ancestors 98765432

Content Search (CQL)#

Confluence Query Language (CQL) supports powerful filtering:

bash

# Search by type
confluence.py search "type=page"

# Search in specific space
confluence.py search "type=page AND space=PROJ"

# Full-text search
confluence.py search "text ~ 'meeting notes'"

# Recently modified
confluence.py search "type=page AND lastModified > now('-7d')"

# By label
confluence.py search "type=page AND label=important"

# By creator
confluence.py search "type=page AND creator=currentUser()"

# Combined query
confluence.py search "type=page AND space=PROJ AND text ~ 'api' AND lastModified > now('-30d')"

Attachments#

bash

# List attachments on a page
confluence.py attachments 98765432

# Filter by filename
confluence.py attachments 98765432 --filename "report.pdf"

# Filter by media type
confluence.py attachments 98765432 --media-type "image/png"

# Upload a file
confluence.py upload 98765432 /path/to/document.pdf

# Upload with comment
confluence.py upload 98765432 /path/to/file.pdf --comment "Q3 report"

# Download attachment
confluence.py download att123456 -o downloaded_file.pdf

# Delete attachment (move to trash)
confluence.py delete-attachment att123456

# Permanently delete
confluence.py delete-attachment att123456 --purge

Comments#

bash

# List comments on a page
confluence.py comments 98765432

# Get comment with body
confluence.py comment comm123456 --body-format storage

# Add a comment
confluence.py create-comment 98765432 "<p>Great work!</p>"

# Update a comment
confluence.py update-comment comm123456 "<p>Updated comment</p>"

# Delete a comment
confluence.py delete-comment comm123456

Labels#

bash

# Get labels for a page
confluence.py labels 98765432

# Add labels
confluence.py add-labels 98765432 "documentation,api,important"

# Remove a label
confluence.py remove-label 98765432 "draft"

Storage Format Reference#

Confluence uses Storage Format (XHTML-based) for page content. See references/storage-format.md for details.

Common Elements#

html

<!-- Headings -->
<h1>Heading 1</h1>
<h2>Heading 2</h2>

<!-- Paragraphs -->
<p>Regular paragraph</p>
<p><strong>Bold</strong> and <em>italic</em> text</p>

<!-- Lists -->
<ul>
  <li>Unordered item</li>
</ul>
<ol>
  <li>Ordered item</li>
</ol>

<!-- Links -->
<a href="https://example.com">External link</a>
<ac:link><ri:page ri:content-title="Other Page" /></ac:link>

<!-- Code block -->
<ac:structured-macro ac:name="code">
  <ac:parameter ac:name="language">python</ac:parameter>
  <ac:plain-text-body><![CDATA[print("Hello")]]></ac:plain-text-body>
</ac:structured-macro>

<!-- Info panel -->
<ac:structured-macro ac:name="info">
  <ac:rich-text-body><p>Info message</p></ac:rich-text-body>
</ac:structured-macro>

<!-- Table -->
<table>
  <tr><th>Header</th></tr>
  <tr><td>Cell</td></tr>
</table>

CQL Reference#

See references/cql.md for the full CQL reference.

Common CQL Patterns#

QueryDescriptiontype=pageAll pagestype=blogpostAll blog postsspace=KEYContent in spacetext ~ "keyword"Full-text searchtitle ~ "keyword"Title searchlabel=labelnameHas labelcreator=currentUser()Created by melastModified > now('-7d')Modified last week

Error Handling#

Common errors:

• 401 Unauthorized: Check CONFLUENCE_USER_EMAIL and CONFLUENCE_API_TOKEN
• 403 Forbidden: User lacks permission for this operation
• 404 Not Found: Space, page, or content doesn't exist
• 400 Bad Request: Invalid parameters or malformed storage format

Raw API Access#

For operations not covered by the script:

bash

# V2 API (preferred)
curl -s -u "$CONFLUENCE_USER_EMAIL:$CONFLUENCE_API_TOKEN" \
  "$CONFLUENCE_BASE_URL/wiki/api/v2/pages?limit=5" | jq .

# V1 API (legacy, some features)
curl -s -u "$CONFLUENCE_USER_EMAIL:$CONFLUENCE_API_TOKEN" \
  "$CONFLUENCE_BASE_URL/wiki/rest/api/content?type=page&limit=5" | jq .

# POST with body
curl -s -X POST -u "$CONFLUENCE_USER_EMAIL:$CONFLUENCE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"spaceId":"12345","title":"Test","body":{"representation":"storage","value":"<p>Hello</p>"}}' \
  "$CONFLUENCE_BASE_URL/wiki/api/v2/pages" | jq .

API docs:

• V2: https://developer.atlassian.com/cloud/confluence/rest/v2/intro/
• V1: https://developer.atlassian.com/cloud/confluence/rest/v1/intro/