Example of response when a merge request is pending (status code 202)

Bitbucket Development Bitbucket Cloud
,
1

The Bitbucket Cloud documentation states here that “When merging a pull request takes too long, the client receives a task ID along with a 202 status code. The task ID can be used in a call to this endpoint to check the status of a merge task.”

The example provided shows that the following syntax is used to poll the merge status:
......pullrequests/2286/merge/task-status/<task_id>

However, the initial API call to request a merge, documented here, doesn’t show where such task ID can be found, but generically states that a response with status code 202 would have “In the Location header, the URL to poll for the pull request merge status”. There is not an example of such URL either.

Can anyone please provide a working example, and can the API documentation be improved to clarify the expected usage?

Thanks in advance!

1 Like
2

Hi @PaoloAscari,

The location header is part of the response and will be in the following format:
https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/merge/task-status/{task-id}

Depending on how the request is being performed, you’ll need to add the logic to:

  • retrieve the response headers
  • get the location one
  • retrieve the value of the location header itself

The subsequent request to the task-status URL will contain the details of the task and, once the merge completed, the related details as well.

For example, a completed and successful merge will contain the following info:

{
    "task_status": "SUCCESS",
    ...
},
"merge_result": {
        "comment_count": 1,
        "task_count": 0,
        "type": "pullrequest",
        "id": 23,
        "title": "Task Status PR",
        "description": "Task Status PR",
...
        "state": "MERGED",
           "merge_commit": {
               "type": "commit",
               "hash": "ca40bc03ff69ad032e5d2fa7e8d559e933ce4e76",
               "date": "2023-09-06T01:52:44+00:00",

Hope this helps, let me know if there are any outstanding questions and I’ll reach out to the team to discuss documentation improvements.

Cheers,
Caterina

3

Hi Caterina

Thank you for your detailed reply.

If it helps, what wasn’t completely clear to me, is whether the Location header returned as part of the response contained the full URL to poll verbatim (complete with task ID), or if the <task_id> placeholder that appears in the example provided further below was to be replaced with a piece of data returned as part of the initial merge request.

I had assumed the former (i.e. Location header = full URL, which aligns with your explanation), but just wanted to be sure before moving on with the implementation, as I haven’t encountered any long merges returning a 202 during my initial POC.

4

That makes sense and thank you for sharing, it’s certainly helpful to understand what wasn’t clear.

Let me also share that I checked the header by adding ?async=true as a parameter to the url of the API request.
By doing so, the runs merge asynchronously and immediately returns a 202 with the polling link.
The async parameter is optional and its default value is false.

Caterina