Create a Bitbucket App Password or OAuth token with 'Pipelines: Read and Write' scope under Account settings > App passwords
POST to 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/pipelines/' with Authorization header using Basic auth (username:app-password encoded) or Bearer token
Include a JSON body with 'target' object containing 'type: pipeline_ref_target', 'ref_type: branch', 'ref_name: your-branch', and optionally 'selector' to pick a specific pipeline configuration
To trigger a custom pipeline by name, include 'selector: {type: custom, pattern: your-custom-pipeline-name}' in the target object
Poll GET '/2.0/repositories/{workspace}/{repo_slug}/pipelines/{pipeline_uuid}' checking 'state.name' for COMPLETED and 'state.result.name' for SUCCESSFUL or FAILED
Known gotchas
Bitbucket Pipelines must be enabled for the repository in Settings > Pipelines > Settings before any API trigger will work; the endpoint returns 404 if Pipelines is disabled
App passwords are user-scoped; using a shared service account's app password is the typical workaround since Bitbucket Cloud does not have native service accounts
Pipeline variables passed via the API body are ephemeral for that run; they do not override repository or deployment variables of the same name unless explicitly designed to do so
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp