Deprecation Notice: Removal of the merge parameter from Bitbucket Cloud Diff and Diffstat APIs

[#1]

Hi Bitbucket Community,

We're writing to give you advance notice of an upcoming change to the Bitbucket Cloud REST API that may affect your integrations: the merge query parameter on the diff and diffstat APIs will be permanently removed on September 4, 2026.

Background

In May 2022, we announced a change to how Bitbucket Cloud calculates diffs, introducing a more performant "three-dot" diff mechanism. As part of that change, the boolean merge query parameter on the diff and diffstat endpoints was marked as deprecated as of November 23, 2022, to be replaced by the topic parameter.

We are now following through on that commitment, and the merge parameter will be fully removed on September 4, 2026.

What is changing

• The merge query parameter on the diff and diffstat REST APIs will no longer be accepted after September 4, 2026.

• Requests that include merge=true will no longer return a Preview Merge Diff

• The topic parameter (introduced in 2022) is the supported replacement. Use topic=true to get a "three-dot" diff, or topic=false for a simple "two-dot" diff. Requests without either parameter default to topic=true.

New Conflict Detection APIs

We recognize that one key use case for the merge parameter was identifying merge conflicts between branches or within a pull request. To ensure you have a supported path forward, we are introducing two new conflict detection APIs that expose this functionality directly.

1. Get conflicts for a pull request GET /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/conflicts

This endpoint returns a list of conflicts for a given pull request, allowing you to programmatically detect whether a pull request has merge conflicts without needing to request a Preview Merge Diff. Full documentation: Get conflicts for a pull request.

2. Get conflicting files between commits or branches GET /repositories/{workspace}/{repo_slug}/file-conflicts/{spec}

This endpoint returns the conflicting files between two commits or branches (specified via the spec parameter), giving you a way to check for conflicts outside the context of a pull request. For more detailed information, go to our Get file conflicts developer document.

Together, these APIs cover the two primary conflict detection use cases previously only possible via the merge parameter. Both APIs are already available today — you can find the full documentation via the links above and begin migrating your integrations immediately.

What you need to do

If you are calling the diff or diffstat API with the merge parameter:

1. Switch to the topic parameter for diff calculations. Replace merge=true with topic=true and merge=false with topic=false.

2. For pull request conflict detection, migrate to the new Get conflicts for a pull request API.

3. For branch or commit conflict detection, migrate to the new Get file conflicts API.

4. Test your integrations before September 4, 2026 to ensure nothing breaks.

If you are NOT using the merge parameter, no action is required.

Questions or concerns

We know API changes can be disruptive, and we want to make this as smooth as possible. Drop a comment below if you have questions, run into issues during migration, or need clarification on anything. We'll be monitoring this thread and will respond.

You can also track the status of these changes on the Bitbucket Cloud changelog.

— The Bitbucket Cloud Team

[roustommx]

Hello,

First of all, thank you for your efforts.

I am currently using Bitbucket API Tokens, and I noticed a potential inconsistency with the new conflict detection APIs.

The endpoint:

/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/conflicts

explicitly states that the following scope is supported:

Forge app and API Token scopes required:

read:pullrequest:bitbucket

However, this endpoint redirects to:

/repositories/{workspace}/{repo_slug}/file-conflicts/{spec}

and the redirected endpoint appears not to support API Token authentication. As a result, I receive the following error:

{ "type": "error", "error": { "message": "This resource does not support authentication using the provided token" } }

For comparison, the standard pull request endpoint:

/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}

works correctly with the same API Token and has the same documented requirement of "Forge app and API Token scopes required".

Could you please investigate whether this is an issue with the implementation or the documentation?

We are currently relying on conflict detection functionality, and we would appreciate clarification as soon as possible, especially given the upcoming deprecation of the merge=true parameter scheduled for September 4, 2026.

Thank you in advance for your assistance. We look forward to your feedback.

[roustommx]

@Dan Bolivar