d0nghyun/api-confluence

Confluence API Skill

When to Activate

• Read/create/update pages
• Manage spaces
• Search content
• Handle attachments and labels

Authentication

Credentials File: .credentials/atlassian.json

{
  "base_url": "https://yourcompany.atlassian.net",
  "user_email": "[email protected]",
  "api_token": "..."
}

Create token at: https://id.atlassian.com/manage-profile/security/api-tokens

Load credentials before API calls:

ATLASSIAN_BASE_URL=$(jq -r '.base_url' /Users/dhlee/Git/personal/neuron/.credentials/atlassian.json)
ATLASSIAN_USER_EMAIL=$(jq -r '.user_email' /Users/dhlee/Git/personal/neuron/.credentials/atlassian.json)
ATLASSIAN_API_TOKEN=$(jq -r '.api_token' /Users/dhlee/Git/personal/neuron/.credentials/atlassian.json)

API Base URL

$ATLASSIAN_BASE_URL/wiki/rest/api

Required Headers

-u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN"
-H "Content-Type: application/json"
-H "Accept: application/json"

Common Operations

Get Current User

curl -s -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  "$ATLASSIAN_BASE_URL/wiki/rest/api/user/current"

List Spaces

curl -s -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  "$ATLASSIAN_BASE_URL/wiki/rest/api/space"

Get Space

curl -s -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  "$ATLASSIAN_BASE_URL/wiki/rest/api/space/{spaceKey}"

Search Content

curl -s -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  "$ATLASSIAN_BASE_URL/wiki/rest/api/content/search?cql=text~'search term'"

Get Page by ID

curl -s -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  "$ATLASSIAN_BASE_URL/wiki/rest/api/content/{pageId}?expand=body.storage,version"

Get Page by Title

curl -s -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  "$ATLASSIAN_BASE_URL/wiki/rest/api/content?title=Page%20Title&spaceKey={spaceKey}&expand=body.storage"

Create Page

curl -s -X POST \
  -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "page",
    "title": "New Page Title",
    "space": {"key": "{spaceKey}"},
    "body": {
      "storage": {
        "value": "<p>Page content in HTML</p>",
        "representation": "storage"
      }
    }
  }' \
  "$ATLASSIAN_BASE_URL/wiki/rest/api/content"

Update Page

curl -s -X PUT \
  -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "version": {"number": 2},
    "title": "Updated Title",
    "type": "page",
    "body": {
      "storage": {
        "value": "<p>Updated content</p>",
        "representation": "storage"
      }
    }
  }' \
  "$ATLASSIAN_BASE_URL/wiki/rest/api/content/{pageId}"

Get Page Children

curl -s -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  "$ATLASSIAN_BASE_URL/wiki/rest/api/content/{pageId}/child/page"

Add Label to Page

curl -s -X POST \
  -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"prefix": "global", "name": "label-name"}]' \
  "$ATLASSIAN_BASE_URL/wiki/rest/api/content/{pageId}/label"

Get Page Labels

curl -s -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  "$ATLASSIAN_BASE_URL/wiki/rest/api/content/{pageId}/label"

CQL (Confluence Query Language)

Common CQL queries:

• space=SPACEKEY - Content in specific space
• type=page - Only pages
• title~"keyword" - Title contains keyword
• text~"keyword" - Content contains keyword
• label=labelname - Content with label
• creator=currentUser() - Created by current user

Combine with AND/OR:

space=DEV AND type=page AND label=api

Error Handling

| Status | Meaning | Action | |--------|---------|--------| | 401 | Invalid credentials | Check email and API token | | 403 | No permission | Verify space/page permissions | | 404 | Not found | Check page ID or space key | | 409 | Version conflict | Get latest version and retry | | 429 | Rate limited | Wait and retry |

Naming Convention Discovery

NEVER hardcode naming conventions. Always infer from existing pages.

Before creating any page:

1. Query sibling pages under the parent
2. Extract naming pattern (prefix, numbering format, structure)
3. Generate next title following the pattern

# 1. Get existing page titles under parent
curl -s -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  "$ATLASSIAN_BASE_URL/wiki/rest/api/content/{parentPageId}/child/page" \
  | jq '.results[] | .title'

# 2. AI infers pattern from titles like:
#    "MTNG-0004-Title", "MTNG-0005-Title"
#    → Pattern: MTNG-{4-digit}-{title}
#    → Next: MTNG-0006-{new-title}

This approach lets the convention evolve in Confluence without touching the skill file.