Short answer. Authenticate to Confluence, enumerate the spaces and pages you are allowed to index, read each page's content and direct restrictions, and store the page ID, space ID, version, URL and allowed principals with every chunk. At query time, resolve the user's group memberships and filter chunks before assembling context. Use CQL and version checks for sync, and test ACL leakage before rollout.
1. Model permissions before content
Confluence has more than one access layer. Space permissions decide who can see a space. Page restrictions can narrow access to specific users or groups. Inherited restrictions can apply from a parent page. A page can also be in a restricted state without listing every inherited principal.
| Control | What it covers | API | Caveat |
|---|---|---|---|
| Space permissions | Who can view or edit content in a space | GET /wiki/api/v2/spaces/{id}/permissions | Resolve group membership separately. |
| Page restrictions | Direct read or update restrictions on a page | GET /wiki/api/v2/pages/{id}/permissions | Returns direct permissions only. |
| Restriction state | Whether a page is open or restricted | GET /wiki/api/v2/pages/{id}/restriction-state | Inherited restrictions are not included. |
| Page status | Current, draft or trashed | Page object fields | Do not index drafts or trashed pages. |
The direct-only limitation is the one that causes leaks. If a parent page is restricted and a child inherits that restriction, the child's permissions endpoint may not repeat it. Walk the ancestor chain and evaluate the space, ancestor restrictions and page restrictions together. If you cannot resolve the chain, fail closed: do not index the page.
2. Authenticate and discover spaces
For a background indexer, an API token with a dedicated service account is the simplest option. For a multi-user app, use OAuth 2.0 three-legged flow so the app acts as the user. The scopes you need are read:page:confluence, read:space:confluence and, if you read blog posts, read:blogpost:confluence.
curl -s -u "$ATLASSIAN_EMAIL:$ATLASSIAN_API_TOKEN" \
"https://$SITE.atlassian.net/wiki/api/v2/spaces?limit=250" \
| jq '.results[] | {id, key, name}'
Store the service account token in a secret manager, not in the repository. A service account that can see every space is an indexer with a large blast radius; scope it to the spaces in the project and document who approved that scope.
3. Walk the hierarchy and read content
The Confluence API v2 exposes spaces, pages and children directly. Ask for body-format=storage so you get XHTML you can convert to text, and paginate with the cursor in _links.next.
GET /wiki/api/v2/spaces/{spaceId}/pages?body-format=storage&limit=250
GET /wiki/api/v2/pages/{pageId}/children?limit=250
GET /wiki/api/v2/pages/{pageId}/ancestors
The older CQL endpoint is still useful for incremental scans: GET /wiki/rest/api/content/search?cql=space%3DDEV%20and%20type%3Dpage. Be careful with expand=body.storage.value; Confluence limits that response to 50 results even if you ask for more. Use it to find changed page IDs, then fetch each page body through the v2 page endpoint.
4. Chunk with permission metadata
Convert storage XHTML to text, then chunk by heading and page section. A fixed character count cuts tables and procedures in half. Each chunk should carry enough metadata to authorize it and to cite it:
page_id,space_id,version,last_modifiedtitle,ancestor_path,section_heading,positionweb_urlfrom_links.webui, plus the base URLallowed_users[],allowed_groups[],restriction_state,source
If a chunk has no resolved permission record, mark it inaccessible. Do not default to public. Re-index a page when its version changes, and delete all chunks for a page that is trashed or no longer visible to the indexer.
5. Sync and cite
Poll CQL for pages modified since the last successful run, with a small overlap window, then compare the page version before re-embedding. A timestamp alone can miss a change that committed during the previous scan. Keep a per-page version and content hash so a no-op update does not trigger a re-embed.
Citations should be the Confluence URL the user can open, not a chunk ID. If the user cannot open the page, the answer should not cite it. When the retrieval filter returns nothing relevant, the assistant should say it does not know instead of answering from general knowledge.
6. Evaluate before rollout
| Test | How to run it | Pass condition |
|---|---|---|
| ACL leakage | Ask as a user without access to a restricted page | Page never appears in context or citations. |
| Recall | 50–100 questions with an expected page ID | Expected page is retrieved in the top results. |
| Citation validity | Open every cited URL as the requesting user | Every citation resolves and is permitted. |
| Freshness | Edit a page, sync, then ask about the change | New content is retrievable; old chunks are gone. |
| Refusal | Ask about a topic absent from the corpus | Assistant refuses instead of inventing an answer. |
For the retrieval and access-control patterns, see RAG for websites and RAG access control. For embedding and chat limits, see pricing.
FAQ
Can I build AI search over Confluence?
Yes. Read pages through the Confluence REST API, chunk the content, embed it, and store the page ID, URL, version and permissions with each chunk. Filter by the requesting user before sending context to the model.
How do I preserve Confluence permissions?
Resolve space permissions, ancestor restrictions and direct page restrictions, then store the allowed users and groups. Filter before generation; a prompt instruction is not an authorization control.
Do page permissions include inherited restrictions?
No. The page permissions endpoint returns direct permissions, and the restriction-state endpoint says inherited restrictions are not included. Walk the ancestor chain and fail closed when you cannot resolve it.
How do I keep the index fresh?
Poll CQL by last-modified time with an overlap window, compare page versions, and remove chunks for trashed or inaccessible pages. Re-embed only changed pages.
What does a Confluence assistant cost?
The main costs are embedding the corpus, re-embedding changed pages, chat tokens per query, vector storage and engineering time. Plugsky paid plans start at $8/month; Builder and Scale have no monthly token cap under fair-use limits.
Sources checked 20 November 2026: Confluence REST API v2 pages; Confluence content permissions; Confluence CQL search. Product behavior, endpoint support and plan limits can change; re-check the primary documentation before production rollout.