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).

Answer 1

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.