Pull Requests API

List pull requests

List all pull requests across all the authenticated user’s projects including owned projects, member projects, and group projects:

GET /api/v1/pull_requests.json

List all pull requests across owned and member projects for the authenticated user:

GET /api/v1/user/pull_requests.json

List all pull requests for a given group for the authenticated user:

GET /api/v1/group/:id/pull_requests.json

Parameters

filter
Optional String
  • assigned: Pull requests assigned to you (default)
  • created: Pull requests created by you
  • all: All pull requests the authenticated user can see
status
Optional String open (default), closed
sort
Optional String submitted (default), updated.
direction
Optional String asc or desc (default).
since
Optional Integer of a timestamp in Unix time format.

Response:

{
  "pull_requests": [
    {
      "number": "serial number",
      "title": "title",
      "to_ref": {
        "ref": "reference",
        "sha": "sha",
        "project": {
          "id": "project id",
          "name": "project name",
          "visibility": "visibility (open/hidden)",
          "fullname": "project fullname",
          "url": "url to project data page",
          "git_url": "path to project git",
          "ssh_url": "path to project git over ssh",
          "maintainer": {
            "id": "user id",
            "uname": "user uname",
            "name": "user name",
            "url": "api user path",
            "email": "user email"
          }
        }
      },
      "from_ref": {
        "ref": "reference",
        "sha": "sha",
        "project": {
          "id": "project id",
          "name": "project name",
          "visibility": "visibility (open/hidden)",
          "fullname": "project fullname",
          "url": "url to project data page",
          "git_url": "path to project git",
          "ssh_url": "path to project git over ssh",
          "maintainer": {
            "id": "user id",
            "uname": "user uname",
            "name": "user name",
            "url": "api user path",
            "email": "user email"
          }
        }
      },
      "status": "pull request status",
      "owner": {
        "id": "user id",
        "uname": "user uname",
        "name": "user name",
        "url": "api user path"
      },
      "assignee": {
        "id": "user id",
        "uname": "user uname",
        "name": "user name",
        "url": "api user path"
      },
      "merged_at": "merged at date and time",
      "mergeable": "can be automatically merged",
      "url": "url to pull request data page"
    }
  ],
  "url": "path to pull request data"
}

Example:

{
  "pull_requests": [
    {
      "number": "11",
      "title": "new feature",
      "to_ref": {
        "ref": "update-version",
        "sha": "3d1468bbb339c8b59234a5bbc35dedf3d89c2043",
        "project": {
          "id": 666,
          "name": "evil_tools",
          "visibility": "open",
          "fullname": "abf/evil_tools",
          "url": "/api/v1/projects/666.json",
          "git_url": "https:/ivan@abf.rosalinux.ru/jaroslav_garkin/hwinfo.git",
          "ssh_url": "git@abf.rosalinux.ru:jaroslav_garkin/hwinfo.git",
          "maintainer": {
            "id": 1,
            "name": "Ivan Aivazovsky",
            "uname": "ivan_aivazovsky",
            "url": "/api/v1/users/1.json",
            "email": "ivan.aivazovsky@email.ru "
          }
        }
      },
      "from_ref": {
        "ref": "update-rails",
        "sha": "3d1468bbb339c8b59234a5bbc35dedf3d89c2043",
        "project": {
          "id": 666,
          "name": "evil_tools",
          "visibility": "open",
          "fullname": "abf/evil_tools",
          "url": "/api/v1/projects/666.json",
          "git_url": "https:/ivan@abf.rosalinux.ru/jaroslav_garkin/hwinfo.git",
          "ssh_url": "git@abf.rosalinux.ru:jaroslav_garkin/hwinfo.git",
          "maintainer": {
            "id": 1,
            "name": "Ivan Aivazovsky",
            "uname": "ivan_aivazovsky",
            "url": "/api/v1/users/1.json",
            "email": "ivan.aivazovsky@email.ru "
          }
        }
      },
      "status": "open",
      "owner": {
        "id": 1,
        "name": "Ivan Aivazovsky",
        "uname": "ivan_aivazovsky",
        "url": "/api/v1/users/1.json"
      },
      "assignee": {
        "id": 1,
        "name": "Ivan Aivazovsky",
        "uname": "ivan_aivazovsky",
        "url": "/api/v1/users/1.json"
      },
      "merged_at": "1348170705",
      "mergeable": "true",
      "url": "/api/v1/projects/3/pull_requests/11.json"
    }
  ],
  "url": "/api/v1/projects/3/pull_requests.json"
}

List pull requests for a project

GET /api/v1/projects/:id/pull_requests.json

Parameters

status
Optional String open (default), closed
assignee
Optional String
  • String User nickname
  • none for Issues with no assigned User.
  • * for Issues with any assigned User.
