# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Tech Risk & Compliance - IT Risk Management API
  version: 1.0.0
extends: openapi/onetrust-risk-management-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: 8
- target: $.paths['/api/risk/v2/risks/upsert'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or update a risk by matching attributes
      effect: write
      questions:
      - Can I upsert a risk so it's created only if no matching risk exists?
      - Which attributes decide whether an upsert updates an existing risk?
      instructions:
      - text: Upsert a {type} risk from source {source} on inventory {associatedInventory} in org {orgGroupId}, matching on {matchAttributes}.
        slots:
          type: requestBody.type
          source: requestBody.source
          associatedInventory: requestBody.associatedInventory
          orgGroupId: requestBody.orgGroupId
          matchAttributes: query.matchAttributes
      - text: Create or update risk {name} matched by {matchAttributes}, type {type}, source {source}, inventory {associatedInventory}, org {orgGroupId}.
        slots:
          name: requestBody.name
          matchAttributes: query.matchAttributes
          type: requestBody.type
          source: requestBody.source
          associatedInventory: requestBody.associatedInventory
          orgGroupId: requestBody.orgGroupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/risk/v2/risks/{id}/assign-stage'].post
  update:
    x-apievangelist-phrasing:
      intent: Move a risk to a workflow stage
      effect: write
      questions:
      - How do I advance a risk to the next stage in its workflow?
      - Can I send a risk back a stage with a comment?
      instructions:
      - text: Move risk {id} {direction} to stage {nextStageId}.
        slots:
          id: path.id
          direction: requestBody.direction
          nextStageId: requestBody.nextStageId
      - text: Send risk {id} {direction} in its workflow with comment {comment}.
        slots:
          id: path.id
          direction: requestBody.direction
          comment: requestBody.comment
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/risk/v2/risks/{riskId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a risk's details
      effect: write
      questions:
      - Can I fully update a risk's name, description, owners and treatment in one call?
      - What result value is required when updating a risk in full?
      instructions:
      - text: Update risk {riskId} with result {result} and description {description}.
        slots:
          riskId: path.riskId
          result: requestBody.result
          description: requestBody.description
      - text: 'Fully update risk {riskId}: set result {result}, treatment {treatment}, deadline {deadline}.'
        slots:
          riskId: path.riskId
          result: requestBody.result
          treatment: requestBody.treatment
          deadline: requestBody.deadline
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/risk/v2/risks/{riskId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a risk
      effect: destructive
      questions:
      - Can I remove a risk from the risk register?
      - Is deleting a risk permanent?
      instructions:
      - text: Delete risk {riskId}.
        slots:
          riskId: path.riskId
      - text: Remove risk {riskId} from the risk register.
        slots:
          riskId: path.riskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/risk/v2/risks/{riskId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially modify a risk
      effect: write
      questions:
      - Can I change just a risk's deadline without resending everything?
      - What setting must be on to change a risk's managing organization?
      instructions:
      - text: Change the deadline of risk {riskId} to {deadline}.
        slots:
          riskId: path.riskId
          deadline: requestBody.deadline
      - text: Patch risk {riskId} to target risk level {targetRiskLevel}.
        slots:
          riskId: path.riskId
          targetRiskLevel: requestBody.targetRiskLevel
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/risk/v2/risks/{riskId}/approvers'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a risk's approvers
      effect: write
      questions:
      - Who can approve a risk, and can I change them?
      - Why can't I change approvers on a risk in the Monitoring stage?
      instructions:
      - text: Set the approvers of risk {riskId} to {riskApprovers}.
        slots:
          riskId: path.riskId
          riskApprovers: requestBody.riskApprovers
      - text: Replace risk {riskId}'s approvers with {riskApprovers}.
        slots:
          riskId: path.riskId
          riskApprovers: requestBody.riskApprovers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/risk/v2/risks/{riskId}/categories'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a risk's categories
      effect: write
      questions:
      - Can I recategorize an existing risk?
      - Is there a call just for changing the categories on a risk?
      instructions:
      - text: Update the categories on risk {riskId}.
        slots:
          riskId: path.riskId
      - text: Recategorize risk {riskId}.
        slots:
          riskId: path.riskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/risk/v2/risks/{riskId}/owners'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a risk's owners
      effect: write
      questions:
      - Can I reassign who owns a risk?
      - Are there stages where risk owners can't be changed?
      instructions:
      - text: Set the owners of risk {riskId} to {riskOwners}.
        slots:
          riskId: path.riskId
          riskOwners: requestBody.riskOwners
      - text: Reassign risk {riskId} to owners {riskOwners}.
        slots:
          riskId: path.riskId
          riskOwners: requestBody.riskOwners
      method: generated
      generated: '2026-09-26'