API Evangelist conversational phrasing for Drata Policies API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Drata Policies API
  version: 1.0.0
extends: openapi/drata-policies-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: 14
- target: $.paths['/policies'].get
  update:
    x-apievangelist-phrasing:
      intent: List published policies
      effect: read
      questions:
      - Which published policies does our Drata account have?
      - Can I filter our policies by status or by who is reviewing them?
      - What policies are waiting on a particular reviewer?
      instructions:
      - text: List published policies whose name contains {name}.
        slots:
          name: query.name
      - text: Show every policy where {reviewer} is a reviewer.
        slots:
          reviewer: query.reviewerUserId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/policies'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new policy with a draft version
      effect: write
      questions:
      - How do I add a brand new security policy with its first draft?
      - Can I create a policy from a file stored externally instead of uploading one?
      - What do I need to supply to start a new policy, like owner and renewal date?
      instructions:
      - text: Create a policy named {name} owned by {owner} that renews on {renewal_date}.
        slots:
          name: requestBody.name
          owner: requestBody.ownerId
          renewal_date: requestBody.renewalDate
      - text: Start a new policy {name} with description {description} and require employees to acknowledge it.
        slots:
          name: requestBody.name
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/policies/{policyId}/policy-versions'].get
  update:
    x-apievangelist-phrasing:
      intent: List the versions of a policy
      effect: read
      questions:
      - What versions exist for one of our policies?
      - Can I see which version of a policy is the current one?
      - Is there a way to filter a policy's version history by status?
      instructions:
      - text: List all versions of policy {policy}.
        slots:
          policy: path.policyId
      - text: Show only the current version entry in the version history of policy {policy}.
        slots:
          policy: path.policyId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/policies/{policyId}/policy-versions'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new version of a policy
      effect: write
      questions:
      - How do I publish a revised version of an existing policy?
      - Does a material change to a policy have to go through approval?
      - Can I record a change summary when I revise a policy?
      instructions:
      - text: 'Create a new version of policy {policy} owned by {owner}, marked as a material change: {is_material}.'
        slots:
          policy: path.policyId
          owner: requestBody.ownerId
          is_material: requestBody.isMaterialChange
      - text: Add a revised version to policy {policy} with change summary {summary}.
        slots:
          policy: path.policyId
          summary: requestBody.changeSummary
      method: generated
      generated: '2026-09-26'
