# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Harness Issues API
  version: 1.0.0
extends: openapi/harness-issues-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/issues'].get
  update:
    x-apievangelist-phrasing:
      intent: List security issues
      effect: read
      questions:
      - Which security issues have scanners found in my account?
      - Can I list security issues for one product without their occurrences?
      instructions:
      - text: List security issues for account {account}.
        slots:
          account: query.accountId
      - text: Show security issues from product {product} with key {key}.
        slots:
          product: query.productId
          key: query.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/issues'].post
  update:
    x-apievangelist-phrasing:
      intent: Record a new security issue from a scan
      effect: write
      questions:
      - How do I record a vulnerability found by a scan as a security issue?
      - What fields are required to create a security issue?
      instructions:
      - text: Create security issue {title} with severity {severity} from scan {scan} of product {product}.
        slots:
          title: requestBody.title
          severity: requestBody.severity
          scan: requestBody.scanId
          product: requestBody.productId
      - text: Log issue {title} with key {key} and severity code {code} for scan {scan}.
        slots:
          title: requestBody.title
          key: requestBody.key
          code: requestBody.severityCode
          scan: requestBody.scanId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/issues/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a security issue
      effect: read
      questions:
      - What are the details and severity of a specific security issue?
      - Can I look up a security issue by ID for a given target?
      instructions:
      - text: Get security issue {issue}.
        slots:
          issue: path.id
      - text: Show security issue {issue} in project {project} for target {target}.
        slots:
          issue: path.id
          project: query.projectId
          target: query.targetId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/issues/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a security issue's occurrences
      effect: write
      questions:
      - How do I update the occurrences of an existing security issue after a new scan?
      - Can I change how many times an issue occurred?
      instructions:
      - text: Update security issue {issue} with occurrences {occurrences} from scan {scan}.
        slots:
          issue: path.id
          occurrences: requestBody.occurrences
          scan: requestBody.scanId
      - text: Set the occurrence count of issue {issue} to {count}.
        slots:
          issue: path.id
          count: requestBody.numOccurrences
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/issues/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a security issue
      effect: destructive
      questions:
      - How do I remove a security issue that was recorded by mistake?
      - Is deleting a security issue permanent?
      instructions:
      - text: Delete security issue {issue}.
        slots:
          issue: path.id
      - text: Remove issue {issue} from account {account}.
        slots:
          issue: path.id
          account: query.accountId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/issues/{id}/augment-remediation'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate AI remediation steps for a security issue
      effect: write
      questions:
      - Can AI suggest remediation steps or a code fix for a security issue?
      - Is it possible to get remediation advice based only on the taint path?
      instructions:
      - text: Use AI to improve remediation for issue {issue}, occurrence {occurrence}, scan {scan}.
        slots:
          issue: path.id
          occurrence: requestBody.occurrenceId
          scan: requestBody.scanId
      - text: Suggest fixes for issue {issue} occurrence {occurrence} using code snippet {snippet}.
        slots:
          issue: path.id
          occurrence: requestBody.occurrenceId
          snippet: requestBody.userSnippet
      method: generated
      generated: '2026-09-26'