# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Drata Vendors API
  version: 1.0.0
extends: openapi/drata-vendors-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['/vendors'].get
  update:
    x-apievangelist-phrasing:
      intent: List vendors
      effect: read
      questions:
      - Which of my vendors are rated high risk?
      - Can I list vendors whose next review is overdue?
      - How do I find the vendors that are sub-processors?
      instructions:
      - text: List vendors with risk level {risk}.
        slots:
          risk: query.risk
      - text: Show vendors whose next review deadline status is {nextReviewDeadlineStatus}.
        slots:
          nextReviewDeadlineStatus: query.nextReviewDeadlineStatus[]
      - text: List vendors renewing on {renewalDate}.
        slots:
          renewalDate: query.renewalDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vendors'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a vendor
      effect: write
      questions:
      - How do I add a new third-party vendor to my inventory?
      - Can I record whether a new vendor stores personal data when adding it?
      instructions:
      - text: Add a vendor named {name} with website {url}.
        slots:
          name: requestBody.name
          url: requestBody.url
      - text: Create vendor {name} with risk level {risk} and annual contract value {cost} cents.
        slots:
          name: requestBody.name
          risk: requestBody.risk
          cost: requestBody.cost
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vendors-stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get vendor statistics
      effect: read
      questions:
      - What do my vendor counts look like broken down by scope?
      - Can vendor statistics include archived vendors?
      instructions:
      - text: Get vendor statistics for scopes {expand}.
        slots:
          expand: query.expand[]
      - text: Get vendor statistics for {expand} with includeArchived set to {includeArchived}.
        slots:
          expand: query.expand[]
          includeArchived: query.includeArchived
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vendors/{vendorId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a vendor's details
      effect: read
      questions:
      - What details do we have on file for a particular vendor?
      - Can I see one vendor's record with related data expanded?
      instructions:
      - text: Get vendor {vendorId}.
        slots:
          vendorId: path.vendorId
      - text: Show vendor {vendorId} with {expand} expanded.
        slots:
          vendorId: path.vendorId
          expand: query.expand[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vendors/{vendorId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a vendor
      effect: write
      questions:
      - How do I change an existing vendor's risk level or renewal date?
      - Can I assign a different compliance owner to a vendor we already track?
      instructions:
      - text: Set the renewal date of vendor {vendorId} to {renewalDate}.
        slots:
          vendorId: path.vendorId
          renewalDate: requestBody.renewalDate
      - text: Change vendor {vendorId}'s compliance owner to user {userId}.
        slots:
          vendorId: path.vendorId
          userId: requestBody.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vendors/{vendorId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a vendor
      effect: destructive
      questions:
      - How do I remove a vendor we no longer use?
      - Is there a way to delete a vendor record entirely?
      instructions:
      - text: Delete vendor {vendorId}.
        slots:
          vendorId: path.vendorId
      - text: Remove vendor {vendorId} from our vendor inventory.
        slots:
          vendorId: path.vendorId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vendors/{vendorId}/questionnaires'].get
  update:
    x-apievangelist-phrasing:
      intent: List questionnaires sent to a vendor
      effect: read
      questions:
      - Which questionnaires have we sent to a vendor?
      - Can I page through every questionnaire a vendor has received?
      instructions:
      - text: List questionnaires sent to vendor {vendorId}.
        slots:
          vendorId: path.vendorId
      - text: Show every questionnaire vendor {vendorId} has been sent, {size} per page.
        slots:
          vendorId: path.vendorId
          size: query.size
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vendors/{vendorId}/questionnaires'].post
  update:
    x-apievangelist-phrasing:
      intent: Email a questionnaire to a vendor
      effect: write
      questions:
      - How do I email a security questionnaire to a vendor contact?
      - Can I customize the subject line of the questionnaire email?
      instructions:
      - text: Email questionnaire {questionnaireId} to {email} at vendor {vendorId} for review {securityReviewId} with message {emailContent}.
        slots:
          vendorId: path.vendorId
          questionnaireId: requestBody.questionnaireId
          email: requestBody.email
          securityReviewId: requestBody.securityReviewId
          emailContent: requestBody.emailContent
      - text: Send vendor {vendorId} questionnaire {questionnaireId} at {email} with subject {emailSubject}.
        slots:
          vendorId: path.vendorId
          questionnaireId: requestBody.questionnaireId
          email: requestBody.email
          emailSubject: requestBody.emailSubject
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vendors/{vendorId}/questionnaires/{questionnaireId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a questionnaire sent to a vendor
      effect: read
      questions:
      - What's the status of one questionnaire I sent to a vendor?
      - Can I open a single vendor questionnaire by its ID?
      instructions:
      - text: Get questionnaire {questionnaireId} sent to vendor {vendorId}.
        slots:
          vendorId: path.vendorId
          questionnaireId: path.questionnaireId
      - text: Check the questionnaire {questionnaireId} we emailed to vendor {vendorId}.
        slots:
          vendorId: path.vendorId
          questionnaireId: path.questionnaireId
      method: generated
      generated: '2026-09-26'