API Evangelist conversational phrasing for GitHub v3 REST Pulls API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for GitHub v3 REST Pulls API
  version: 1.0.0
extends: openapi/github-pulls-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-24'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 27
- target: $.paths['/repos/{owner}/{repo}/pulls'].get
  update:
    x-apievangelist-phrasing:
      intent: List pull requests in a repository
      effect: read
      questions:
      - What pull requests are open in a repository right now?
      - Can I list only the pull requests targeting a particular base branch?
      - Which closed pull requests came from a given head branch?
      instructions:
      - text: List the open pull requests in {owner}/{repo}.
        slots:
          owner: path.owner
          repo: path.repo
      - text: Show {state} pull requests in {owner}/{repo} that target base branch {base}.
        slots:
          owner: path.owner
          repo: path.repo
          state: query.state
          base: query.base
      - text: List pull requests in {owner}/{repo} coming from head {head}.
        slots:
          owner: path.owner
          repo: path.repo
          head: query.head
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls'].post
  update:
    x-apievangelist-phrasing:
      intent: Open a pull request
      effect: write
      questions:
      - How do I open a pull request from my feature branch into main?
      - Can I open a pull request as a draft?
      - Is it possible to turn an existing issue into a pull request?
      instructions:
      - text: Open a pull request in {owner}/{repo} from {head} into {base} titled {title}.
        slots:
          owner: path.owner
          repo: path.repo
          head: requestBody.head
          base: requestBody.base
          title: requestBody.title
      - text: Create a draft pull request in {owner}/{repo} merging {head} into {base}, draft set to {draft}.
        slots:
          owner: path.owner
          repo: path.repo
          head: requestBody.head
          base: requestBody.base
          draft: requestBody.draft
      - text: Convert issue {issue} into a pull request from {head} to {base} in {owner}/{repo}.
        slots:
          issue: requestBody.issue
          head: requestBody.head
          base: requestBody.base
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/comments'].get
  update:
    x-apievangelist-phrasing:
      intent: List review comments across all PRs in a repo
      effect: read
      questions:
      - What line-level code review comments have been left across every pull request in a repository?
      - Can I pull all diff review comments in a repo posted since a date?
      instructions:
      - text: List code review comments on all pull requests in {owner}/{repo}.
        slots:
          owner: path.owner
          repo: path.repo
      - text: Show every diff review comment across {owner}/{repo} since {since}.
        slots:
          owner: path.owner
          repo: path.repo
          since: query.since
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/comments/{comment_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one pull request review comment
      effect: read
      questions:
      - What does a specific inline review comment on a pull request diff say?
      - Which file and line is a given review comment attached to?
      instructions:
      - text: Get pull request review comment {comment_id} in {owner}/{repo}.
        slots:
          comment_id: path.comment_id
          owner: path.owner
          repo: path.repo
      - text: Show the file, line and text of diff review comment {comment_id} in {owner}/{repo}.
        slots:
          comment_id: path.comment_id
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/comments/{comment_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a pull request review comment
      effect: destructive
      questions:
      - Can I delete an inline code review comment I left on a pull request diff?
      - What's the way to remove a line comment from a PR review?
      instructions:
      - text: Delete pull request review comment {comment_id} in {owner}/{repo}.
        slots:
          comment_id: path.comment_id
          owner: path.owner
          repo: path.repo
      - text: Remove the inline diff comment {comment_id} from {owner}/{repo}.
        slots:
          comment_id: path.comment_id
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/comments/{comment_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit a pull request review comment
      effect: write
      questions:
      - Can I edit the text of an inline review comment on a pull request?
      - How do I correct a line comment I left on a diff?
      instructions:
      - text: Change pull request review comment {comment_id} in {owner}/{repo} to {body}.
        slots:
          comment_id: path.comment_id
          owner: path.owner
          repo: path.repo
          body: requestBody.body
      - text: Edit my inline diff comment {comment_id} on {owner}/{repo} so it reads {body}.
        slots:
          comment_id: path.comment_id
          owner: path.owner
          repo: path.repo
          body: requestBody.body
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/{pull_number}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a pull request by number
      effect: read
      questions:
      - What's the status, branches and mergeability of a specific pull request?
      - Can I fetch one pull request's details by its number?
      instructions:
      - text: 'Get pull request #{pull_number} in {owner}/{repo}.'
        slots:
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      - text: Show the title, branches and state of PR {pull_number} in {owner}/{repo}.
        slots:
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/{pull_number}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit, close or retarget a pull request
      effect: write
      questions:
      - Can I change the base branch a pull request merges into?
      - How do I close a pull request without merging it?
      - Is it possible to rename a pull request or rewrite its description?
      instructions:
      - text: 'Change the base branch of PR #{pull_number} in {owner}/{repo} to {base}.'
        slots:
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
          base: requestBody.base
      - text: Set pull request {pull_number} in {owner}/{repo} to state {state}.
        slots:
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
          state: requestBody.state
      - text: 'Retitle PR #{pull_number} in {owner}/{repo} to {title}.'
        slots:
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
          title: requestBody.title
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/{pull_number}/comments'].get
  update:
    x-apievangelist-phrasing:
      intent: List review comments on one pull request
      effect: read
      questions:
      - What inline code review comments were left on a particular pull request?
      - Can I sort a PR's diff comments by when they were updated?
      instructions:
      - text: 'List all inline diff comments on PR #{pull_number} in {owner}/{repo}.'
        slots:
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      - text: Show diff comments on pull request {pull_number} of {owner}/{repo} since {since}.
        slots:
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
          since: query.since
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/{pull_number}/comments'].post
  update:
    x-apievangelist-phrasing:
      intent: Comment on a line in a pull request diff
      effect: write
      questions:
      - How do I leave a comment on a specific line of code in a pull request?
      - Can I comment on a range of lines, or on a whole file, in a PR diff?
      instructions:
      - text: 'Comment {body} on line {line} of {path} in PR #{pull_number} of {owner}/{repo} at commit {commit_id}.'
        slots:
          body: requestBody.body
          line: requestBody.line
          path: requestBody.path
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
          commit_id: requestBody.commit_id
      - text: Add a diff comment {body} on lines {start_line} to {line} of {path} in PR {pull_number}, {owner}/{repo}, commit {commit_id}.
        slots:
          body: requestBody.body
          start_line: requestBody.start_line
          line: requestBody.line
          path: requestBody.path
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
          commit_id: requestBody.commit_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/{pull_number}/comments/{comment_id}/replies'].post
  update:
    x-apievangelist-phrasing:
      intent: Reply to a pull request review comment
      effect: write
      questions:
      - Can I reply in-thread to someone's inline review comment on a pull request?
      - Which comment id do I use when answering a code review comment?
      instructions:
      - text: 'Reply {body} to review comment {comment_id} on PR #{pull_number} in {owner}/{repo}.'
        slots:
          body: requestBody.body
          comment_id: path.comment_id
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      - text: Answer the reviewer's comment {comment_id} in PR {pull_number} of {owner}/{repo} with {body}.
        slots:
          comment_id: path.comment_id
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
          body: requestBody.body
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/{pull_number}/commits'].get
  update:
    x-apievangelist-phrasing:
      intent: List the commits in a pull request
      effect: read
      questions:
      - Which commits make up a pull request?
      - Is there a cap on how many commits I can list for a pull request?
      instructions:
      - text: 'List the commits on PR #{pull_number} in {owner}/{repo}.'
        slots:
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      - text: Show the commits included in pull request {pull_number} of {owner}/{repo}.
        slots:
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/{pull_number}/files'].get
  update:
    x-apievangelist-phrasing:
      intent: List the files changed in a pull request
      effect: read
      questions:
      - Which files does a pull request touch, and how many lines changed in each?
      - What's the maximum number of files returned for a very large pull request?
      instructions:
      - text: 'List the files changed in PR #{pull_number} of {owner}/{repo}.'
        slots:
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      - text: Show additions and deletions per file for pull request {pull_number} in {owner}/{repo}.
        slots:
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/{pull_number}/merge'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether a pull request was merged
      effect: read
      questions:
      - Has a given pull request actually been merged into its base branch?
      - Can I check merge status with just the HTTP response code?
      instructions:
      - text: 'Check whether PR #{pull_number} in {owner}/{repo} has been merged.'
        slots:
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      - text: Confirm whether pull request {pull_number} in {owner}/{repo} was merged into its base branch.
        slots:
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/{pull_number}/merge'].put
  update:
    x-apievangelist-phrasing:
      intent: Merge a pull request
      effect: write
      questions:
      - How do I merge a pull request through the API?
      - Can I squash or rebase instead of making a merge commit?
      - Is there a way to make the merge fail if the branch head moved since I reviewed it?
      instructions:
      - text: 'Merge PR #{pull_number} in {owner}/{repo}.'
        slots:
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      - text: Merge pull request {pull_number} in {owner}/{repo} using the {merge_method} method.
        slots:
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
          merge_method: requestBody.merge_method
      - text: Merge PR {pull_number} in {owner}/{repo} only if its head is still {sha}, with commit title {commit_title}.
        slots:
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
          sha: requestBody.sha
          commit_title: requestBody.commit_title
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers'].get
  update:
    x-apievangelist-phrasing:
      intent: List pending reviewers on a pull request
      effect: read
      questions:
      - Whose review is still pending on a pull request?
      - Which users or teams have been asked to review this PR but haven't yet?
      instructions:
      - text: 'List the requested reviewers on PR #{pull_number} in {owner}/{repo}.'
        slots:
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      - text: Show who still owes a review on pull request {pull_number} of {owner}/{repo}.
        slots:
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers'].post
  update:
    x-apievangelist-phrasing:
      intent: Request reviews on a pull request
      effect: write
      questions:
      - How do I ask specific people to review my pull request?
      - Can I request a review from a whole team instead of individuals?
      instructions:
      - text: 'Request reviews from {reviewers} on PR #{pull_number} in {owner}/{repo}.'
        slots:
          reviewers: requestBody.reviewers
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      - text: Ask team {team_reviewers} to review pull request {pull_number} in {owner}/{repo}.
        slots:
          team_reviewers: requestBody.team_reviewers
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers'].delete
  update:
    x-apievangelist-phrasing:
      intent: Cancel review requests on a pull request
      effect: destructive
      questions:
      - Can I withdraw a review request I sent to someone on a pull request?
      - What's the way to take a team off a PR's requested reviewers?
      instructions:
      - text: 'Remove the review request for {reviewers} on PR #{pull_number} in {owner}/{repo}.'
        slots:
          reviewers: requestBody.reviewers
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      - text: Cancel review requests to {reviewers} and team {team_reviewers} on pull request {pull_number} of {owner}/{repo}.
        slots:
          reviewers: requestBody.reviewers
          team_reviewers: requestBody.team_reviewers
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/{pull_number}/reviews'].get
  update:
    x-apievangelist-phrasing:
      intent: List the reviews on a pull request
      effect: read
      questions:
      - Who has approved or requested changes on a pull request?
      - In what order were the reviews on this PR submitted?
      instructions:
      - text: 'List the reviews on PR #{pull_number} in {owner}/{repo}.'
        slots:
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      - text: Show approvals and change requests on pull request {pull_number} of {owner}/{repo}.
        slots:
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/{pull_number}/reviews'].post
  update:
    x-apievangelist-phrasing:
      intent: Start or submit a review on a pull request
      effect: write
      questions:
      - How do I approve a pull request through the API?
      - Can I submit a review that requests changes and includes several line comments at once?
      - What happens if I create a review without choosing an approve or request-changes event?
      instructions:
      - text: 'Review PR #{pull_number} in {owner}/{repo} with event {event}.'
        slots:
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
          event: requestBody.event
      - text: Leave a new review on pull request {pull_number} in {owner}/{repo} saying {body} with line comments {comments}.
        slots:
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
          body: requestBody.body
          comments: requestBody.comments
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one review on a pull request
      effect: read
      questions:
      - What did a specific review on a pull request say, and was it an approval?
      - Can I look up a single PR review by its review id?
      instructions:
      - text: 'Get review {review_id} on PR #{pull_number} in {owner}/{repo}.'
        slots:
          review_id: path.review_id
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      - text: Show the state and summary of review {review_id} on pull request {pull_number} of {owner}/{repo}.
        slots:
          review_id: path.review_id
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a pull request review's summary
      effect: write
      questions:
      - Can I change the summary text of a review I already left on a pull request?
      - How do I reword the top-level comment of my PR review?
      instructions:
      - text: 'Change the summary of review {review_id} on PR #{pull_number} in {owner}/{repo} to {body}.'
        slots:
          review_id: path.review_id
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
          body: requestBody.body
      - text: Rewrite my review {review_id} summary on pull request {pull_number} of {owner}/{repo} as {body}.
        slots:
          review_id: path.review_id
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
          body: requestBody.body
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an unsubmitted pull request review
      effect: destructive
      questions:
      - Can I throw away a pending review I haven't submitted yet?
      - Is it possible to delete a review after it has been submitted?
      instructions:
      - text: 'Delete my pending review {review_id} on PR #{pull_number} in {owner}/{repo}.'
        slots:
          review_id: path.review_id
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      - text: Discard unsubmitted review {review_id} on pull request {pull_number} of {owner}/{repo}.
        slots:
          review_id: path.review_id
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}/comments'].get
  update:
    x-apievangelist-phrasing:
      intent: List the comments within one review
      effect: read
      questions:
      - Which line comments belong to one particular pull request review?
      - Can I see only the comments a reviewer left as part of a single review?
      instructions:
      - text: 'List only the comments belonging to review {review_id} on PR #{pull_number} in {owner}/{repo}.'
        slots:
          review_id: path.review_id
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      - text: Show the line comments grouped under review {review_id} of pull request {pull_number}, {owner}/{repo}.
        slots:
          review_id: path.review_id
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}/dismissals'].put
  update:
    x-apievangelist-phrasing:
      intent: Dismiss a review on a pull request
      effect: destructive
      questions:
      - Can I dismiss a stale change request so it no longer blocks a pull request?
      - What permissions do I need to dismiss a review on a protected branch?
      instructions:
      - text: 'Dismiss review {review_id} on PR #{pull_number} in {owner}/{repo} with message {message}.'
        slots:
          review_id: path.review_id
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
          message: requestBody.message
      - text: Clear the blocking review {review_id} from pull request {pull_number} of {owner}/{repo}, explaining {message}.
        slots:
          review_id: path.review_id
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
          message: requestBody.message
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}/events'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit a pending pull request review
      effect: write
      questions:
      - How do I submit a review I started earlier but left pending?
      - Can I finalize a pending review as an approval or a change request?
      instructions:
      - text: 'Submit pending review {review_id} on PR #{pull_number} in {owner}/{repo} as {event}.'
        slots:
          review_id: path.review_id
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
          event: requestBody.event
      - text: Finalize my draft review {review_id} on pull request {pull_number} of {owner}/{repo} with event {event} and note {body}.
        slots:
          review_id: path.review_id
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
          event: requestBody.event
          body: requestBody.body
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/pulls/{pull_number}/update-branch'].put
  update:
    x-apievangelist-phrasing:
      intent: Bring a pull request branch up to date with base
      effect: write
      questions:
      - Can I update a pull request's branch with the latest changes from its base branch?
      - Is there a safeguard so the update fails if the PR head changed underneath me?
      instructions:
      - text: 'Update the branch of PR #{pull_number} in {owner}/{repo} with the latest base changes.'
        slots:
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
      - text: Merge base into pull request {pull_number} of {owner}/{repo} only if its head is {expected_head_sha}.
        slots:
          pull_number: path.pull_number
          owner: path.owner
          repo: path.repo
          expected_head_sha: requestBody.expected_head_sha
      method: generated
      generated: '2026-09-24'