How to create a pull request via the Bitbucket API?

[Vincent THOMAS]

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 endpoint 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 optional ? How does reviewers[i].user works ? If I only put my BitBucket login in reviewers[i].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.

Additional information :

• BitBucket Server V5.7.1
• I am not administrator of my BitBucket platform.
• I am administrator (+ Read/Write) of my BitBucket Project (and all repo inside it)