How do you specify a reason when you are declining a Pull Request via the API?

[butters646]

When I use this rest call to decline a PR it works fine:

https://api.bitbucket.org/2.0/repositories/my-repo/pullrequests/13/decline

However, I don't see how to set the reason for declining the PR. I see this as an option in the UI, but don't see how to do it via the API when I looked in the docs. 

Thanks. 

[Stephen Sifers · Accepted solution]

Hello Kesniel,

If you’re wanting to decline a PR via the API and then add a comment for the reason of decline then you’ll need to make a second call to add the comment. The API endpoint for decline does not have a field to allow for commenting while declining. You’ll need to use POST | /2.0/repositories/{username}/{repo_slug}/pullrequests/{pull_request_id}/comments to add your comment.

If you’re having issues with the decline and comments endpoints please let us know so we may help.

Regards,
Stephen Sifers

[butters646]

That worked. Thanks. 

[Martyn Lloyd-Kelly]

For any one who stumbles upon this answer and can't actually post any comments on the PR using "ever-so-useful" documentation found at the link provided above,  let me help you out.

If you POST to the endpoint stipulated in the API documentation, with the JSON body: {"_body":"Your comment"} (as stipulated in the API documentation), you will get the following response from the API:

`````````"type": "error",    

    "error": {

        "fields": {            

        "content": "required key not provided",            

        "_body": "extra keys not allowed"        

    },        

    "message": "Bad request"    

}

Turns out, you actually need to supply the following JSON body, which is not mentioned anywhere in the API documentation!

{"content": {"raw": "Your comment"}}

I only found this out after trawling for other answers to "How do I post a reason for declining a PR using the Bitbucket API?" and found this thread https://community.atlassian.com/t5/Bitbucket-questions/Bitbucket-Cloud-REST-API-v2-0-Commenting-on-Pull-Requests/qaq-p/847107. The answer specifically came from josemonsalve2's comment on the 22nd of May 2019.

The Bitbucket API and its supporting documentation is shockingly poor in places. Please get them both up to spec, Atlassian! Two things that could be improved to dramatically improve the experience for others looking to automate PR declines through the Bitbucket API:

1. Allow API clients to supply a comment in the JSON body sent to the "/decline" endpoint

2. Actually specify the correct JSON body keys to send to endpoints in the API documentation!

[Alex Bondarev]

as of 12/06/2023 for bitbucket cloud answers above are wrong/do not work for me (set reason when decline)

/comments api affects ONLY comments, and reason is NOT a comment

/decline documentation pull-request-id-decline-post  - does not have request body at all, which is not correct - see below

Working solution

it appears that /decline api is able to accept reason for decline - it is not obvious from documentation, actually it is misleading, but if you open dev tools and manually decline with the reason string, you can see

and with that the PowerShell script is

$workspace       = 'your company name'
$repo_slug       = 'your repo name'
$pull_request_id = 77 # pr number
$reason          = 'your reason to decline' #plain text

declineUrl = "https://api.bitbucket.org/2.0/repositories/$workspace/$repo_slug/pullrequests/$pull_request_id/decline" 
$reasonBody = '{ "message": "reason" }'.Replace('reason', $reason) 
Invoke-RestMethod -Method Post -Body $reasonBody -ContentType 'application/json' -Uri $declineUrl -Headers $headersCloud