How to create a pull request via the Bitbucket API?

Question

TL;DR : Where can I find the documentation on what to pass to the POST request in order to create a Pull Request ? (What to put in the JSON)

Using a Groovy script, I'm trying to automatize some tasks that include a commit/push of a tmp branch on multiple projects. I want to automatically create pull request between the tmp branch and the prod branch of all those projects at the end of my script. In order to do so, I tried using the BitBucket REST API.

I found this documentation which gave me the following endpoint to use with a POST request : /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests . This enpoint need the following JSON :

{
    "title": "Talking Nerdy",
    "description": "It’s a kludge, but put the tuple from the database in the cache.",
    "state": "OPEN",
    "open": true,
    "closed": false,
    "fromRef": {
        "id": "refs/heads/feature-ABC-123",
        "repository": {
            "slug": "my-repo",
            "name": null,
            "project": {
                "key": "PRJ"
            }
        }
    },
    "toRef": {
        "id": "refs/heads/master",
        "repository": {
            "slug": "my-repo",
            "name": null,
            "project": {
                "key": "PRJ"
            }
        }
    },
    "locked": false,
    "reviewers": [
        {
            "user": {
                "name": "charlie"
            }
        }
    ]
}

However, I can't find any information on how to build this JSON ... I can guess what title and description are, but what are state, open, closed, etc. for ? How do I build a correct fromRef.id ? Why the repo name is set to null ? which attribute are optinal ? If I put my BitBucket login in reviewers[0].user.name, will it work ? etc.

Every answers I've found on this subject is just a copy/past this same JSON, and everybody seems to understand how it works without any explanations... Did I miss something ?

Anyway, here is my real question : where can I find some documentation on this Pull Request JSON Object ?

Thanks.

EDIT : This is not a duplicate of this post since this is not the same problem. I have no problem with the permission/authentication, and I even managed to make the request works by fiddling with it. I am only asking for documentation because I want to understand what I am doing in order to best customize the request. While there is some (very light) explanations in the answers of the other post, it doesn't actually answers my question at all (see comments).

Search https://bitbucket.org/api/swagger.json for "Creates a new pull request where the destination repository is" -- I found it easier to dump this into a swagger ui and navigate it there. Leaving this as a comment vs answer b/c it's almost certainly going to succumb to linkrot. — thehole, May 23 '19 at 16:46
Thanks. It's definitly a good start. However, it looks a lot like the parameter for the Cloud equivalent of the request I use (I have Bitbucket Server). The parameters are not the same, it seems. ([link](https://developer.atlassian.com/bitbucket/api/2/reference/resource/repositories/%7Busername%7D/%7Brepo_slug%7D/pullrequests#post) for cloud API documentation) — Nefrasky, May 24 '19 at 15:44
Possible duplicate of [Pull request using Stash rest api](https://stackoverflow.com/questions/36977257/pull-request-using-stash-rest-api) — thehole, May 24 '19 at 23:21
You may want to contact Atlassian directly, and answer here if their response is something publicly available. — thehole, May 24 '19 at 23:23
@thehole I don't think it's a duplicate : It is not the same problem at all (he has an authentication problem) and while there is some light explanation of the JSON in the answers, it doesn't actually answer any of my questions. — Nefrasky, May 27 '19 at 08:43
I have created the same post on the Atlassian Community forum, but I haven't got any answers there either ... After playing with the request on my own, I manage to make it works and understand most of the parameters, but I still can't add reviewers ... I'll answer my own question with what I learned once It'll works exactly how I want. (And if nobody answers before) — Nefrasky, May 27 '19 at 08:46
I also had some tries with it. For the reviewers I found out, that you can't add yourself as a reviewer and that a reviewer need at least read permission for the repository. — TheFRedFox, Jul 08 '19 at 14:59

score 2 · Answer 1 · answered Mar 29 '21 at 06:52

Using the documentation found here I was able to successfully created a pull request with minimal properties (inferring what, therefore, are optional properties) from a PowerShell script.

My example uses master as the branch to merge to, foo as the branch to merge from, Project1 and Repository1 as the BitBucket project and repository, respectively. The uri is as follows (replace the root, project and repository): https://bitbucket.example.com/rest/api/1.0/projects/Project1/repos/Repository1/pull-requests.

Sending the following JSON (using the correct Content-Type and Authorization headers) creates a pull request:

{
            "title" : "This is the title of my pull request",
            "description" : "This is the description of my pull request",
            "fromRef" : {
                "id" : "refs/heads/foo",
                "repository" : "Repository1",
                "project" : {
                    "key" : "Project1"
                }
            },
            "toRef" : {
                "id" : "refs/heads/master",
                "repository" : "Repository1",
                "project" : {
                    "key" : "Project1"
                }
            }
        }

The state and reviewers are optional and are left out in this example.

How to create a pull request via the Bitbucket API?

1 Answers1