creator
Optional String User nickname.
sort
Optional String submitted (default), updated.
direction
Optional String asc or desc (default).
since
Optional Integer of a timestamp in Unix time format.

Response:

{
  "pull_requests": [
    {
      "number": "serial number",
      "title": "title",
      "to_ref": {
        "ref": "reference",
        "sha": "sha",
        "project": {
          "id": "project id",
          "name": "project name",
          "visibility": "visibility (open/hidden)",
          "fullname": "project fullname",
          "url": "url to project data page",
          "git_url": "path to project git",
          "ssh_url": "path to project git over ssh",
          "maintainer": {
            "id": "user id",
            "uname": "user uname",
            "name": "user name",
            "url": "api user path",
            "email": "user email"
          }
        }
      },
      "from_ref": {
        "ref": "reference",
        "sha": "sha",
        "project": {
          "id": "project id",
          "name": "project name",
          "visibility": "visibility (open/hidden)",
          "fullname": "project fullname",
          "url": "url to project data page",
          "git_url": "path to project git",
          "ssh_url": "path to project git over ssh",
          "maintainer": {
            "id": "user id",
            "uname": "user uname",
            "name": "user name",
            "url": "api user path",
            "email": "user email"
          }
        }
      },
      "status": "pull request status",
      "owner": {
        "id": "user id",
        "uname": "user uname",
        "name": "user name",
        "url": "api user path"
      },
      "assignee": {
        "id": "user id",
        "uname": "user uname",
        "name": "user name",
        "url": "api user path"
      },
      "merged_at": "merged at date and time",
      "mergeable": "can be automatically merged",
      "url": "url to pull request data page"
    }
  ],
  "url": "path to pull request data"
}

Example:

{
  "pull_requests": [
    {
      "number": "11",
      "title": "new feature",
      "to_ref": {
        "ref": "update-version",
        "sha": "3d1468bbb339c8b59234a5bbc35dedf3d89c2043",
        "project": {
          "id": 666,
          "name": "evil_tools",
          "visibility": "open",
          "fullname": "abf/evil_tools",
          "url": "/api/v1/projects/666.json",
          "git_url": "https:/ivan@abf.rosalinux.ru/jaroslav_garkin/hwinfo.git",
          "ssh_url": "git@abf.rosalinux.ru:jaroslav_garkin/hwinfo.git",
          "maintainer": {
            "id": 1,
            "name": "Ivan Aivazovsky",
            "uname": "ivan_aivazovsky",
            "url": "/api/v1/users/1.json",
            "email": "ivan.aivazovsky@email.ru "
          }
        }
      },
      "from_ref": {
        "ref": "update-rails",
        "sha": "3d1468bbb339c8b59234a5bbc35dedf3d89c2043",
        "project": {
          "id": 666,
          "name": "evil_tools",
          "visibility": "open",
          "fullname": "abf/evil_tools",
          "url": "/api/v1/projects/666.json",
          "git_url": "https:/ivan@abf.rosalinux.ru/jaroslav_garkin/hwinfo.git",
          "ssh_url": "git@abf.rosalinux.ru:jaroslav_garkin/hwinfo.git",
          "maintainer": {
            "id": 1,
            "name": "Ivan Aivazovsky",
            "uname": "ivan_aivazovsky",
            "url": "/api/v1/users/1.json",
            "email": "ivan.aivazovsky@email.ru "
          }
        }
      },
      "status": "open",
      "owner": {
        "id": 1,
        "name": "Ivan Aivazovsky",
        "uname": "ivan_aivazovsky",
        "url": "/api/v1/users/1.json"
      },
      "assignee": {
        "id": 1,
        "name": "Ivan Aivazovsky",
        "uname": "ivan_aivazovsky",
        "url": "/api/v1/users/1.json"
      },
      "merged_at": "1348170705",
      "mergeable": "true",
      "url": "/api/v1/projects/3/pull_requests/11.json"
    }
  ],
  "url": "/api/v1/projects/3/pull_requests.json"
}

Get a single pull request

GET /api/v1/projects/:project_id/pull_requests/:number.json

Parameters:

project_id
Required Integer identifier of current project.
number
Required Integer identifier of current pull request.

Response:

