Confluence Agent

The confluence agent connects to Confluence Cloud via REST API v2. It uses Basic auth (email + API token) to fetch page content, search with CQL, and create or update pages. Fetched pages are converted from Confluence storage format to markdown for downstream consumption. Target operations accept HTML content for creating or updating pages.

---

Sample Phase

- name: fetch-spec
  agent: confluence
  action: get_page
  sources:
      - name: spec.json
        ref: "12345678"

---

Phase Configuration

Actions

Action	Direction	Description
get_page	Source	Fetch a page by ID; content is converted to markdown
search	Source	Run a CQL query and return matching pages
create_page	Target	Create a new page in a space
update_page	Target	Update an existing page; auto-increments the version number

Phase YAML Fields

Field	Type	Required	Description
name	string	Yes	Unique phase name within the workflow
type	string	No	Defaults to "standard"
agent	string	Yes	Must be "confluence"
depends_on	string[]	No	Upstream phases that must complete before this phase runs
action	string	Yes	One of: get_page, search, create_page, update_page
sources	SourceEntry[]	For fetch actions	Entries to fetch from Confluence
target_entries	TargetEntry[]	For write actions	Entries to deliver to Confluence

Source Entry Fields

Field	Type	Required	Description
name	string	Yes	Output filename (written to .cliq/files/{phase}/{name})
ref	string	Yes	Page ID (for get_page) or CQL query string (for search)

Target Entry Fields

Field	Type	Required	Description
name	string	Yes	Identifier for the operation
ref	string	Yes	Page ID (for update_page) or space key (for create_page)
title	string	Yes	Page title
file	string	Yes	Workspace file containing page content (HTML)

---

Settings

Confluence credentials are configured under agents.confluence in settings.json:

Key	Required	Default	Description
agents.confluence.base_url	Yes	—	Confluence instance URL (e.g., https://your-org.atlassian.net)
agents.confluence.email	Yes	—	Atlassian account email for API auth
agents.confluence.api_token	Yes	—	Confluence API token (same token type as Jira)

---

Output

Handoff Structure

Source operations return page metadata and content; target operations confirm creation or update.

get_page

{
    "data": {
        "action": "get_page",
        "sources": {
            "design-doc": {
                "ref": "123456",
                "page_id": "123456",
                "title": "Architecture Overview",
                "space_key": "ENG"
            }
        },
        "targets": {}
    },
    "text": "## Confluence Results\n\n✓ Fetched design-doc — Architecture Overview"
}

search

{
    "data": {
        "action": "search",
        "sources": {
            "results": {
                "ref": "type = page AND space = ENG AND text ~ 'migration'",
                "page_id": "search",
                "results": 8
            }
        },
        "targets": {}
    },
    "text": "## Confluence Results\n\n✓ Searched results (8 pages)"
}

create_page

{
    "data": {
        "action": "create_page",
        "sources": {},
        "targets": {
            "new-page": {
                "ref": "ENG",
                "page_id": "789012",
                "title": "API Migration Guide",
                "version": 1,
                "url": "https://myco.atlassian.net/wiki/spaces/ENG/pages/789012"
            }
        }
    },
    "text": "## Confluence Results\n\n✓ Created API Migration Guide → https://myco.atlassian.net/wiki/spaces/ENG/pages/789012"
}

update_page

{
    "data": {
        "action": "update_page",
        "sources": {},
        "targets": {
            "updated-doc": {
                "ref": "123456",
                "page_id": "123456",
                "title": "Architecture Overview",
                "version": 4,
                "url": "https://myco.atlassian.net/wiki/spaces/ENG/pages/123456"
            }
        }
    },
    "text": "## Confluence Results\n\n✓ Updated Architecture Overview (v4) → https://myco.atlassian.net/wiki/spaces/ENG/pages/123456"
}

Field Reference

Field	Location	Description
ref	data.sources.*, data.targets.*	Page ID, space key, or CQL query
page_id	data.sources.*, data.targets.*	Confluence page ID
title	data.sources.*, data.targets.*	Page title
space_key	data.sources.*	Space key where the page lives (get_page only)
results	data.sources.*	Number of search results (search only)
version	data.targets.*	Page version number after create/update
url	data.targets.*	Browsable URL of the created or updated page

Files Written

Source operations write to .cliq/files/{phase}/{source.name}:

• get_page — Page content converted to markdown
• search — JSON array of matching page objects with ID, title, space, and excerpt

Downstream Access

Reference handoff data in downstream phases using template variables:

- name: review
  agent: cursor
  prompt: |
      Review the design doc "$(handoff.fetch-doc.sources.design-doc.title)"
      from the $(handoff.fetch-doc.sources.design-doc.space_key) space.

---

Examples

Example: Fetch a design doc and generate implementation tasks

Pull a design document from Confluence and have an LLM break it into implementation tasks.

phases:
    - name: fetch-design
      agent: confluence
      action: get_page
      sources:
          - name: design-doc
            ref: "456789"

    - name: plan
      agent: cursor
      depends_on: [fetch-design]
      prompt: |
          Read the design doc "$(handoff.fetch-design.sources.design-doc.title)"
          and produce a list of implementation tasks with acceptance criteria.

Example: Search for related documentation

Find all pages related to a topic and summarize them for context.

phases:
    - name: find-docs
      agent: confluence
      action: search
      sources:
          - name: results
            ref: "type = page AND space = ENG AND text ~ 'authentication'"

    - name: summarize
      agent: cursor
      depends_on: [find-docs]
      prompt: |
          Summarize the $(handoff.find-docs.sources.results.results) pages
          found about authentication. Highlight any conflicting information.

Example: Publish generated documentation

Generate documentation with an LLM, then publish it to Confluence.

phases:
    - name: generate-docs
      agent: cursor
      role: technical-writer
      prompt: |
          Generate HTML documentation for the payments module API.
          Write the output to docs-output.html.

    - name: publish
      agent: confluence
      action: create_page
      depends_on: [generate-docs]
      target_entries:
          - name: new-page
            ref: "ENG"
            title: "Payments Module API Reference"
            file: docs-output.html

Example: Keep a living document updated

Fetch the current page, regenerate content, and update it in place.

phases:
    - name: fetch-current
      agent: confluence
      action: get_page
      sources:
          - name: current
            ref: "234567"

    - name: regenerate
      agent: cursor
      depends_on: [fetch-current]
      prompt: |
          Update the runbook at "$(handoff.fetch-current.sources.current.title)"
          with the latest deployment procedures. Output HTML to runbook.html.

    - name: update-page
      agent: confluence
      action: update_page
      depends_on: [regenerate]
      target_entries:
          - name: updated-doc
            ref: "234567"
            title: "$(handoff.fetch-current.sources.current.title)"
            file: runbook.html

---

Setup

1. Find your Confluence instance URL: https://your-org.atlassian.net (Cloud) or your self-hosted URL
2. Go to https://id.atlassian.com/manage-profile/security/api-tokens
3. Click Create API token, name it (e.g., cliq-confluence), and copy it
4. Confirm your account email at https://id.atlassian.com/manage-profile/email

The same Atlassian API token works for both Jira and Confluence. Permissions are inherited from your Atlassian account.

cliq settings agents.confluence.base_url "https://your-org.atlassian.net" --global
cliq settings agents.confluence.email "[email protected]" --global
echo $CONFLUENCE_TOKEN | cliq settings agents.confluence.api_token --stdin --global
cliq doctor agent confluence

---

See Also

• Agent Overview
• Agent SDK