# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Drata Vendor Security Reviews API
  version: 1.0.0
extends: openapi/drata-vendor-security-reviews-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: 11
- target: $.paths['/vendors/{vendorId}/security-reviews'].get
  update:
    x-apievangelist-phrasing:
      intent: List a vendor's security reviews
      effect: read
      questions:
      - What security reviews have been done for one particular vendor?
      - Can I filter a single vendor's reviews by decision, like rejected?
      instructions:
      - text: List security reviews for vendor {vendorId}.
        slots:
          vendorId: path.vendorId
      - text: Show vendor {vendorId}'s security reviews with decision {decision}.
        slots:
          vendorId: path.vendorId
          decision: query.decision[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vendors/{vendorId}/security-reviews'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a vendor security review
      effect: write
      questions:
      - How do I open a new security review for a vendor with a deadline?
      - Can I record who requested a vendor review when I create it?
      instructions:
      - text: Start a {securityReviewType} review for vendor {vendorId} due {reviewDeadlineAt} with status {securityReviewStatus}.
        slots:
          vendorId: path.vendorId
          securityReviewType: requestBody.securityReviewType
          reviewDeadlineAt: requestBody.reviewDeadlineAt
          securityReviewStatus: requestBody.securityReviewStatus
      - text: Create review {title} for vendor {vendorId}, requested by user {requesterUserId}, due {reviewDeadlineAt}.
        slots:
          vendorId: path.vendorId
          title: requestBody.title
          requesterUserId: requestBody.requesterUserId
          reviewDeadlineAt: requestBody.reviewDeadlineAt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vendors/{vendorId}/security-reviews/with-file'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a vendor review with an attached file
      effect: write
      questions:
      - Can I create a vendor security review and upload its report file in one step?
      - Which file types can I attach when creating a review together with a document?
      instructions:
      - text: Create review {title} for vendor {vendorId} with file {file}, due {reviewDeadlineAt}, type {securityReviewType}, status {securityReviewStatus}.
        slots:
          vendorId: path.vendorId
          title: requestBody.title
          file: requestBody.file
          reviewDeadlineAt: requestBody.reviewDeadlineAt
          securityReviewType: requestBody.securityReviewType
          securityReviewStatus: requestBody.securityReviewStatus
      - text: Open a review on vendor {vendorId} and attach {file} as a {documentType} document.
        slots:
          vendorId: path.vendorId
          file: requestBody.file
          documentType: requestBody.documentType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vendor-security-reviews'].get
  update:
    x-apievangelist-phrasing:
      intent: List security reviews across all vendors
      effect: read
      questions:
      - Where can I see every vendor security review in the account at once?
      - Can I filter reviews across all vendors by when they were last updated?
      instructions:
      - text: List security reviews across all vendors with status {status}.
        slots:
          status: query.status[]
      - text: Show reviews for vendors {vendorIds} created since {createdAtFrom}.
        slots:
          vendorIds: query.vendorIds[]
          createdAtFrom: query.createdAtFrom
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vendors/{vendorId}/security-reviews/{securityReviewId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one vendor security review
      effect: read
      questions:
      - How do I see the SOC report form data for one vendor review?
      - What are the full details of a single security review?
      instructions:
      - text: Get security review {securityReviewId} for vendor {vendorId}.
        slots:
          vendorId: path.vendorId
          securityReviewId: path.securityReviewId
      - text: Show review {securityReviewId} of vendor {vendorId} with {expand} expanded.
        slots:
          vendorId: path.vendorId
          securityReviewId: path.securityReviewId
          expand: query.expand[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vendors/{vendorId}/security-reviews/{securityReviewId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a vendor security review
      effect: write
      questions:
      - Can I rename a vendor security review after it's created?
      - How do I fill in the SOC form on a SOC report review?
      instructions:
      - text: Rename security review {securityReviewId} of vendor {vendorId} to {title}.
        slots:
          vendorId: path.vendorId
          securityReviewId: path.securityReviewId
          title: requestBody.title
      - text: Save SOC form data {socForm} on review {securityReviewId} for vendor {vendorId}.
        slots:
          vendorId: path.vendorId
          securityReviewId: path.securityReviewId
          socForm: requestBody.socForm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vendors/{vendorId}/security-questionnaires'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a questionnaire to a vendor
      effect: write
      questions:
      - Can I upload a completed security questionnaire at the vendor level, not tied to a review?
      - Which file formats does the vendor-level questionnaire upload accept?
      instructions:
      - text: Upload questionnaire files {files} to vendor {vendorId} without linking a review.
        slots:
          vendorId: path.vendorId
          files: requestBody.files
      - text: Add security questionnaire {files} to vendor {vendorId}'s record.
        slots:
          vendorId: path.vendorId
          files: requestBody.files
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vendors/{vendorId}/security-reviews/{securityReviewId}/security-questionnaires'].get
  update:
    x-apievangelist-phrasing:
      intent: List questionnaires on a security review
      effect: read
      questions:
      - Which questionnaires belong to one vendor security review?
      - Are archived questionnaires left out when listing a review's questionnaires?
      instructions:
      - text: List questionnaires attached to review {securityReviewId} of vendor {vendorId}.
        slots:
          vendorId: path.vendorId
          securityReviewId: path.securityReviewId
      - text: Show {size} questionnaires per page for security review {securityReviewId} on vendor {vendorId}.
        slots:
          vendorId: path.vendorId
          securityReviewId: path.securityReviewId
          size: query.size
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vendors/{vendorId}/security-reviews/{securityReviewId}/security-questionnaires'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a questionnaire to a security review
      effect: write
      questions:
      - How do I attach a questionnaire file to a specific security review?
      - Can a vendor's questionnaire be filed under one review instead of the vendor overall?
      instructions:
      - text: Upload {files} as a questionnaire for security review {securityReviewId} on vendor {vendorId}.
        slots:
          vendorId: path.vendorId
          securityReviewId: path.securityReviewId
          files: requestBody.files
      - text: File the completed questionnaire {files} under review {securityReviewId} of vendor {vendorId}.
        slots:
          vendorId: path.vendorId
          securityReviewId: path.securityReviewId
          files: requestBody.files
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vendors/{vendorId}/security-reviews/{securityReviewId}/actions'].get
  update:
    x-apievangelist-phrasing:
      intent: List available actions for a security review
      effect: read
      questions:
      - Which actions, like finalize or reopen, are available for a review right now?
      - Can this vendor review be finalized yet, given its current state?
      instructions:
      - text: List available actions for review {securityReviewId} of vendor {vendorId}.
        slots:
          vendorId: path.vendorId
          securityReviewId: path.securityReviewId
      - text: Check whether review {securityReviewId} on vendor {vendorId} can be finalized or reopened.
        slots:
          vendorId: path.vendorId
          securityReviewId: path.securityReviewId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vendors/{vendorId}/security-reviews/{securityReviewId}/actions'].post
  update:
    x-apievangelist-phrasing:
      intent: Finalize or reopen a security review
      effect: write
      questions:
      - How do I finalize a vendor security review as approved with conditions?
      - Can I reopen a finalized review and reset its decision to pending?
      instructions:
      - text: Run {action} on security review {securityReviewId} for vendor {vendorId}.
        slots:
          vendorId: path.vendorId
          securityReviewId: path.securityReviewId
          action: requestBody.action
      - text: Finalize review {securityReviewId} for vendor {vendorId} with decision {decision} and note {note}.
        slots:
          vendorId: path.vendorId
          securityReviewId: path.securityReviewId
          decision: requestBody.decision
          note: requestBody.note
      method: generated
      generated: '2026-09-26'