snowsand-confluence（雪沙交汇处）

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:

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:

Common Workflows

Space Management

# 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

# 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):

# 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

# 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

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

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

Page Tree Navigation

# 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:

# 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

# 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

# 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

# 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

<!-- 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

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:

# 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/