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