Confluence Pages
Find, read and write Confluence Cloud pages: browse spaces, look up pages by title or space, read page bodies, walk the page tree, read labels and comments, create new pages, update existing ones and leave footer comments. Curated from Atlassian's official OpenAPI specification.
Connect this API to an AI agent Browse all specs
What you can do with Confluence Pages via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /spaces |
listSpaces | List the Confluence spaces you can see (filter by key or type) |
| GET | /spaces/{id} |
getSpace | Get one space by its numeric id, including its homepage id |
| GET | /pages |
listPages | List pages, filtered by exact title, space ids or status |
| POST | /pages |
createPage | Create a new page in a space, optionally under a parent page |
| GET | /spaces/{id}/pages |
listPagesInSpace | List the pages in one space |
| GET | /pages/{id} |
getPage | Get a page with its body (use body-format=storage) and current version |
| PUT | /pages/{id} |
updatePage | Replace a page's title and body (version number must be current + 1) |
| GET | /pages/{id}/direct-children |
listChildPages | List the direct child pages of a page |
| GET | /pages/{id}/labels |
listPageLabels | List the labels on a page |
| GET | /pages/{id}/footer-comments |
listPageFooterComments | List the comments at the bottom of a page |
| POST | /footer-comments |
createFooterComment | Add a comment at the bottom of a page |
Authentication
basicAuth
HTTP Basic
HTTP Basic auth: your Atlassian account email as the username and an API token as the password.
How to get a credential
- Sign in at https://id.atlassian.com/manage-profile/security/api-tokens with the Atlassian account that can see the Confluence spaces you need.
- Click Create API token (or Create API token with scopes and pick the Confluence scopes below), give it a name and an expiry, then copy the token. It is shown only once.
- Username = your account email, password = the token. The calls run with that account's Confluence permissions, so the account must be able to view (and edit, for writes) the target spaces.
Permissions used
Classic API tokens act with the account's permissions. Scoped tokens need these granular scopes:
| Scope | Operations |
|---|---|
read:page:confluence |
listPages, getPage, listPagesInSpace, listPageLabels |
write:page:confluence |
createPage, updatePage |
read:space:confluence |
listSpaces, getSpace |
read:hierarchical-content:confluence |
listChildPages |
read:comment:confluence |
listPageFooterComments |
write:comment:confluence |
createFooterComment |
Common errors
- 401 Unauthorized: wrong email/token pair, an expired or revoked token, or the token was sent as Bearer. Use Basic auth with email:token.
- 403 Forbidden: the account lacks permission on that space or page, or a scoped token is missing a scope from the table.
- 400 Bad Request: invalid body, e.g. updatePage without
version.numberset to current + 1, or an unknownspaceId. - 404 Not Found: wrong site name in the base URL, or a page/space id the account cannot see.
- 409 Conflict: version conflict on update; re-read the page and retry with the latest version + 1.
- 429 Too Many Requests: rate limited; wait for the
Retry-Afterseconds before retrying.
Store the email and token together as a VX Agents credential for this spec; never paste the token into chat.
Usage guide
Setup
- Credential: Basic auth with your Atlassian email + API token (see the auth docs).
- Base URL: replace
{site}with your site name (acmefor https://acme.atlassian.net). The API path/wiki/api/v2is already included. - Worth pinning: the
space-idof the space you work in most (get it once with listSpaces, filterkeys=ENG).
Find and update a page
- listSpaces with
keysto turn a space key (ENG) into its numericid. - listPages with
title(exact match) andspace-id, or listPagesInSpace to browse. There is no full-text/CQL search in v2: search by exact title or walk the tree. - getPage with
body-format=storageto read the content and the currentversion.number. - listChildPages / listPageLabels / listPageFooterComments for context.
- Draft the change and show it to the user. After they confirm, call updatePage with
id,status: current,title,body: {representation: storage, value}andversion: {number: <current + 1>}. The whole body is replaced, so send the full new content, not just the changed part.
Create a page or comment
- createPage:
spaceId,status: current(ordraft),title,parentId(optional, defaults to the space homepage),body: {representation: storage, value: "<p>...</p>"}. - createFooterComment:
pageId+body: {representation: storage, value}. Confirm the title, location and content with the user before creating; pages and comments are visible to everyone with access to the space and watchers get notified.
Good to know
- Ids are numeric strings; space keys (ENG) are not ids.
- Storage format is XHTML (
<p>,<h2>,<ul><li>,<ac:structured-macro>). Keep macros you did not change when you update a page. - Lists are cursor paginated: follow
_links.next(pass itscursor),limitup to 250. - 409 on update means someone else edited the page: re-read it and redo the edit on the new version.
- Deleting pages is intentionally not available.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Confluence Pages” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.