API Evangelist conversational phrasing for Drata Evidence 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 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'