Connecting an AI Agent to Confluence: Putting Knowledge to Work
Confluence is where many engineering and operations teams keep the knowledge that matters: runbooks, architecture decision records, onboarding guides, meeting notes. Finding the right page is another matter, especially after years of growth and reorganisation. An AI agent can answer plain-language questions and point to its sources. Whether that works safely depends on how the agent reaches the content and whose permissions it uses.
What does connecting an AI agent to Confluence actually mean?
A Confluence agent is a language model with tools that search, read and, optionally, write pages. To answer a question it finds candidate pages, reads them and replies with links to the pages it used. The integration decides which content the agent can see, how fresh it is, and whether access rules survive.
Questions people typically ask such an agent:
- "What is the change approval process for production systems?"
- "Why did we pick PostgreSQL over the managed database service?"
- "What does the runbook say about restarting the billing service?"
The agent does not fix a poorly maintained wiki. It makes existing knowledge easier to find, but it will happily quote an outdated page. For the business side of knowledge agents — who uses them and for what — see the page on knowledge management agents. This article covers the Confluence-specific plumbing.
What are the integration options?
There are three patterns: live search through the REST API using CQL, a separate search index kept in sync, or Atlassian's hosted MCP server. Live search is simplest and always current. An index handles paraphrased questions better. The MCP server removes most custom code but is limited to Confluence Cloud.
Live search with the REST API and CQL
The agent gets a "search Confluence" tool that calls the search endpoint. On Confluence Cloud that is GET /wiki/rest/api/search with a required cql parameter. According to Atlassian's search API reference, only content the calling user has permission to view is returned. The model writes the query, reads the hits and answers.
Confluence Query Language (CQL) lets the agent narrow results by space, content type or date:
space = "OPS" AND type = page AND text ~ "restart billing"
lastmodified > startOfDay("-7d") AND space = "ARCH"
Relative date functions such as startOfDay() are listed in the CQL functions reference.
A separate index
A background job pulls pages on a schedule, splits them into sections, computes embeddings and stores them in a search index. The agent then queries the index instead of Confluence. This is the retrieval-augmented generation pattern; the building blocks and failure modes are covered in enterprise RAG architecture. It finds pages that use different wording from the question, at the price of having to sync changes, deletions and permissions yourself.
Atlassian's Rovo MCP Server
Atlassian runs a hosted Rovo MCP Server at https://mcp.atlassian.com/v2/mcp. MCP clients authenticate through OAuth 2.1, or with an API token for headless use, and get tools for CQL search and for reading, creating and updating pages. Atlassian states that the server never grants access beyond what the user already has, and calls consume Rovo credits. For MCP in general, including how to vet third-party servers, see MCP servers: connecting AI agents in a standard way; this article focuses on what is specific to Confluence.
How does the agent read pages? REST API v2 and the storage format
For bulk retrieval on Cloud, use REST API v2. GET /wiki/api/v2/pages filters by space, sorts by modification date and returns page bodies in a chosen format. The format is the part teams underestimate: Confluence stores pages as XML-like markup with its own elements, not as clean text.
The REST API v2 reference (checked November 2026) lists, for GET /pages:
space-idfilters on up to 100 spaces,sortaccepts values includingmodified-dateand-modified-date,body-formatacceptsstorageoratlas_doc_format,limitdefaults to 25 with a maximum of 250,- further results come via the
nextURL in theLinkheader (cursor pagination), - the OAuth scope required is
read:page:confluence.
A minimal paging loop in Python (a sketch using requests, with email and API token authentication as described in Atlassian's basic auth guide):
import os
import requests
BASE = os.environ["CONFLUENCE_BASE"] # e.g. https://your-site.atlassian.net
AUTH = (os.environ["CONFLUENCE_EMAIL"], os.environ["CONFLUENCE_API_TOKEN"])
def pages_in_space(space_id: str):
url = f"{BASE}/wiki/api/v2/pages"
params = {"space-id": space_id, "body-format": "storage",
"sort": "-modified-date", "limit": 100}
while url:
r = requests.get(url, params=params, auth=AUTH, timeout=30)
r.raise_for_status()
for page in r.json()["results"]:
yield page["id"], page["title"], page["body"]["storage"]["value"]
nxt = r.links.get("next", {}).get("url")
url, params = (f"{BASE}{nxt}" if nxt else None), None
What the storage format contains
Atlassian describes the Confluence storage format as XHTML-based, though technically XML because of its custom elements. Page links appear as <ac:link> wrapping <ri:page ri:space-key="…" ri:content-title="…"/>, attachments as <ri:attachment ri:filename="…"/>, task lists as <ac:task-list>. Feeding this raw into a model wastes context and confuses it. Convert to Markdown that keeps headings, tables and page links, and drops layout wrappers.
Three things conversions often get wrong:
- Ignoring headings. A section under a heading is a better retrieval unit than a fixed-size chunk.
- Flattening tables. Runbooks and configuration references often live in tables; as running text they lose their meaning.
- Dropping macros. Expand and info macros frequently hold the actual answer.
How do you keep Confluence permissions intact?
Permissions survive when every lookup runs as the person asking. Live search and the MCP server do this automatically, provided the agent uses that person's session or token. With your own index you must store permissions alongside the content and filter on every query; otherwise everyone sees whatever the indexing account could read.
Confluence enforces access at two levels: space permissions and restrictions on individual pages. REST API v2 exposes both: GET /spaces/{id}/permissions returns a space's permission assignments and GET /pages/{id}/permissions the direct permissions on a page, as documented in the API reference.
For an index, that means:
- Store permissions as metadata on every chunk: the space and the groups or users allowed to read it.
- Filter before retrieval, not after. Restrict the index query to what the user may see before anything reaches the model.
- Propagate permission changes quickly. A newly restricted page should drop out of results well before the next full sync.
- Re-check sensitive content. For HR or legal spaces, the agent can confirm with the user's own token that a page is accessible before quoting it.
The tempting shortcut — one service account with read access to everything, answering anyone — quietly bypasses page restrictions. Under the GDPR and similar regimes, a setup like this can be operated in line with the GDPR only if access rights are passed through consistently; treat this as orientation, not legal advice.
Confluence Cloud vs Data Center: what changes?
Cloud and Data Center differ in API, authentication and long-term outlook. Cloud offers REST API v2 and the hosted MCP server. Data Center uses the older REST API with personal access tokens. Atlassian has also announced the end of life of Confluence Data Center, which limits how much you should invest in a Data Center-only integration.
| Criterion | Confluence Cloud | Confluence Data Center |
|---|---|---|
| Page API | REST API v2 (/wiki/api/v2/pages) | REST API under /rest/api/ |
| Search | /wiki/rest/api/search?cql= | /rest/api/content/search?cql= |
| Authentication | OAuth app (3LO), email + API token | personal access tokens (Bearer) |
| Atlassian MCP server | yes (Rovo MCP Server) | not documented |
| Where data lives | Atlassian's cloud | your own data centre |
Working with Data Center
According to Atlassian's guide, personal access tokens are available from Confluence 7.9. They are sent as Authorization: Bearer <token> and match their owner's current permission level. CQL search works as on Cloud, for example /rest/api/content/search?cql=space=TEST per the Data Center CQL documentation.
The case for Data Center is control: if the language model also runs on your own infrastructure, content never leaves your network. Organisations that chose Data Center for that reason will usually want a self-hosted model as well; the sovereign AI page outlines that setup.
The announced end of Data Center
According to Atlassian Ascend, Confluence Data Center reaches end of life on 28 March 2029. Customers without an agreed plan will see their licence expire that day and their environment become read-only. Atlassian mentions extended maintenance by exception for certain customers.
Practical consequence: build the Confluence connector as a replaceable module. Keep search, page retrieval and permission checks behind your own interface, so a later move to Cloud changes that layer and not the agent.
What do you need before you start?
You need three things: clear access rules, a decision on which spaces the agent should cover, and content that is current enough to be worth quoting. Technically, an API credential and a model with tool use are enough. The harder question is usually organisational: who owns outdated pages?
- Systems: Confluence Cloud with an API token or OAuth app, or Data Center 7.9+ with personal access tokens; a model that supports tool calling, hosted or self-run.
- Space selection: Do not index everything. Personal spaces, archives and sandbox spaces skew answers.
- Content quality: If three pages contradict each other, the agent will quote one of them. Labels such as "deprecated" make it possible to exclude stale pages.
- Employee representation: Where works councils or similar bodies exist (common in Germany and other EU countries), involve them early if the agent processes content linked to individuals.
- Operations: Someone has to watch sync errors, cost and user feedback.
How do you roll it out step by step?
Start with a narrow, read-only agent on a few spaces using live search. Record which questions it cannot answer. Only when keyword search demonstrably misses too often is an index worth building. Write access comes last, and only behind human approval.
- Collect a question set. Twenty to thirty real questions from support, operations or onboarding, each with the page that holds the answer.
- Pick spaces. Two to four well-maintained spaces.
- Build a read-only agent with live search. Two tools: "search" (CQL) and "read page" (storage format to Markdown), running with the asking user's credentials.
- Require citations. Every answer links its pages; if nothing fits, the agent says so.
- Evaluate against the question set. How often does it find the right page? Where does the conversion lose content?
- Add an index if needed. Heading-based chunks, permissions as metadata, incremental sync on
lastmodified, and a periodic full sync to catch deletions. - Allow writing last. For example, draft meeting notes that a person approves.
In our own operations, rerunning the question set after every change to conversion or search has been the most reliable way to catch regressions before users notice them.
What are the limits and risks?
The main risks are stale content, broken permissions and lossy conversion. An agent quotes a five-year-old page with the same confidence as yesterday's. An index without permission filtering exposes restricted pages. A crude text conversion drops tables and macro content that carried the answer.
- Stale knowledge: Show the last-modified date of each cited page next to the answer.
- Permissions: Over-privileged service accounts are the most common failure.
- Deletions: An incremental sync by modification date does not see deleted or moved pages; without regular full syncs they linger in the index.
- Attachments: PDFs and Office files attached to pages are not part of the storage format and need their own retrieval and conversion.
- Vendor lock-in: The Rovo MCP Server is convenient, but ties you to Cloud and to Atlassian's credit model.
- When it is the wrong tool: If most of the relevant knowledge sits in file shares, tickets or email, a Confluence-only agent will not solve the problem.
Where should you start?
Start with the question set and a read-only agent on a handful of spaces. Within a short pilot you will know whether your Confluence content can answer the questions at all. If it can, the measured gaps tell you whether live search is enough or an index is justified.
Settle early whether you are on Cloud or Data Center and what your plan is before 2029; authentication, the MCP option and where the model runs all depend on it. For an overview of agents by department and typical starting points, see AI agents for business; terms such as Model Context Protocol and embeddings are explained in the glossary.
Frequently asked questions
Do I need a vector database to chat with Confluence?
Not necessarily. For small and medium wikis, live CQL search plus reading the top pages often works well enough. Build an index once you can show that keyword search misses too many real questions.
Can the agent leak restricted pages?
Only if it runs under a service account that can read everything and answers for everyone. When each request uses the asking person's OAuth session or token, Confluence returns only what that person may see.
Is the Atlassian MCP server available for Data Center?
Atlassian documents the Rovo MCP Server as a hosted service for Atlassian Cloud. On Data Center, the REST API with personal access tokens remains the usual route.
Should the agent be allowed to edit pages?
Start read-only. Writing is technically possible through both the REST API and the MCP server, but it needs approval steps and an audit trail before it belongs in production.
Sources
- Atlassian Developer: Confluence Cloud REST API v2 – Page developer.atlassian.com
- Atlassian Developer: Confluence Cloud REST API v1 – Search (CQL) developer.atlassian.com
- Atlassian Developer: CQL functions developer.atlassian.com
- Atlassian Support: Confluence Storage Format confluence.atlassian.com
- Atlassian Developer: Rovo MCP Server developer.atlassian.com
- Atlassian Developer: Basic auth for REST APIs (Confluence Cloud) developer.atlassian.com
- Atlassian Support: Using personal access tokens (Data Center) confluence.atlassian.com
- Atlassian Developer: Advanced searching using CQL (Data Center) developer.atlassian.com
- Atlassian Ascend: Data Center end of life atlassian.com