# 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'