Confluence

Integration

ConfluenceService → ConfluenceAdapter → Confluence API v2

Service Layer

ConfluenceService

Business logic
CQL construction
Storage format handling
Pagination + tree traversal

~14 methods

→

Adapter Layer

ConfluenceAdapter

Shared Atlassian auth
OAuth 2.0 token (same as Jira)
API Token (Basic Auth)
CQL query serialization

cursor / limit pagination

→

External API

Confluence REST API

API version 2
your-domain.atlassian.net
/wiki/api/v2/
CQL search endpoint

cloud.id + access_token

OAuth 2.0 — Shared with Jira

Same Atlassian 3LO token as Jira
Scopes: read:confluence-space.summary,
write:confluence-content, read:confluence-content.all
One OAuth flow covers both products

API Token (Basic Auth)

Base64(email:api_token)
Authorization: Basic …
Same token as Jira API Token auth
Direct domain URL

What & Why

Confluence is the enterprise wiki and knowledge base. The Octopus Confluence integration exposes spaces, pages, content search, labels, and attachments through the Confluence REST API v2 — the same adapter pattern as every other Octopus integration.

Three key use cases drive this integration:

GraphRAG ingestion — read documentation pages in bulk, traverse page trees, and extract body content in storage format (XHTML) for embedding pipelines
Runbook automation — programmatically create and update operational runbooks, incident reports, and architecture decision records from agent workflows
Knowledge base search — use CQL (Confluence Query Language) to search across spaces, filter by label, page type, or text match, and surface relevant documentation to LLM agents

The ConfluenceAdapter shares the same Atlassian OAuth token as JiraAdapter. One authorization flow unlocks both products. The adapter handles Confluence's cursor-based pagination and the storage format XHTML that pages use for their body content.

Content Hierarchy

Space → Pages → Body / Labels / Attachments

Confluence Space

Space

key · name · homepage_id

↓

contains

↓

Root Page

Page (parent)

id · title · version

get_page_children→

Child Page

Page (child)

parent_id · depth

get_page_ancestors←

Ancestor

Page (ancestor)

breadcrumb path

↓

each page has

↓

Body

body.storage.value
XHTML storage format
HTML output format
get_page_body

Labels

name · prefix
get_page_labels
add_page_label
remove_page_label

Attachments

filename · media_type · size
list_attachments
add_attachment
download URL

Version History

version.number
createdAt · authorId
Auto-incremented
on every update

Methods Reference

All ~14 methods grouped by category. Key params listed for each.

Spaces

Method	Description	Key Params
`list_spaces`	List all accessible Confluence spaces	`limit`, `cursor`, `type` (`global`/`personal`)
`get_space`	Get full details for a single space	`space_id` or `space_key`
`create_space`	Create a new Confluence space	`name`, `key`, `description`

Pages

Method	Description	Key Params
`list_pages`	List pages within a space	`space_id`, `limit`, `cursor`, `status`
`get_page`	Get full page metadata and optionally body	`page_id`, `include_body`
`create_page`	Create a new page in a space	`space_id`, `title`, `body` (storage format XHTML), `parent_id`
`update_page`	Update title and/or body of an existing page	`page_id`, `title`, `body`, `version` (must be current + 1)
`delete_page`	Delete a page permanently	`page_id`
`get_page_children`	List direct child pages of a page	`page_id`, `limit`, `cursor`
`get_page_ancestors`	Get the ancestor chain (breadcrumb path) for a page	`page_id`

Content Search

Method	Description	Key Params
`search_content`	Run a CQL query to search across spaces and pages	`cql` (Confluence Query Language string), `limit`, `cursor`
`get_page_body`	Fetch just the body of a page in a specific format	`page_id`, `format` (`storage` or `html`)

Labels

Method	Description	Key Params
`get_page_labels`	List labels attached to a page	`page_id`
`add_page_label`	Add a label to a page	`page_id`, `label`
`remove_page_label`	Remove a label from a page	`page_id`, `label`

Attachments

Method	Description	Key Params
`list_attachments`	List attachments on a page	`page_id`, `limit`, `cursor`
`add_attachment`	Upload a file as an attachment to a page	`page_id`, `file_path`, `file_name`, `media_type`

CLI + CQL Examples

# List all spaces
constellation confluence list-spaces

# Get details for a specific space
constellation confluence get-space --space-id DEV

# List pages in a space
constellation confluence list-pages --space-id DEV --limit 50

# Get a specific page (including body)
constellation confluence get-page --page-id 123456 --include-body

# Fetch page body in HTML format (easier to read than storage format)
constellation confluence get-page-body --page-id 123456 --format html

# Get child pages (one level of tree)
constellation confluence get-page-children --page-id 123456

# Get the ancestor path (breadcrumb) for a page
constellation confluence get-page-ancestors --page-id 123456

# Create a new page
constellation confluence create-page --space DEV --title "New Runbook" --body "<p>Content here</p>"