{
  "pull_request": {
    "number": "serial number",
    "title": "title",
    "to_ref": {
      "ref": "reference",
      "sha": "sha",
      "project": {
        "id": "project id",
        "name": "project name",
        "visibility": "visibility (open/hidden)",
        "fullname": "project fullname",
        "url": "url to project data page",
        "git_url": "path to project git",
        "ssh_url": "path to project git over ssh",
        "maintainer": {
          "id": "user id",
          "uname": "user uname",
          "name": "user name",
          "url": "api user path",
          "email": "user email"
        }
      }
    },
    "from_ref": {
      "ref": "reference",
      "sha": "sha",
      "project": {
        "id": "project id",
        "name": "project name",
        "visibility": "visibility (open/hidden)",
        "fullname": "project fullname",
        "url": "url to project data page",
        "git_url": "path to project git",
        "ssh_url": "path to project git over ssh",
        "maintainer": {
          "id": "user id",
          "uname": "user uname",
          "name": "user name",
          "url": "api user path",
          "email": "user email"
        }
      }
    },
    "status": "pull request status",
    "owner": {
      "id": "user id",
      "uname": "user uname",
      "name": "user name",
      "url": "api user path"
    },
    "assignee": {
      "id": "user id",
      "uname": "user uname",
      "name": "user name",
      "url": "api user path"
    },
    "merged_at": "merged at date and time",
    "mergeable": "can be automatically merged",
    "url": "url to pull request data page",
    "body": "body",
    "closed_at": "closed at date and time",
    "closed_by": {
      "id": "user id",
      "uname": "user uname",
      "name": "user name",
      "url": "api user path"
    },
    "created_at": "created at date and time",
    "updated_at": "updated at date and time",
    "merged_by": {
      "id": "user id",
      "uname": "user uname",
      "name": "user name",
      "url": "api user path"
    }
  }
}

Example:

{
  "pull_request": {
    "number": "11",
    "title": "new feature",
    "to_ref": {
      "ref": "update-version",
      "sha": "3d1468bbb339c8b59234a5bbc35dedf3d89c2043",
      "project": {
        "id": 666,
        "name": "evil_tools",
        "visibility": "open",
        "fullname": "abf/evil_tools",
        "url": "/api/v1/projects/666.json",
        "git_url": "https:/ivan@abf.rosalinux.ru/jaroslav_garkin/hwinfo.git",
        "ssh_url": "git@abf.rosalinux.ru:jaroslav_garkin/hwinfo.git",
        "maintainer": {
          "id": 1,
          "name": "Ivan Aivazovsky",
          "uname": "ivan_aivazovsky",
          "url": "/api/v1/users/1.json",
          "email": "ivan.aivazovsky@email.ru "
        }
      }
    },
    "from_ref": {
      "ref": "update-rails",
      "sha": "3d1468bbb339c8b59234a5bbc35dedf3d89c2043",
      "project": {
        "id": 666,
        "name": "evil_tools",
        "visibility": "open",
        "fullname": "abf/evil_tools",
        "url": "/api/v1/projects/666.json",
        "git_url": "https:/ivan@abf.rosalinux.ru/jaroslav_garkin/hwinfo.git",
        "ssh_url": "git@abf.rosalinux.ru:jaroslav_garkin/hwinfo.git",
        "maintainer": {
          "id": 1,
          "name": "Ivan Aivazovsky",
          "uname": "ivan_aivazovsky",
          "url": "/api/v1/users/1.json",
          "email": "ivan.aivazovsky@email.ru "
        }
      }
    },
    "status": "open",
    "owner": {
      "id": 1,
      "name": "Ivan Aivazovsky",
      "uname": "ivan_aivazovsky",
      "url": "/api/v1/users/1.json"
    },
    "assignee": {
      "id": 1,
      "name": "Ivan Aivazovsky",
      "uname": "ivan_aivazovsky",
      "url": "/api/v1/users/1.json"
    },
    "merged_at": "1348170705",
    "mergeable": "true",
    "url": "/api/v1/projects/3/pull_requests/11.json",
    "body": "new cool feature for us",
    "closed_at": "1348170705",
    "closed_by": {
      "id": 1,
      "name": "Ivan Aivazovsky",
      "uname": "ivan_aivazovsky",
      "url": "/api/v1/users/1.json"
    },
    "created_at": "1348168705",
    "updated_at": "1348170705",
    "merged_by": {
      "id": 1,
      "name": "Ivan Aivazovsky",
      "uname": "ivan_aivazovsky",
      "url": "/api/v1/users/1.json"
    }
  }
}

Create a pull request

Any authenticated user with read access to a project can create a pull request.

POST /api/v1/projects/:id/pull_requests.json

Input

title
Required String
body
Required String
assignee_id
Optional Integer - Id for the user that this pull request should be assigned to. NOTE: Only users with push access can set the assignee for pull request. The assignee is silently dropped otherwise.
to_ref
Required String the branch (or git ref) you want your changes pulled into. This should be an existing branch on the current repository. You cannot submit a pull request to one repo that requests a merge to a base of another repo.
from_project_id
_Optional Integer Identifier project where your changes are implemented. Default current project.
from_ref
Required String the branch (or git ref) where your changes are implemented.

