The GitHub Pull Requests API lets you create, list, update, and merge pull requests in a repository. It provides endpoints for managing pull request reviews, review comments, review requests, and merge operations. You can also check mergeability, list commits and changed files, and manage draft pull requests.
openapi: 3.1.0
info:
version: 1.1.4
title: github-repos-api
description: |-
Use the REST API to create, manage and control the workflow of public and
private GitHub repositories.
license:
name: MIT
url: https://spdx.org/licenses/MIT
termsOfService: https://docs.github.com/articles/github-terms-of-service
contact:
name: Support
url: https://support.github.com/contact
servers:
- url: '{protocol}://{hostname}'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: api.github.com
protocol:
description: Self-hosted Enterprise Server protocol
default: https
externalDocs:
description: GitHub Enterprise Developer Docs
url: https://docs.github.com/[email protected]/rest/
tags:
- name: All
- name: Branches
- name: Checks
- name: Comment
- name: Comments
- name: Commits
- name: Create
- name: Delete
- name: Dismiss
- name: Files
- name: Get
- name: Lists
- name: Merge
- name: Merged
- name: Pending
- name: Pull
- name: Reactions
- name: Remove
- name: Reply
- name: Repositories
description: Source control repositories.
- name: Requested
- name: Requests
- name: Reviewers
- name: Reviews
- name: Submit
- name: Update
paths:
/repos/{owner}/{repo}/pulls:
get:
summary: GitHub List Pull Requests
description: |-
Lists pull requests in a specified repository.
Draft pull requests are available in public repositories with GitHub
Free and GitHub Free for organizations, GitHub Pro, and legacy per-repository billing
plans, and in public and private repositories with GitHub Team and GitHub Enterprise
Cloud. For more information, see [GitHub's products](https://docs.github.com/[email protected]/github/getting-started-with-github/githubs-products)
in the GitHub Help documentation.
This endpoint supports the following custom media types. For more information, see "[Media types](https://docs.github.com/[email protected]/rest/using-the-rest-api/getting-started-with-the-rest-api#media-types)."
- **`application/vnd.github.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.text+json`**: Returns a text only representation of the markdown body. Response will include `body_text`.
- **`application/vnd.github.html+json`**: Returns HTML rendered from the body's markdown. Response will include `body_html`.
- **`application/vnd.github.full+json`**: Returns raw, text, and HTML representations. Response will include `body`, `body_text`, and `body_html`.
- **`application/vnd.github.diff`**: For more information, see "[git-diff](https://git-scm.com/docs/git-diff)" in the Git documentation. If a diff is corrupt, contact us through the [GitHub Support portal](https://support.github.com/). Include the repository name and pull request ID in your message.
- **`application/vnd.github.patch`**: For more information, see "[git-format-patch](https://git-scm.com/docs/git-format-patch)" in the Git documentation.
tags:
- Lists
- Pull
- Requests
operationId: listPullRequests
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/pulls/pulls#list-pull-requests
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- name: state
description: Either `open`, `closed`, or `all` to filter by state.
in: query
required: false
schema:
type: string
enum:
- open
- closed
- all
default: open
example: open
- name: head
description: |-
Filter pulls by head user or head organization and branch name in the format of `user:ref-name` or `organization:ref-name`. For example: `github:new-script-format` or `octocat:test-branch`.
in: query
required: false
schema:
type: string
example: example_value
- name: base
description: 'Filter pulls by base branch name. Example: `gh-pages`.'
in: query
required: false
schema:
type: string
example: example_value
- name: sort
description: |-
What to sort results by. `popularity` will sort by the number of comments. `long-running` will sort by date created and will limit the results to pull requests that have been open for more than a month and have had activity within the past month.
in: query
required: false
schema:
type: string
enum:
- created
- updated
- popularity
- long-running
default: created
example: created
- name: direction
description: |-
The direction of the sort. Default: `desc` when sort is `created` or sort is not specified, otherwise `asc`.
in: query
required: false
schema:
type: string
enum:
- asc
- desc
example: asc
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/pull-request-simple'
examples:
default:
$ref: '#/components/examples/pull-request-simple-items'
headers:
Link:
$ref: '#/components/headers/link'
'304':
$ref: '#/components/responses/not_modified'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: pulls
subcategory: pulls
x-api-evangelist-certified: '2025-07-16'
x-api-naftiko-published: '2025-07-25'
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: GitHub Create Pull Request
description: |-
Draft pull requests are available in public repositories with GitHub Free and GitHub Free for organizations, GitHub Pro, and legacy per-repository billing plans, and in public and private repositories with GitHub Team and GitHub Enterprise Cloud. For more information, see [GitHub's products](https://docs.github.com/[email protected]/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.
To open or update a pull request in a public repository, you must have write access to the head or the source branch. For organization-owned repositories, you must be a member of the organization that owns the repository to open or update a pull request.
This endpoint triggers [notifications](https://docs.github.com/[email protected]/github/managing-subscriptions-and-notifications-on-github/about-notifications). Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see "[Rate limits for the API](https://docs.github.com/[email protected]/rest/overview/rate-limits-for-the-rest-api#about-secondary-rate-limits)" and "[Best practices for using the REST API](https://docs.github.com/[email protected]/rest/guides/best-practices-for-using-the-rest-api)."
This endpoint supports the following custom media types. For more information, see "[Media types](https://docs.github.com/[email protected]/rest/using-the-rest-api/getting-started-with-the-rest-api#media-types)."
- **`application/vnd.github.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.text+json`**: Returns a text only representation of the markdown body. Response will include `body_text`.
- **`application/vnd.github.html+json`**: Returns HTML rendered from the body's markdown. Response will include `body_html`.
- **`application/vnd.github.full+json`**: Returns raw, text, and HTML representations. Response will include `body`, `body_text`, and `body_html`.
- **`application/vnd.github.diff`**: For more information, see "[git-diff](https://git-scm.com/docs/git-diff)" in the Git documentation. If a diff is corrupt, contact us through the [GitHub Support portal](https://support.github.com/). Include the repository name and pull request ID in your message.
tags:
- Create
- Pull
- Requests
operationId: createPullRequest
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/pulls/pulls#create-a-pull-request
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title:
type: string
description: |-
The title of the new pull request. Required unless `issue` is specified.
head:
type: string
description: |-
The name of the branch where your changes are implemented. For cross-repository pull requests in the same network, namespace `head` with a user like this: `username:branch`.
head_repo:
type: string
description: |-
The name of the repository where the changes in the pull request were made. This field is required for cross-repository pull requests if both repositories are owned by the same organization.
format: repo.nwo
example: octo-org/octo-repo
base:
type: string
description: |-
The name of the branch you want the changes pulled into. This should be an existing branch on the current repository. You cannot submit a pull request to one repository that requests a merge to a base of another repository.
body:
type: string
description: The contents of the pull request.
maintainer_can_modify:
type: boolean
description: |-
Indicates whether [maintainers can modify](https://docs.github.com/[email protected]/articles/allowing-changes-to-a-pull-request-branch-created-from-a-fork/) the pull request.
draft:
type: boolean
description: |-
Indicates whether the pull request is a draft. See "[Draft Pull Requests](https://docs.github.com/[email protected]/articles/about-pull-requests#draft-pull-requests)" in the GitHub Help documentation to learn more.
issue:
type: integer
format: int64
example: 1
description: |-
An issue in the repository to convert to a pull request. The issue title, body, and comments will become the title, body, and comments on the new pull request. Required unless `title` is specified.
required:
- head
- base
examples:
default:
value:
title: Amazing new feature
body: Please pull these awesome changes in!
head: octocat:new-feature
base: master
responses:
'201':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/pull-request'
examples:
default:
$ref: '#/components/examples/pull-request'
headers:
Location:
example: https://api.github.com/repos/octocat/Hello-World/pulls/1347
schema:
type: string
'403':
$ref: '#/components/responses/forbidden'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
triggersNotification: true
githubCloudOnly: false
enabledForGitHubApps: true
category: pulls
subcategory: pulls
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/pulls/comments:
get:
summary: GitHub List Review Comments in Repository
description: |-
Lists review comments for all pull requests in a repository. By default,
review comments are in ascending order by ID.
This endpoint supports the following custom media types. For more information, see "[Media types](https://docs.github.com/[email protected]/rest/using-the-rest-api/getting-started-with-the-rest-api#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`.
tags:
- Comments
- Lists
- Repositories
- Reviews
operationId: listReviewCommentsInRepository
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/pulls/comments#list-review-comments-in-a-repository
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- name: sort
in: query
required: false
schema:
type: string
enum:
- created
- updated
- created_at
example: created
- name: direction
description: The direction to sort results. Ignored without `sort` parameter.
in: query
required: false
schema:
type: string
enum:
- asc
- desc
example: asc
- $ref: '#/components/parameters/since'
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/pull-request-review-comment'
examples:
default:
$ref: '#/components/examples/pull-request-review-comment-items'
headers:
Link:
$ref: '#/components/headers/link'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: pulls
subcategory: comments
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/pulls/comments/{comment_id}:
get:
summary: GitHub Get Review Comment for Pull Request
description: |-
Provides details for a specified review comment.
This endpoint supports the following custom media types. For more information, see "[Media types](https://docs.github.com/[email protected]/rest/using-the-rest-api/getting-started-with-the-rest-api#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`.
tags:
- Comment
- Get
- Pull
- Requests
- Reviews
operationId: getReviewCommentForPullRequest
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/pulls/comments#get-a-review-comment-for-a-pull-request
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/comment-id'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/pull-request-review-comment'
examples:
default:
$ref: '#/components/examples/pull-request-review-comment-2'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: pulls
subcategory: comments
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
summary: GitHub Update Review Comment for Pull Request
description: |-
Edits the content of a specified review comment.
This endpoint supports the following custom media types. For more information, see "[Media types](https://docs.github.com/[email protected]/rest/using-the-rest-api/getting-started-with-the-rest-api#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`.
tags:
- Comment
- Pull
- Requests
- Reviews
- Update
operationId: updateReviewCommentForPullRequest
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/pulls/comments#update-a-review-comment-for-a-pull-request
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/comment-id'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
body:
type: string
description: The text of the reply to the review comment.
required:
- body
examples:
default:
value:
body: I like this too!
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/pull-request-review-comment'
examples:
default:
$ref: '#/components/examples/pull-request-review-comment-2'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: pulls
subcategory: comments
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Delete Review Comment for Pull Request
description: Deletes a review comment.
tags:
- Comment
- Delete
- Pull
- Requests
- Reviews
operationId: deleteReviewCommentForPullRequest
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/pulls/comments#delete-a-review-comment-for-a-pull-request
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/comment-id'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'204':
description: Response
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: pulls
subcategory: comments
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/pulls/comments/{comment_id}/reactions:
get:
summary: GitHub List Reactions for Pull Request Review Comment
description: |-
List the reactions to a [pull request review comment](https://docs.github.com/[email protected]/rest/pulls/comments#get-a-review-comment-for-a-pull-request).
tags:
- Comment
- Lists
- Pull
- Reactions
- Requests
- Reviews
operationId: listReactionsForPullRequestReviewComment
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/reactions/reactions#list-reactions-for-a-pull-request-review-comment
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/comment-id'
- name: content
description: |-
Returns a single [reaction type](https://docs.github.com/[email protected]/rest/reactions/reactions#about-reactions). Omit this parameter to list all reactions to a pull request review comment.
in: query
required: false
schema:
type: string
enum:
- '+1'
- '-1'
- laugh
- confused
- heart
- hooray
- rocket
- eyes
example: '+1'
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/reaction'
examples:
default:
$ref: '#/components/examples/reaction-items'
headers:
Link:
$ref: '#/components/headers/link'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: reactions
subcategory: reactions
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: GitHub Create Reaction for Pull Request Review Comment
description: |-
Create a reaction to a [pull request review comment](https://docs.github.com/[email protected]/rest/pulls/comments#get-a-review-comment-for-a-pull-request). response with an HTTP `200` status means that you already added the reaction type to this pull request review comment.
tags:
- Comment
- Create
- Pull
- Reactions
- Requests
- Reviews
operationId: createReactionForPullRequestReviewComment
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/reactions/reactions#create-reaction-for-a-pull-request-review-comment
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/comment-id'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
content:
type: string
description: |-
The [reaction type](https://docs.github.com/[email protected]/rest/reactions/reactions#about-reactions) to add to the pull request review comment.
enum:
- '+1'
- '-1'
- laugh
- confused
- heart
- hooray
- rocket
- eyes
required:
- content
examples:
default:
value:
content: heart
responses:
'200':
description: Reaction exists
content:
application/json:
schema:
$ref: '#/components/schemas/reaction'
examples:
default:
$ref: '#/components/examples/reaction'
'201':
description: Reaction created
content:
application/json:
schema:
$ref: '#/components/schemas/reaction'
examples:
default:
$ref: '#/components/examples/reaction'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: reactions
subcategory: reactions
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/pulls/comments/{comment_id}/reactions/{reaction_id}:
delete:
summary: GitHub Delete Pull Request Comment Reaction
description: |-
**Note:** You can also specify a repository by `repository_id` using the route `DELETE /repositories/:repository_id/pulls/comments/:comment_id/reactions/:reaction_id.`
Delete a reaction to a [pull request review comment](https://docs.github.com/[email protected]/rest/pulls/comments#get-a-review-comment-for-a-pull-request).
tags:
- Comment
- Delete
- Pull
- Reactions
- Requests
operationId: deletePullRequestCommentReaction
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/reactions/reactions#delete-a-pull-request-comment-reaction
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/comment-id'
- $ref: '#/components/parameters/reaction-id'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'204':
description: Response
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: reactions
subcategory: reactions
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/pulls/{pull_number}:
get:
summary: GitHub Get Pull Request
description: |-
Draft pull requests are available in public repositories with GitHub Free and GitHub Free for organizations, GitHub Pro, and legacy per-repository billing plans, and in public and private repositories with GitHub Team and GitHub Enterprise Cloud. For more information, see [GitHub's products](https://docs.github.com/[email protected]/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.
Lists details of a pull request by providing its number.
When you get, [create](https://docs.github.com/[email protected]/rest/pulls/pulls/#create-a-pull-request), or [edit](https://docs.github.com/[email protected]/rest/pulls/pulls#update-a-pull-request) a pull request, GitHub Enterprise Server creates a merge commit to test whether the pull request can be automatically m
# --- truncated at 32 KB (345 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-repo-pulls-api-openapi.yml