# 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 Risks API
  version: 1.0.0
extends: openapi/onetrust-risks-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: 9
- target: $.paths['/api/risk/v2/entities/risks/unlink'].post
  update:
    x-apievangelist-phrasing:
      intent: Unlink risks from an entity
      effect: write
      questions:
      - How do I detach risks from an asset or vendor without deleting them?
      - Can I disassociate several risks from one entity at once?
      instructions:
      - text: Unlink risks {riskIds} from the entity described by {riskSourceInformation}.
        slots:
          riskIds: requestBody.riskIds
          riskSourceInformation: requestBody.riskSourceInformation
      - text: Disassociate risk {riskIds} from its target entity {riskSourceInformation}.
        slots:
          riskIds: requestBody.riskIds
          riskSourceInformation: requestBody.riskSourceInformation
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/risk/v2/risk-categories'].get
  update:
    x-apievangelist-phrasing:
      intent: List risk categories
      effect: read
      questions:
      - What risk categories are configured in my risk register?
      - Where do I find the category IDs to tag a risk with?
      instructions:
      - text: List all risk categories with their IDs and descriptions.
      - text: Show me the available risk categories.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/risk/v2/risk-settings/matrix'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the risk matrix scoring configuration
      effect: read
      questions:
      - How are impact and probability combined into a score in my risk matrix?
      - What impact and probability levels does the risk matrix define?
      instructions:
      - text: Show the risk score matrix configuration.
      - text: Get the impact and probability levels from the risk matrix settings.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/risk/v2/risk-settings/standard'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the standard risk level configuration
      effect: read
      questions:
      - What score ranges define low, medium and high risk under the standard configuration?
      - Which risk levels exist in the standard scoring setup?
      instructions:
      - text: Show the standard risk levels with their minimum and maximum scores.
      - text: Get the standard risk score configuration.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/risk/v2/risks'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a risk tied to an inventory (v2)
      effect: write
      questions:
      - How do I log a new risk against an asset in the risk register?
      - Can I set impact and probability levels when creating a risk on an inventory?
      instructions:
      - text: Create a v2 risk of type {type} from source {source} on inventory {associatedInventory} for org group {orgGroupId}.
        slots:
          type: requestBody.type
          source: requestBody.source
          associatedInventory: requestBody.associatedInventory
          orgGroupId: requestBody.orgGroupId
      - text: Log risk {name} against inventory {associatedInventory} (type {type}, source {source}, org group {orgGroupId}) with deadline {deadline}.
        slots:
          name: requestBody.name
          associatedInventory: requestBody.associatedInventory
          type: requestBody.type
          source: requestBody.source
          orgGroupId: requestBody.orgGroupId
          deadline: requestBody.deadline
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/risk/v2/risks/pages'].post
  update:
    x-apievangelist-phrasing:
      intent: Search and list risks in the register
      effect: read
      questions:
      - Which risks in my register match a keyword?
      - Can I filter and sort the full risk register list?
      instructions:
      - text: Search the risk register for {fullTextSearch}.
        slots:
          fullTextSearch: requestBody.fullTextSearch
      - text: List risks matching filters {filters}, sorted by {sort}.
        slots:
          filters: requestBody.filters
          sort: query.sort
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/risk/v2/risks/{riskEntityType}/{entityId}/risks'].post
  update:
    x-apievangelist-phrasing:
      intent: List risks linked to a specific entity
      effect: read
      questions:
      - What risks are attached to a particular vendor or asset?
      - Can I include risks from child inventories when listing an entity's risks?
      instructions:
      - text: List the risks linked to {riskEntityType} {entityId}.
        slots:
          riskEntityType: path.riskEntityType
          entityId: path.entityId
      - text: Show risks on {riskEntityType} {entityId} including child inventory risks.
        slots:
          riskEntityType: path.riskEntityType
          entityId: path.entityId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/risk/v2/risks/{riskId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single risk's details
      effect: read
      questions:
      - Who owns and approves a particular risk, and what is its status?
      - What does the full record of one risk contain?
      instructions:
      - text: Show risk {riskId}.
        slots:
          riskId: path.riskId
      - text: Tell me the owners, approvers and status of risk {riskId}.
        slots:
          riskId: path.riskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/risk/v3/risks'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a standalone risk (v3)
      effect: write
      questions:
      - How do I create a risk that is not tied to an inventory record?
      - Can I set inherent and residual risk levels on a new v3 risk?
      instructions:
      - text: Create a standalone v3 risk {name} for org group {orgGroupId}.
        slots:
          name: requestBody.name
          orgGroupId: requestBody.orgGroupId
      - text: Add a v3 risk in org group {orgGroupId} with inherent level {inherentRiskLevel} and treatment plan {treatmentPlan}.
        slots:
          orgGroupId: requestBody.orgGroupId
          inherentRiskLevel: requestBody.inherentRiskLevel
          treatmentPlan: requestBody.treatmentPlan
      method: generated
      generated: '2026-09-26'