Showing results for 
Search instead for 
Did you mean: 
Sign up Log in
It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage

Bitbucket Cloud REST API v2.0 - Commenting on Pull Requests


As Atlassian deprecated REST API v1.0 and will be removing it in the end of the year, how we will post Pull Request comments with API v2.0?


We have custom java app which is posting comments on Bitbucket PRs to notify users on which problems their PR failed.




6 answers

1 accepted

0 votes
Answer accepted
seanaty Atlassian Team Jul 20, 2018

Hi Daniel,

We just deployed the docs for the remainder of the allowed HTTP methods for the pull request comments. You can see them here:

Let me know if you have any other questions.

Hi Sean,

Thanks for the update! I was getting quite worried that we won't be able to post comments for the Pull Requests in 2.0.


Glad to have it documented.




seanaty Atlassian Team Jul 20, 2018

No worries. It's critical functionality. Also, thanks for updating your app to the v2 APIs!

I am struggling to get this to work from my CI Server, specifically Jenkins. Jenkins has a set of credentials (hidden from me) which give it access to our BitBucket repository. I am getting a 404 back from the call to Bitbucket and need some help figuring connecting the dots. 

The call from my Jenkins pipeline

httpRequest authentication: 'bitbucket', consoleLogResponseBody: true, contentType: 'TEXT_PLAIN', httpMode: 'POST', ignoreSslErrors: true, requestBody: '{"text":"Jenkins COMMENT"}', responseHandle: 'NONE', url: changeUrl

And the values I have tried for changeUrl

PR 2572 is an open and valid pull request in our repository. Any assistance would be appreciated.


EDIT: So, as best I can tell, the Atlassian API documentation is wrong and the actual endpoint is!api/2.0/repositories/messagegears/messagegears-accelerator/pullrequests/2572/comments/

The !api and the 2.0 being somewhat undocumented, although I nearly guessed it myself.  Now, just dealing with the 400 bad request error because it doesnt like the payload.  Thanks Atlassian! 

seanaty Atlassian Team Feb 11, 2020

Hi @John Camerin I have a couple of suggestions.

1. The base URL you should use is ( may work but it is deprecated. Also the other URLs refer to the website and not the API--they wouldn't work).

2. The content type needs to be 'application/json' (it looks like you're using TEXT_PLAIN)

3. The content body needs to be the same "shape" as the JSON for getting comments. Here is an example:

curl<workspace>/<repo>/pullrequests/<id>/comments \
  -u myusername:mypassword \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "content": {
      "raw": "first!"

Hope this helps!


Thanks. This did help.  Of course, what I really want to do is POST much more rich content, like a report generated in the build.  How would I post content other than plain text?  Is there a way to post some multi-line or HTML based content?

I get 400 errors back when I try and Bitbucket starts sending emails to our abuse mailbox.


EDIT: So, its taken a lot of poking and prodding and what I have learned is: 1) extreme sensitivity to where and how carriage returns and spaces are added and 2) the Bitbucket markdown is a bit of a discovery process.

Is there documentation on the Bitbucket comment markdown language?

Like Ryan McBride likes this

@seanaty How would I go about supplying credentials from my pipeline?

Can I use an API token or do I have to create a user dedicated to only comment posting?

-u username:password \


seanaty Atlassian Team Aug 03, 2020

@david_alsh The authentication is the same as outside of a pipeline. You could use your credentials but I'd recommend making an app password. For the most security you could create a new user and use them as a bot. (Note this will be counted towards your bill depending on your plan--it's just a regular user).

Read more about different authentication here:

We do run a proxy inside of the pipeline to do 2 things right now:

  1. You can `git push`
  2. You can POST to the reports API

This doesn't really help you, but just an FYI. You might actually be able to surface your information in a report instead of a comment.

I can't get the create pull request comments api working with basic authentication using app passwords. It seems to work in read-only mode where the POST call is ignored and returns empty or existing comments.

