Overview
The Confluence integration enables Potpie agents to interact with Confluence workspaces using Atlassian OAuth 2.0 (3LO), providing access to spaces, pages, and content management.
Quick Start
Create Atlassian OAuth App
Go to Atlassian Developer ConsoleCreate OAuth 2.0 integration:
- App name: Potpie AI
- Callback URL:
https://app.potpie.ai/integrations/confluence/callback
- Permissions: See scopes below
Configure Environment
# Can reuse Jira credentials if same Atlassian account
CONFLUENCE_CLIENT_ID=your_client_id
CONFLUENCE_CLIENT_SECRET=your_client_secret
CONFLUENCE_OAUTH_SCOPE="write:confluence-content read:confluence-space.summary ... offline_access"
Connect Confluence Site
- Settings → Integrations → Confluence
- Click “Connect”
- Select the Confluence site
- Authorize permissions
- Name the integration
Test Integration
“List all Confluence spaces”“Search Confluence for ‘API documentation‘“
OAuth Setup
Atlassian OAuth 2.0 (3LO)
Authorization URL: https://auth.atlassian.com/authorize
Token URL: https://auth.atlassian.com/oauth/token
API Base: https://api.atlassian.com/ex/confluence/{cloud_id}
Required Scopes
write:confluence-content # Create/update pages
read:confluence-space.summary # Read space info
write:confluence-space # Manage spaces
write:confluence-file # Upload attachments
read:confluence-props # Read properties
write:confluence-props # Write properties
read:confluence-content.all # Read all content
read:confluence-content.summary # Read summaries
search:confluence # Search (CQL)
read:confluence-content.permission # Read permissions
read:confluence-user # Read user info
read:confluence-groups # Read groups
readonly:content.attachment:confluence # Read attachments
read:space:confluence # Read spaces
read:page:confluence # Read pages
write:page:confluence # Write pages
write:comment:confluence # Write comments
read:content-details:confluence # Read details
offline_access # Refresh tokens
Cloud ID
Same as Jira - fetch accessible resources after OAuth:
GET https://api.atlassian.com/oauth/token/accessible-resources
Authorization: Bearer {access_token}
The Confluence integration provides 7 tools. See Confluence Tools in the Tools Reference for full documentation.
| Tool | Description |
|---|
| Space Lister | List all spaces |
| Page Fetcher | Fetch a page by ID |
| Space Pages | List pages in a space |
| Page Search | Search using CQL |
| Page Creator | Create a new page |
| Page Updater | Update an existing page |
| Comment Writer | Add a comment to a page |
Confluence uses its own storage format for content:
<p>Hello world!</p>
<p>This is <strong>bold</strong> and <em>italic</em> text.</p>
<h2>Heading 2</h2>
<ul>
<li>Item 1</li>
<li>Item 2</li>
</ul>
<ac:structured-macro ac:name="code">
<ac:plain-text-body><![CDATA[
console.log('Hello');
]]></ac:plain-text-body>
</ac:structured-macro>
create_confluence_page_tool accepts HTML or plain text.
- HTML: Passed through directly as Confluence storage format.
- Plain text: Automatically wrapped in
<p> tags.
For code blocks, wrap content manually using HTML tags (<pre>, <code>) or the Confluence macro XML shown above.
CQL (Confluence Query Language)
Basic Syntax
# Search by text
text ~ "authentication"
# Filter by space
space = DOCS
# Filter by type
type = page
# Combine conditions
space = DOCS AND type = page AND text ~ "API"
# Date filters
lastModified >= "2024-01-01"
created >= now("-7d")
# User filters
creator = currentUser()
contributor = "john@company.com"
# Sort results
order by lastModified desc
Advanced Examples
# Recent pages in multiple spaces
space in (DOCS, ENG) AND lastModified >= now("-30d")
# Pages with specific label
label = "api-docs" AND space = DOCS
# My recent edits
contributor = currentUser() AND lastModified >= now("-7d")
# Popular pages
space = DOCS AND type = page ORDER BY lastModified desc
Webhook Support
Confluence OAuth 2.0 apps cannot register webhooks via API. Webhooks are only available for Atlassian Connect apps.
For endpoint details and request schemas, see the API reference.
What’s Next?
