# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Harness Pull Requests API
  version: 1.0.0
extends: openapi/harness-pull-requests-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 6
- target: $.paths['/sto/api/v2/pull-requests/repositories'].get
  update:
    x-apievangelist-phrasing:
      intent: List pull requests for a repository
      effect: read
      questions:
      - Which pull requests are open on a repository scanned by Security Testing Orchestration?
      - Can I list a repository's pull requests from inside STO?
      instructions:
      - text: List pull requests on repository {repo} from provider {provider} for account {account}.
        slots:
          repo: query.repositoryPath
          provider: query.provider
          account: query.accountId
      - text: Show PRs for {repo} hosted on {provider}.
        slots:
          repo: query.repositoryPath
          provider: query.provider
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/pull-requests/repositories/pulls'].get
  update:
    x-apievangelist-phrasing:
      intent: Find a pull request by number
      effect: read
      questions:
      - What are the details of a specific pull request number in my repository?
      - Can I look up one PR by its number for a security fix?
      instructions:
      - text: Find pull request {number} on repository {repo} at {provider}.
        slots:
          number: query.pullRequestNumber
          repo: query.repositoryPath
          provider: query.provider
      - text: 'Get PR #{number} in {repo} for account {account}.'
        slots:
          number: query.pullRequestNumber
          repo: query.repositoryPath
          account: query.accountId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/pull-requests/repositories/pulls'].put
  update:
    x-apievangelist-phrasing:
      intent: Add an AI remediation fix to an existing PR
      effect: write
      questions:
      - Can I push an AI-suggested remediation for a security issue onto a pull request I already have open?
      - How do I add a code fix for a vulnerability to an existing PR?
      instructions:
      - text: Add the remediation for occurrence {occurrence} of issue {issue} to existing PR {number} on {repo}.
        slots:
          occurrence: requestBody.occurrenceId
          issue: requestBody.id
          number: requestBody.pullRequestNumber
          repo: query.repositoryPath
      - text: Update pull request {number} with the fix {code} for {path}.
        slots:
          number: requestBody.pullRequestNumber
          code: requestBody.remediationCode
          path: requestBody.remediationCodePath
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/pull-requests/repositories/pulls'].post
  update:
    x-apievangelist-phrasing:
      intent: Open a new PR with an AI remediation
      effect: write
      questions:
      - Can STO open a new pull request that fixes a vulnerability it found?
      - How do I create a fresh remediation PR on a new branch for a security issue?
      instructions:
      - text: Open a new pull request on branch {branch} in {repo} fixing occurrence {occurrence} of issue {issue}.
        slots:
          branch: requestBody.branch
          repo: query.repositoryPath
          occurrence: requestBody.occurrenceId
          issue: requestBody.id
      - text: Create a remediation PR described as {description} from scan {scan}.
        slots:
          description: requestBody.description
          scan: requestBody.scanId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/pull-requests/repositories/pulls/action'].get
  update:
    x-apievangelist-phrasing:
      intent: Decide which PR action to offer for an issue
      effect: read
      questions:
      - Should the UI offer to create a PR, suggest a fix, or show an existing PR for this occurrence?
      - What pull request action is available for a given security issue occurrence?
      instructions:
      - text: Get the PR action for occurrence {occurrence} of issue {issue} in scan {scan}.
        slots:
          occurrence: query.occurrenceId
          issue: query.id
          scan: query.scanId
      - text: Tell me whether to create, suggest a fix, or display a PR for issue {issue} occurrence {occurrence}.
        slots:
          issue: query.id
          occurrence: query.occurrenceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/pull-requests/repositories/pulls/correlation'].get
  update:
    x-apievangelist-phrasing:
      intent: Check if a code path is touched by a PR
      effect: read
      questions:
      - Is this file path part of a particular pull request?
      - Can I correlate a vulnerable code path with an open PR?
      instructions:
      - text: Check whether path {path} is correlated with PR {number} in {repo}.
        slots:
          path: query.codePath
          number: query.pullRequestNumber
          repo: query.repositoryPath
      - text: See if pull request {number} on {provider} touches {path}.
        slots:
          number: query.pullRequestNumber
          provider: query.provider
          path: query.codePath
      method: generated
      generated: '2026-09-26'