Last updated Jun 7, 2022

Rate this page:


This changelog is the source of truth for all changes to the Bitbucket API and Bitbucket Connect API that affect people using Bitbucket Cloud and developing Bitbucket Cloud apps.

To ask any questions related to Bitbucket Cloud development please visit the Bitbucket Cloud developer community.

7 June 2022

Deprecation Notice Removing project:write scope from Bitbucket Cloud API on 15 May 2023

Beginning 15 May 2023, we are removing the project:write scope from the Bitbucket Cloud API.

More details

We have released a new scope, project:admin, which means the project:write scope is now obsolete.

  • All integrations currently using the project:write scope to call the Project endpoints (listed here) need to start using the project:admin scope.

  • All integrations currently using the project:write scope to call the Repository endpoints (listed here) or Git LFS need to start using the repository scope.

27 May 2022

Deprecation Notice The diff type is changing

We are changing the type of diff that is returned in the Bitbucket Cloud API from a ‘3-way’ diff to Git’s ‘three-dot’ diff. This new diff reflects the difference between the tip of a source branch and the commit from which it branched off of the destination. Read more about the new ‘three-dot’ diff here.

As a part of this change we are deprecating the merge query parameter in the diff and diffstat API endpoints. It is being replaced with a new query parameter topic, an optional boolean where true returns the new 'three-dot' diff and false returns a simple two-dot diff.

More details

For the next six months, requests to the diff APIs with neither the merge nor topic parameter provided will continue to return a '3-way' diff. After this period, the merge parameter will be removed entirely and requests without a topic parameter will return a 'three-dot' diff.

28 March 2022

Added New 3LO App Controls for Site Admins

An improvement will be made in the coming days to allow customers (site admins) to turn off (or back on) end-user installation capabilities for OAuth 2.0 (3LO) apps. If you are a developer of OAuth 2.0 (3LO) apps, you do not need to take any action as a result of this change, as this message is only to communicate the impact to the customer.

More details

Previously, controls were not in place for an admin to block their users from installing 3LO apps. Adding the ability for an admin to prohibit users from installing 3LO apps now aligns more closely to how a user would install any other, non-3LO apps on the Marketplace. This functionality was requested by several Atlassian enterprise customers to gain increased control over where their data is shared and which apps have access to their instance. By allowing admins to control end-user app installs, we are making it possible for more enterprise customers to move to cloud. Once in cloud, these companies will not be blocked from installing 3LO apps, because admins will retain the ability to vet and install the apps at their discretion.

Figure (a) below demonstrates the section of the customer’s admin console where they will now be able to block their users from installing 3LO apps. Figure (b) below shows the new experience when a customer tries to install a 3LO app after their admin has disabled this function.

If a customer attempts to install a 3LO app after their admin has disabled this function, the following error message will appear:

App is blocked by an admin
An admin has not allowed [App Name] to access data from [Your Atlassian Instance] . Select another site to authorize access to or contact your admin for more information.



9 August 2021

Deprecation Notice Atlassian account passwords for API and Git activity will be disabled 1 March 2022

As previously announced in the Bitbucket blog, beginning 1 March 2022, Bitbucket users will not be able to use their Atlassian account passwords for API and Git activity.

Additionally, we've recently announced that new users with Atlassian accounts created on or after 13 September 2021 will not be able to use their account passwords for these Bitbucket activities.

Read more here.

10 March 2021

Deprecation Notice Bitbucket Cloud JSAPI Messages is deprecated effective 10 March 2021

Bitbucket is deprecating Connect JSAPI Messages. This change requires minimal changes to start using the new JSAPI Flag component. We are enacting this change to align Bitbucket Connect JSAPI with other Atlassian cloud products. You will have 6 months to update your app and make the required changes.

Read more here.

19 February 2021

Added You can now subscribe to Request Changes Webhooks

The newly introduced Request Changes status in Bitbucket Cloud brings an explicit method to tell the pull request author that there is still some work to do. For more information on this feature, you can take a look at our blog post. To help teams determine when this action has been performed, we have added the ability with webhooks to subscribe to the Request Changes callback.

Read more here.

30 November 2020

Deprecation Notice Updating commit status permissions

