bb api

Send a raw HTTP request to the Bitbucket REST API

bb api <endpoint> [flags]

Send a raw HTTP request to the Bitbucket REST API as an escape hatch for uncovered endpoints.

Reuses stored authentication, host aliases, TLS options, retries, and pagination. A request is authenticated as every other command's is. A credential given on the command line -- an Authorization, Proxy-Authorization or Cookie header, or a user and password in a URL -- is refused, since it would be readable in the process list and shell history.

A JSON response is printed indented and other text trimmed; anything else -- a file's raw bytes, an archive -- is written byte for byte as it arrives. Text is held to be formatted, up to 256 MiB. Under --json the response goes into the document's data as JSON or as a string. A body that is not text goes in as base64, up to 64 MiB, with meta.encoding set to base64 and meta.contentType to its type; an empty one is null.

Note: On Windows Git Bash (MSYS2), set MSYS_NO_PATHCONV=1 or omit the leading slash (e.g. rest/api/1.0/...) to prevent shell path mangling.

# GET a pull request settings resource
bb api /rest/api/1.0/projects/PROJ/repos/repo/settings/pull-requests

# Target a specific Bitbucket instance
bb api /rest/api/1.0/projects --host https://bitbucket.example.com

# Paginate all admin groups
bb api /rest/api/1.0/admin/groups --paginate

# POST with typed JSON body fields
bb api /rest/api/1.0/projects/PROJ/repos/repo/branches -X POST -F name=feature/test -F startPoint=main

# POST with JSON payload from file or stdin
bb api /rest/api/1.0/projects/PROJ/repos/repo/branches --method POST --input body.json
cat body.json | bb api /rest/api/1.0/projects/PROJ/repos/repo/branches -X POST --input -

-F, --field stringArray

Add a typed parameter (key=value, booleans, numbers, null, or @file)

-H, --header stringArray

Add a custom HTTP request header (Name: Value)

--host string

Bitbucket host URL (defaults to the configured host)

--input string

File to use as request body (or '-' for stdin)

-X, --method string

HTTP method (one of: GET, POST, PUT, DELETE, PATCH, HEAD)

--paginate

Automatically fetch all pages for paginated endpoints

-f, --raw-field stringArray

Add a string parameter, key=value: a query parameter for GET, a JSON body field otherwise

Also takes the global flags.

Dry run: Sends a GET or HEAD as usual, since it only reads; any other request is shown as what it would send, without sending it (predicted)

Output with --json: this command writes no document of its own: streams the upstream response body verbatim, which is the point of the escape hatch