# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Drata Risk Notes API
  version: 1.0.0
extends: openapi/drata-risk-notes-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: 5
- target: $.paths['/risk-registers/{riskRegisterId}/risks/{riskId}/notes'].get
  update:
    x-apievangelist-phrasing:
      intent: List notes on a risk
      effect: read
      questions:
      - What notes have been recorded on a risk?
      - Can I see the comment history for one risk in a register?
      instructions:
      - text: List notes on risk {risk} in risk register {register}.
        slots:
          register: path.riskRegisterId
          risk: path.riskId
      - text: Show all comments on risk {risk}.
        slots:
          risk: path.riskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/risk-registers/{riskRegisterId}/risks/{riskId}/notes'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a note to a risk
      effect: write
      questions:
      - How do I add a comment to a risk?
      - Can I document treatment decisions as a note on a risk?
      instructions:
      - text: Add note {comment} to risk {risk} in register {register}.
        slots:
          register: path.riskRegisterId
          risk: path.riskId
          comment: requestBody.comment
      - text: Comment {comment} on risk {risk}.
        slots:
          comment: requestBody.comment
          risk: path.riskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/risk-registers/{riskRegisterId}/risks/{riskId}/notes/{noteId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one risk note
      effect: read
      questions:
      - Can I read a specific note on a risk?
      - What did a particular risk note say?
      instructions:
      - text: Get note {note} on risk {risk} in register {register}.
        slots:
          register: path.riskRegisterId
          risk: path.riskId
          note: path.noteId
      - text: Show risk note {note}.
        slots:
          note: path.noteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/risk-registers/{riskRegisterId}/risks/{riskId}/notes/{noteId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a risk note
      effect: write
      questions:
      - Can I edit a note I left on a risk?
      - Is it possible to correct the text of a risk comment?
      instructions:
      - text: Change note {note} on risk {risk} in register {register} to {comment}.
        slots:
          register: path.riskRegisterId
          risk: path.riskId
          note: path.noteId
          comment: requestBody.comment
      - text: Rewrite risk note {note} as {comment}.
        slots:
          note: path.noteId
          comment: requestBody.comment
      method: generated
      generated: '2026-09-26'
- target: $.paths['/risk-registers/{riskRegisterId}/risks/{riskId}/notes/{noteId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a risk note
      effect: destructive
      questions:
      - Can I remove a note from a risk?
      - Is deleting a risk comment permanent?
      instructions:
      - text: Delete note {note} from risk {risk} in register {register}.
        slots:
          register: path.riskRegisterId
          risk: path.riskId
          note: path.noteId
      - text: Remove risk note {note}.
        slots:
          note: path.noteId
      method: generated
      generated: '2026-09-26'