A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Bitbucket API is how an app or AI agent works with a Bitbucket Cloud workspace: reading repositories and commits, opening and merging pull requests, creating and updating issues, and running build pipelines. Access is granted through a token and a set of scopes that decide what each call can read or write, and an agent is limited to the workspaces and repositories that token reaches. Bitbucket can also push events to a webhook URL when something happens in a repository.
How an app or AI agent connects to Bitbucket determines what it can reach. There are several routes, each governed by the token behind it and the scopes that token carries.
The Bitbucket Cloud REST API answers at https://api.bitbucket.org/2.0 and returns resource-oriented JSON over HTTPS. It is the main way an app or AI agent reads and changes repositories, pull requests, issues, and pipelines.
The Atlassian Rovo MCP Server is generally available and supports Bitbucket Cloud, letting an AI client browse repositories, create commits, open pull requests, and check pipeline results over the Model Context Protocol. It is hosted by Atlassian at https://mcp.atlassian.com/v1/mcp, and Bitbucket Cloud tools currently use API token authentication enabled by an organization admin.
Webhooks deliver the chosen repository events to a receiver URL, so an app or AI agent is told when something happens instead of polling. When a secret is set, the X-Hub-Signature HMAC header on each delivery confirms it came from Bitbucket.
An OAuth 2.0 app exchanges an authorization code for a short-lived bearer token tied to the scopes the user granted, and refreshes it as needed. It is the fit for an app acting on behalf of a user, since access is limited to the granted scopes and can be revoked. From 4 May 2026 these requests must be sent to api.bitbucket.org with the token in the Authorization header.
An API token is used with Basic authentication, where the username is the Atlassian account email and the password is the token. It must be created with an expiry of up to one year and can carry chosen scopes. It is the replacement for app passwords in scripts and CI jobs.
An access token is a single-purpose bearer token bound to one repository, project, or workspace, with its own scopes and no tie to a user account. It suits automation that should act on just one resource, since its reach is fixed to that resource.
An app password is the older Basic-auth credential, a single-purpose password with chosen permissions. It is being retired: no new ones can be created from 9 September 2025, and all stop working on 9 June 2026, so it should not be used for new integrations.
The Bitbucket API is split into areas an agent can act on, such as repositories, pull requests, commits, branches, issues, and pipelines. Each area has its own methods and its own scopes, and some grant access to far more than others.
List the repositories in a workspace, read a single repository, and create or update one.
List, read, create, and update pull requests, merge, approve, decline, and request changes, and list and create their comments and commits.
List commits in a repository and read a single commit.
List branches, read a single branch, and create or delete a branch.
List, read, create, and update issues in a repository's issue tracker.
List pipelines, read a single pipeline, run a pipeline, and stop a running pipeline.
List a repository's webhooks, create a webhook, and delete one.
List the workspaces a user belongs to, read a workspace, and list and read the projects inside a workspace.
Read the profile of the authenticated user.
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 | |
|---|---|---|---|---|---|---|
RepositoriesList the repositories in a workspace, read a single repository, and create or update one.4 | ||||||
| GET | /repositories/{workspace} | List the repositories in a workspace. | read | repository | Current | |
The repository scope grants read access to every repository the token can see in the workspace. Acts onrepository Permission (capability) repositoryVersionAvailable since the API’s base version Webhook eventNone Rate limit1,000 to 10,000 requests per hour SourceOfficial documentation ↗ | ||||||
| GET | /repositories/{workspace}/{repo_slug} | Get a single repository's details. | read | repository | Current | |
The baseline read scope for repository data. Acts onrepository Permission (capability) repositoryVersionAvailable since the API’s base version Webhook eventNone Rate limit1,000 to 10,000 requests per hour SourceOfficial documentation ↗ | ||||||
| POST | /repositories/{workspace}/{repo_slug} | Create a new repository in a workspace. | write | repository:admin | Current | |
Creating a repository needs repository:admin, not just repository:write. Acts onrepository Permission (capability) repository:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /repositories/{workspace}/{repo_slug} | Update a repository's settings. | write | repository:admin | Current | |
Updating repository settings needs repository:admin. Acts onrepository Permission (capability) repository:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Pull requestsList, read, create, and update pull requests, merge, approve, decline, and request changes, and list and create their comments and commits.12 | ||||||
| GET | /repositories/{workspace}/{repo_slug}/pullrequests | List the pull requests in a repository. | read | pullrequest | Current | |
The pullrequest scope also grants the repository scope's read access. Acts onpull request Permission (capability) pullrequestVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id} | Get a single pull request. | read | pullrequest | Current | |
Read access to one pull request. Acts onpull request Permission (capability) pullrequestVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repositories/{workspace}/{repo_slug}/pullrequests | Create a pull request. | write | pullrequest:write | Current | |
Creating a pull request needs pullrequest:write. Acts onpull request Permission (capability) pullrequest:writeVersionAvailable since the API’s base version Webhook event pullrequest-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id} | Update a pull request's title, description, reviewers, or destination. | write | pullrequest:write | Current | |
Editing a pull request needs pullrequest:write. Acts onpull request Permission (capability) pullrequest:writeVersionAvailable since the API’s base version Webhook event pullrequest-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/merge | Merge a pull request into its destination branch. | write | pullrequest:write | Current | |
Merging commits to the destination branch and needs pullrequest:write. Acts onpull request Permission (capability) pullrequest:writeVersionAvailable since the API’s base version Webhook event pullrequest-fulfilledRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/approve | Approve a pull request as the authenticated user. | write | pullrequest:write | Current | |
Recording an approval needs pullrequest:write. Acts onpull request Permission (capability) pullrequest:writeVersionAvailable since the API’s base version Webhook event pullrequest-approvedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/decline | Decline a pull request, closing it without merging. | write | pullrequest:write | Current | |
Declining a pull request needs pullrequest:write. Acts onpull request Permission (capability) pullrequest:writeVersionAvailable since the API’s base version Webhook event pullrequest-rejectedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/request-changes | Request changes on a pull request as the authenticated user. | write | pullrequest:write | Current | |
Recording a request for changes needs pullrequest:write. Acts onpull request Permission (capability) pullrequest:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/comments | List the comments on a pull request. | read | pullrequest | Current | |
Reading pull request comments needs the pullrequest scope. Acts onpull request Permission (capability) pullrequestVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/comments | Create a comment on a pull request. | write | pullrequest | Current | |
Bitbucket gates creating a pull request comment on the pullrequest scope rather than pullrequest:write. Acts onpull request Permission (capability) pullrequestVersionAvailable since the API’s base version Webhook event pullrequest-comment-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/commits | List the commits that are part of a pull request. | read | pullrequest | Current | |
Reading a pull request's commits needs the pullrequest scope. Acts onpull request Permission (capability) pullrequestVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/diff | Get the changes in a pull request as a diff. | read | pullrequest | Current | |
Returns plain-text diff output rather than JSON. Needs the pullrequest scope. Acts onpull request Permission (capability) pullrequestVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CommitsList commits in a repository and read a single commit.2 | ||||||
| GET | /repositories/{workspace}/{repo_slug}/commits | List the commits in a repository. | read | repository | Current | |
Reading commit history needs the repository scope. Acts oncommit Permission (capability) repositoryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repositories/{workspace}/{repo_slug}/commit/{commit} | Get a single commit by its hash. | read | repository | Current | |
Reading one commit needs the repository scope. Acts oncommit Permission (capability) repositoryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BranchesList branches, read a single branch, and create or delete a branch.4 | ||||||
| GET | /repositories/{workspace}/{repo_slug}/refs/branches | List the open branches in a repository. | read | repository | Current | |
Listing branches needs the repository scope. Acts onbranch Permission (capability) repositoryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repositories/{workspace}/{repo_slug}/refs/branches/{name} | Get a single branch by name. | read | repository | Current | |
Reading one branch needs the repository scope. Acts onbranch Permission (capability) repositoryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repositories/{workspace}/{repo_slug}/refs/branches | Create a branch pointing at a chosen commit. | write | repository:write | Current | |
Creating a branch needs repository:write. Acts onbranch Permission (capability) repository:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /repositories/{workspace}/{repo_slug}/refs/branches/{name} | Delete a branch by name. | write | repository:write | Current | |
Deleting a branch needs repository:write. Acts onbranch Permission (capability) repository:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
IssuesList, read, create, and update issues in a repository's issue tracker.4 | ||||||
| GET | /repositories/{workspace}/{repo_slug}/issues | List the issues in a repository's issue tracker. | read | issue | Current | |
The issue tracker is optional per repository; the issue scope grants read access where it is enabled. Acts onissue Permission (capability) issueVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repositories/{workspace}/{repo_slug}/issues | Create an issue in a repository's issue tracker. | write | issue:write | Current | |
Creating an issue needs issue:write. Acts onissue Permission (capability) issue:writeVersionAvailable since the API’s base version Webhook event issue-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repositories/{workspace}/{repo_slug}/issues/{issue_id} | Get a single issue. | read | issue | Current | |
Reading one issue needs the issue scope. Acts onissue Permission (capability) issueVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /repositories/{workspace}/{repo_slug}/issues/{issue_id} | Update an issue, such as its state, assignee, or content. | write | issue:write | Current | |
Updating an issue needs issue:write. Acts onissue Permission (capability) issue:writeVersionAvailable since the API’s base version Webhook event issue-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PipelinesList pipelines, read a single pipeline, run a pipeline, and stop a running pipeline.4 | ||||||
| GET | /repositories/{workspace}/{repo_slug}/pipelines | List the pipelines in a repository. | read | pipeline | Current | |
Reading pipeline runs needs the pipeline scope. Acts onpipeline Permission (capability) pipelineVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repositories/{workspace}/{repo_slug}/pipelines | Run a pipeline on a chosen branch, commit, or pattern. | write | pipeline | Current | |
Starting a pipeline run is gated on the pipeline scope. Acts onpipeline Permission (capability) pipelineVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repositories/{workspace}/{repo_slug}/pipelines/{pipeline_uuid} | Get a single pipeline by its UUID. | read | pipeline | Current | |
Reading one pipeline needs the pipeline scope. Acts onpipeline Permission (capability) pipelineVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repositories/{workspace}/{repo_slug}/pipelines/{pipeline_uuid}/stopPipeline | Stop a running pipeline. | write | pipeline:write | Current | |
Stopping a pipeline needs pipeline:write. Acts onpipeline Permission (capability) pipeline:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksList a repository's webhooks, create a webhook, and delete one.3 | ||||||
| GET | /repositories/{workspace}/{repo_slug}/hooks | List the webhooks registered on a repository. | read | webhook | Current | |
Both reading and managing webhooks use the single webhook scope. Acts onwebhook Permission (capability) webhookVersionAvailable since the API’s base version Webhook eventNone Rate limit1,000 requests per hour SourceOfficial documentation ↗ | ||||||
| POST | /repositories/{workspace}/{repo_slug}/hooks | Create a webhook on a repository for chosen events. | write | webhook | Current | |
A secret on the webhook produces an X-Hub-Signature HMAC header for verification. Needs the webhook scope. Acts onwebhook Permission (capability) webhookVersionAvailable since the API’s base version Webhook eventNone Rate limit1,000 requests per hour SourceOfficial documentation ↗ | ||||||
| DELETE | /repositories/{workspace}/{repo_slug}/hooks/{uid} | Delete a webhook from a repository. | write | webhook | Current | |
Deleting a webhook needs the webhook scope. Acts onwebhook Permission (capability) webhookVersionAvailable since the API’s base version Webhook eventNone Rate limit1,000 requests per hour SourceOfficial documentation ↗ | ||||||
Workspaces & projectsList the workspaces a user belongs to, read a workspace, and list and read the projects inside a workspace.4 | ||||||
| GET | /workspaces | List the workspaces the authenticated user belongs to. | read | account | Current | |
Listing the user's workspaces needs the account scope. Acts onworkspace Permission (capability) accountVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workspaces/{workspace} | Get a single workspace. | read | — | Current | |
Public workspaces are readable without a scope; a private workspace needs a token with access to it. Acts onworkspace Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workspaces/{workspace}/projects | List the projects in a workspace. | read | project | Current | |
A project groups repositories inside a workspace; listing projects needs the project scope. Acts onproject Permission (capability) projectVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workspaces/{workspace}/projects/{project_key} | Get a single project in a workspace by its key. | read | project | Current | |
Reading one project needs the project scope. Acts onproject Permission (capability) projectVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersRead the profile of the authenticated user.1 | ||||||
| GET | /user | Get the profile of the authenticated user. | read | account | Current | |
Reading the current user's account needs the account scope. Acts onuser Permission (capability) accountVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Bitbucket can notify an app or AI agent when something happens in a repository, instead of the app repeatedly asking. Bitbucket posts the event payload to a webhook URL that has been registered for the chosen events.
| Event | What it signals | Triggered by |
|---|---|---|
repo:push | Fires when commits are pushed to a repository, including new branches and tags. | In-app only |
pullrequest:created | Fires when a pull request is created in a repository. | /repositories/{workspace}/{repo_slug}/pullrequests |
pullrequest:updated | Fires when a pull request's title, description, reviewers, or destination is updated. | /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id} |
pullrequest:approved | Fires when a user approves a pull request. | /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/approve |
pullrequest:fulfilled | Fires when a pull request is merged. | /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/merge |
pullrequest:rejected | Fires when a pull request is declined. | /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/decline |
pullrequest:comment_created | Fires when a comment is added to a pull request. | /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/comments |
issue:created | Fires when an issue is created in a repository's issue tracker. | /repositories/{workspace}/{repo_slug}/issues |
issue:updated | Fires when an issue is updated, such as a change to its state, assignee, or content. | /repositories/{workspace}/{repo_slug}/issues/{issue_id} |
Bitbucket limits how fast an app or AI agent can call, through an hourly request quota that depends on how the call is authenticated and which resource it touches.
Bitbucket Cloud sets hourly request limits that depend on how a call is authenticated and which resource it touches, measured over a one-hour rolling window. Anonymous requests are capped at 60 per hour, counted against the calling IP address. Authenticated requests are counted against the user, and the ceiling varies by resource: repository data access scales from 1,000 to 10,000 requests per hour, webhook operations get 1,000 per hour, and application property access gets 2,000 per hour, while Git operations over HTTPS or SSH get 60,000 per hour and raw file downloads get 5,000 per hour. Standard and Premium workspaces with at least 100 paid users earn an extra 10 requests per hour per paid user, up to a maximum of 10,000 per hour. Responses carry X-RateLimit-Limit and X-RateLimit-Resource headers, and X-RateLimit-NearLimit turns true when under 20 percent of the quota remains.
List endpoints return a paged envelope with a values array, a size or pagelen field, and a next field holding the full URL of the following page. Pagination is cursor-based, so the next URL should be followed as given rather than built by hand, and it is absent on the final page. The pagelen query parameter sets the page size, which defaults to a per-endpoint value and is capped per endpoint.
Requests and responses are JSON over HTTPS. Diffs, patches, and raw file contents are returned as plain text rather than JSON. Archive downloads are limited to 1,500 files per hour, and individual endpoints set their own ceilings on fields such as comment and description length.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | Authentication is missing, or the credentials are invalid or expired. A common cause is sending an app password after it has been disabled, or an API token with the wrong username. | Send valid credentials: an OAuth bearer token, or an API token used as the password with the Atlassian account email as the username. |
| 403 | Forbidden | The request is authenticated but not permitted. The token is missing the scope the endpoint requires, or the user lacks access to the resource. | Grant the missing scope, such as pullrequest:write or repository:admin, or give the token access to the repository. |
| 404 | Not Found | The resource does not exist, or the token cannot see a private resource. Bitbucket returns 404 rather than 403 for a private resource the token cannot access, so it does not reveal the resource exists. | Confirm the workspace, repo_slug, and id in the path, and that the token has access to the resource. |
| 429 | Too Many Requests | An hourly rate limit was exceeded for the identity and resource being called. | Slow down and retry after the window resets. Watch the X-RateLimit-NearLimit header, which turns true when under 20 percent of the quota remains. |
| 500 | Internal Server Error | An unexpected error occurred on Bitbucket's side while handling the request. | Retry the request after a short delay, and if it persists, check the Bitbucket status page. |
Bitbucket Cloud exposes a single REST API version, 2.0, served from one host. It does not mint new dated versions, so changes ship as additive updates and announced deprecations rather than a version bump.
Version 2.0 is the current Bitbucket Cloud REST API, served from one host. Bitbucket does not mint new dated versions of it, so changes ship as additive endpoints and fields, or as deprecations with their own announced timelines, rather than a version bump. Two such migrations dominate the recent timeline: the retirement of app passwords in favor of API tokens, and a change to where OAuth requests must be sent.
From 9 September 2025 Bitbucket Cloud stopped allowing the creation of new app passwords. Existing app passwords kept working through this phase, so running integrations were not interrupted, but new integrations had to adopt API tokens authenticated with an Atlassian account email. It was the first phase of moving Bitbucket Cloud authentication onto scoped, expiring API tokens.
An integration written against 2.0 keeps working as Bitbucket adds endpoints and fields over time.
Bitbucket Cloud API changelog ↗Bollard AI sits between a team's AI agents and Bitbucket. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.