# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Harness Exemptions API
  version: 1.0.0
extends: openapi/harness-exemptions-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: 22
- target: $.paths['/sto/api/v2/exemptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List security testing issue exemptions
      effect: read
      questions:
      - Which STO security issue exemptions exist in my Harness account?
      - Can I page through all the vulnerability exemptions scoped to one project?
      instructions:
      - text: List the STO issue exemptions in account {account}.
        slots:
          account: query.accountId
      - text: Show page {page} of STO exemptions for project {project} in org {org}, {pageSize} per page.
        slots:
          page: query.page
          project: query.projectId
          org: query.orgId
          pageSize: query.pageSize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/exemptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Request an exemption for a security issue
      effect: write
      questions:
      - How do I request an exemption for a vulnerability that STO flagged?
      - Can an STO issue exemption expire automatically after a set date?
      - Is it possible to also exempt future occurrences of the same security issue?
      instructions:
      - text: Request a {type} exemption for STO issue {issueId} in project {project} because {reason}.
        slots:
          type: requestBody.type
          issueId: requestBody.issueId
          project: query.projectId
          reason: requestBody.reason
      - text: Exempt issue {issueId} in org {org}, project {project}, expiring at {expiration}.
        slots:
          issueId: requestBody.issueId
          org: query.orgId
          project: query.projectId
          expiration: requestBody.expiration
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/exemptions/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up one security issue exemption
      effect: read
      questions:
      - What are the details and status of a single STO exemption by its ID?
      - Can I fetch an STO exemption regardless of which scope it was created in?
      instructions:
      - text: Get STO exemption {id} in account {account}.
        slots:
          id: path.id
          account: query.accountId
      - text: Look up STO exemption {id} as seen by pipeline execution {executionId}.
        slots:
          id: path.id
          executionId: query.executionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/exemptions/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit an existing security issue exemption
      effect: write
      questions:
      - Can I change the reason or expiration on an STO exemption I already requested?
      - How do I edit an existing security issue exemption request?
      instructions:
      - text: Update STO exemption {id} to expire at {expiration}.
        slots:
          id: path.id
          expiration: requestBody.expiration
      - text: Change the reason on STO exemption {id} to {reason}.
        slots:
          id: path.id
          reason: requestBody.reason
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/exemptions/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a security issue exemption
      effect: destructive
      questions:
      - How do I remove an STO exemption so the issue blocks pipelines again?
      - Can I delete a security issue exemption that is no longer needed?
      instructions:
      - text: Delete STO exemption {id}.
        slots:
          id: path.id
      - text: Remove STO exemption {id} from account {account}.
        slots:
          id: path.id
          account: query.accountId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/exemptions/{id}/{action}'].put
  update:
    x-apievangelist-phrasing:
      intent: Approve or reject a security issue exemption
      effect: write
      questions:
      - How do I approve a pending STO exemption request?
      - Can I reject a security issue exemption and leave a comment explaining why?
      instructions:
      - text: Apply action {action} to STO exemption {id}.
        slots:
          action: path.action
          id: path.id
      - text: Take action {action} on STO exemption {id} with comment {comment}.
        slots:
          action: path.action
          id: path.id
          comment: requestBody.comment
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/exemptions/{id}/promote'].put
  update:
    x-apievangelist-phrasing:
      intent: Promote an exemption to a higher scope
      effect: write
      questions:
      - Can I promote a project-level STO exemption so it applies across the org or account?
      - What happens when I widen an issue exemption to a higher scope?
      instructions:
      - text: Promote STO exemption {id} to a higher scope.
        slots:
          id: path.id
      - text: Promote STO exemption {id} with the note {comment}.
        slots:
          id: path.id
          comment: requestBody.comment
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/exemptions/bulk'].post
  update:
    x-apievangelist-phrasing:
      intent: Create many security issue exemptions at once
      effect: write
      questions:
      - Can I exempt many STO issues in a single request?
      - What happens to a bulk exemption batch if one item violates an exemption rule?
      instructions:
      - text: Bulk-create {type} exemptions for these issues {items} in project {project} with reason {reason}.
        slots:
          type: requestBody.type
          items: requestBody.items
          project: query.projectId
          reason: requestBody.reason
      - text: Exempt the batch of issues {items} in org {org}, project {project}, all or none.
        slots:
          items: requestBody.items
          org: query.orgId
          project: query.projectId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/exemptions/issue/{issueId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Find the exemption that applies to an issue
      effect: read
      questions:
      - Which exemption actually applies to this STO issue across account, org and project?
      - Is a given security issue currently covered by any exemption?
      instructions:
      - text: Find the highest-priority exemption for issue {issueId}.
        slots:
          issueId: path.issueId
      - text: Check whether issue {issueId} in project {project} is exempted.
        slots:
          issueId: path.issueId
          project: query.projectId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/exemptions/issue/{issueId}/history'].get
  update:
    x-apievangelist-phrasing:
      intent: Show the exemption history timeline for an issue
      effect: read
      questions:
      - Who requested, approved or rejected exemptions on this security issue over time?
      - Can I filter an issue's exemption timeline by pipeline or target?
      instructions:
      - text: Show the exemption history for issue {issueId}.
        slots:
          issueId: path.issueId
      - text: List exemption history events for issue {issueId} in pipeline {pipelineId}.
        slots:
          issueId: path.issueId
          pipelineId: query.pipelineId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sto/api/v2/exemptions/issue/{issueId}/history/export'].get
  update:
    x-apievangelist-phrasing:
      intent: Export an issue's exemption history as CSV
      effect: read
      questions:
      - Can I download the full exemption history of a security issue as a CSV file?
      - Is there a way to export an issue's exemption audit trail without paging?
      instructions:
      - text: Export the exemption history for issue {issueId} to CSV.
        slots:
          issueId: path.issueId
      - text: Download a CSV of exemption events for issue {issueId} on target {targetId}.
        slots:
          issueId: path.issueId
          targetId: query.targetId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/orgs/{org}/projects/{project}/exemptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List component exemptions in a project
      effect: read
      questions:
      - Which supply chain component exemptions are set up in my Harness project?
      - Can I filter a project's component exemptions by status or artifact?
      instructions:
      - text: List component exemptions in project {project} of org {org}.
        slots:
          project: path.project
          org: path.org
      - text: Show {status} component exemptions in project {project}, org {org}.
        slots:
          status: query.status
          project: path.project
          org: path.org
      - text: Search component exemptions in project {project}, org {org} for {search_term}.
        slots:
          project: path.project
          org: path.org
          search_term: query.search_term
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/orgs/{org}/projects/{project}/exemptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Exempt a component across a project
      effect: write
      questions:
      - How do I exempt an open source component version for every artifact in a project?
      - Can a project-wide component exemption be limited to a duration?
      instructions:
      - text: Create a project-wide exemption for component {component_name} {component_version} in project {project}, org {org}.
        slots:
          component_name: requestBody.component_name
          component_version: requestBody.component_version
          project: path.project
          org: path.org
      - text: Exempt component {component_name} across project {project} in org {org} for {exemption_duration} because {reason}.
        slots:
          component_name: requestBody.component_name
          project: path.project
          org: path.org
          exemption_duration: requestBody.exemption_duration
          reason: requestBody.reason
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/orgs/{org}/projects/{project}/artifacts/{artifact}/exemptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Exempt a component for one artifact
      effect: write
      questions:
      - Can I exempt a component only for a single artifact instead of the whole project?
      - How do I add a component exemption scoped to one artifact?
      instructions:
      - text: Create an exemption for component {component_name} on artifact {artifact} in project {project}, org {org}.
        slots:
          component_name: requestBody.component_name
          artifact: path.artifact
          project: path.project
          org: path.org
      - text: Exempt {component_name} version {component_version} only on artifact {artifact} in org {org}, project {project}.
        slots:
          component_name: requestBody.component_name
          component_version: requestBody.component_version
          artifact: path.artifact
          org: path.org
          project: path.project
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/orgs/{org}/projects/{project}/exemptions/{exemption}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a project-level component exemption
      effect: read
      questions:
      - What are the details of one project-wide component exemption?
      - Can I see the reason and duration on a project component exemption?
      instructions:
      - text: Get project component exemption {exemption} in project {project}, org {org}.
        slots:
          exemption: path.exemption
          project: path.project
          org: path.org
      - text: Show the project-level exemption {exemption} for org {org}, project {project}.
        slots:
          exemption: path.exemption
          org: path.org
          project: path.project
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/orgs/{org}/projects/{project}/exemptions/{exemption}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a project-level component exemption
      effect: write
      questions:
      - Can I change the component version range on a project-wide exemption?
      - How do I extend the duration of a project component exemption?
      instructions:
      - text: Update project exemption {exemption} in project {project}, org {org} to last {exemption_duration}.
        slots:
          exemption: path.exemption
          project: path.project
          org: path.org
          exemption_duration: requestBody.exemption_duration
      - text: Change project exemption {exemption} in org {org}, project {project} to cover version {component_version}.
        slots:
          exemption: path.exemption
          org: path.org
          project: path.project
          component_version: requestBody.component_version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/orgs/{org}/projects/{project}/exemptions/{exemption}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a project-level component exemption
      effect: destructive
      questions:
      - How do I remove a project-wide component exemption?
      - Can I delete a component exemption that applies to a whole project?
      instructions:
      - text: Delete project component exemption {exemption} from project {project}, org {org}.
        slots:
          exemption: path.exemption
          project: path.project
          org: path.org
      - text: Remove the project-level exemption {exemption} in org {org}, project {project}.
        slots:
          exemption: path.exemption
          org: path.org
          project: path.project
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/orgs/{org}/projects/{project}/artifacts/{artifact}/exemptions/{exemption}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an artifact-level component exemption
      effect: read
      questions:
      - What does a component exemption on a specific artifact look like?
      - Can I check the status of an exemption tied to one artifact?
      instructions:
      - text: Get exemption {exemption} on artifact {artifact} in project {project}, org {org}.
        slots:
          exemption: path.exemption
          artifact: path.artifact
          project: path.project
          org: path.org
      - text: Show artifact {artifact}'s exemption {exemption} in org {org}, project {project}.
        slots:
          artifact: path.artifact
          exemption: path.exemption
          org: path.org
          project: path.project
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/orgs/{org}/projects/{project}/artifacts/{artifact}/exemptions/{exemption}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit an artifact-level component exemption
      effect: write
      questions:
      - Can I change the reason on a component exemption tied to one artifact?
      - How do I modify an exemption that only applies to a single artifact?
      instructions:
      - text: Update exemption {exemption} on artifact {artifact} in project {project}, org {org} with reason {reason}.
        slots:
          exemption: path.exemption
          artifact: path.artifact
          project: path.project
          org: path.org
          reason: requestBody.reason
      - text: Set artifact {artifact}'s exemption {exemption} in org {org}, project {project} to last {exemption_duration}.
        slots:
          artifact: path.artifact
          exemption: path.exemption
          org: path.org
          project: path.project
          exemption_duration: requestBody.exemption_duration
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/orgs/{org}/projects/{project}/artifacts/{artifact}/exemptions/{exemption}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an artifact-level component exemption
      effect: destructive
      questions:
      - How do I remove a component exemption from a single artifact?
      - Can I delete just one artifact's exemption without touching project-wide ones?
      instructions:
      - text: Delete exemption {exemption} on artifact {artifact} in project {project}, org {org}.
        slots:
          exemption: path.exemption
          artifact: path.artifact
          project: path.project
          org: path.org
      - text: Remove artifact {artifact}'s component exemption {exemption} from org {org}, project {project}.
        slots:
          artifact: path.artifact
          exemption: path.exemption
          org: path.org
          project: path.project
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/orgs/{org}/projects/{project}/exemptions/{exemption}/review'].put
  update:
    x-apievangelist-phrasing:
      intent: Review a project-level component exemption
      effect: write
      questions:
      - How do I approve or reject a project-wide component exemption request?
      - Can I leave a review comment when deciding on a project exemption?
      instructions:
      - text: Review project exemption {exemption} in project {project}, org {org} and set it to {exemption_status}.
        slots:
          exemption: path.exemption
          project: path.project
          org: path.org
          exemption_status: requestBody.exemption_status
      - text: Mark project exemption {exemption} in org {org}, project {project} as {exemption_status} with comment {review_comment}.
        slots:
          exemption: path.exemption
          org: path.org
          project: path.project
          exemption_status: requestBody.exemption_status
          review_comment: requestBody.review_comment
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/orgs/{org}/projects/{project}/artifacts/{artifact}/exemptions/{exemption}/review'].put
  update:
    x-apievangelist-phrasing:
      intent: Review an artifact-level component exemption
      effect: write
      questions:
      - How do I approve or reject a component exemption requested for one artifact?
      - Can a reviewer comment on an artifact-specific exemption decision?
      instructions:
      - text: Review exemption {exemption} on artifact {artifact} in project {project}, org {org} as {exemption_status}.
        slots:
          exemption: path.exemption
          artifact: path.artifact
          project: path.project
          org: path.org
          exemption_status: requestBody.exemption_status
      - text: Set artifact {artifact}'s exemption {exemption} in org {org}, project {project} to {exemption_status} noting {review_comment}.
        slots:
          artifact: path.artifact
          exemption: path.exemption
          org: path.org
          project: path.project
          exemption_status: requestBody.exemption_status
          review_comment: requestBody.review_comment
      method: generated
      generated: '2026-09-26'