Skip to content
Bitbucket CLI Bitbucket CLI

API Command — Raw Authenticated Bitbucket API Access

bb api makes an authenticated request to any Bitbucket Cloud 2.0 API endpoint, reusing the same stack as every other command: Basic/Bearer auth, automatic OAuth token refresh, rate-limit and transient-error retries, and secret redaction. It is the escape hatch for endpoints not yet wrapped by a typed command family, so you are never blocked. Mirrors gh api.

Global options: --json [fields], --jq <expression>, --no-color, -w, --workspace, -r, --repo.

bb api

Section titled “bb api”
Terminal window
bb api [method] <endpoint> [options]

Arguments

Section titled “Arguments”
ArgumentDescription
methodOptional HTTP verb (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS). When omitted, defaults to GET, or POST when fields/body are present. Both bb api GET /user and bb api /user work.
endpointThe API path, relative to https://api.bitbucket.org/2.0 (a leading / is optional). {workspace} and {repo} placeholders are substituted from --workspace/--repo or the current repository.

Options

Section titled “Options”
OptionDescription
-X, --method <method>HTTP method. Overrides a positional verb.
-f, --raw-field <key=value>Add a string parameter. Query param on GET/HEAD, JSON body field otherwise. Repeatable.
-F, --field <key=value>Add a typed parameter: true/false/null and numbers are converted; @file reads a file and @- reads stdin. Repeatable.
--input <file>Read the raw request body from a file, or - for stdin. Sent as application/json (override with -H 'Content-Type: ...'). Mutually exclusive with -f/-F.
-H, --header <key:value>Add a request header. Repeatable. Authorization is managed automatically and cannot be set here.
-i, --includePrint the HTTP status line and response headers before the body (text mode only — suppressed under --json).
--paginateFollow the cursor (next) across pages and merge every page into a single { "values": [...] } result (GET/HEAD only).

Examples

Section titled “Examples”
Terminal window
# Current user
bb api /user


# Explicit method (equivalent to the above)
bb api GET /user


# List every pull request, following pagination, using the current repo
bb api /repositories/{workspace}/{repo}/pullrequests --paginate


# Create an issue (method inferred as POST because fields are present)
bb api POST /repositories/my-ws/my-repo/issues -f title=Bug -F priority=3


# Send a JSON body from a file
bb api PUT /repositories/my-ws/my-repo/pullrequests/42 --input body.json


# Pipe a body in from stdin
cat body.json | bb api POST /repositories/my-ws/my-repo/pullrequests/42/comments --input -


# Force a GET with query parameters (fields normally infer POST)
bb api GET /repositories/my-ws/my-repo/pullrequests -f state=MERGED


# Filter the response with jq (no --json needed — bb api output is already JSON)
bb api /repositories/my-ws --jq '.values[].name'


# Inspect the status line and response headers
bb api -i /user

How fields are sent

Section titled “How fields are sent”
  • GET / HEAD — -f/-F fields are appended as a URL query string (?key=value&...).
  • Other methods — -f/-F fields are assembled into a JSON request body.
  • --input — sends the file (or stdin) contents as the raw body verbatim, and cannot be combined with -f/-F.
  • Repeating the same key turns it into an array, matching gh.

Placeholders

Section titled “Placeholders”

{workspace} and {repo} in the endpoint are filled from --workspace / --repo or inferred from the current git checkout. Repository context is only resolved when a placeholder is actually present, so bb api /user works anywhere.

Terminal window
# Inside a Bitbucket checkout, these resolve automatically:
bb api /repositories/{workspace}/{repo}/commits


# Or override explicitly:
bb api -w my-ws -r my-repo /repositories/{workspace}/{repo}/commits

Output

Section titled “Output”

The response body is printed to stdout. JSON responses are pretty-printed and respect the global --json [fields] projection and --jq filtering; non-JSON responses (e.g. raw diffs) are printed verbatim, and --json/--jq are inert on them. An empty response body (e.g. a HEAD or 204) prints nothing in text mode, and {} under --json so a downstream jq never sees zero bytes.

Terminal window
bb api /user
{
  "type": "user",
  "username": "my-user",
  "display_name": "My User",
  "account_id": "557058:..."
}

Notes

Section titled “Notes”
  • Authentication is automatic. The same credentials as the rest of the CLI are attached to every request; you cannot (and need not) set Authorization yourself.
  • Only the Bitbucket API host is allowed. Absolute URLs are accepted only when they point at api.bitbucket.org. This prevents the CLI from sending your token to a foreign host. Pagination cursors (which are absolute api.bitbucket.org URLs) are followed safely.
  • Errors surface the API response. On a non-2xx status, the API’s error body is printed and the command exits non-zero. With --json, the error payload (including statusCode and response) is emitted as structured JSON.
  • Retries and redaction are inherited from the shared API client — rate limits (429) and the transient gateway errors 502/503/504 are retried with backoff, and sensitive values are redacted from DEBUG logs.
Section titled “Related”
  • Scripting & Automation — combine bb api with --jq to build pipelines over endpoints without a typed command.
  • JSON Output — how --json projection and --jq filtering work across the CLI.
  • Authentication — the auth methods that bb api reuses.