Bitbucket Cloud and Data Center · REST API · Checked November 2, 2026

Bitbucket pull requests from the command line

Bitbucket has no official command-line tool for pull requests, nothing like GitHub's gh pr create or the Azure CLI's az repos pr create. The Atlassian CLI (acli) has command groups for Jira, administration and Rovo Dev, and none for Bitbucket (its command reference). What works is one call to Bitbucket's REST API, which curl can make. The examples below follow Atlassian's API references for Bitbucket Cloud and Bitbucket Data Center 10.2.

Bitbucket Cloud

Create an API token with scopes, with Bitbucket as the app. For creating a pull request, Atlassian's reference lists read:pullrequest:bitbucket and write:pullrequest:bitbucket. With an API token, the user name for the REST API is your Atlassian account email, not your Bitbucket username (Using API tokens). You can also send the token as Authorization: Bearer, without the email.

curl --request POST \
  --url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repository}/pullrequests' \
  --user 'you@example.com:{api_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Login page",
    "source": { "branch": { "name": "feature/login" } },
    "destination": { "branch": { "name": "main" } },
    "reviewers": [ { "uuid": "{504c3b62-8120-4f0c-a7bc-87800b9d6f70}" } ],
    "close_source_branch": true
  }'

• Only title and source are required. Without destination, the pull request goes to the repository's main branch.
• Reviewers are given by UUID, braces included, not by name. Yours is in GET /2.0/user; the workspace's people are in GET /2.0/workspaces/{workspace}/members.
• Other fields: description, close_source_branch (close the branch after the merge) and draft.
• The answer is the new pull request as JSON. Its links.html.href is the web page.

Bitbucket Data Center

Create a personal HTTP access token and send it as Authorization: Bearer. Atlassian's reference says the account needs read permission (REPO_READ) on both repositories.

curl --request POST \
  --url 'https://bitbucket.example.com/rest/api/latest/projects/PRJ/repos/my-repo/pull-requests' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Login page",
    "fromRef": { "id": "refs/heads/feature/login", "repository": { "slug": "my-repo", "project": { "key": "PRJ" } } },
    "toRef": { "id": "refs/heads/main", "repository": { "slug": "my-repo", "project": { "key": "PRJ" } } },
    "reviewers": [ { "user": { "name": "charlie" } } ]
  }'

• Branches are full refs (refs/heads/…). The source may be a tag; the target must be a branch. The two can be in different repositories of the same fork hierarchy.
• Reviewers are given by user name. Add "draft": true for a draft; drafts exist from Data Center 8.18.

When a reviewer is refused

One reviewer that Bitbucket will not take makes the whole call fail, and no pull request is created.

• Cloud answers 400. In a public report on gildas/bitbucket-cli (2026), the author was among the default reviewers sent: reviewers: <name> is the author and cannot be included as a reviewer. Leave yourself out.
• Data Center answers 409 with InvalidPullRequestReviewersException, a reviewerErrors entry for each refused name and the validReviewers. In a report on bitbucket-data-center-cli (2026), a reviewer group had been sent as a user name: reviewer-group/cog_product is not a user. Send people's user names only.

What the call does not do

• On Data Center, it does not add the default reviewers that the create page would. Read them first and send them; on Cloud, effective-default-reviewers lists them. Both are in Bitbucket default reviewers.
• It does not push. The source branch has to be on Bitbucket already; push it first.

Community tools wrap these same calls, such as the two above; none of them is from Atlassian.

Creating Bitbucket pull requests from IntelliJ IDEA

Pull Request Inbox for Bitbucket, a plugin by Lesstep for JetBrains IDEs 2024.1 or later, adds Git → Create Bitbucket Pull Request… for Bitbucket Cloud and Data Center. It opens a pull request from the branch you are on, into the repository's main branch unless you pick another, optionally as a draft. It asks the default reviewers itself, on Cloud and on Data Center, leaving you out, and offers people from the repository's recent pull requests. If Bitbucket still refuses one of them, it creates the pull request without them and shows Bitbucket's reason. If the branch is not on Bitbucket yet, it says so and opens the IDE's push dialog first. Creating, approving and merging pull requests are Pro (US$1.50 a month, with a 30-day trial); the review inbox is free.

Get it on JetBrains Marketplace

Bitbucket, Jira and Rovo are trademarks of Atlassian; IntelliJ IDEA is a trademark of JetBrains s.r.o. This page is not affiliated with or endorsed by Atlassian or JetBrains.

More: Bitbucket default reviewers · Bitbucket draft pull requests · 日本語