# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Harness Registry V3 - Firewall API
  version: 1.0.0
extends: openapi/harness-registry-v3-firewall-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: 14
- target: $.paths['/har/api/v3/build-info'].post
  update:
    x-apievangelist-phrasing:
      intent: Record build info from a package install
      effect: write
      questions:
      - How does the CLI report package installation build info to the registry?
      - Can I attach pipeline context to the build info I record?
      instructions:
      - text: Add build info for root package {root_package} in registry {registry} with status {status}.
        slots:
          root_package: requestBody.rootPackage
          registry: requestBody.registryId
          status: requestBody.status
      - text: Record build info of package type {package_type} for account {account}.
        slots:
          package_type: requestBody.packageType
          account: query.account_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/build-info/pipeline/details'].get
  update:
    x-apievangelist-phrasing:
      intent: List pipeline build info details
      effect: read
      questions:
      - Which pipelines installed a given package version?
      - Can I filter pipeline build info by scan id or package type?
      instructions:
      - text: List pipeline build info for package {package} version {version}.
        slots:
          package: query.package_name
          version: query.version
      - text: Show build info details from pipeline {pipeline_id} in account {account}.
        slots:
          pipeline_id: query.pipeline_id
          account: query.account_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/scans'].get
  update:
    x-apievangelist-phrasing:
      intent: List artifact firewall scan results
      effect: read
      questions:
      - Which artifacts in my registries were flagged by firewall scans?
      - Can I filter scan results by scan status or policy set?
      instructions:
      - text: List artifact scans with status {scan_status} in account {account}.
        slots:
          scan_status: query.scan_status
          account: query.account_identifier
      - text: Show firewall scan results for registries {registry_ids}.
        slots:
          registry_ids: query.registry_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/scans/{id}/details'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the details of one artifact scan
      effect: read
      questions:
      - Why was a specific artifact blocked by the firewall scan?
      - Can I see the full findings recorded for one scan?
      instructions:
      - text: Show details of artifact scan {scan_id}.
        slots:
          scan_id: path.id
      - text: Get scan {scan_id} details evaluated against policy set {policy_set}.
        slots:
          scan_id: path.id
          policy_set: query.policy_set_ref
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/scans/bulk-evaluate'].post
  update:
    x-apievangelist-phrasing:
      intent: Start an asynchronous bulk firewall evaluation
      effect: write
      questions:
      - Can I trigger firewall policy evaluation for many artifacts in the background?
      - How do I kick off an asynchronous bulk scan evaluation?
      instructions:
      - text: Start a bulk firewall evaluation of artifacts {artifacts} in registry {registry}.
        slots:
          artifacts: requestBody.artifacts
          registry: requestBody.registryId
      - text: Queue background policy evaluation for registry {registry} covering {artifacts}.
        slots:
          artifacts: requestBody.artifacts
          registry: requestBody.registryId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/scans/bulk-evaluate-sync'].post
  update:
    x-apievangelist-phrasing:
      intent: Evaluate up to 50 artifacts synchronously
      effect: read
      questions:
      - Can I get firewall results immediately for a batch of artifacts without saving anything?
      - What's the limit on artifacts in a synchronous bulk evaluation?
      instructions:
      - text: Synchronously evaluate artifacts {artifacts} against firewall policies in registry {registry}.
        slots:
          artifacts: requestBody.artifacts
          registry: requestBody.registryId
      - text: Evaluate {artifacts} right now without recording results, skip cache {skip_cache}.
        slots:
          artifacts: requestBody.artifacts
          skip_cache: requestBody.skipCache
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/scans/bulk-evaluate/{evaluation_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a bulk scan evaluation's status
      effect: read
      questions:
      - Is my bulk firewall evaluation finished?
      - Where do I check progress on a bulk scan evaluation I started earlier?
      instructions:
      - text: Get status of bulk evaluation {evaluation_id}.
        slots:
          evaluation_id: path.evaluation_id
      - text: Check whether bulk scan evaluation {evaluation_id} completed in account {account}.
        slots:
          evaluation_id: path.evaluation_id
          account: query.account_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/scans/evaluate'].post
  update:
    x-apievangelist-phrasing:
      intent: Re-evaluate an artifact scan
      effect: write
      questions:
      - Can I rerun the firewall evaluation for an artifact after a policy change?
      - How do I re-evaluate a specific artifact version's scan?
      instructions:
      - text: Re-evaluate scan {scan_id}.
        slots:
          scan_id: requestBody.scanId
      - text: Rerun the firewall evaluation for version {version_id}.
        slots:
          version_id: requestBody.versionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/scans/exceptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List firewall exceptions
      effect: read
      questions:
      - Which firewall exceptions are still pending approval?
      - Can I find the exceptions granted for a particular package?
      instructions:
      - text: List firewall exceptions with status {status}.
        slots:
          status: query.status
      - text: Show firewall exceptions for package {package} in account {account}.
        slots:
          package: query.package_name
          account: query.account_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/scans/exceptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Request a firewall exception for a package
      effect: write
      questions:
      - What does it take to request an exception so a blocked package can be used?
      - Can a firewall exception expire automatically after a set time?
      instructions:
      - text: Create a firewall exception for package {package} in registry {registry} because {justification}.
        slots:
          package: requestBody.packageName
          registry: requestBody.registryId
          justification: requestBody.businessJustification
      - text: Request an exception for {package} versions {versions} expiring after {expire_after}.
        slots:
          package: requestBody.packageName
          versions: requestBody.versionList
          expire_after: requestBody.expireAfter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/scans/exceptions/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a pending firewall exception
      effect: write
      questions:
      - Can I change the justification on an exception that's still pending?
      - Why can't I edit a firewall exception once it's no longer pending?
      instructions:
      - text: Update pending exception {exception_id} with remediation plan {plan}.
        slots:
          exception_id: path.id
          plan: requestBody.remediationPlan
      - text: Change the expiry of firewall exception {exception_id} to {expire_after}.
        slots:
          exception_id: path.id
          expire_after: requestBody.expireAfter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/scans/exceptions/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a firewall exception
      effect: destructive
      questions:
      - Is there a way to withdraw a firewall exception entirely?
      - Can a firewall exception be removed by its id?
      instructions:
      - text: Delete firewall exception {exception_id}.
        slots:
          exception_id: path.id
      - text: Remove exception {exception_id} from account {account}.
        slots:
          exception_id: path.id
          account: query.account_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/scans/exceptions/{id}/status'].put
  update:
    x-apievangelist-phrasing:
      intent: Approve or reject a firewall exception
      effect: write
      questions:
      - How do I approve a pending firewall exception?
      - Can I leave notes when rejecting an exception request?
      instructions:
      - text: Approve firewall exception {exception_id}.
        slots:
          exception_id: path.id
      - text: Set exception {exception_id} to {status} with notes {notes}.
        slots:
          exception_id: path.id
          status: requestBody.status
          notes: requestBody.notes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/scans/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: List package versions eligible for an exception
      effect: read
      questions:
      - Which versions of a package can I include in a firewall exception?
      - Can I list a package's versions in a registry before requesting an exception?
      instructions:
      - text: List versions of package {package} in registry {registry} for an exception.
        slots:
          package: query.package_name
          registry: query.registry_id
      - text: Show exception-eligible versions of {package}.
        slots:
          package: query.package_name
      method: generated
      generated: '2026-09-26'