Is there any other easier way to add comments from the pipeline without creating oauth applications and implementing the authentication flows to retrieve an access_token?

I have tried the proxy approach as well with no luck.

Any finding on that?

seanaty Atlassian Team Jan 13, 2021

Unfortunately only a few API endpoints are available for use by the pipelines proxy. I don't actually have a comprehensive list but I do know that the proxy supports at least the reports API and `git push`

Other than that there should be nothing special about using the Bitbucket API inside of a pipeline (versus using the Bitbucket API outside of a pipeline). Basic auth with app passwords should work. If it's not, please provide more details (in a new thread please) to see if someone can troubleshoot.

Hi All,

I know this seems to be an old thread and you may already fixed your issues, but will put it here for reference and if somebody else is looking for Java solution for Bitbucket API V2

This java library Bitbucket-Client is build to implement bitbucket api v2



I was wondering how to connect these with token based authentication. It does not seem to support it. I tried this (which might be totally wrong):


curl{user}/{repo}/pullrequests/7/activity \
--request POST --header 'Content-Type: application/json' \
-d '{"_body":"This is a test"}' \
--header 'Authorization: Bearer "{access_token}"'

I also obtained by access token with: 

curl -X POST -u "{Key}:{secret}" \
-d grant_type=client_credentials

An I doing something wrong, or is this just not supported at all? 

Thanks for your help



I have figured it out. It should be added in the documentation that the only supported mode is non-POST authentication. as explained here

First, in the original post I meant to use /comments, not /activity



Unsupported modes (ERRORS):

# This one returns: This endpoint does not support token-based authentication 
curl{user}/{repo}/pullrequests/7/comments \
--request POST --header 'Content-Type: application/json' \
-d '{"content":{"raw":"This is a test"}}' \
--header 'Authorization: Bearer "{access_token}"'
# This one returns: {"type": "error", "error": {"fields": {"access_token": "extra keys not allowed"}, "message": "Bad request"}
curl{user}/{repo}/pullrequests/7/comments \
--request POST --header 'Content-Type: application/json' \
-d '{"access_token":"{access_token}, "content":{"raw":"This is a test"}}' 

The only available option is:

curl{user}/{repo}/pullrequests/7/comments?access_token={access_token} \
--request POST --header 'Content-Type: application/json' \
-d '{"content":{"raw":"This is a test"}}' 


seanaty Atlassian Team May 22, 2019

I'm glad that you figured it out. In the future, if you can specify the specific errors you receive, that can be helpful to determining what the issue is. For example is it 403, 401, 400, 404, etc?

Also, adding the `-v` flag to curl for verbose is helpful for seeing the request/response headers. This information is also useful for troubleshooting issues, if you can paste that the next time you have an issue. (But still be sure to remove sensitive information)

Secondly, the Authorization header is supported and is the preferred method.

In the first error example you do: 

--header 'Authorization: Bearer "{access_token}"'

This looks like the double quotes "" are a part of the string, which would make things fail.

In the second error example you're passing in the the access token as a part of the body. This isn't supported. Is there are reason you attempted it this way?

Hi Sean,

Thanks for your response. 

I tried again without the quotes, but it gave me the same error. The only reason why I tried sending it in the body was because the preferred method did not work for me. I agree that it would be better to send this information in the header.

The error is a 403. Here is the `-v` output.


curl{user}/{repo}/pullrequests/7     --request POST     --header 'Content-Type: application/json' -v -d '{"content"{"raw":"This is a test"}}' --header 'Authorization: Bearer ****'
Note: Unnecessary use of -X or --request, POST is already inferred.

