# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Drata Risks API
  version: 1.0.0
extends: openapi/drata-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: 8
- target: $.paths['/risk-registers/{riskRegisterId}/risks'].get
  update:
    x-apievangelist-phrasing:
      intent: List risks in a register
      effect: read
      questions:
      - Which risks in a register are currently active?
      - Can I list a register's risks tied to a particular vendor?
      instructions:
      - text: List risks in register {riskRegisterId} with status {status}.
        slots:
          riskRegisterId: path.riskRegisterId
          status: query.status
      - text: List risks in register {riskRegisterId} scoring at least {minScore}.
        slots:
          riskRegisterId: path.riskRegisterId
          minScore: query.minScore
      method: generated
      generated: '2026-09-26'
- target: $.paths['/risk-registers/{riskRegisterId}/risks'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a risk in a register
      effect: write
      questions:
      - How do I add a custom risk to a risk register?
      - Can I set impact and likelihood when I log a new risk?
      instructions:
      - text: 'Create risk {title} in register {riskRegisterId}: {description}.'
        slots:
          riskRegisterId: path.riskRegisterId
          title: requestBody.title
          description: requestBody.description
      - text: Log risk {title} in register {riskRegisterId} as {description} with impact {impact} and likelihood {likelihood}.
        slots:
          riskRegisterId: path.riskRegisterId
          title: requestBody.title
          description: requestBody.description
          impact: requestBody.impact
          likelihood: requestBody.likelihood
      method: generated
      generated: '2026-09-26'
- target: $.paths['/risk-registers/{riskRegisterId}/risks-search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search risks within one register
      effect: read
      questions:
      - Can I full-text search the risks inside one register?
      - Which risks in one register have a residual score above a threshold?
      instructions:
      - text: Search register {riskRegisterId} for risks matching {q}.
        slots:
          riskRegisterId: path.riskRegisterId
          q: query.q
      - text: Find risks in register {riskRegisterId} owned by {ownerEmails}.
        slots:
          riskRegisterId: path.riskRegisterId
          ownerEmails: query.ownerEmails[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/risks-search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search risks across all registers
      effect: read
      questions:
      - How do I search risks across every risk register I can access?
      - Can I find all risks linked to control AC-04 in any register?
      instructions:
      - text: Search all risk registers for {q}.
        slots:
          q: query.q
      - text: Find risks across registers mapped to control {controls}.
        slots:
          controls: query.controls[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/risk-registers/{riskRegisterId}/risks/{riskId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a risk's details
      effect: read
      questions:
      - What are the details of risk RISK-001?
      - Can I look up one risk by its string identifier instead of its number?
      instructions:
      - text: Get risk {riskId} in register {riskRegisterId}.
        slots:
          riskRegisterId: path.riskRegisterId
          riskId: path.riskId
      - text: Show risk {riskId} from register {riskRegisterId} with {expand} expanded.
        slots:
          riskRegisterId: path.riskRegisterId
          riskId: path.riskId
          expand: query.expand[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/risk-registers/{riskRegisterId}/risks/{riskId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a risk
      effect: write
      questions:
      - How do I change a risk's treatment plan?
      - Can I record residual impact and likelihood after treatment?
      instructions:
      - text: Set the treatment plan of risk {riskId} in register {riskRegisterId} to {treatmentPlan}.
        slots:
          riskRegisterId: path.riskRegisterId
          riskId: path.riskId
          treatmentPlan: requestBody.treatmentPlan
      - text: Mark risk {riskId} in register {riskRegisterId} as treated on {completionDate}.
        slots:
          riskRegisterId: path.riskRegisterId
          riskId: path.riskId
          completionDate: requestBody.completionDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/risk-registers/{riskRegisterId}/risks/{riskId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a risk
      effect: destructive
      questions:
      - How do I delete a risk that was logged by mistake?
      - Can a risk be removed from a register permanently?
      instructions:
      - text: Delete risk {riskId} from register {riskRegisterId}.
        slots:
          riskRegisterId: path.riskRegisterId
          riskId: path.riskId
      - text: Permanently remove the risk {riskId} logged in register {riskRegisterId}.
        slots:
          riskRegisterId: path.riskRegisterId
          riskId: path.riskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/risk-registers/{riskRegisterId}/insights'].get
  update:
    x-apievangelist-phrasing:
      intent: Get risk register insights
      effect: read
      questions:
      - What does the risk heatmap look like for a register?
      - Can I see risk trends over time for only certain owners?
      instructions:
      - text: Get risk insights for register {riskRegisterId}.
        slots:
          riskRegisterId: path.riskRegisterId
      - text: Show risk insights for register {riskRegisterId} limited to owners {ownerIds}.
        slots:
          riskRegisterId: path.riskRegisterId
          ownerIds: query.ownerIds[]
      method: generated
      generated: '2026-09-26'