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