A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Confluence API is how an app or AI agent works with a Confluence workspace: reading and creating pages, organizing them into spaces, posting blog posts, and adding comments. Access is granted through an OAuth token carrying granular permissions that name a resource and an action, and an agent is limited to the spaces and content the user behind the token can already see. Confluence is moving from a broad original API to a faster, more specialized one, and it can push events to a registered app when content changes.
How an app or AI agent connects to Confluence determines what it can reach. There are several routes, each governed by the token behind it and the permissions that token carries.
The v2 REST API answers under the base path /wiki/api/v2 on a site at https://a-site.atlassian.net. It splits the old broad content endpoints into specialized ones for pages, blog posts, spaces, and comments, which are faster and map to granular OAuth scopes. Lists page through a cursor returned in the Link header.
The original v1 REST API answers under /wiki/rest/api and still hosts capabilities v2 does not yet cover, most notably CQL content search. Atlassian is deprecating parts of v1 in favor of v2, but the search endpoints remain.
Atlassian's first-party Rovo MCP Server connects Jira, Confluence, and Compass to an AI agent or LLM client through the Model Context Protocol. It is generally available at https://mcp.atlassian.com/v1/mcp, uses OAuth 2.1, and acts only within the signed-in user's existing permissions. Tools cover searching and summarizing Confluence and creating or updating pages in natural language.
A Connect or Forge app can subscribe to Confluence webhook events, and Confluence posts a payload to the app's registered URL when one fires, such as a page being created or updated. Webhooks are configured by the app, not by a standalone OAuth integration.
Three-legged OAuth lets a user grant an app access to their Confluence through a consent screen. The app receives an access token carrying the granular scopes the user approved, such as read:page:confluence or write:space:confluence, and calls the API through the cloud id of the authorized site. This is the route for an external app or AI agent.
A user creates an API token and sends it with their email address as HTTP Basic auth. The token carries that user's full permissions, with no per-scope narrowing, so it suits scripts and server-to-server jobs rather than least-privilege agent access.
A Forge app runs on Atlassian's own platform and declares the scopes it needs in its manifest. It can call the API as the app or as the user, and is the path for an integration that lives inside Confluence rather than calling in from outside.
The Confluence API is split into areas an agent can act on, such as pages, spaces, blog posts, comments, attachments, and labels. Each area has its own methods and its own permissions, and some grant access to far more than others.
List pages, read a page by id, create and update pages, list a page's child pages and versions, and delete a page.
List spaces, read a space by id, create a space, and list the pages inside a space.
List blog posts, read one by id, create, update, and delete blog posts, and list the blog posts in a space.
List a page's footer and inline comments, read a comment by id, create a footer or inline comment, and delete a footer comment.
List attachments, read an attachment by id, list a page's attachments, and delete an attachment.
List all labels, and list the labels on a page or a space.
Search content with the Confluence Query Language, and search for users.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
PagesList pages, read a page by id, create and update pages, list a page's child pages and versions, and delete a page.8 | ||||||
| GET | /wiki/api/v2/pages | Return all pages the token can view, limited by the limit parameter. | read | read:page | Current | |
Only pages the user behind the token can view are returned. Full scope: read:page:confluence. Acts onpage Permission (capability) read:pageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /wiki/api/v2/pages/{id} | Return a specific page by its id. | read | read:page | Current | |
The body-format parameter selects the content representation returned, such as storage or atlas_doc_format. Full scope: read:page:confluence. Acts onpage Permission (capability) read:pageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /wiki/api/v2/pages | Create a page in a space. Pages are created as published by default. | write | write:page | Current | |
A draft can be created instead by setting the status to draft. Full scope: write:page:confluence. Acts onpage Permission (capability) write:pageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /wiki/api/v2/pages/{id} | Update an existing page's title, content, or status. | write | write:page | Current | |
The request must send the next version number, so a page is read before it is updated. Full scope: write:page:confluence. Acts onpage Permission (capability) write:pageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /wiki/api/v2/pages/{id} | Delete a page, moving it to the trash or purging it permanently. | write | write:page | Current | |
Deleting uses the write scope, not a separate delete scope. A purge of an already-trashed page is permanent. Full scope: write:page:confluence. Acts onpage Permission (capability) write:pageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /wiki/api/v2/pages/{id}/children | List the direct child pages of a page. | read | read:hierarchical-content | Current | |
Walking the page tree uses read:hierarchical-content:confluence, a different scope from reading a single page. Acts onpage Permission (capability) read:hierarchical-contentVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /wiki/api/v2/pages/{id}/versions | List the versions of a page. | read | read:page | Current | |
Listing versions enforces a maximum limit of 50 results when body-format is included. Full scope: read:page:confluence. Acts onpage Permission (capability) read:pageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /wiki/api/v2/spaces/{id}/pages | List the pages inside a space. | read | read:page | Current | |
Returns only the pages within that space the token can view. Full scope: read:page:confluence. Acts onpage Permission (capability) read:pageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SpacesList spaces, read a space by id, create a space, and list the pages inside a space.3 | ||||||
| GET | /wiki/api/v2/spaces | List all spaces the token can view. | read | read:space | Current | |
Results are filtered to the spaces the user behind the token can access. Full scope: read:space:confluence. Acts onspace Permission (capability) read:spaceVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /wiki/api/v2/spaces/{id} | Return a specific space by its id. | read | read:space | Current | |
Read-only. Full scope: read:space:confluence. Acts onspace Permission (capability) read:spaceVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /wiki/api/v2/spaces | Create a new space with a name, key, and role assignments. | write | write:space | Current | |
Creating a space sets up a new container for pages, blog posts, and their permissions. Full scope: write:space:confluence. Acts onspace Permission (capability) write:spaceVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Blog postsList blog posts, read one by id, create, update, and delete blog posts, and list the blog posts in a space.5 | ||||||
| GET | /wiki/api/v2/blogposts | List all blog posts the token can view, limited by the limit parameter. | read | read:page | Current | |
Blog posts use the page scopes in v2, so read:page:confluence covers reading them. Acts onblogpost Permission (capability) read:pageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /wiki/api/v2/blogposts/{id} | Return a specific blog post by its id. | read | read:page | Current | |
Blog posts share the page scopes in v2. Full scope: read:page:confluence. Acts onblogpost Permission (capability) read:pageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /wiki/api/v2/blogposts | Create a blog post in a space. | write | write:page | Current | |
Blog posts share the page scopes, so write:page:confluence covers creating them. Acts onblogpost Permission (capability) write:pageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /wiki/api/v2/blogposts/{id} | Update an existing blog post. | write | write:page | Current | |
The request must send the next version number, so a blog post is read before it is updated. Full scope: write:page:confluence. Acts onblogpost Permission (capability) write:pageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /wiki/api/v2/blogposts/{id} | Delete a blog post, moving it to the trash or purging it permanently. | write | write:page | Current | |
Deleting uses the write scope. A purge of an already-trashed blog post is permanent. Full scope: write:page:confluence. Acts onblogpost Permission (capability) write:pageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CommentsList a page's footer and inline comments, read a comment by id, create a footer or inline comment, and delete a footer comment.5 | ||||||
| GET | /wiki/api/v2/pages/{id}/footer-comments | List the root footer comments on a page. | read | read:comment | Current | |
Footer comments are the threaded discussion at the bottom of a page, separate from inline comments anchored to text. Full scope: read:comment:confluence. Acts oncomment Permission (capability) read:commentVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /wiki/api/v2/pages/{id}/inline-comments | List the root inline comments on a page. | read | read:comment | Current | |
Inline comments are anchored to a highlighted span of text within the page. Full scope: read:comment:confluence. Acts oncomment Permission (capability) read:commentVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /wiki/api/v2/footer-comments | Create a footer comment on a page, blog post, attachment, or as a reply. | write | write:comment | Current | |
The body names the parent content the comment attaches to, or another comment to reply to. Full scope: write:comment:confluence. Acts oncomment Permission (capability) write:commentVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /wiki/api/v2/inline-comments | Create an inline comment anchored to a selection of text. | write | write:comment | Current | |
The body includes the text selection the comment is anchored to. Full scope: write:comment:confluence. Acts oncomment Permission (capability) write:commentVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /wiki/api/v2/footer-comments/{comment-id} | Delete a footer comment. | write | delete:comment | Current | |
Deleting a comment needs delete:comment:confluence, a distinct scope from writing one. Acts oncomment Permission (capability) delete:commentVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AttachmentsList attachments, read an attachment by id, list a page's attachments, and delete an attachment.3 | ||||||
| GET | /wiki/api/v2/attachments | List all attachments the token can view. | read | read:attachment | Current | |
The scope also covers downloading an attachment's file. Full scope: read:attachment:confluence. Acts onattachment Permission (capability) read:attachmentVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /wiki/api/v2/pages/{id}/attachments | List the attachments on a page. | read | read:attachment | Current | |
Read-only. Full scope: read:attachment:confluence. Acts onattachment Permission (capability) read:attachmentVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /wiki/api/v2/attachments/{id} | Delete an attachment, moving it to the trash or purging it permanently. | write | delete:attachment | Current | |
Deleting an attachment needs delete:attachment:confluence. A purge is permanent. Acts onattachment Permission (capability) delete:attachmentVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
LabelsList all labels, and list the labels on a page or a space.3 | ||||||
| GET | /wiki/api/v2/labels | List all labels. | read | read:label | Current | |
Read-only. Full scope: read:label:confluence. Acts onlabel Permission (capability) read:labelVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /wiki/api/v2/pages/{id}/labels | List the labels on a page. | read | read:page | Current | |
Listing the labels on a page reads through the page scope, not the label scope. Full scope: read:page:confluence. Acts onlabel Permission (capability) read:pageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /wiki/api/v2/spaces/{id}/labels | List the labels on a space. | read | read:space | Current | |
Listing the labels on a space reads through the space scope. Full scope: read:space:confluence. Acts onlabel Permission (capability) read:spaceVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Content search (CQL)Search content with the Confluence Query Language, and search for users.2 | ||||||
| GET | /wiki/rest/api/search | Search content using the Confluence Query Language (CQL). | read | read:content-details | Current | |
CQL search is still a v1 endpoint, under /wiki/rest/api, not the v2 base path. It no longer accepts user-specific CQL fields. Full scope: read:content-details:confluence. Acts onsearch result Permission (capability) read:content-detailsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /wiki/rest/api/search/user | Search for users with a CQL query that includes user-specific fields. | read | read:content-details | Current | |
User search is the v1 endpoint that still accepts fields like user, user.fullname, and user.accountid. Full scope: read:content-details:confluence. Acts onsearch result Permission (capability) read:content-detailsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Confluence can notify an app or AI agent when something happens in a space, instead of the app repeatedly asking. A Connect or Forge app registers webhook events, and Confluence posts a payload to the registered URL when one fires.
| Event | What it signals | Triggered by |
|---|
Confluence limits how much an app or AI agent can call through a points-based cost budget, where each call spends from an hourly quota and the cost depends on the work the call performs.
Confluence meters API use with a points-based cost budget rather than a flat request count. Each call starts at a base cost of about 1 point, and more is added for the work it performs, such as the number of objects returned or the complexity of the operation, with identity and access calls costing more. An app shares a single hourly point quota across all tenants, reset at the start of each UTC hour, and apps with sustained high use can qualify for per-tenant quotas after review. The response headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and X-RateLimit-NearLimit report the current state, and exceeding the budget returns HTTP 429 with a Retry-After header. Enforcement of this points-based model for Forge, Connect, and OAuth 2.0 apps began on 2 March 2026; API token traffic stays on the older burst limits.
The v2 API uses cursor-based pagination. A list takes a limit parameter for the page size, and the response carries a Link header whose rel="next" URL holds the cursor for the following page, which should be followed rather than built by hand. Version listings cap the page at 50 results when the body-format parameter is included.
Content is returned in a chosen body format, such as storage or atlas_doc_format, selected with the body-format parameter. List page sizes are bounded by the limit parameter per endpoint, and large bodies should be fetched a page at a time rather than in one call.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed, such as an invalid parameter, a missing required field, or a CQL query that does not parse. | Correct the parameters or the request body and resend. |
| 401 | Unauthorized | Authentication is missing, or the token or credentials are invalid or expired. | Send a valid OAuth token or API token, refreshing it if it has expired. |
| 403 | Forbidden | The request is authenticated but not permitted: the token lacks the required scope, or the user does not have permission on the space or content. | Grant the missing scope, or confirm the user has access to the space or content. |
| 404 | Not Found | The content does not exist, or the token cannot see it. Confluence can return 404 rather than 403 so that it does not confirm restricted content exists. | Confirm the id is correct and the token has permission to view the content. |
| 429 | Too Many Requests | The points-based cost budget for the hour was exhausted, or a burst limit was hit. | Wait for the Retry-After seconds, then resume, and spread requests to stay under the hourly quota. |
Confluence is moving from its original v1 REST API to a faster, more specialized v2 API. The v2 endpoints answer under a separate base path and use granular permissions, while CQL content search still lives on v1.
The v2 API splits the v1 content endpoints into specialized ones for pages, blog posts, spaces, comments, attachments, and labels, under the base path /wiki/api/v2. The endpoints are faster, use cursor-based pagination, and map to granular OAuth scopes. It was first announced for pages and blog posts on 3 October 2022 and has expanded since.
A migration API was introduced to move space permissions from the legacy granular model to role-based access control, with endpoints to convert existing permission grants to equivalent role assignments.
The v2 endpoints for listing page and blog post versions now enforce a maximum of 50 results per page when the body-format query parameter is included.
Enforcement of the points-based API rate limits and tiered quotas for Forge, Connect, and OAuth 2.0 apps began. API token traffic stays on the older burst limits.
Atlassian announced the initial release of the v2 Confluence REST API, with endpoints for retrieving pages and blog posts, as an experimental preview that has since grown to cover more resources.
An integration can call v2 for pages, spaces, and comments, and fall back to v1 for the few capabilities v2 does not yet cover, such as CQL search.
Confluence API changelog ↗Bollard AI sits between a team's AI agents and Confluence. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.