Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
version: 1.1.4
title: APIs.io Engineering Platform GitHub v3 REST Pulls API
description: GitHub's v3 REST API.
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?tags=dotcom-rest-api
x-github-plan: ghes
x-github-release: 3.9
servers:
- url: '{protocol}://{hostname}/api/v3'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: HOSTNAME
protocol:
description: Self-hosted Enterprise Server protocol
default: http
tags:
- name: Pulls
description: Interact with GitHub Pull Requests.
paths:
/repos/{owner}/{repo}/pulls:
get:
summary: APIs.io Engineering Platform 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/enterprise-server@3.9/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/enterprise-server@3.9/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`.'
tags:
- Pulls
operationId: pulls/list
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/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
- 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
- name: base
description: 'Filter pulls by base branch name. Example: `gh-pages`.'
in: query
required: false
schema:
type: string
- 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
- 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
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
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
post:
summary: APIs.io Engineering Platform Create a 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/enterprise-server@3.9/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/enterprise-server@3.9/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/enterprise-server@3.9/rest/using-the-rest-api/rate-limits-for-the-rest-api#about-secondary-rate-limits)" and "[Best practices for using the REST API](https://docs.github.com/enterprise-server@3.9/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/enterprise-server@3.9/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`.'
tags:
- Pulls
operationId: pulls/create
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/pulls/pulls#create-a-pull-request
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
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/enterprise-server@3.9/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/enterprise-server@3.9/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
/repos/{owner}/{repo}/pulls/comments:
get:
summary: APIs.io Engineering Platform List review comments in a 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/enterprise-server@3.9/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:
- Pulls
operationId: pulls/list-review-comments-for-repo
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/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
- name: direction
description: The direction to sort results. Ignored without `sort` parameter.
in: query
required: false
schema:
type: string
enum:
- asc
- desc
- $ref: '#/components/parameters/since'
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
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
/repos/{owner}/{repo}/pulls/comments/{comment_id}:
get:
summary: APIs.io Engineering Platform Get a review comment for a 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/enterprise-server@3.9/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:
- Pulls
operationId: pulls/get-review-comment
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/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'
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
patch:
summary: APIs.io Engineering Platform Update a review comment for a 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/enterprise-server@3.9/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:
- Pulls
operationId: pulls/update-review-comment
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/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'
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
delete:
summary: APIs.io Engineering Platform Delete a review comment for a pull request
description: Deletes a review comment.
tags:
- Pulls
operationId: pulls/delete-review-comment
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/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'
responses:
'204':
description: Response
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: pulls
subcategory: comments
/repos/{owner}/{repo}/pulls/{pull_number}:
get:
summary: APIs.io Engineering Platform Get a 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/enterprise-server@3.9/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/enterprise-server@3.9/rest/pulls/pulls/#create-a-pull-request), or [edit](https://docs.github.com/enterprise-server@3.9/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 merged into the base branch. This test commit is not added to the base branch or the head branch. You can review the status of the test commit using the `mergeable` key. For more information, see "[Checking mergeability of pull requests](https://docs.github.com/enterprise-server@3.9/rest/guides/getting-started-with-the-git-database-api#checking-mergeability-of-pull-requests)".
The value of the `mergeable` attribute can be `true`, `false`, or `null`. If the value is `null`, then GitHub Enterprise Server has started a background job to compute the mergeability. After giving the job time to complete, resubmit the request. When the job finishes, you will see a non-`null` value for the `mergeable` attribute in the response. If `mergeable` is `true`, then `merge_commit_sha` will be the SHA of the _test_ merge commit.
The value of the `merge_commit_sha` attribute changes depending on the state of the pull request. Before merging a pull request, the `merge_commit_sha` attribute holds the SHA of the _test_ merge commit. After merging a pull request, the `merge_commit_sha` attribute changes depending on how you merged the pull request:
* If merged as a [merge commit](https://docs.github.com/enterprise-server@3.9/articles/about-merge-methods-on-github/), `merge_commit_sha` represents the SHA of the merge commit.
* If merged via a [squash](https://docs.github.com/enterprise-server@3.9/articles/about-merge-methods-on-github/#squashing-your-merge-commits), `merge_commit_sha` represents the SHA of the squashed commit on the base branch.
* If [rebased](https://docs.github.com/enterprise-server@3.9/articles/about-merge-methods-on-github/#rebasing-and-merging-your-commits), `merge_commit_sha` represents the commit that the base branch was updated to.
Pass the appropriate [media type](https://docs.github.com/enterprise-server@3.9/rest/using-the-rest-api/getting-started-with-the-rest-api#media-types) to fetch diff and patch formats.
This endpoint supports the following custom media types. For more information, see "[Media types](https://docs.github.com/enterprise-server@3.9/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:
- Pulls
operationId: pulls/get
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/pulls/pulls#get-a-pull-request
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/pull-number'
responses:
'200':
description: Pass the appropriate [media type](https://docs.github.com/enterprise-server@3.9/rest/using-the-rest-api/getting-started-with-the-rest-api#media-types) to fetch diff and patch formats.
content:
application/json:
schema:
$ref: '#/components/schemas/pull-request'
examples:
default:
$ref: '#/components/examples/pull-request'
'304':
$ref: '#/components/responses/not_modified'
'404':
$ref: '#/components/responses/not_found'
'406':
$ref: '#/components/responses/unacceptable'
'500':
$ref: '#/components/responses/internal_error'
'503':
$ref: '#/components/responses/service_unavailable'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: pulls
subcategory: pulls
patch:
summary: APIs.io Engineering Platform Update a 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/enterprise-server@3.9/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 supports the following custom media types. For more information, see "[Media types](https://docs.github.com/enterprise-server@3.9/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`.'
tags:
- Pulls
operationId: pulls/update
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/pulls/pulls#update-a-pull-request
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/pull-number'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
title:
type: string
description: The title of the pull request.
body:
type: string
description: The contents of the pull request.
state:
type: string
description: State of this Pull Request. Either `open` or `closed`.
enum:
- open
- closed
base:
type: string
description: The name of the branch you want your changes pulled into. This should be an existing branch on the current repository. You cannot update the base branch on a pull request to point to another repository.
maintainer_can_modify:
type: boolean
description: Indicates whether [maintainers can modify](https://docs.github.com/enterprise-server@3.9/articles/allowing-changes-to-a-pull-request-branch-created-from-a-fork/) the pull request.
examples:
default:
value:
title: new title
body: updated body
state: open
base: master
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/pull-request'
examples:
default:
$ref: '#/components/examples/pull-request'
'422':
$ref: '#/components/responses/validation_failed'
'403':
$ref: '#/components/responses/forbidden'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: pulls
subcategory: pulls
/repos/{owner}/{repo}/pulls/{pull_number}/comments:
get:
summary: APIs.io Engineering Platform List review comments on a pull request
description: 'Lists all review comments for a specified pull request. 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/enterprise-server@3.9/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:
- Pulls
operationId: pulls/list-review-comments
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/pulls/comments#list-review-comments-on-a-pull-request
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/pull-number'
- $ref: '#/components/parameters/sort'
- name: direction
description: The direction to sort results. Ignored without `sort` parameter.
in: query
required: false
schema:
type: string
enum:
- asc
- desc
- $ref: '#/components/parameters/since'
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
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
post:
summary: APIs.io Engineering Platform Create a review comment for a pull request
description: '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](https://docs.github.com/enterprise-server@3.9/rest/issues/comments#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 deprecated. If you use `position`, the `line`, `side`, `start_line`, and `start_side` parameters are not required.
This endpoint triggers [notifications](https://docs.github.com/enterprise-server@3.9/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/enterprise-server@3.9/rest/using-the-rest-api/rate-limits-for-the-rest-api#about-secondary-rate-limits)"
and "[Best practices for using the REST API](https://docs.github.com/enterprise-server@3.9/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/enterprise-server@3.9/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 t
# --- truncated at 32 KB (307 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/engineering-platform/refs/heads/main/openapi/engineering-platform-pulls-api-openapi.yml