# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand. overlay: 1.0.0 info: title: API Evangelist conversational phrasing for Drata Evidence API version: 1.0.0 extends: openapi/drata-evidence-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: 10 - target: $.paths['/workspaces/{workspaceId}/evidence'].get update: x-apievangelist-phrasing: intent: List evidence items in a workspace effect: read questions: - What evidence do we have collected for our compliance program? - Can I filter evidence by framework, owner or status? - Which evidence items contain a particular type of artifact? instructions: - text: List evidence items in workspace {workspace}. slots: workspace: path.workspaceId - text: Find evidence named {name} in workspace {workspace}. slots: name: query.name workspace: path.workspaceId method: generated generated: '2026-09-26' - target: $.paths['/workspaces/{workspaceId}/evidence'].post update: x-apievangelist-phrasing: intent: Create an evidence item with artifacts effect: write questions: - How do I add new evidence and attach files to it? - Can I link new evidence to controls when I create it? - Do I have to upload files before creating the evidence item? instructions: - text: Create evidence {name} in workspace {workspace} with artifacts {artifacts}. slots: name: requestBody.name workspace: path.workspaceId artifacts: requestBody.artifacts - text: Add evidence {name} to workspace {workspace}, owned by {owner} and linked to controls {controls}. slots: name: requestBody.name workspace: path.workspaceId owner: requestBody.ownerId controls: requestBody.controlIds method: generated generated: '2026-09-26' - target: $.paths['/workspaces/{workspaceId}/evidence-files'].post update: x-apievangelist-phrasing: intent: Pre-upload a file for evidence effect: write questions: - Can I send an evidence file as Base64 instead of multipart? - How do I get a file key to reference in an evidence item? instructions: - text: Upload this file to workspace {workspace} so I can use it as an evidence artifact. slots: workspace: path.workspaceId - text: Pre-upload the Base64 file {base64} to workspace {workspace} and give me the file key. slots: base64: requestBody.base64File workspace: path.workspaceId method: generated generated: '2026-09-26' - target: $.paths['/workspaces/{workspaceId}/evidence/{evidenceId}'].get update: x-apievangelist-phrasing: intent: Get one evidence item effect: read questions: - What does a single evidence item contain? - Can I look up evidence by its ID? instructions: - text: Get evidence {evidence} in workspace {workspace}. slots: evidence: path.evidenceId workspace: path.workspaceId - text: Show me the details of evidence item {evidence}. slots: evidence: path.evidenceId method: generated generated: '2026-09-26' - target: $.paths['/workspaces/{workspaceId}/evidence/{evidenceId}'].put update: x-apievangelist-phrasing: intent: Update an evidence item and its artifacts effect: write questions: - Can I replace or archive artifacts while editing an evidence item? - How can I change the renewal date on existing evidence? - Is it possible to add new artifacts to evidence I already created? instructions: - text: Update evidence {evidence} in workspace {workspace} to renew on {renewal_date}. slots: evidence: path.evidenceId workspace: path.workspaceId renewal_date: requestBody.renewalDate - text: Add new artifacts {artifacts} to existing evidence {evidence}. slots: artifacts: requestBody.newArtifacts evidence: path.evidenceId method: generated generated: '2026-09-26' - target: $.paths['/workspaces/{workspaceId}/evidence/{evidenceId}'].delete update: x-apievangelist-phrasing: intent: Permanently delete an evidence item effect: destructive questions: - Can I remove an evidence item together with all its artifacts? - Is deleting evidence permanent? instructions: - text: Delete evidence {evidence} from workspace {workspace}. slots: evidence: path.evidenceId workspace: path.workspaceId - text: Permanently remove evidence item {evidence} and everything attached to it. slots: evidence: path.evidenceId method: generated generated: '2026-09-26' - target: $.paths['/workspaces/{workspaceId}/evidence/{evidenceId}/artifacts'].get update: x-apievangelist-phrasing: intent: List the artifacts on an evidence item effect: read questions: - Which files, URLs or tickets are attached to an evidence item? - Can I see only the archived artifacts on a piece of evidence? instructions: - text: List artifacts on evidence {evidence} in workspace {workspace}. slots: evidence: path.evidenceId workspace: path.workspaceId - text: Show the archived artifacts of evidence {evidence}. slots: evidence: path.evidenceId method: generated generated: '2026-09-26' - target: $.paths['/workspaces/{workspaceId}/evidence/{evidenceId}/artifacts/{artifactId}'].put update: x-apievangelist-phrasing: intent: Rename an artifact or change its filed date effect: write questions: - Can I rename a single artifact without replacing its file? - How do I correct the filed date on one artifact? instructions: - text: Rename artifact {artifact} on evidence {evidence} in workspace {workspace} to {artifact_name}. slots: artifact: path.artifactId evidence: path.evidenceId workspace: path.workspaceId artifact_name: requestBody.artifactName - text: Set the filed date of artifact {artifact} to {filed_at}. slots: artifact: path.artifactId filed_at: requestBody.filedAt method: generated generated: '2026-09-26' - target: $.paths['/workspaces/{workspaceId}/evidence/{evidenceId}/artifacts/{artifactId}'].delete update: x-apievangelist-phrasing: intent: Delete one artifact and its history effect: destructive questions: - Can I delete just one artifact and keep the evidence item? - Does deleting an artifact also wipe its version history? instructions: - text: Delete artifact {artifact} from evidence {evidence} in workspace {workspace}. slots: artifact: path.artifactId evidence: path.evidenceId workspace: path.workspaceId - text: Permanently remove artifact {artifact} including all its versions. slots: artifact: path.artifactId method: generated generated: '2026-09-26' - target: $.paths['/workspaces/{workspaceId}/evidence/{evidenceId}/artifacts/{artifactId}/actions'].post update: x-apievangelist-phrasing: intent: Archive or restore an evidence artifact effect: write questions: - Can I move an artifact to past artifacts without deleting it? - Is archiving an evidence artifact reversible? instructions: - text: Archive artifact {artifact} on evidence {evidence} in workspace {workspace}. slots: artifact: path.artifactId evidence: path.evidenceId workspace: path.workspaceId - text: Run action {action} on artifact {artifact} of evidence {evidence}. slots: action: requestBody.action artifact: path.artifactId evidence: path.evidenceId method: generated generated: '2026-09-26'