GitHub Copilot Pulls API

openapi: 3.2.0
info:
  version: 1.1.4
  title: 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: api.github.com
servers:
- url: https://api.github.com
tags:
- name: Pulls
  description: Interact with GitHub Pull Requests.
paths:
  /repos/{owner}/{repo}/pulls/{pull_number}/copilot-code-review:
    post:
      summary: Request a Copilot code review for a pull request
      description: 'Requests a Copilot code review for a pull request. Every call expresses intent to start a

        new review: if no Copilot review has been requested yet, an initial request is created; if

        the most recent Copilot review has already completed (including if it was later dismissed or

        superseded), a new request is created automatically to continue the review lifecycle. If a

        Copilot code review request is already pending for the pull request, no new request is

        created and the response is `409`.


        If the actor or repository is not eligible for Copilot code review, the actor has no quota

        remaining, or the licensing organization is unavailable, no request is created and the

        response is `422` with a stable `failure_reason`. A `review_effort` is accepted only when that

        effort level is available for the repository and actor; an unrecognized or unavailable

        `review_effort` returns `422` with `failure_reason` `INVALID_REVIEW_EFFORT`. If

        the actor, repository owner, or requesting application owner has been flagged, the response

        is `403` with `failure_reason` `ACTOR_FLAGGED`. If the per-actor or per-owner request rate

        limit is exceeded, the response is `429` with `failure_reason` `RATE_LIMITED`. If Copilot

        code review cannot be serviced right now, the response is `503`.


        Existing human and team review requests on the pull request are left unchanged.'
      tags:
      - Pulls
      operationId: pulls/request-copilot-code-review
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/rest/pulls/copilot-code-review#request-a-copilot-code-review-for-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
              - 'null'
              properties:
                review_effort:
                  type: string
                  description: The effort level to use for the Copilot code review. Omit to use the default effort level. Only effort levels available for the repository and actor are accepted. For more information, see [Review effort level](https://docs.github.com/copilot/concepts/agent-capabilities/agent-powered-workflows-and-operations/code-review#review-effort-level).
            examples:
              default:
                summary: Request a review with a specific effort level
                value:
                  review_effort: balanced
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/copilot-code-review-request'
              examples:
                default:
                  summary: A Copilot code review request was created
                  value:
                    node_id: RRR_kwDOAA
                    state: PENDING
        '401':
          $ref: '#/components/responses/requires_authentication'
        '403':
          description: Forbidden. `failure_reason` is `ACTOR_FLAGGED` when the actor, repository owner, or requesting application owner has been flagged; it is absent for other authorization failures.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/copilot-code-review-request-denied'
        '404':
          $ref: '#/components/responses/not_found'
        '409':
          description: Conflict, a Copilot code review request is already pending for this pull request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/copilot-code-review-request-denied'
        '422':
          description: Validation failed. `failure_reason` is present for a stable business denial (the actor or repository is not eligible, the actor has no quota remaining, or the licensing organization is unavailable) and absent when the request body fails generic request validation. `failure_reason` is `INVALID_REVIEW_EFFORT` when the requested `review_effort` is unrecognized or not available for the repository and actor, and `message` lists the available effort levels.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/copilot-code-review-request-denied'
        '429':
          description: Too many requests. The per-actor or per-owner Copilot code review request rate limit has been exceeded. `failure_reason` is `RATE_LIMITED`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/copilot-code-review-request-denied'
        '503':
          description: Service unavailable, Copilot code review cannot be serviced right now
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/copilot-code-review-request-denied'
      x-github:
        triggersNotification: false
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: pulls
        subcategory: copilot-code-review
components:
  schemas:
    copilot-code-review-request-denied:
      title: Copilot Code Review Request Denied
      description: A Copilot code review request was denied, conflicted with an existing request, or could not be serviced. The `failure_reason` field is present for stable, machine-readable denials -- overlapping with the reasons returned by the `failureReason` field on the `requestCopilotCodeReview` GraphQL mutation, plus a few additional reasons this REST endpoint reports explicitly rather than as an opaque error -- and is absent for generic validation failures.
      allOf:
      - $ref: '#/components/schemas/basic-error'
      - type: object
        properties:
          failure_reason:
            type: string
            description: The stable reason the request was denied, conflicted with an existing request, or could not be serviced.
            enum:
            - ACTOR_INELIGIBLE
            - REPOSITORY_INELIGIBLE
            - APP_NOT_INSTALLED
            - NO_QUOTA_REMAINING
            - LICENSED_ORGANIZATION_UNAVAILABLE
            - INVALID_REVIEW_EFFORT
            - REQUEST_FAILED
            - REQUEST_CONFLICT
            - REVIEWER_UNAVAILABLE
            - REQUEST_UNAVAILABLE
            - ACTOR_FLAGGED
            - RATE_LIMITED
            example: REQUEST_CONFLICT
    copilot-code-review-request:
      title: Copilot Code Review Request
      description: A request for Copilot to review a pull request.
      type: object
      properties:
        node_id:
          type: string
          description: The global node ID of the review request.
          example: RRR_kwDOAA
        state:
          type: string
          description: The current state of the review request.
          enum:
          - PENDING
          example: PENDING
      required:
      - node_id
      - state
    basic-error:
      title: Basic Error
      description: Basic Error
      type: object
      properties:
        message:
          type: string
        documentation_url:
          type: string
        url:
          type: string
        status:
          type: string
  parameters:
    pull-number:
      name: pull_number
      description: The number that identifies the pull request.
      in: path
      required: true
      schema:
        type: integer
    owner:
      name: owner
      description: The account owner of the repository. The name is not case sensitive.
      in: path
      required: true
      schema:
        type: string
    repo:
      name: repo
      description: The name of the repository without the `.git` extension. The name is not case sensitive.
      in: path
      required: true
      schema:
        type: string
  responses:
    not_found:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
    requires_authentication:
      description: Requires authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
externalDocs:
  description: GitHub v3 REST API
  url: https://docs.github.com/rest/