# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Harness Scans API
  version: 1.0.0
extends: openapi/harness-scans-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: 10
- target: $.paths['/sto/api/v2/scans'].get
  update:
    x-apievangelist-phrasing:
      intent: List security test scans
      effect: read
      questions:
      - What security scans have run in my Harness STO account?
      - Can I list only the scans from one pipeline execution?
      instructions:
      - text: List security test scans in account {account}.
        slots:
          account: query.accountId
      - text: Show scans from pipeline execution {execution} in account {account}.
        slots:
          execution: query.executionId
          account: query.accountId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/scans'].post
  update:
    x-apievangelist-phrasing:
      intent: Record a new security test scan
      effect: write
      questions:
      - How do I register a new security scan record for a pipeline step?
      - What do I need to supply when creating a scan, such as scanner product and target variant?
      instructions:
      - text: Create a scan for execution {execution}, product {product}, target variant {target} in account {account}.
        slots:
          execution: requestBody.executionId
          product: requestBody.productId
          target: requestBody.targetVariantId
          account: query.accountId
      - text: Record a new {status} scan for pipeline {pipeline} step {step} in account {account}.
        slots:
          status: requestBody.status
          pipeline: requestBody.pipelineId
          step: requestBody.stepId
          account: query.accountId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/scans/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a security test scan by ID
      effect: read
      questions:
      - What are the details and status of a particular security scan?
      - Can I look up one scan record by its ID?
      instructions:
      - text: Get scan {scan} in account {account}.
        slots:
          scan: path.id
          account: query.accountId
      - text: Show the status and target of security scan {scan} for account {account}.
        slots:
          scan: path.id
          account: query.accountId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/scans/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an existing security test scan
      effect: write
      questions:
      - How do I mark a running security scan as succeeded or failed?
      - Can I attach an artifact fingerprint to a scan after it has been created?
      instructions:
      - text: Update scan {scan} in account {account} to status {status}.
        slots:
          scan: path.id
          account: query.accountId
          status: requestBody.status
      - text: Set artifact fingerprint {fingerprint} on existing scan {scan} (account {account}).
        slots:
          fingerprint: requestBody.artifactFingerprint
          scan: path.id
          account: query.accountId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/scans/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a security test scan
      effect: destructive
      questions:
      - How do I remove a security scan record I no longer need?
      - Can I delete a scan by its ID?
      instructions:
      - text: Delete scan {scan} in account {account}.
        slots:
          scan: path.id
          account: query.accountId
      - text: Remove security test scan {scan} from account {account}.
        slots:
          scan: path.id
          account: query.accountId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/scans/{id}/issue/{issueId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one issue found by a scan
      effect: read
      questions:
      - What are the details of one vulnerability a security scan reported?
      - Can I view a single issue within a scan's findings?
      instructions:
      - text: Get issue {issue} from scan {scan} in account {account}.
        slots:
          issue: path.issueId
          scan: path.id
          account: query.accountId
      - text: Show the details of finding {issue} reported by scan {scan} (account {account}).
        slots:
          issue: path.issueId
          scan: path.id
          account: query.accountId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/scans/{id}/issue/{issueId}/occurrences'].get
  update:
    x-apievangelist-phrasing:
      intent: List occurrences of a scan issue
      effect: read
      questions:
      - Where in the code or image does a scan issue occur, and how many times?
      - Can I filter an issue's occurrences by exemption status?
      instructions:
      - text: List occurrences of issue {issue} in scan {scan}, account {account}.
        slots:
          issue: path.issueId
          scan: path.id
          account: query.accountId
      - text: Show {exemption_status} occurrences of issue {issue} in scan {scan} (account {account}).
        slots:
          exemption_status: query.exemptionStatus
          issue: path.issueId
          scan: path.id
          account: query.accountId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/scans/{id}/issues'].get
  update:
    x-apievangelist-phrasing:
      intent: List the issues found by a scan
      effect: read
      questions:
      - What vulnerabilities did a particular security scan find?
      - Can I include or exclude exempted issues when listing a scan's findings?
      instructions:
      - text: List issues found by scan {scan} in account {account}.
        slots:
          scan: path.id
          account: query.accountId
      - text: Show only exempted issues for scan {scan} (account {account}).
        slots:
          scan: path.id
          account: query.accountId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/scans/{id}/issues/counts'].get
  update:
    x-apievangelist-phrasing:
      intent: Count active issues in a scan by severity
      effect: read
      questions:
      - How many active critical and high issues did this scan report?
      - What's the issue count breakdown for a security scan?
      instructions:
      - text: Get active issue counts for scan {scan} in project {project}, org {org}, account {account}.
        slots:
          scan: path.id
          project: query.projectId
          org: query.orgId
          account: query.accountId
      - text: Count the open security issues in scan {scan} (account {account}, org {org}, project {project}).
        slots:
          scan: path.id
          account: query.accountId
          org: query.orgId
          project: query.projectId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/scans/latest'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the latest scans for a target variant
      effect: read
      questions:
      - What is the most recent successful scan for each scanner on this target?
      - Can I get the latest scan for one scanner product and subproduct only?
      instructions:
      - text: Get the latest successful scans for target variant {target} in account {account}.
        slots:
          target: query.targetVariantId
          account: query.accountId
      - text: Show the most recent {product} scan for target variant {target} (account {account}).
        slots:
          product: query.productId
          target: query.targetVariantId
          account: query.accountId
      method: generated
      generated: '2026-09-26'