api-confluence

name	api-confluence
description	Confluence REST API for pages, spaces, and content. Uses API token for headless/CI. Activate for Confluence operations.
allowed-tools	Bash, Read, Grep
user-invocable	true
quality_grade	C
quality_checked	"2026-03-19T00:00:00.000Z"

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": "[e-mail]",
  "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.