Create a review for a pull request

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 are not submitted and therefore do not include the submitted_at property in the response. To create a pending review for a pull request, leave the event parameter blank. For more information about submitting a PENDING review, see "Submit a review for a pull request."

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 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.

curl --location --request POST 'https://api.github.com/repos///pulls//reviews' \ --header 'Content-Type: application/json' \ --data-raw '{ "body": "This is close to perfect! Please address the suggested inline change.", "comments": [ { "body": "Please add more information here, and fix this typo.", "path": "file.md", "position": 6 } ], "commit_id": "ecdd80bb57125d7ba9641ffaa4d7d2c19d3f3091", "event": "REQUEST_CHANGES" }'

{ "_links": { "html": { "href": "string" }, "pull_request": { "href": "string" } }, "author_association": "OWNER", "body": "This looks great.", "body_html": "string", "body_text": "string", "commit_id": "54bb654c9e6025347f57900a4a5c2313a96b8035", "html_url": "https://github.com/octocat/Hello-World/pull/12#pullrequestreview-80", "id": 42, "node_id": "MDE3OlB1bGxSZXF1ZXN0UmV2aWV3ODA=", "pull_request_url": "https://api.github.com/repos/octocat/Hello-World/pulls/12", "state": "CHANGES_REQUESTED", "submitted_at": "2019-08-24T14:15:22Z", "user": { "avatar_url": "https://github.com/images/error/octocat_happy.gif", "email": "string", "events_url": "https://api.github.com/users/octocat/events{/privacy}", "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}", "gravatar_id": "41d064eb2195891e12d0413f63227ea7", "html_url": "https://github.com/octocat", "id": 1, "login": "octocat", "name": "string", "node_id": "MDQ6VXNlcjE=", "organizations_url": "https://api.github.com/users/octocat/orgs", "received_events_url": "https://api.github.com/users/octocat/received_events", "repos_url": "https://api.github.com/users/octocat/repos", "site_admin": true, "starred_at": "\"2020-07-09T00:17:55Z\"", "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", "type": "User", "url": "https://api.github.com/users/octocat" } }

Request

Path Params

owner

string

required

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

repo

string

required

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

pull_number

integer

required

The number that identifies the pull request.

Body Params application/json

body

string

optional

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

comments

array [object {7}]

optional

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

body

string

required

Text of the review comment.

line

integer

optional

Example:

path

string

required

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

position

integer

optional

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.

side

string

optional

Example:

RIGHT

start_line

integer

optional

Example:

start_side

string

optional

Example:

LEFT

commit_id

string

optional

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.

event

enum<string>

optional

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.

Allowed values:

APPROVEREQUEST_CHANGESCOMMENT

Examples

Responses

🟢200Response

application/json

Body

Pull Request Reviews are reviews on pull requests.

_links

object

required

html

object

required

pull_request

object

required

author_association

enum<string>

required

How the author is associated with the repository.

Allowed values:

COLLABORATORCONTRIBUTORFIRST_TIMERFIRST_TIME_CONTRIBUTORMANNEQUINMEMBERNONEOWNER

Example:

OWNER

body

string

required

The text of the review.

Example:

This looks great.

body_html

string

optional

body_text

string

optional

commit_id

string | null

required

A commit SHA for the review. If the commit object was garbage collected or forcibly deleted, then it no longer exists in Git and this value will be null.

Example:

54bb654c9e6025347f57900a4a5c2313a96b8035

html_url

string <uri>

required

Example:

https://github.com/octocat/Hello-World/pull/12#pullrequestreview-80

integer

required

Unique identifier of the review

Example:

node_id

string

required

Example:

MDE3OlB1bGxSZXF1ZXN0UmV2aWV3ODA=

pull_request_url

string <uri>

required

Example:

https://api.github.com/repos/octocat/Hello-World/pulls/12

state

string

required

Example:

CHANGES_REQUESTED

submitted_at

string <date-time>

optional

user

object (Simple User) | null

required

A GitHub user.

avatar_url

string <uri>

required

Example:

https://github.com/images/error/octocat_happy.gif

string | null

optional

events_url

string

required

Example:

https://api.github.com/users/octocat/events{/privacy}

followers_url

string <uri>

required

Example:

https://api.github.com/users/octocat/followers

following_url

string

required

Example:

https://api.github.com/users/octocat/following{/other_user}

gists_url

string

required

Example:

https://api.github.com/users/octocat/gists{/gist_id}

gravatar_id

string | null

required

Example:

41d064eb2195891e12d0413f63227ea7

html_url

string <uri>

required

Example:

https://github.com/octocat

integer

required

Example:

string

required

Example:

octocat

name

string | null

optional

node_id

string

required

Example:

MDQ6VXNlcjE=

organizations_url

string <uri>

required

Example:

https://api.github.com/users/octocat/orgs

received_events_url

string <uri>

required

Example:

https://api.github.com/users/octocat/received_events

repos_url

string <uri>

required

Example:

https://api.github.com/users/octocat/repos

site_admin

boolean

required

starred_at

string

optional

Example:

"2020-07-09T00:17:55Z"

starred_url

string

required

Example:

https://api.github.com/users/octocat/starred{/owner}{/repo}

subscriptions_url

string <uri>

required

Example:

https://api.github.com/users/octocat/subscriptions

type

string

required

Example:

User

url

string <uri>

required

Example:

https://api.github.com/users/octocat

🟠403403

🟠422422