# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Drata Controls API
  version: 1.0.0
extends: openapi/drata-controls-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: 8
- target: $.paths['/workspaces/{workspaceId}/controls'].get
  update:
    x-apievangelist-phrasing:
      intent: List controls in a workspace
      effect: read
      questions:
      - Which of our controls are not ready yet?
      - Can I find controls that have no evidence or no passing test?
      - What controls are linked to a specific policy?
      instructions:
      - text: List controls in workspace {workspace}.
        slots:
          workspace: path.workspaceId
      - text: Show controls in workspace {workspace} tied to policy {policy}.
        slots:
          workspace: path.workspaceId
          policy: query.policyId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/controls'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom control
      effect: write
      questions:
      - How do I add our own custom control?
      - Can I attach policies, tests and owners when creating a control?
      instructions:
      - text: Create a custom control {name} with code {code} and description {description} in workspace {workspace}.
        slots:
          name: requestBody.name
          code: requestBody.code
          description: requestBody.description
          workspace: path.workspaceId
      - text: Add control {code} named {name} and assign owners {owners}.
        slots:
          code: requestBody.code
          name: requestBody.name
          owners: requestBody.ownersIds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/controls/{controlId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a control's full detail
      effect: read
      questions:
      - What is everything recorded about one control?
      - Can I look up a single control by its ID?
      instructions:
      - text: Get control {control} in workspace {workspace}.
        slots:
          control: path.controlId
          workspace: path.workspaceId
      - text: Show me all the information for control {control}.
        slots:
          control: path.controlId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/controls/{controlId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a control
      effect: write
      questions:
      - Can I rename a control or change its code?
      - Is it possible to re-map a control to different policies or tests?
      instructions:
      - text: Rename control {control} in workspace {workspace} to {name}.
        slots:
          control: path.controlId
          workspace: path.workspaceId
          name: requestBody.name
      - text: Link control {control} to tests {tests}.
        slots:
          control: path.controlId
          tests: requestBody.testIds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/controls/{controlId}/requirements'].get
  update:
    x-apievangelist-phrasing:
      intent: List the requirements a control maps to
      effect: read
      questions:
      - Which framework requirements does a control satisfy?
      - Can I see a control's requirements for just one framework?
      instructions:
      - text: List requirements mapped to control {control} in workspace {workspace}.
        slots:
          control: path.controlId
          workspace: path.workspaceId
      - text: Show requirements for control {control} in framework {framework}.
        slots:
          control: path.controlId
          framework: query.frameworkSlug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/controls/action-reset-mappings'].post
  update:
    x-apievangelist-phrasing:
      intent: Reset controls to template mappings
      effect: write
      questions:
      - Can I undo our changes to control requirement mappings?
      - Which controls can't be reset to their original mappings?
      instructions:
      - text: Reset requirement mappings for controls {controls} in workspace {workspace}.
        slots:
          controls: requestBody.controlIds
          workspace: path.workspaceId
      - text: Restore the template requirement mappings on controls {controls}.
        slots:
          controls: requestBody.controlIds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/controls/{controlId}/actions'].post
  update:
    x-apievangelist-phrasing:
      intent: Mark a control in or out of scope
      effect: write
      questions:
      - How do I mark a control as out of scope?
      - Can I bring an out-of-scope control back into scope?
      instructions:
      - text: Mark control {control} in workspace {workspace} out of scope because {rationale}.
        slots:
          control: path.controlId
          workspace: path.workspaceId
          rationale: requestBody.rationale
      - text: Apply action {action} to control {control}.
        slots:
          action: requestBody.action
          control: path.controlId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/controls-requirement-comparison'].get
  update:
    x-apievangelist-phrasing:
      intent: Compare control mappings with templates
      effect: read
      questions:
      - How do our control requirement mappings differ from the template defaults?
      - Can I compare several controls against their template mappings at once?
      instructions:
      - text: Compare requirement mappings for controls {controls} in workspace {workspace} against the templates.
        slots:
          controls: query.controlIds[]
          workspace: path.workspaceId
      - text: Show where controls {controls} drift from their global template mappings.
        slots:
          controls: query.controlIds[]
      method: generated
      generated: '2026-09-26'