Skip to main content

Pull request reviews

About the Pull request reviews API

Pull Request Reviews are groups of pull request review comments on a pull request, grouped together with a state and optional body comment.

List reviews for a pull request

Works with GitHub Apps

The list of reviews returns in chronological order.

Parameters

Headers
Name, Type, Description
acceptstring

Setting to application/vnd.github.v3+json is recommended.

Path parameters
Name, Type, Description
ownerstringRequired

The account owner of the repository. The name is not case sensitive.

repostringRequired

The name of the repository. The name is not case sensitive.

pull_numberintegerRequired

The number that identifies the pull request.

Query parameters
Name, Type, Description
per_pageinteger

The number of results per page (max 100).

Default: 30

pageinteger

Page number of the results to fetch.

Default: 1

HTTP response status codes

Status codeDescription
200

The list of reviews returns in chronological order.

Code samples

get/repos/{owner}/{repo}/pulls/{pull_number}/reviews
curl \ -H "Accept: application/vnd.github.v3+json" \ https://api.github.com/repos/OWNER/REPO/pulls/PULL_NUMBER/reviews

The list of reviews returns in chronological order.

Status: 200
[ { "id": 80, "node_id": "MDE3OlB1bGxSZXF1ZXN0UmV2aWV3ODA=", "user": { "login": "octocat", "id": 1, "node_id": "MDQ6VXNlcjE=", "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "", "url": "https://api.github.com/users/octocat", "html_url": "https://github.com/octocat", "followers_url": "https://api.github.com/users/octocat/followers", "following_url": "https://api.github.com/users/octocat/following{/other_user}", "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}", "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", "organizations_url": "https://api.github.com/users/octocat/orgs", "repos_url": "https://api.github.com/users/octocat/repos", "events_url": "https://api.github.com/users/octocat/events{/privacy}", "received_events_url": "https://api.github.com/users/octocat/received_events", "type": "User", "site_admin": false }, "body": "Here is the body for the review.", "state": "APPROVED", "html_url": "https://github.com/octocat/Hello-World/pull/12#pullrequestreview-80", "pull_request_url": "https://api.github.com/repos/octocat/Hello-World/pulls/12", "_links": { "html": { "href": "https://github.com/octocat/Hello-World/pull/12#pullrequestreview-80" }, "pull_request": { "href": "https://api.github.com/repos/octocat/Hello-World/pulls/12" } }, "submitted_at": "2019-11-17T17:43:43Z", "commit_id": "ecdd80bb57125d7ba9641ffaa4d7d2c19d3f3091", "author_association": "COLLABORATOR" } ]

Create a review for a pull request

Works with GitHub Apps

This endpoint triggers notifications. Creating content too quickly using this endpoint may result in secondary rate limiting. See "Secondary rate limits" and "Dealing with secondary rate limits" for details.

Pull request reviews created in the PENDING state do not include the submitted_at property in the response.

Note: To comment on a specific line in a file, you need to first determine the position of that line in the diff. The GitHub REST API v3 offers the application/vnd.github.v3.diff media type. To see a pull request diff, add this media type to the Accept header of a call to the single pull request endpoint.

The position value equals the number of lines down from the first "@@" hunk header in the file you want to add a comment. The line just below the "@@" line is position 1, the next line is position 2, and so on. The position in the diff continues to increase through lines of whitespace and additional hunks until the beginning of a new file.

Parameters

Headers
Name, Type, Description
acceptstring

Setting to application/vnd.github.v3+json is recommended.

Path parameters
Name, Type, Description
ownerstringRequired

The account owner of the repository. The name is not case sensitive.

repostringRequired

The name of the repository. The name is not case sensitive.

pull_numberintegerRequired

The number that identifies the pull request.

Body parameters
Name, Type, Description
commit_idstring

The SHA of the commit that needs a review. Not using the latest commit SHA may render your review comment outdated if a subsequent commit modifies the line you specify as the position. Defaults to the most recent commit in the pull request when you do not specify a value.

bodystring

Required when using REQUEST_CHANGES or COMMENT for the event parameter. The body text of the pull request review.

eventstring

The review action you want to perform. The review actions include: APPROVE, REQUEST_CHANGES, or COMMENT. By leaving this blank, you set the review action state to PENDING, which means you will need to submit the pull request review when you are ready.

Can be one of: APPROVE, REQUEST_CHANGES, COMMENT

commentsarray of objects

Use the following table to specify the location, destination, and contents of the draft review comment.

Name, Type, Description
pathstringRequired

The relative path to the file that necessitates a review comment.

positioninteger

The position in the diff where you want to add a review comment. Note this value is not the same as the line number in the file. For help finding the position value, read the note below.

bodystringRequired

Text of the review comment.

lineinteger
sidestring
start_lineinteger
start_sidestring

HTTP response status codes

Status codeDescription
200

OK

403

Forbidden

422

Validation failed

Code samples

post/repos/{owner}/{repo}/pulls/{pull_number}/reviews
curl \ -X POST \ -H "Accept: application/vnd.github.v3+json" \ https://api.github.com/repos/OWNER/REPO/pulls/PULL_NUMBER/reviews \ -d '{"commit_id":"ecdd80bb57125d7ba9641ffaa4d7d2c19d3f3091","body":"This is close to perfect! Please address the suggested inline change.","event":"REQUEST_CHANGES","comments":[{"path":"file.md","position":6,"body":"Please add more information here, and fix this typo."}]}'

Response

Status: 200
{ "id": 80, "node_id": "MDE3OlB1bGxSZXF1ZXN0UmV2aWV3ODA=", "user": { "login": "octocat", "id": 1, "node_id": "MDQ6VXNlcjE=", "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "", "url": "https://api.github.com/users/octocat", "html_url": "https://github.com/octocat", "followers_url": "https://api.github.com/users/octocat/followers", "following_url": "https://api.github.com/users/octocat/following{/other_user}", "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}", "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", "organizations_url": "https://api.github.com/users/octocat/orgs", "repos_url": "https://api.github.com/users/octocat/repos", "events_url": "https://api.github.com/users/octocat/events{/privacy}", "received_events_url": "https://api.github.com/users/octocat/received_events", "type": "User", "site_admin": false }, "body": "This is close to perfect! Please address the suggested inline change.", "state": "CHANGES_REQUESTED", "html_url": "https://github.com/octocat/Hello-World/pull/12#pullrequestreview-80", "pull_request_url": "https://api.github.com/repos/octocat/Hello-World/pulls/12", "_links": { "html": { "href": "https://github.com/octocat/Hello-World/pull/12#pullrequestreview-80" }, "pull_request": { "href": "https://api.github.com/repos/octocat/Hello-World/pulls/12" } }, "submitted_at": "2019-11-17T17:43:43Z", "commit_id": "ecdd80bb57125d7ba9641ffaa4d7d2c19d3f3091", "author_association": "COLLABORATOR" }

Get a review for a pull request

Works with GitHub Apps

Parameters

Headers
Name, Type, Description
acceptstring

Setting to application/vnd.github.v3+json is recommended.

Path parameters
Name, Type, Description
ownerstringRequired

The account owner of the repository. The name is not case sensitive.

repostringRequired

The name of the repository. The name is not case sensitive.

pull_numberintegerRequired

The number that identifies the pull request.

review_idintegerRequired

The unique identifier of the review.

HTTP response status codes

Status codeDescription
200

OK

404

Resource not found

Code samples

get/repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}
curl \ -H "Accept: application/vnd.github.v3+json" \ https://api.github.com/repos/OWNER/REPO/pulls/PULL_NUMBER/reviews/REVIEW_ID

Response

Status: 200
{ "id": 80, "node_id": "MDE3OlB1bGxSZXF1ZXN0UmV2aWV3ODA=", "user": { "login": "octocat", "id": 1, "node_id": "MDQ6VXNlcjE=", "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "", "url": "https://api.github.com/users/octocat", "html_url": "https://github.com/octocat", "followers_url": "https://api.github.com/users/octocat/followers", "following_url": "https://api.github.com/users/octocat/following{/other_user}", "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}", "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", "organizations_url": "https://api.github.com/users/octocat/orgs", "repos_url": "https://api.github.com/users/octocat/repos", "events_url": "https://api.github.com/users/octocat/events{/privacy}", "received_events_url": "https://api.github.com/users/octocat/received_events", "type": "User", "site_admin": false }, "body": "Here is the body for the review.", "state": "APPROVED", "html_url": "https://github.com/octocat/Hello-World/pull/12#pullrequestreview-80", "pull_request_url": "https://api.github.com/repos/octocat/Hello-World/pulls/12", "_links": { "html": { "href": "https://github.com/octocat/Hello-World/pull/12#pullrequestreview-80" }, "pull_request": { "href": "https://api.github.com/repos/octocat/Hello-World/pulls/12" } }, "submitted_at": "2019-11-17T17:43:43Z", "commit_id": "ecdd80bb57125d7ba9641ffaa4d7d2c19d3f3091", "author_association": "COLLABORATOR" }

Update a review for a pull request

Works with GitHub Apps

Update the review summary comment with new text.

Parameters

Headers
Name, Type, Description
acceptstring

Setting to application/vnd.github.v3+json is recommended.

Path parameters
Name, Type, Description
ownerstringRequired

The account owner of the repository. The name is not case sensitive.

repostringRequired

The name of the repository. The name is not case sensitive.

pull_numberintegerRequired

The number that identifies the pull request.

review_idintegerRequired

The unique identifier of the review.

Body parameters
Name, Type, Description
bodystringRequired

The body text of the pull request review.

HTTP response status codes

Status codeDescription
200

OK

422

Validation failed

Code samples

put/repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}
curl \ -X PUT \ -H "Accept: application/vnd.github.v3+json" \ https://api.github.com/repos/OWNER/REPO/pulls/PULL_NUMBER/reviews/REVIEW_ID \ -d '{"body":"This is close to perfect! Please address the suggested inline change. And add more about this."}'

Response

Status: 200
{ "id": 80, "node_id": "MDE3OlB1bGxSZXF1ZXN0UmV2aWV3ODA=", "user": { "login": "octocat", "id": 1, "node_id": "MDQ6VXNlcjE=", "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "", "url": "https://api.github.com/users/octocat", "html_url": "https://github.com/octocat", "followers_url": "https://api.github.com/users/octocat/followers", "following_url": "https://api.github.com/users/octocat/following{/other_user}", "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}", "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", "organizations_url": "https://api.github.com/users/octocat/orgs", "repos_url": "https://api.github.com/users/octocat/repos", "events_url": "https://api.github.com/users/octocat/events{/privacy}", "received_events_url": "https://api.github.com/users/octocat/received_events", "type": "User", "site_admin": false }, "body": "This is close to perfect! Please address the suggested inline change. And add more about this.", "state": "CHANGES_REQUESTED", "html_url": "https://github.com/octocat/Hello-World/pull/12#pullrequestreview-80", "pull_request_url": "https://api.github.com/repos/octocat/Hello-World/pulls/12", "_links": { "html": { "href": "https://github.com/octocat/Hello-World/pull/12#pullrequestreview-80" }, "pull_request": { "href": "https://api.github.com/repos/octocat/Hello-World/pulls/12" } }, "submitted_at": "2019-11-17T17:43:43Z", "commit_id": "ecdd80bb57125d7ba9641ffaa4d7d2c19d3f3091", "author_association": "COLLABORATOR" }

Delete a pending review for a pull request

Works with GitHub Apps

Parameters

Headers
Name, Type, Description
acceptstring

Setting to application/vnd.github.v3+json is recommended.

Path parameters
Name, Type, Description
ownerstringRequired

The account owner of the repository. The name is not case sensitive.

repostringRequired

The name of the repository. The name is not case sensitive.

pull_numberintegerRequired

The number that identifies the pull request.

review_idintegerRequired

The unique identifier of the review.

HTTP response status codes

Status codeDescription
200

OK

404

Resource not found

422

Validation failed

Code samples

delete/repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}
curl \ -X DELETE \ -H "Accept: application/vnd.github.v3+json" \ https://api.github.com/repos/OWNER/REPO/pulls/PULL_NUMBER/reviews/REVIEW_ID

Response

Status: 200
{ "id": 80, "node_id": "MDE3OlB1bGxSZXF1ZXN0UmV2aWV3ODA=", "user": { "login": "octocat", "id": 1, "node_id": "MDQ6VXNlcjE=", "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "", "url": "https://api.github.com/users/octocat", "html_url": "https://github.com/octocat", "followers_url": "https://api.github.com/users/octocat/followers", "following_url": "https://api.github.com/users/octocat/following{/other_user}", "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}", "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", "organizations_url": "https://api.github.com/users/octocat/orgs", "repos_url": "https://api.github.com/users/octocat/repos", "events_url": "https://api.github.com/users/octocat/events{/privacy}", "received_events_url": "https://api.github.com/users/octocat/received_events", "type": "User", "site_admin": false }, "body": "This is close to perfect! Please address the suggested inline change.", "state": "CHANGES_REQUESTED", "html_url": "https://github.com/octocat/Hello-World/pull/12#pullrequestreview-80", "pull_request_url": "https://api.github.com/repos/octocat/Hello-World/pulls/12", "_links": { "html": { "href": "https://github.com/octocat/Hello-World/pull/12#pullrequestreview-80" }, "pull_request": { "href": "https://api.github.com/repos/octocat/Hello-World/pulls/12" } }, "submitted_at": "2019-11-17T17:43:43Z", "commit_id": "ecdd80bb57125d7ba9641ffaa4d7d2c19d3f3091", "author_association": "COLLABORATOR" }

List comments for a pull request review

Works with GitHub Apps

List comments for a specific pull request review.

Parameters

Headers
Name, Type, Description
acceptstring

Setting to application/vnd.github.v3+json is recommended.

Path parameters
Name, Type, Description
ownerstringRequired

The account owner of the repository. The name is not case sensitive.

repostringRequired

The name of the repository. The name is not case sensitive.

pull_numberintegerRequired

The number that identifies the pull request.

review_idintegerRequired

The unique identifier of the review.

Query parameters
Name, Type, Description
per_pageinteger

The number of results per page (max 100).

Default: 30

pageinteger

Page number of the results to fetch.

Default: 1

HTTP response status codes

Status codeDescription
200

OK

404

Resource not found

Code samples

get/repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}/comments
curl \ -H "Accept: application/vnd.github.v3+json" \ https://api.github.com/repos/OWNER/REPO/pulls/PULL_NUMBER/reviews/REVIEW_ID/comments

Response

Status: 200
[ { "url": "https://api.github.com/repos/octocat/Hello-World/pulls/comments/1", "pull_request_review_id": 42, "id": 10, "node_id": "MDI0OlB1bGxSZXF1ZXN0UmV2aWV3Q29tbWVudDEw", "diff_hunk": "@@ -16,33 +16,40 @@ public class Connection : IConnection...", "path": "file1.txt", "position": 1, "original_position": 4, "commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "original_commit_id": "9c48853fa3dc5c1c3d6f1f1cd1f2743e72652840", "in_reply_to_id": 8, "user": { "login": "octocat", "id": 1, "node_id": "MDQ6VXNlcjE=", "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "", "url": "https://api.github.com/users/octocat", "html_url": "https://github.com/octocat", "followers_url": "https://api.github.com/users/octocat/followers", "following_url": "https://api.github.com/users/octocat/following{/other_user}", "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}", "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", "organizations_url": "https://api.github.com/users/octocat/orgs", "repos_url": "https://api.github.com/users/octocat/repos", "events_url": "https://api.github.com/users/octocat/events{/privacy}", "received_events_url": "https://api.github.com/users/octocat/received_events", "type": "User", "site_admin": false }, "body": "Great stuff!", "created_at": "2011-04-14T16:00:49Z", "updated_at": "2011-04-14T16:00:49Z", "html_url": "https://github.com/octocat/Hello-World/pull/1#discussion-diff-1", "pull_request_url": "https://api.github.com/repos/octocat/Hello-World/pulls/1", "author_association": "NONE", "_links": { "self": { "href": "https://api.github.com/repos/octocat/Hello-World/pulls/comments/1" }, "html": { "href": "https://github.com/octocat/Hello-World/pull/1#discussion-diff-1" }, "pull_request": { "href": "https://api.github.com/repos/octocat/Hello-World/pulls/1" } } } ]

Dismiss a review for a pull request

Works with GitHub Apps

Note: To dismiss a pull request review on a protected branch, you must be a repository administrator or be included in the list of people or teams who can dismiss pull request reviews.

Parameters

Headers
Name, Type, Description
acceptstring

Setting to application/vnd.github.v3+json is recommended.

Path parameters
Name, Type, Description
ownerstringRequired

The account owner of the repository. The name is not case sensitive.

repostringRequired

The name of the repository. The name is not case sensitive.

pull_numberintegerRequired

The number that identifies the pull request.

review_idintegerRequired

The unique identifier of the review.

Body parameters
Name, Type, Description
messagestringRequired

The message for the pull request review dismissal

eventstring

HTTP response status codes

Status codeDescription
200

OK

404

Resource not found

422

Validation failed

Code samples

put/repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}/dismissals
curl \ -X PUT \ -H "Accept: application/vnd.github.v3+json" \ https://api.github.com/repos/OWNER/REPO/pulls/PULL_NUMBER/reviews/REVIEW_ID/dismissals

Response

Status: 200
{ "id": 80, "node_id": "MDE3OlB1bGxSZXF1ZXN0UmV2aWV3ODA=", "user": { "login": "octocat", "id": 1, "node_id": "MDQ6VXNlcjE=", "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "", "url": "https://api.github.com/users/octocat", "html_url": "https://github.com/octocat", "followers_url": "https://api.github.com/users/octocat/followers", "following_url": "https://api.github.com/users/octocat/following{/other_user}", "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}", "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", "organizations_url": "https://api.github.com/users/octocat/orgs", "repos_url": "https://api.github.com/users/octocat/repos", "events_url": "https://api.github.com/users/octocat/events{/privacy}", "received_events_url": "https://api.github.com/users/octocat/received_events", "type": "User", "site_admin": false }, "body": "Here is the body for the review.", "state": "DISMISSED", "html_url": "https://github.com/octocat/Hello-World/pull/12#pullrequestreview-80", "pull_request_url": "https://api.github.com/repos/octocat/Hello-World/pulls/12", "_links": { "html": { "href": "https://github.com/octocat/Hello-World/pull/12#pullrequestreview-80" }, "pull_request": { "href": "https://api.github.com/repos/octocat/Hello-World/pulls/12" } }, "submitted_at": "2019-11-17T17:43:43Z", "commit_id": "ecdd80bb57125d7ba9641ffaa4d7d2c19d3f3091", "author_association": "COLLABORATOR" }

Submit a review for a pull request

Works with GitHub Apps

Parameters

Headers
Name, Type, Description
acceptstring

Setting to application/vnd.github.v3+json is recommended.

Path parameters
Name, Type, Description
ownerstringRequired

The account owner of the repository. The name is not case sensitive.

repostringRequired

The name of the repository. The name is not case sensitive.

pull_numberintegerRequired

The number that identifies the pull request.

review_idintegerRequired

The unique identifier of the review.

Body parameters
Name, Type, Description
bodystring

The body text of the pull request review

eventstringRequired

The review action you want to perform. The review actions include: APPROVE, REQUEST_CHANGES, or COMMENT. When you leave this blank, the API returns HTTP 422 (Unrecognizable entity) and sets the review action state to PENDING, which means you will need to re-submit the pull request review using a review action.

Can be one of: APPROVE, REQUEST_CHANGES, COMMENT

HTTP response status codes

Status codeDescription
200

OK

403

Forbidden

404

Resource not found

422

Validation failed

Code samples

post/repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}/events
curl \ -X POST \ -H "Accept: application/vnd.github.v3+json" \ https://api.github.com/repos/OWNER/REPO/pulls/PULL_NUMBER/reviews/REVIEW_ID/events

Response

Status: 200
{ "id": 80, "node_id": "MDE3OlB1bGxSZXF1ZXN0UmV2aWV3ODA=", "user": { "login": "octocat", "id": 1, "node_id": "MDQ6VXNlcjE=", "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "", "url": "https://api.github.com/users/octocat", "html_url": "https://github.com/octocat", "followers_url": "https://api.github.com/users/octocat/followers", "following_url": "https://api.github.com/users/octocat/following{/other_user}", "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}", "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", "organizations_url": "https://api.github.com/users/octocat/orgs", "repos_url": "https://api.github.com/users/octocat/repos", "events_url": "https://api.github.com/users/octocat/events{/privacy}", "received_events_url": "https://api.github.com/users/octocat/received_events", "type": "User", "site_admin": false }, "body": "Here is the body for the review.", "state": "APPROVED", "html_url": "https://github.com/octocat/Hello-World/pull/12#pullrequestreview-80", "pull_request_url": "https://api.github.com/repos/octocat/Hello-World/pulls/12", "_links": { "html": { "href": "https://github.com/octocat/Hello-World/pull/12#pullrequestreview-80" }, "pull_request": { "href": "https://api.github.com/repos/octocat/Hello-World/pulls/12" } }, "submitted_at": "2019-11-17T17:43:43Z", "commit_id": "ecdd80bb57125d7ba9641ffaa4d7d2c19d3f3091", "author_association": "COLLABORATOR" }