On May 21, 2021 Bitbucket /2.0/.../commit/{node}/statuses/build API for creating and retrieving commit build statues will have updated permissions. Only the creator of the build status will be able to overwrite existing records (PUT/POST requests). If you are using this API endpoint, please read on.

Read more here.

28 October 2020

Deprecation Notice Removing webhooks registered via Connect apps from /2.0/.../hooks API response

On April 30, 2021 Bitbucket /2.0/.../hooks API for retrieving webhooks will no longer include the read-only hooks registered via Connect apps in the response. If you are using these API endpoints, please read on.

Read more here.

1 July 2020

Removed Connect app webhooks to be restricted by scopes 1 July 2020

Bitbucket is making a change that may result in connect apps receiving fewer webhooks than they were previously. We are doing this to provide end-users with more information about the type of access an app may have to their content. This could potentially break applications—read on to determine if your app will be impacted.

Previously, apps could register for any Bitbucket webhook, regardless of its scopes. Scopes were only applied to the API requests that the app made, not the webhooks it received—and this is what we’re changing.

We will begin enforcing the same scopes that are applied to API requests to webhooks as well. For example, your app will need to have the pullrequest scope in order to receive the pullrequest:updated webhook.

Read more here.

8 April 2020

Deprecation Notice Sandboxing of Connect App iframes

To improve security, we are adding sandboxing to Connect App iframes in Bitbucket. These changes have been implemented by Jira and Confluence. The sandbox adds extra security by preventing the content of the iframe from performing certain actions. You have until February 20, 2021 to update your Connect Apps and fix any breaking changes.

Read more here.

2 February 2020

Announcement Updates to Bitbucket webhook infrastructure

We are making changes to Bitbucket webhooks to improve the reliability and scalability of the infrastructure. These changes should be mostly transparent, however it is important to note that webhooks might be sent from a different range of IPs than they have been in the past as highlighted in this blog post.

Most users will not have to do anything to continue receiving webhooks. Users with services behind firewalls might want to double check whether their firewall rules include the full list of addresses. The full list of Atlassian IP ranges can be found here:

As always, please contact our support team if you have further questions or if you need further assistance.

10 January 2020

Announcement Changes to external app install links effective 10 January 2020

Depending on if an app has been registered in the “Develop apps” section of Bitbucket settings, the URL that installs the app may change. Apps that have been registered must use the addon_key URL parameter to identify the app. Apps that have not been registered may continue to use the descriptor_uri URL parameter to identify the app, i.e. no change is necessary.

Apps that need to change can and should start using the addon_key parameter today.

As of 10 January 2020 if a registered app is not using the addon_key URL parameter, the installation page will not be able to install the app.

Read more here.

14 October 2019

Announcement Changes to how apps are installed by URL in Bitbucket Cloud effective 14 October 2019

To install apps from unknown sources you will need to enable development mode in your Bitbucket settings.

We're changing how to install Bitbucket Cloud apps using the URL of an app descriptor from an unknown source. Going forward, to install apps from unknown sources you will need to enable development mode in your Bitbucket settings.

Read more here.

31 August 2019

Deprecation Notice Deprecating /2.0/teams/ and some /2.0/users API endpoints

On October 14, 2020 all of the /2.0/teams/ and most of the /2.0/users/ API endpoints will be removed. You need to update your Bitbucket Cloud integrations to use the new /2.0/workspaces/ endpoints. These endpoints are available today, so you can start updating your code immediately.

Additionally, the owner property found in the repository, project and snippet request and response payloads will be removed. You must replace the owner property with the new workspace property, which is available now for usage and testing.

Read more here.

11 April 2019

Announcement Updates to Bitbucket Cloud repository URL paths

As announced previously, Bitbucket Cloud REST APIs are changing to improve user privacy. This page guides you through the process of reliably generating repository URL paths in your integrations. As the previous notice stated,

We are excluding repository URLs from this deprecation to avoid breaking repository references. As part of giving users better control of their data, we are going to separate references to user-spaces from content-spaces, which will preserve existing repository URLs.

Users are able to separately define a username and workspace ID. The username is used to authenticate over SSH or HTTPS using the Git command line client. The workspace ID is used to form repository URL paths.

Read more here.