Request:

{
  "pull_request": {
    "title": "fix security bug",
    "body": "fixed at 123456",
    "assignee_id": 15,
    "to_ref": "master",
    "from_project_id": 93862,
    "from_ref": "new_branch"
  }
}

Response:

{
  "pull_request": {
    "number": "pull request number (null if failed)",
    "message": "success or fail message"
  }
}

Examples:

{
  "pull_request": {
    "number": 12,
    "message": "Pull request has been created successfully"
  }
}

Update a single pull request

PUT /api/v1/projects/:id/pull_requests/:number.json

Parameters:

id
Required Integer identifier of current project.
number
Required Integer identifier of current pull request.

Input:

title
Optional String
body
Optional String
assignee_id
Optional Integer - Identifier for the user that this pull request should be assigned to.
status
Optional String - State of the pull request: closed or reopen.

Request:

{
  "pull_request": {
    "title": "fix security bug",
    "body": "fixed at 123456",
    "status": "closed",
    "assignee_id": 15
  }
}

Response:

{
  "pull_request": {
    "number": "pull request number (null if failed)",
    "message": "success or fail message"
  }
}

Example:

{
  "pull_request": {
    "number": 12,
    "message": "Pull request has been updated successfully"
  }
}

List commits on a pull request

GET /api/v1/projects/:id/pull_requests/:number/commits.json

Parameters:

id
Required Integer identifier of current project.
number
Required Integer identifier of current pull request.

Response:

{
  "commits": [
    {
      "sha": "commit sha",
      "https_url": "commit url",
      "author": {
        "name": "author name",
        "email": "author email",
        "date": "authored date"
      },
      "committer": {
        "name": "committer name",
        "email": "committer email",
        "date": "committed date"
      },
      "message": "Fix all the bugs",
      "tree": {
        "sha": "commit sha",
        "https_url": "tree url"
      },
      "parents": [
        {
          "sha": "commit sha",
          "https_url": "tree url"
        }
      ]
    }
  ]
}

Example:

{
  "commits": [
    {
      "sha": "4c2553a5a339c8b59234a5bbc35dedf3d89c2043",
      "https_url": "https://abf.rosalinux.ru/abf/rosa-build/commit/4c2553a5a339c8b59234a5bbc35dedf3d89c2043",
      "author": {
        "name": "abf",
        "email": "abf@test.ru",
        "date": "1348168705"
      },
      "committer": {
        "name": "abf",
        "email": "abf@test.ru",
        "date": "1348168705"
      },
      "message": "Fix all the bugs",
      "tree": {
        "sha": "4c2553a5a339c8b59234a5bbc35dedf3d89c2043",
        "https_url": "https://abf.rosalinux.ru/abf/rosa-build/tree/4c2553a5a339c8b59234a5bbc35dedf3d89c2043"
      },
      "parents": [
        {
          "sha": "20056fbc319722cc64cf7e718b22607693e7f0b0",
          "https_url": "https://abf.rosalinux.ru/abf/rosa-build/commit/20056fbc319722cc64cf7e718b22607693e7f0b0"
        }
      ]
    }
  ]
}

List pull requests files

GET /api/v1/projects/:id/pull_requests/:number/files.json

Parameters:

id
Required Integer identifier of current project.
number
Required Integer identifier of current pull request.

Response:

{
  "files": [
    {
      "sha": "sha",
      "filename": "file name",
      "status": "file status",
      "additions": "additional lines count",
      "deletions": "deletions lines count",
      "changes": "total lines changes",
      "blob_https_url": "blob url",
      "raw_https_url": "raw file url"
    }
  ]
}

Example:

{
  "files": [
    {
      "sha": "473cca87b339c8b59234a5bbc35dedf3d89c2043",
      "filename": "test.log",
      "status": "added",
      "additions": "42",
      "deletions": "24",
      "changes": "66",
      "blob_https_url": "https://abf.rosalinux.ru/abf/rosa-build/blob/master/Gemfile",
      "raw_https_url": "https://abf.rosalinux.ru/abf/rosa-build/raw/master/Gemfile"
    }
  ]
}

Merge a single pull request

PUT /api/v1/projects/:id/pull_requests/:number/merge.json

Parameters:

id
Required Integer identifier of current project.
number
Required Integer identifier of current pull request.

Input:

commit_message
Optional string the message that will be used for the merge commit

Request:

{
  "pull_request": {
    "commit_message": "commit message"
  }
}

Response:

{
  "pull_request": {
    "number": "pull request number (null if failed)",
    "message": "success or fail message"
  }
}

Example:

{
  "pull_request": {
    "number": 12,
    "message": "Pull request has been merged successfully"
  }
}