*   Trying
* Connected to ( port 443 (#0)
* ALPN, offering h2
* ALPN, offering http/1.1
* Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH
* successfully set certificate verify locations:
*   CAfile: /etc/ssl/cert.pem
  CApath: none

* TLSv1.2 (OUT), TLS handshake, Client hello (1):
* TLSv1.2 (IN), TLS handshake, Server hello (2):
* TLSv1.2 (IN), TLS handshake, Certificate (11):
* TLSv1.2 (IN), TLS handshake, Server key exchange (12):
* TLSv1.2 (IN), TLS handshake, Server finished (14):
* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
* TLSv1.2 (OUT), TLS change cipher, Client hello (1):
* TLSv1.2 (OUT), TLS handshake, Finished (20):
* TLSv1.2 (IN), TLS change cipher, Client hello (1):
* TLSv1.2 (IN), TLS handshake, Finished (20):

* SSL connection using TLSv1.2 / ECDHE-ECDSA-AES128-GCM-SHA256
* ALPN, server accepted to use h2
* Server certificate:
*  subject: C=US; ST=California; L=San Francisco; O=Atlassian, Inc.; OU=Bitbucket; CN=*
*  start date: Jun 12 00:00:00 2017 GMT
*  expire date: Jun 16 12:00:00 2020 GMT
*  subjectAltName: host "" matched cert's "*"
*  issuer: C=US; O=DigiCert Inc;; CN=DigiCert SHA2 High Assurance Server CA
*  SSL certificate verify ok.
* Using HTTP2, server supports multi-use
* Connection state changed (HTTP/2 confirmed)
* Copying HTTP/2 data in stream buffer to connection buffer after upgrade: len=0
* Using Stream ID: 1 (easy handle 0x7f***0)

> POST /2.0/repositories/{user}/{repo}/pullrequests/7 HTTP/2
> Host:
> User-Agent: curl/7.54.0
> Accept: */*
> Content-Type: application/json
> Authorization: Bearer **************
> Content-Length: 35

* Connection state changed (MAX_CONCURRENT_STREAMS updated)!
* We are completely uploaded and fine
< HTTP/2 403
< server: nginx
< content-type: text/plain; charset=utf-8
< x-oauth-scopes: pullrequest:write
< strict-transport-security: max-age=31536000; includeSubDomains; preload
< date: Wed, 22 May 2019 20:27:19 GMT
< x-served-by: app-144
< x-static-version: *****
< etag: "*******"
< x-render-time: 0.0305991172791
< x-credential-type: oauth2
< x-version: ********
< x-request-count: 183
< x-frame-options: SAMEORIGIN
< content-length: 57

* Connection #0 to host left intact
This endpoint does not support token-based authentication

Hi @dhanielk,

I am troubling to set author of the comment. Can you help me?


"content": {
"raw": "Comment on PR.
"user": {
"username": "suresh2702",
"display_name": "Suresh Sakhare"
"type": "user"


hi Sureesh,

have you succeed to commet with author? if succeed, could you share your json? thanks!

0 votes

Hi Daniel,

Bitbucket cloud's API v2.0 has several resources online discussing the changes. One very useful resource is the API documentation itself which has a relatively easy search function built in. If you are looking specifically for Pull Request comments then click here. Hopefully this helps!


Hi Michael,

No it doesn't help at all. You can't create comments on PRs with API v2.0. At least as per documentation.


My question is about posting comments on PRs.




Hi Daniel,

I spoke to our developers about this and it appears they are putting the final tweaks on our documentation for Pull Requests right now. Please keep an eye out for in the coming days as it will be published soon. Sorry for the inconvenience!

Best Regards,


Hi Michael,

Thanks for pushing this forward.


Much appreciated,


Suggest an answer

Log in or Sign up to answer
Community showcase
Published in Bitbucket

⭐ Calling all Bitbucket and DevOps experts: Special showcase opportunity ⭐

Hi, Bitbucket community! Are you a DevOps practitioner (or know one in your network)? Do you have DevOps tips, tricks, or learnings you'd like to share with the community? If so, we'd love to hea...

1,440 views 4 7
Read article

Community Events

Connect with like-minded Atlassian users at free events near you!

Find an event

Connect with like-minded Atlassian users at free events near you!

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you