# 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 Documents API
  version: 1.0.0
extends: openapi/drata-risk-documents-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: 4
- target: $.paths['/risk-registers/{riskRegisterId}/risks/{riskId}/documents'].get
  update:
    x-apievangelist-phrasing:
      intent: List documents on a risk
      effect: read
      questions:
      - Which documents are attached to a specific risk?
      - Can I page through a risk's supporting documents?
      instructions:
      - text: List documents for risk {riskId} in register {riskRegisterId}.
        slots:
          riskRegisterId: path.riskRegisterId
          riskId: path.riskId
      - text: Show {size} documents per page for risk {riskId} in register {riskRegisterId}.
        slots:
          riskRegisterId: path.riskRegisterId
          riskId: path.riskId
          size: query.size
      method: generated
      generated: '2026-09-26'
- target: $.paths['/risk-registers/{riskRegisterId}/risks/{riskId}/documents'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload documents to a risk
      effect: write
      questions:
      - How do I attach supporting files to a risk?
      - What's the limit on how many files I can upload to a risk at once?
      instructions:
      - text: Upload {files} to risk {riskId} in register {riskRegisterId}.
        slots:
          riskRegisterId: path.riskRegisterId
          riskId: path.riskId
          files: requestBody.files
      - text: Attach documents {files} as evidence on risk {riskId}, register {riskRegisterId}.
        slots:
          riskRegisterId: path.riskRegisterId
          riskId: path.riskId
          files: requestBody.files
      method: generated
      generated: '2026-09-26'
- target: $.paths['/risk-registers/{riskRegisterId}/risks/{riskId}/documents/{documentId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a risk document
      effect: read
      questions:
      - Can I retrieve one specific document attached to a risk?
      - What details come back for a single risk document?
      instructions:
      - text: Get document {documentId} on risk {riskId} in register {riskRegisterId}.
        slots:
          riskRegisterId: path.riskRegisterId
          riskId: path.riskId
          documentId: path.documentId
      - text: Show risk {riskId}'s document {documentId} from register {riskRegisterId}.
        slots:
          riskRegisterId: path.riskRegisterId
          riskId: path.riskId
          documentId: path.documentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/risk-registers/{riskRegisterId}/risks/{riskId}/documents/{documentId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a risk document
      effect: destructive
      questions:
      - How do I remove a document that was attached to the wrong risk?
      - Can a single risk document be deleted without touching the risk?
      instructions:
      - text: Delete document {documentId} from risk {riskId} in register {riskRegisterId}.
        slots:
          riskRegisterId: path.riskRegisterId
          riskId: path.riskId
          documentId: path.documentId
      - text: Remove the attachment {documentId} on risk {riskId}, register {riskRegisterId}.
        slots:
          riskRegisterId: path.riskRegisterId
          riskId: path.riskId
          documentId: path.documentId
      method: generated
      generated: '2026-09-26'