# Update an existing page (version must be current version + 1)
constellation confluence update-page --page-id 123456 --title "Updated Runbook" --body "<p>Updated content</p>" --version 2

# Delete a page
constellation confluence delete-page --page-id 123456

# Search with CQL — pages in DEV space with "Architecture" in title
constellation confluence search-content --cql "space = DEV AND type = page AND title ~ 'Architecture'"

# Search with CQL — recently modified pages with a specific label
constellation confluence search-content --cql "space = DEV AND label = 'runbook' AND lastModified >= '2026-01-01'"

# Search with CQL — all pages of type blogpost across all spaces
constellation confluence search-content --cql "type = blogpost ORDER BY created DESC" --limit 20

# List labels on a page
constellation confluence get-page-labels --page-id 123456

# Add a label to a page
confluence add-page-label --page-id 123456 --label runbook

# Remove a label from a page
confluence remove-page-label --page-id 123456 --label runbook

# List attachments on a page
constellation confluence list-attachments --page-id 123456

# Upload an attachment to a page
constellation confluence add-attachment --page-id 123456 --file ./diagram.png --name "architecture-diagram.png"

HTTP API

# Search with CQL via HTTP
curl -X POST https://api.yourdomain.com/confluence/search-content \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"cql": "space = DEV AND type = page AND title ~ '\''Architecture'\''", "limit": 10}'

# Response
# {
#   "results": [
#     {"id": "123456", "title": "Architecture Overview", "spaceKey": "DEV", "type": "page"}
#   ],
#   "cursor": null
# }

# Get page body via HTTP
curl -X POST https://api.yourdomain.com/confluence/get-page-body \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"page_id": "123456", "format": "html"}'

# Create page via HTTP
curl -X POST https://api.yourdomain.com/confluence/create-page \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"space_id": "DEV", "title": "New Runbook", "body": "<p>Content here</p>"}'

Content Format: Confluence Storage Format

Confluence stores page bodies as storage format — a subset of XHTML. When creating or updating pages, the body parameter must be valid storage format XML.

<!-- Simple paragraph -->
<p>This is a paragraph.</p>

<!-- Code block (storage format macro) -->
<ac:structured-macro ac:name="code">
  <ac:parameter ac:name="language">bash</ac:parameter>
  <ac:plain-text-body><![CDATA[
echo "Hello from a code block"
  ]]></ac:plain-text-body>
</ac:structured-macro>

<!-- Link to another Confluence page -->
<ac:link>
  <ri:page ri:content-title="Target Page Title" ri:space-key="DEV"/>
</ac:link>

When reading pages, use --format html with get_page_body to retrieve rendered HTML instead of raw storage format — this is much easier to process in agent pipelines.

CQL Reference

CQL (Confluence Query Language) is modelled on JQL. Key fields and operators:

Field	Operators	Example
`space`	`=`, `!=`, `in`	`space = DEV`
`type`	`=`	`type = page`, `type = blogpost`
`title`	`=`, `~` (contains), `!~`	`title ~ "Architecture"`
`text`	`~` (full-text search)	`text ~ "incident response"`
`label`	`=`, `in`	`label = runbook`
`creator`	`=`	`creator = "john.doe@example.com"`
`lastModified`	`>=`, `<=`, `>`, `<`	`lastModified >= "2026-01-01"`
`created`	`>=`, `<=`, `>`, `<`	`created >= "2026-01-01"`
`ancestor`	`=`	`ancestor = 123456` (search within subtree)

Combine with AND, OR, NOT. Sort with ORDER BY created DESC or ORDER BY lastModified DESC.

Auth Setup

OAuth 2.0 (shared with Jira):

The Confluence integration reuses the same Atlassian OAuth 2.0 token as Jira. If your tenant is already authorized for Jira via OAuth, Confluence access is available with no additional OAuth flow — provided the OAuth app was registered with Confluence scopes.

Required scopes for full Confluence access:

read:confluence-space.summary
read:confluence-content.all
read:confluence-content.summary
write:confluence-content
write:confluence-space
read:confluence-user

API Token (Basic Auth):

Generate a token at id.atlassian.com/manage-profile/security/api-tokens
The same token works for both Jira and Confluence — same Atlassian account
Pass credentials in the connection config:
- base_url: https://your-domain.atlassian.net
- email: your Atlassian account email
- api_token: the generated token
The adapter constructs Authorization: Basic base64(email:api_token) and prefixes all paths with /wiki/api/v2/

ConfluenceService → ConfluenceAdapter → Confluence API v2

What & Why​

Space → Pages → Body / Labels / Attachments

Methods Reference​

Spaces​

Pages​

Content Search​

Labels​

Attachments​

CLI + CQL Examples​

HTTP API​

Content Format: Confluence Storage Format​

CQL Reference​

Auth Setup​

What & Why

Methods Reference

Spaces

Pages

Content Search

Labels

Attachments

CLI + CQL Examples

HTTP API

Content Format: Confluence Storage Format

CQL Reference

Auth Setup