Sample - GitHub REST API
POST/repos/{owner}/{repo}/pulls/{pull_number}/comments

Create a review comment for a pull request

Creates a review comment on the diff of a specified pull request. To add a regular comment to a pull request timeline, see "Create an issue comment."

If your comment applies to more than one line in the pull request diff, you should use the parameters line, side, and optionally start_line and start_side in your request.

The position parameter is closing down. If you use position, the line, side, start_line, and start_side parameters are not required.

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

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.
  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

3 parameters · 10 body fields
ownerstringrequired
The account owner of the repository. The name is not case sensitive.
repostringrequired
The name of the repository without the `.git` extension. The name is not case sensitive.
pull_numberintegerrequired
The number that identifies the pull request.
bodystringrequired
The text of the review comment.
commit_idstringrequired
The SHA of the commit needing a comment. Not using the latest commit SHA may render your comment outdated if a subsequent commit modifies the line you specify as the `position`.
pathstringrequired
The relative path to the file that necessitates a comment.
positionintegerdeprecatedoptional
**This parameter is closing down. Use `line` instead**. 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.
sidestringoptional
In a split diff view, the side of the diff that the pull request's changes appear on. Can be `LEFT` or `RIGHT`. Use `LEFT` for deletions that appear in red. Use `RIGHT` for additions that appear in green or unchanged lines that appear in white and are shown for context. For a multi-line comment, side represents whether the last line of the comment range is a deletion or addition. For more information, see "[Diff view options](https://docs.github.com/articles/about-comparing-branches-in-pull-requests#diff-view-options)" in the GitHub Help documentation.
Allowed:LEFTRIGHT
lineintegeroptional
**Required unless using `subject_type:file`**. The line of the blob in the pull request diff that the comment applies to. For a multi-line comment, the last line of the range that your comment applies to.
start_lineintegeroptional
**Required when using multi-line comments unless using `in_reply_to`**. The `start_line` is the first line in the pull request diff that your multi-line comment applies to. To learn more about multi-line comments, see "[Commenting on a pull request](https://docs.github.com/articles/commenting-on-a-pull-request#adding-line-comments-to-a-pull-request)" in the GitHub Help documentation.
start_sidestringoptional
**Required when using multi-line comments unless using `in_reply_to`**. The `start_side` is the starting side of the diff that the comment applies to. Can be `LEFT` or `RIGHT`. To learn more about multi-line comments, see "[Commenting on a pull request](https://docs.github.com/articles/commenting-on-a-pull-request#adding-line-comments-to-a-pull-request)" in the GitHub Help documentation. See `side` in this table for additional context.
Allowed:LEFTRIGHTside
in_reply_tointegeroptional
The ID of the review comment to reply to. To find the ID of a review comment with ["List review comments on a pull request"](#list-review-comments-on-a-pull-request). When specified, all parameters other than `body` in the request body are ignored.
subject_typestringoptional
The level at which the comment is targeted.
Allowed:linefile

3 status codes
201Response
urlstringrequired
URL for the pull request review comment
pull_request_review_idintegerrequired
The ID of the pull request review to which the comment belongs.
idintegerrequired
The ID of the pull request review comment.
node_idstringrequired
The node ID of the pull request review comment.
diff_hunkstringrequired
The diff of the line that the comment refers to.
pathstringrequired
The relative path of the file to which the comment applies.
positionintegeroptional
The line index in the diff to which the comment applies. This field is closing down; use `line` instead.
original_positionintegeroptional
The index of the original line in the diff to which the comment applies. This field is closing down; use `original_line` instead.
commit_idstringrequired
The SHA of the commit to which the comment applies.
original_commit_idstringrequired
The SHA of the original commit to which the comment applies.
in_reply_to_idintegeroptional
The comment ID to reply to.
userobjectrequired
A GitHub user.
bodystringrequired
The text of the comment.
created_atstringrequired
updated_atstringrequired
html_urlstringrequired
HTML URL for the pull request review comment.
pull_request_urlstringrequired
URL for the pull request that the review comment belongs to.
author_associationstringrequired
How the author is associated with the repository.
Allowed:COLLABORATORCONTRIBUTORFIRST_TIMERFIRST_TIME_CONTRIBUTORMANNEQUINMEMBERNONEOWNER
_linksobjectrequired
start_lineintegeroptional
The first line of the range for a multi-line comment.
original_start_lineintegeroptional
The first line of the range for a multi-line comment.
start_sidestringoptional
The side of the first line of the range for a multi-line comment.
Allowed:LEFTRIGHTDefault:RIGHT
lineintegeroptional
The line of the blob to which the comment applies. The last line of the range for a multi-line comment
original_lineintegeroptional
The line of the blob to which the comment applies. The last line of the range for a multi-line comment
sidestringoptional
The side of the diff to which the comment applies. The side of the last line of the range for a multi-line comment
Allowed:LEFTRIGHTDefault:RIGHT
subject_typestringoptional
The level at which the comment is targeted, can be a diff line or a file.
Allowed:linefile
reactionsobjectoptional
body_htmlstringoptional
body_textstringoptional
403Forbidden
messagestringoptional
documentation_urlstringoptional
urlstringoptional
statusstringoptional
422Validation failed, or the endpoint has been spammed.
messagestringrequired
documentation_urlstringrequired
errorsarray<object>optional

Error handling

A 403 is returned: Forbidden. A 422 is returned: Validation failed, or the endpoint has been spammed.