Bitbucket REST API: A Practical Guide

atlassian-cli is an independent, community open-source project, not affiliated with, endorsed by, or sponsored by Atlassian, and is not Atlassian's official CLI (acli). Product names are used only to identify compatibility.

What Is the Bitbucket REST API?

The Bitbucket REST API is the HTTP interface Atlassian exposes for automating Bitbucket Cloud: creating repositories, opening and merging pull requests, triggering pipelines, managing branch permissions, and reading commits. The current version is 2.0, and every endpoint lives under a single base URL: https://api.bitbucket.org/2.0/. Requests are ordinary HTTPS calls, and responses come back as JSON, so anything that can send an authenticated GET or POST (curl, a Python script, a CI job) can drive Bitbucket.

The API is organized around a few nouns. A workspace groups your repositories, a repository is identified by a slug, and resources like pull requests and pipelines hang off a repository. A typical path reads left to right: /2.0/repositories/{workspace}/{repo_slug}/pullrequests. Once you know that shape, most of the API is discoverable by swapping the last segment.

This guide walks through authentication, the endpoints you will actually reach for, how pagination and rate limits work, and how to avoid writing the same curl-and-jq plumbing every time by putting a command-line wrapper in front of the API.

Authentication Options

Every request to the Bitbucket REST API must be authenticated. Bitbucket Cloud supports several methods, and which one you pick depends on whether you are running a quick script or a long-lived automation.

• App passwords (HTTP Basic auth). An app password is a scoped credential tied to your account that you pass as the password in Basic auth. It is the simplest option for scripts and works with curl -u "username:app_password".
• Access tokens. Repository, project, and workspace access tokens are scoped to a single resource rather than your whole account. They are the safer default for automation because you can grant narrow permissions and revoke a token without changing your password.
• OAuth 2.0. For applications acting on behalf of other users, register an OAuth consumer and exchange it for a bearer token. This is the right path when you are building an integration rather than a personal script.

For the examples below, store your credential in an environment variable so it never lands in shell history or a committed file:

# Export a Basic-auth credential for the current shell session
export BB_USER="your-bitbucket-username"
export BB_APP_PASSWORD="your-app-password"

With an access token instead, you send it as a bearer token: -H "Authorization: Bearer $BB_TOKEN". The endpoints are identical; only the auth header changes.

Core REST 2.0 Endpoints

You do not need to memorize the whole API. In practice, a handful of endpoints cover the vast majority of automation. Here are the ones worth knowing, all relative to https://api.bitbucket.org/2.0/:

Making Requests With curl

The fastest way to learn the API is to hit it directly. Start with a read that confirms your credential and shows you the JSON shape:

# List the first 10 repositories in a workspace
curl -s -u "$BB_USER:$BB_APP_PASSWORD" \
  "https://api.bitbucket.org/2.0/repositories/myteam?pagelen=10"

Reads are safe to experiment with. Writes are where the API earns its keep. Creating a pull request is a POST with a small JSON body describing the source and destination branches:

# Open a pull request from feature/new into main
curl -s -u "$BB_USER:$BB_APP_PASSWORD" \
  -X POST \
  -H "Content-Type: application/json" \
  "https://api.bitbucket.org/2.0/repositories/myteam/api-service/pullrequests" \
  -d '{
    "title": "Add feature",
    "source": { "branch": { "name": "feature/new" } },
    "destination": { "branch": { "name": "main" } }
  }'

Triggering a pipeline follows the same pattern. The body tells Bitbucket which ref to build:

# Trigger the default pipeline on the main branch
curl -s -u "$BB_USER:$BB_APP_PASSWORD" \
  -X POST \
  -H "Content-Type: application/json" \
  "https://api.bitbucket.org/2.0/repositories/myteam/api-service/pipelines/" \
  -d '{
    "target": {
      "type": "pipeline_ref_target",
      "ref_type": "branch",
      "ref_name": "main"
    }
  }'

These three requests (list, create PR, trigger pipeline) are representative of the whole API. Most other operations are a variation on the same theme: a path built from workspace and repo, a method, and a JSON body. The friction shows up around the edges: encoding query parameters, following pagination, parsing JSON out of every response, and retrying when you get throttled.

Pagination and Rate Limits

Two behaviors trip people up when they script against the Bitbucket REST API directly.

Pagination. Collection endpoints do not return every result at once. They return a page object shaped like this:

{
  "pagelen": 10,
  "page": 1,
  "values": [ /* repositories, PRs, commits... */ ],
  "next": "https://api.bitbucket.org/2.0/repositories/myteam?page=2"
}

To read the full result set, you follow the next URL until the field disappears. You can request bigger pages with the pagelen query parameter to cut the number of round trips. Any script that only reads the first page silently misses data, which is a common and hard-to-spot bug.

Rate limits. Bitbucket enforces per-hour rate limits and returns an HTTP 429 when you exceed them. A robust client has to detect that status and back off before retrying, otherwise a large batch will start failing partway through. Getting pagination and backoff right is most of the work in a good Bitbucket client, and it is exactly the boilerplate a wrapper removes.

Wrapping the API With a CLI

If you are reaching for the Bitbucket REST API repeatedly, a command-line wrapper turns each of those curl blocks into a single line. atlassian-cli maps the REST 2.0 endpoints above to short commands, and it handles authentication, pagination, and 429 backoff internally so you get complete results without writing the plumbing.

Authenticate once, then call the API by intent instead of URL. See the authentication guide for the full setup:

# Store credentials in a named profile
atlassian-cli auth login \
  --profile work \
  --base-url https://your-workspace.atlassian.net \
  --email you@example.com \
  --token $TOKEN \
  --default

# Confirm the Bitbucket credential resolves
atlassian-cli bitbucket whoami

From there, the same operations you wrote by hand become one-liners. Listing repositories walks every page for you:

# List repositories in a workspace (pagination handled automatically)
atlassian-cli bitbucket --workspace myteam repo list --limit 10

# Machine-readable output for scripting
atlassian-cli bitbucket --workspace myteam repo list --format json | jq '.[].slug'

Opening a pull request no longer needs a hand-built JSON body:

# Create a PR from feature/new into main
atlassian-cli bitbucket --workspace myteam pr create api-service \
  --title "Add feature" \
  --source feature/new \
  --destination main

# Approve and merge it
atlassian-cli bitbucket --workspace myteam pr approve api-service 123
atlassian-cli bitbucket --workspace myteam pr merge api-service 123 --strategy merge_commit

Triggering a pipeline collapses the earlier POST into its arguments, including named custom pipelines defined in bitbucket-pipelines.yml:

# Trigger the pipeline on main
atlassian-cli bitbucket --workspace myteam pipeline trigger api-service --ref-name main

# Trigger a named custom pipeline
atlassian-cli bitbucket --workspace myteam pipeline trigger api-service \
  --ref-name main --custom-pipeline s3-access-test

Every command accepts the global --format json|csv|yaml flag, so you can pipe results into jq, a spreadsheet, or another tool without parsing raw HTTP responses. The bb alias is interchangeable with bitbucket if you want to type less.

Mapping Endpoints to CLI Commands

If you already know the REST endpoint you need, this table shows the equivalent atlassian-cli command. It is a useful bridge when you are porting an existing curl script to the CLI. The full list is in the command reference.

For repeatable workflows built on these commands, the Bitbucket PR automation runbook shows a complete review-and-merge script, and the Bitbucket CLI guide covers day-to-day usage in more depth. Sibling walkthroughs on calling the Bitbucket API from the CLI and the full Bitbucket CLI command list go further on each area.

FAQ

Related Resources