- target: $.paths['/policies/{policyId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one published policy
      effect: read
      questions:
      - What are the details of a specific published policy?
      - Can I look up a single policy by its ID?
      instructions:
      - text: Get policy {policy}.
        slots:
          policy: path.policyId
      - text: Show me the details of published policy {policy}.
        slots:
          policy: path.policyId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/policies/{policyId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a policy's settings
      effect: write
      questions:
      - Can I change a policy's renewal date or renewal schedule?
      - How can I link controls or assign groups to an existing policy?
      - Is it possible to rename a policy or change its disclaimer?
      instructions:
      - text: Rename policy {policy} to {name}.
        slots:
          policy: path.policyId
          name: requestBody.name
      - text: Set the renewal date of policy {policy} to {renewal_date}.
        slots:
          policy: path.policyId
          renewal_date: requestBody.renewalDate
      - text: Map policy {policy} to controls {control_ids}.
        slots:
          policy: path.policyId
          control_ids: requestBody.controlIds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/policies/{policyId}/owner'].put
  update:
    x-apievangelist-phrasing:
      intent: Change who owns a policy
      effect: write
      questions:
      - Can I hand ownership of a policy to another person?
      - Who can be made the owner of a policy?
      instructions:
      - text: Make user {user} the owner of policy {policy}.
        slots:
          user: requestBody.userId
          policy: path.policyId
      - text: Transfer ownership of policy {policy} to {user}.
        slots:
          policy: path.policyId
          user: requestBody.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/policies/{policyId}/approval-configuration'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a policy's approval workflow
      effect: read
      questions:
      - Which review groups have to approve this policy, and in what order?
      - What does the approval sequence for a policy look like?
      instructions:
      - text: Show the approval configuration for policy {policy}.
        slots:
          policy: path.policyId
      - text: List the review tiers set up for policy {policy}.
        slots:
          policy: path.policyId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/policies/{policyId}/approval-configuration'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a review group tier to a policy
      effect: write
      questions:
      - How many approval tiers can a single policy have?
      - Can I add another group of reviewers at the end of a policy's approval chain?
      - What consensus rules can a review group use?
      instructions:
      - text: Add a review group {name} with users {users} to the end of policy {policy}'s approval sequence.
        slots:
          name: requestBody.name
          users: requestBody.userIds
          policy: path.policyId
      - text: Append a review tier {name} to policy {policy} using consensus rule {rule} and timeline {timeline}.
        slots:
          name: requestBody.name
          policy: path.policyId
          rule: requestBody.consensusRule
          timeline: requestBody.timeline
      method: generated
      generated: '2026-09-26'
- target: $.paths['/policies/{policyId}/approval-configuration/{approvalConfigurationTier}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update one review tier of a policy
      effect: write
      questions:
      - Can I change the reviewers in one approval tier without touching the others?
      - What happens if I try to edit a review tier that doesn't exist?
      instructions:
      - text: Replace the reviewers in tier {tier} of policy {policy} with {users}.
        slots:
          tier: path.approvalConfigurationTier
          policy: path.policyId
          users: requestBody.userIds
      - text: 'Update review tier {tier} of policy {policy}: name {name}, consensus rule {rule}, timeline {timeline}.'
        slots:
          tier: path.approvalConfigurationTier
          policy: path.policyId
          name: requestBody.name
          rule: requestBody.consensusRule
          timeline: requestBody.timeline
      method: generated
      generated: '2026-09-26'
- target: $.paths['/policies/{policyId}/approval-configuration/{approvalConfigurationTier}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a review tier from a policy
      effect: destructive
      questions:
      - Can I drop one of the approval tiers from a policy?
      - Is it allowed to remove the last remaining review tier?
      instructions:
      - text: Remove approval tier {tier} from policy {policy}.
        slots:
          tier: path.approvalConfigurationTier
          policy: path.policyId
      - text: Delete review group tier {tier} on policy {policy} and renumber the rest.
        slots:
          tier: path.approvalConfigurationTier
          policy: path.policyId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/policies/{policyId}/actions'].get
  update:
    x-apievangelist-phrasing:
      intent: See which actions I can take on a policy
      effect: read
      questions:
      - What can I do with this policy right now, given its state?
      - Am I allowed to publish or discard this policy yet?
      instructions:
      - text: List the actions available to me on policy {policy}.
        slots:
          policy: path.policyId
      - text: Check whether policy {policy} can be submitted for approval right now.
        slots:
          policy: path.policyId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/policies/{policyId}/actions'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit, approve, publish or discard a policy
      effect: write
      questions:
      - How do I submit a policy for approval or publish it?
      - Can I request changes on a policy draft and give a reason?
      - Is there a way to override-approve a policy?
      instructions:
      - text: Perform action {action} on policy {policy}.
        slots:
          action: requestBody.action
          policy: path.policyId
      - text: Request changes on policy {policy} with reason {reason}.
        slots:
          policy: path.policyId
          reason: requestBody.reason
      - text: Override-approve policy {policy} because {override_reason}.
        slots:
          policy: path.policyId
          override_reason: requestBody.overrideReason
      method: generated
      generated: '2026-09-26'
- target: $.paths['/policies/{policyId}/policy-versions/{policyVersionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one version of a policy
      effect: read
      questions:
      - Can I read the HTML content of a specific policy version?
      - What changed in a particular version of a policy?
      instructions:
      - text: Get version {version} of policy {policy}.
        slots:
          version: path.policyVersionId
          policy: path.policyId
      - text: Fetch the content of policy {policy} as it was in version {version}.
        slots:
          policy: path.policyId
          version: path.policyVersionId
      method: generated
      generated: '2026-09-26'