Skip to content
forgit api docs

Create a review for a pull request

POST
/repos/{owner}/{repo}/pulls/{pull_number}/reviews

Creates a review on a specified pull request.

This endpoint triggers notifications. Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see “Rate limits for the API” and “Best practices for using the REST API.”

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. To see a pull request diff, add the application/vnd.github.v3.diff media type to the Accept header of a call to the Get a 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.

This endpoint supports the following custom media types. For more information, see “Media types.”

  • application/vnd.github-commitcomment.raw+json: Returns the raw markdown body. Response will include body. This is the default if you do not pass any specific media type.
  • application/vnd.github-commitcomment.text+json: Returns a text only representation of the markdown body. Response will include body_text.
  • application/vnd.github-commitcomment.html+json: Returns HTML rendered from the body’s markdown. Response will include body_html.
  • application/vnd.github-commitcomment.full+json: Returns raw, text, and HTML representations. Response will include body, body_text, and body_html.

API method documentation

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
owner
required
string

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

repo
required
string

The name of the repository without the .git extension. The name is not case sensitive.

pull_number
required
integer

The number that identifies the pull request.

Request Body

Section titled “ Request Body ”
Media type application/json
object
commit_id

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.

string
body

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

string
event

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.

string
Allowed values: APPROVE REQUEST_CHANGES COMMENT
comments

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

Array<object>
object
path
required

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

string
position

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

integer
body
required

Text of the review comment.

string
line
integer
side
string
start_line
integer
start_side
string
Examples
Example default 
{
  "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."
    }
  ]
}

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Response

Media type application/json
Pull Request Review

Pull Request Reviews are reviews on pull requests.

object
id
required

Unique identifier of the review

integer format: int64
node_id
required
string
user
required
Simple User

A GitHub user.

object
name
string
nullable
email
string
nullable
login
required
string
id
required
integer format: int64
node_id
required
string
avatar_url
required
string format: uri
gravatar_id
required
string
nullable
url
required
string format: uri
html_url
required
string format: uri
followers_url
required
string format: uri
following_url
required
string
gists_url
required
string
starred_url
required
string
subscriptions_url
required
string format: uri
organizations_url
required
string format: uri
repos_url
required
string format: uri
events_url
required
string
received_events_url
required
string format: uri
type
required
string
site_admin
required
boolean
starred_at
string
user_view_type
string
body
required

The text of the review.

string
state
required
string
html_url
required
string format: uri
pull_request_url
required
string format: uri
_links
required
object
html
required
object
href
required
string
pull_request
required
object
href
required
string
submitted_at
string format: date-time
commit_id
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.

string
nullable
body_html
string
body_text
string
author_association
required
author_association

How the author is associated with the repository.

string
Allowed values: COLLABORATOR CONTRIBUTOR FIRST_TIMER FIRST_TIME_CONTRIBUTOR MANNEQUIN MEMBER NONE OWNER
Examples
Example default 
{
  "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"
}

403

Section titled “ 403 ”

Forbidden

Media type application/json
Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}

422

Section titled “ 422 ”

Validation failed, or the endpoint has been spammed.

Media type application/json
Validation Error Simple

Validation Error Simple

object
message
required
string
documentation_url
required
string
errors
Array<string>
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "errors": [
    "example"
  ]
}