Atlassian Bitbucket Pull Requests API
The Atlassian Bitbucket Pull Requests API allows users to interact with pull requests in their repositories, providing endpoints for viewing, creating, updating, and merging pull requests.
OpenAPI Specification
openapi: 3.0.0
info:
title: 'Atlassian pullrequests/{selected user}/'
description: Needs description.
version: '2.0'
termsOfService: https://www.atlassian.com/legal/customer-agreement
contact:
name: Bitbucket Support
url: https://support.atlassian.com/bitbucket-cloud/
email: [email protected]
paths:
/pullrequests/{selected_user}:
get:
tags:
- Pullrequests
description: >-
Returns all pull requests authored by the specified user.<br><br>By
default only open pull requests are returned. This can be
controlled<br>using the `state` query parameter. To retrieve pull
requests that are<br>in one of multiple states, repeat the `state`
parameter for each<br>individual state.<br><br>This endpoint also
supports filtering and sorting of the results. See<br>[filtering and
sorting](/cloud/bitbucket/rest/intro/#filtering) for more details.
summary: Atlassian List Pull Requests For A User
responses:
'200':
description: All pull requests authored by the specified user.
content:
application/json:
schema:
$ref: '#/components/schemas/paginated_pullrequests'
'404':
description: If the specified user does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
parameters:
- name: state
in: query
description: >-
Only return pull requests that are in this state. This parameter can
be repeated.
schema:
type: string
enum:
- OPEN
- MERGED
- DECLINED
- SUPERSEDED
security:
- oauth2:
- pullrequest
- basic: []
- api_key: []
operationId: atlassianListPullRequestsForAUser
parameters:
- name: selected_user
in: path
description: >
This can either be the username of the pull request author, the
author's UUID
surrounded by curly-braces, for example: `{account UUID}`, or the
author's Atlassian ID.
required: true
schema:
type: string
/repositories/{workspace}/{repo_slug}/pullrequests:
get:
tags:
- Pullrequests
description: >-
Returns all pull requests on the specified repository.<br><br>By default
only open pull requests are returned. This can be controlled<br>using
the `state` query parameter. To retrieve pull requests that are<br>in
one of multiple states, repeat the `state` parameter for
each<br>individual state.<br><br>This endpoint also supports filtering
and sorting of the results. See<br>[filtering and
sorting](/cloud/bitbucket/rest/intro/#filtering) for more details.
summary: Atlassian List Pull Requests
responses:
'200':
description: All pull requests on the specified repository.
content:
application/json:
schema:
$ref: '#/components/schemas/paginated_pullrequests'
'401':
description: If the repository is private and the request was not authenticated.
'404':
description: If the specified repository does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
parameters:
- name: state
in: query
description: >-
Only return pull requests that are in this state. This parameter can
be repeated.
schema:
type: string
enum:
- OPEN
- MERGED
- DECLINED
- SUPERSEDED
security:
- oauth2:
- pullrequest
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:pullrequest:bitbucket
operationId: atlassianListPullRequests
post:
tags:
- Pullrequests
description: >-
Creates a new pull request where the destination repository is<br>this
repository and the author is the authenticated user.<br><br>The minimum
required fields to create a pull request are `title` and<br>`source`,
specified by a branch name.<br><br>```<br>curl
https://api.bitbucket.org/2.0/repositories/my-workspace/my-repository/pullrequests
\<br> -u my-username:my-password \<br> --request POST \<br> --header 'Content-Type: application/json' \<br> --data '{<br> "title": "My Title",<br> "source": {<br> "branch":
{<br> "name": "staging"<br> }<br> }<br> }'<br>```<br><br>If the pull request's `destination` is not
specified, it will default<br>to the `repository.mainbranch`. To open a
pull request to a<br>different branch, say from a feature branch to a
staging branch,<br>specify a `destination` (same format as the
`source`):<br><br>```<br>{<br> "title": "My Title",<br> "source":
{<br> "branch": {<br> "name":
"my-feature-branch"<br> }<br> },<br> "destination":
{<br> "branch": {<br> "name": "staging"<br> }<br> }<br>}<br>```<br><br>Reviewers can be specified by adding an
array of user objects as the<br>`reviewers`
property.<br><br>```<br>{<br> "title": "My Title",<br> "source":
{<br> "branch": {<br> "name":
"my-feature-branch"<br> }<br> },<br> "reviewers":
[<br> {<br> "uuid":
"{504c3b62-8120-4f0c-a7bc-87800b9d6f70}"<br> }<br> ]<br>}<br>```<br><br>Other fields:<br><br>* `description` - a
string<br>* `close_source_branch` - boolean that specifies if the source
branch should be closed upon merging
summary: Atlassian Create A Pull Request
responses:
'201':
description: The newly created pull request.
headers:
Location:
description: The URL of new newly created pull request.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/pullrequest'
'400':
description: >-
If the input document was invalid, or if the caller lacks the
privilege to create repositories under the targeted account.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'401':
description: If the request was not authenticated.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/pullrequest'
description: >-
The new pull request.
The request URL you POST to becomes the destination repository URL.
For this reason, you must specify an explicit source repository in the
request object if you want to pull from a different repository (fork).
Since not all elements are required or even mutable, you only need to
include the elements you want to initialize, such as the source branch
and the title.
security:
- oauth2:
- pullrequest:write
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:pullrequest:bitbucket
- write:pullrequest:bitbucket
operationId: atlassianCreateAPullRequest
parameters:
- name: repo_slug
in: path
description: |
This can either be the repository slug or the UUID of the repository,
surrounded by curly-braces, for example: `{repository UUID}`.
required: true
schema:
type: string
- name: workspace
in: path
description: |
This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
required: true
schema:
type: string
/repositories/{workspace}/{repo_slug}/pullrequests/activity:
get:
tags:
- Pullrequests
description: >-
Returns a paginated list of the pull request's activity log.<br><br>This
handler serves both a v20 and internal endpoint. The v20
endpoint<br>returns reviewer comments, updates, approvals and request
changes. The internal<br>endpoint includes those plus tasks and
attachments.<br><br>Comments created on a file or a line of code have an
inline property.<br><br>Comment example:<br>```<br>{<br> "pagelen":
20,<br> "values": [<br> {<br> "comment":
{<br> "links": {<br> "self":
{<br> "href":
"https://api.bitbucket.org/2.0/repositories/atlassian/atlaskit-mk-2/pullrequests/5695/comments/118571088"<br> },<br> "html": {<br> "href":
"https://bitbucket.org/atlassian/atlaskit-mk-2/pull-requests/5695/_/diff#comment-118571088"<br> }<br> },<br> "deleted":
false,<br> "pullrequest": {<br> "type": "pullrequest",<br> "id":
5695,<br> "links": {<br> "self": {<br> "href":
"https://api.bitbucket.org/2.0/repositories/atlassian/atlaskit-mk-2/pullrequests/5695"<br> },<br> "html": {<br> "href":
"https://bitbucket.org/atlassian/atlaskit-mk-2/pull-requests/5695"<br> }<br> },<br> "title":
"username/NONE: small change from onFocus to onClick to handle tabbing
through the page and not expand the editor unless a click event triggers
it"<br> },<br> "content":
{<br> "raw": "inline with to a dn from
lines",<br> "markup":
"markdown",<br> "html": "inline with to a dn from
lines",<br> "type": "rendered"<br> },<br> "created_on":
"2019-09-27T00:33:46.039178+00:00",<br> "user":
{<br> "display_name": "Name
Lastname",<br> "uuid": "{}",<br> "links": {<br> "self":
{<br> "href":
"https://api.bitbucket.org/2.0/users/%7B%7D"<br> },<br> "html": {<br> "href": "https://bitbucket.org/%7B%7D/"<br> },<br> "avatar": {<br> "href":
"https://avatar-management--avatars.us-west-2.prod.public.atl-paas.net/:/128"<br> }<br> },<br> "type":
"user",<br> "nickname":
"Name",<br> "account_id": ""<br> },<br> "created_on":
"2019-09-27T00:33:46.039178+00:00",<br> "user":
{<br> "display_name": "Name
Lastname",<br> "uuid": "{}",<br> "links": {<br> "self":
{<br> "href":
"https://api.bitbucket.org/2.0/users/%7B%7D"<br> },<br> "html": {<br> "href": "https://bitbucket.org/%7B%7D/"<br> },<br> "avatar": {<br> "href":
"https://avatar-management--avatars.us-west-2.prod.public.atl-paas.net/:/128"<br> }<br> },<br> "type":
"user",<br> "nickname":
"Name",<br> "account_id": ""<br> },<br> "updated_on":
"2019-09-27T00:33:46.055384+00:00",<br> "inline":
{<br> "context_lines": "",<br> "to": null,<br> "path": "",<br> "outdated": false,<br> "from": 211<br> },<br> "type": "pullrequest_comment",<br> "id": 118571088<br> },<br> "pull_request":
{<br> "type": "pullrequest",<br> "id":
5695,<br> "links": {<br> "self":
{<br> "href":
"https://api.bitbucket.org/2.0/repositories/atlassian/atlaskit-mk-2/pullrequests/5695"<br> },<br> "html": {<br> "href":
"https://bitbucket.org/atlassian/atlaskit-mk-2/pull-requests/5695"<br> }<br> },<br> "title": "username/NONE:
small change from onFocus to onClick to handle tabbing through the page
and not expand the editor unless a click event triggers
it"<br> }<br> }<br> ]<br>}<br>```<br><br>Updates
include a state property of OPEN, MERGED, or DECLINED.<br><br>Update
example:<br>```<br>{<br> "pagelen": 20,<br> "values": [<br> {<br> "update": {<br> "description":
"",<br> "title": "username/NONE: small change from
onFocus to onClick to handle tabbing through the page and not expand the
editor unless a click event triggers it",<br> "destination": {<br> "commit":
{<br> "type":
"commit",<br> "hash":
"6a2c16e4a152",<br> "links":
{<br> "self":
{<br> "href":
"https://api.bitbucket.org/2.0/repositories/atlassian/atlaskit-mk-2/commit/6a2c16e4a152"<br> },<br> "html":
{<br> "href":
"https://bitbucket.org/atlassian/atlaskit-mk-2/commits/6a2c16e4a152"<br> }<br> }<br> },<br> "branch": {<br> "name":
"master"<br> },<br> "repository":
{<br> "name":
"Atlaskit-MK-2",<br> "type":
"repository",<br> "full_name":
"atlassian/atlaskit-mk-2",<br> "links":
{<br> "self":
{<br> "href":
"https://api.bitbucket.org/2.0/repositories/atlassian/atlaskit-mk-2"<br> },<br> "html":
{<br> "href":
"https://bitbucket.org/atlassian/atlaskit-mk-2"<br> },<br> "avatar":
{<br> "href":
"https://bytebucket.org/ravatar/%7B%7D?ts=js"<br> }<br> },<br> "uuid":
"{}"<br> }<br> },<br> "reason": "",<br> "source": {<br> "commit": {<br> "type":
"commit",<br> "hash":
"728c8bad1813",<br> "links":
{<br> "self":
{<br> "href":
"https://api.bitbucket.org/2.0/repositories/atlassian/atlaskit-mk-2/commit/728c8bad1813"<br> },<br> "html":
{<br> "href":
"https://bitbucket.org/atlassian/atlaskit-mk-2/commits/728c8bad1813"<br> }<br> }<br> },<br> "branch": {<br> "name":
"username/NONE-add-onClick-prop-for-accessibility"<br> },<br> "repository": {<br> "name": "Atlaskit-MK-2",<br> "type":
"repository",<br> "full_name":
"atlassian/atlaskit-mk-2",<br> "links":
{<br> "self":
{<br> "href":
"https://api.bitbucket.org/2.0/repositories/atlassian/atlaskit-mk-2"<br> },<br> "html":
{<br> "href":
"https://bitbucket.org/atlassian/atlaskit-mk-2"<br> },<br> "avatar":
{<br> "href":
"https://bytebucket.org/ravatar/%7B%7D?ts=js"<br> }<br> },<br> "uuid":
"{}"<br> }<br> },<br> "state": "OPEN",<br> "author": {<br> "display_name": "Name Lastname",<br> "uuid":
"{}",<br> "links": {<br> "self": {<br> "href":
"https://api.bitbucket.org/2.0/users/%7B%7D"<br> },<br> "html": {<br> "href": "https://bitbucket.org/%7B%7D/"<br> },<br> "avatar": {<br> "href":
"https://avatar-management--avatars.us-west-2.prod.public.atl-paas.net/:/128"<br> }<br> },<br> "type":
"user",<br> "nickname":
"Name",<br> "account_id": ""<br> },<br> "date":
"2019-05-10T06:48:25.305565+00:00"<br> },<br> "pull_request": {<br> "type":
"pullrequest",<br> "id": 5695,<br> "links": {<br> "self": {<br> "href":
"https://api.bitbucket.org/2.0/repositories/atlassian/atlaskit-mk-2/pullrequests/5695"<br> },<br> "html": {<br> "href":
"https://bitbucket.org/atlassian/atlaskit-mk-2/pull-requests/5695"<br> }<br> },<br> "title": "username/NONE:
small change from onFocus to onClick to handle tabbing through the page
and not expand the editor unless a click event triggers
it"<br> }<br> }<br> ]<br>}<br>```<br><br>Approval
example:<br>```<br>{<br> "pagelen": 20,<br> "values": [<br> {<br> "approval": {<br> "date":
"2019-09-27T00:37:19.849534+00:00",<br> "pullrequest":
{<br> "type": "pullrequest",<br> "id": 5695,<br> "links": {<br> "self": {<br> "href":
"https://api.bitbucket.org/2.0/repositories/atlassian/atlaskit-mk-2/pullrequests/5695"<br> },<br> "html": {<br> "href":
"https://bitbucket.org/atlassian/atlaskit-mk-2/pull-requests/5695"<br> }<br> },<br> "title":
"username/NONE: small change from onFocus to onClick to handle tabbing
through the page and not expand the editor unless a click event triggers
it"<br> },<br> "user":
{<br> "display_name": "Name
Lastname",<br> "uuid": "{}",<br> "links": {<br> "self":
{<br> "href":
"https://api.bitbucket.org/2.0/users/%7B%7D"<br> },<br> "html": {<br> "href": "https://bitbucket.org/%7B%7D/"<br> },<br> "avatar": {<br> "href":
"https://avatar-management--avatars.us-west-2.prod.public.atl-paas.net/:/128"<br> }<br> },<br> "type":
"user",<br> "nickname":
"Name",<br> "account_id": ""<br> }<br> },<br> "pull_request": {<br> "type": "pullrequest",<br> "id": 5695,<br> "links": {<br> "self": {<br> "href":
"https://api.bitbucket.org/2.0/repositories/atlassian/atlaskit-mk-2/pullrequests/5695"<br> },<br> "html": {<br> "href":
"https://bitbucket.org/atlassian/atlaskit-mk-2/pull-requests/5695"<br> }<br> },<br> "title": "username/NONE:
small change from onFocus to onClick to handle tabbing through the page
and not expand the editor unless a click event triggers
it"<br> }<br> }<br> ]<br>}<br>```
summary: Atlassian List A Pull Request Activity Log
responses:
'200':
description: The pull request activity log
'401':
description: If the repository is private and the request was not authenticated.
'404':
description: If the specified repository does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- pullrequest
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:pullrequest:bitbucket
operationId: atlassianListAPullRequestActivityLog
parameters:
- name: repo_slug
in: path
description: |
This can either be the repository slug or the UUID of the repository,
surrounded by curly-braces, for example: `{repository UUID}`.
required: true
schema:
type: string
- name: workspace
in: path
description: |
This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
required: true
schema:
type: string
/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}:
get:
tags:
- Pullrequests
description: Returns the specified pull request.
summary: Atlassian Get A Pull Request
responses:
'200':
description: The pull request object
content:
application/json:
schema:
$ref: '#/components/schemas/pullrequest'
'401':
description: If the repository is private and the request was not authenticated.
'404':
description: If the repository or pull request does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- pullrequest
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:pullrequest:bitbucket
operationId: atlassianGetAPullRequest
put:
tags:
- Pullrequests
description: >-
Mutates the specified pull request.<br><br>This can be used to change
the pull request's branches or description.<br><br>Only open pull
requests can be mutated.
summary: Atlassian Update A Pull Request
responses:
'200':
description: The updated pull request
content:
application/json:
schema:
$ref: '#/components/schemas/pullrequest'
'400':
description: If the input document was invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'401':
description: If the request was not authenticated.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: If the repository or pull request id does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/error'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/pullrequest'
description: The pull request that is to be updated.
security:
- oauth2:
- pullrequest:write
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:pullrequest:bitbucket
- write:pullrequest:bitbucket
operationId: atlassianUpdateAPullRequest
parameters:
- name: pull_request_id
in: path
description: The id of the pull request.
required: true
schema:
type: integer
- name: repo_slug
in: path
description: |
This can either be the repository slug or the UUID of the repository,
surrounded by curly-braces, for example: `{repository UUID}`.
required: true
schema:
type: string
- name: workspace
in: path
description: |
This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
required: true
schema:
type: string
/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/activity:
get:
tags:
- Pullrequests
description: >-
Returns a paginated list of the pull request's activity log.<br><br>This
handler serves both a v20 and internal endpoint. The v20
endpoint<br>returns reviewer comments, updates, approvals and request
changes. The internal<br>endpoint includes those plus tasks and
attachments.<br><br>Comments created on a file or a line of code have an
inline property.<br><br>Comment example:<br>```<br>{<br> "pagelen":
20,<br> "values": [<br> {<br> "comment":
{<br> "links": {<br> "self":
{<br> "href":
"https://api.bitbucket.org/2.0/repositories/atlassian/atlaskit-mk-2/pullrequests/5695/comments/118571088"<br> },<br> "html": {<br> "href":
"https://bitbucket.org/atlassian/atlaskit-mk-2/pull-requests/5695/_/diff#comment-118571088"<br> }<br> },<br> "deleted":
false,<br> "pullrequest": {<br> "type": "pullrequest",<br> "id":
5695,<br> "links": {<br> "self": {<br> "href":
"https://api.bitbucket.org/2.0/repositories/atlassian/atlaskit-mk-2/pullrequests/5695"<br> },<br> "html": {<br> "href":
"https://bitbucket.org/atlassian/atlaskit-mk-2/pull-requests/5695"<br> }<br> },<br> "title":
"username/NONE: small change from onFocus to onClick to handle tabbing
through the page and not expand the editor unless a click event triggers
it"<br> },<br> "content":
{<br> "raw": "inline with to a dn from
lines",<br> "markup":
"markdown",<br> "html": "inline with to a dn from
lines",<br> "type": "rendered"<br> },<br> "created_on":
"2019-09-27T00:33:46.039178+00:00",<br> "user":
{<br> "display_name": "Name
Lastname",<br> "uuid": "{}",<br> "links": {<br> "self":
{<br> "href":
"https://api.bitbucket.org/2.0/users/%7B%7D"<br> },<br> "html": {<br> "href": "https://bitbucket.org/%7B%7D/"<br> },<br> "avatar": {<br> "href":
"https://avatar-management--avatars.us-west-2.prod.public.atl-paas.net/:/128"<br> }<br> },<br> "type":
"user",<br> "nickname":
"Name",<br> "account_id": ""<br> },<br> "created_on":
"2019-09-27T00:33:46.039178+00:00",<br> "user":
{<br> "display_name": "Name
Lastname",<br> "uuid": "{}",<br> "links": {<br> "self":
{<br> "href":
"https://api.bitbucket.org/2.0/users/%7B%7D"<br> },<br> "html": {<br> "href": "https://bitbucket.org/%7B%7D/"<br> },<br> "avatar": {<br> "href":
"https://avatar-management--avatars.us-west-2.prod.public.atl-paas.net/:/128"<br> }<br> },<br> "type":
"user",<br> "nickname":
"Name",<br> "account_id": ""<br> },<br> "updated_on":
"2019-09-27T00:33:46.055384+00:00",<br> "inline":
{<br> "context_lines": "",<br> "to": null,<br> "path": "",<br> "outdated": false,<br> "from": 211<br> },<br> "type": "pullrequest_comment",<br> "id": 118571088<br> },<br> "pull_request":
{<br> "type": "pullrequest",<br> "id":
5695,<br> "links": {<br> "self":
{<br> "href":
"https://api.bitbucket.org/2.0/repositories/atlassian/atlaskit-mk-2/pullrequests/5695"<br> },<br> "html": {<br> "href":
"https://bitbucket.org/atlassian/atlaskit-mk-2/pull-requests/5695"<br> }<br> },<br> "title": "username/NONE:
small change from onFocus to onClick to handle tabbing through the page
and not expand the editor unless a click event triggers
it"<br> }<br> }<br> ]<br>}<br>```<br><br>Updates
include a state property of OPEN, MERGED, or DECLINED.<br><br>Update
example:<br>```<br>{<br> "pagelen": 20,<br> "values": [<br> {<br> "update": {<br> "description":
"",<br> "tit
# --- truncated at 32 KB (206 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-pullrequests-selected-user--openapi-original.yml