title: How to create a pull request via the Bitbucket API?
body: <p><strong>TL;DR</strong> : 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)</p>
  
  <hr>
  
  <p>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.</p>
  
  <p>I found <a href="https://docs.atlassian.com/bitbucket-server/rest/5.7.1/bitbucket-rest.html#idm45187779531808" rel="nofollow noreferrer">this documentation</a> which gave me the following endpoint to use with a POST request : <code>/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests</code> . 
  This enpoint need the following JSON :</p>
  
  <pre><code>{
      "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"
              }
          }
      ]
  }
  </code></pre>
  
  <p>However, I can't find any information on how to build this JSON ...
  I can guess what <code>title</code> and <code>description</code> are, but what are <code>state</code>, <code>open</code>, <code>closed</code>, etc. for ? How do I build a correct <code>fromRef.id</code> ? Why the repo name is set to <code>null</code> ? which attribute are optinal ? If I put my BitBucket login in <code>reviewers[0].user.name</code>, will it work ? etc.</p>
  
  <p>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 ?</p>
  
  <p><strong>Anyway, here is my real question : where can I find some documentation on this Pull Request JSON Object ?</strong></p>
  
  <p>Thanks.</p>
  
  <hr>
  
  <p>EDIT : This is not a duplicate of <a href="https://stackoverflow.com/questions/36977257/pull-request-using-stash-rest-api">this post</a> 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 <a href="https://stackoverflow.com/questions/36977257/pull-request-using-stash-rest-api">the other post</a>, it doesn't actually answers my question at all (see comments).</p>