# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Harness Test Targets API
  version: 1.0.0
extends: openapi/harness-test-targets-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: 13
- target: $.paths['/sto/api/v2/targets'].get
  update:
    x-apievangelist-phrasing:
      intent: List security test targets
      effect: read
      questions:
      - Which test targets are defined for security scanning in my project?
      - Can I search test targets by name?
      instructions:
      - text: List the test targets in project {project} of org {org}.
        slots:
          project: query.projectId
          org: query.orgId
      - text: Find test targets named {name} in project {project}.
        slots:
          name: query.name
          project: query.projectId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/targets'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a security test target
      effect: write
      questions:
      - How do I create a new test target for security scans?
      - Can I set a baseline branch pattern when creating a test target?
      instructions:
      - text: Create a {type} test target named {name} in project {project}.
        slots:
          type: requestBody.type
          name: requestBody.name
          project: query.projectId
      - text: Create test target {name} of type {type} with baseline pattern {baseline}.
        slots:
          name: requestBody.name
          type: requestBody.type
          baseline: requestBody.baselineRegEx
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/targets/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a test target by ID
      effect: read
      questions:
      - How do I look up one test target and its settings?
      - What type and baseline does a given test target have?
      instructions:
      - text: Get test target {target_id}.
        slots:
          target_id: path.id
      - text: Show test target {target_id} in project {project}.
        slots:
          target_id: path.id
          project: query.projectId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/targets/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a test target's definition
      effect: write
      questions:
      - How do I fully replace a test target's name, type and baseline?
      - Can I overwrite every field of a test target in one update?
      instructions:
      - text: Replace test target {target_id} with name {name} and type {type}.
        slots:
          target_id: path.id
          name: requestBody.name
          type: requestBody.type
      - text: Overwrite target {target_id} as {name}, type {type}, directory {directory}.
        slots:
          target_id: path.id
          name: requestBody.name
          type: requestBody.type
          directory: requestBody.directory
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/targets/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a test target
      effect: destructive
      questions:
      - How do I delete a test target I no longer scan?
      - Can I remove a test target from a project?
      instructions:
      - text: Delete test target {target_id}.
        slots:
          target_id: path.id
      - text: Remove test target {target_id} from project {project}.
        slots:
          target_id: path.id
          project: query.projectId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/targets/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change selected fields on a test target
      effect: write
      questions:
      - Can I change just the baseline of a test target without resending everything?
      - How do I update only the URL of an existing test target?
      instructions:
      - text: Patch test target {target_id} so its baseline pattern is {baseline}.
        slots:
          target_id: path.id
          baseline: requestBody.baselineRegEx
      - text: Change only the URL of test target {target_id} to {url}.
        slots:
          target_id: path.id
          url: requestBody.url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/targets/{id}/executions'].get
  update:
    x-apievangelist-phrasing:
      intent: List a test target's scan history
      effect: read
      questions:
      - What is the scan history for a test target, newest first?
      - Can I filter a target's scan executions by branch or scan type?
      instructions:
      - text: List scan executions for test target {target_id}.
        slots:
          target_id: path.id
      - text: Show target {target_id} executions on branch {branch}.
        slots:
          target_id: path.id
          branch: query.branch
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/targets/{id}/executions/{executionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get metadata for one target execution
      effect: read
      questions:
      - Which pipeline and build produced a given target scan execution?
      - How many findings and SBOMs did one target execution produce?
      instructions:
      - text: Get execution {execution_id} of test target {target_id}.
        slots:
          execution_id: path.executionId
          target_id: path.id
      - text: Show the header details for scan run {execution_id} on target {target_id}.
        slots:
          execution_id: path.executionId
          target_id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/targets/{id}/executions/{executionId}/occurrences'].get
  update:
    x-apievangelist-phrasing:
      intent: List findings from a target execution
      effect: read
      questions:
      - What security findings did one scan execution of a target report?
      - Can I filter a target execution's findings by severity?
      instructions:
      - text: List findings for execution {execution_id} of target {target_id}.
        slots:
          execution_id: path.executionId
          target_id: path.id
      - text: Show {severity} findings from execution {execution_id} on target {target_id}.
        slots:
          severity: query.severityCodes
          execution_id: path.executionId
          target_id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/targets/{id}/executions/{executionId}/occurrences/{occurrenceInternalId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one finding occurrence from a target execution
      effect: read
      questions:
      - How do I open the details of a single finding occurrence from a scan?
      - Why do I need the scan ID to fetch one occurrence of a finding?
      instructions:
      - text: Get occurrence {occurrence} from scan {scan} in execution {execution_id} of target {target_id}.
        slots:
          occurrence: path.occurrenceInternalId
          scan: query.scanId
          execution_id: path.executionId
          target_id: path.id
      - text: Show occurrence {occurrence} of execution {execution_id} on target {target_id} for scan {scan}.
        slots:
          occurrence: path.occurrenceInternalId
          execution_id: path.executionId
          target_id: path.id
          scan: query.scanId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/targets/{id}/overview'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a test target's findings overview
      effect: read
      questions:
      - What does the security overview for a test target look like, by issue type and severity?
      - Can I see scan coverage and findings totals for one target?
      instructions:
      - text: Show the overview for test target {target_id}.
        slots:
          target_id: path.id
      - text: Summarize findings by severity for target {target_id}, variant {variant}.
        slots:
          target_id: path.id
          variant: query.variantId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/targets/{id}/sbom'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a test target's SBOM
      effect: read
      questions:
      - Can I export the software bill of materials for a test target?
      - Which SBOM formats can I request for a target?
      instructions:
      - text: Download the SBOM for target {target_id} in format {format}.
        slots:
          target_id: path.id
          format: query.format
      - text: Export the {format} SBOM of target {target_id} from execution {execution_id}.
        slots:
          format: query.format
          target_id: path.id
          execution_id: query.executionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/targets/{id}/sca/packages'].get
  update:
    x-apievangelist-phrasing:
      intent: List open-source packages found on a target
      effect: read
      questions:
      - Which open-source packages did software composition analysis find in a target?
      - Can I filter a target's SCA packages by license?
      instructions:
      - text: List SCA packages for test target {target_id}.
        slots:
          target_id: path.id
      - text: Show packages on target {target_id} with license {license}.
        slots:
          target_id: path.id
          license: query.licenses
      method: generated
      generated: '2026-09-26'