Drata · OpenAPI Overlay 1.0.0

API Evangelist conversational phrasing for Drata Control Owners API

5 actions 5 updates phrasing extends openapi/drata-control-owners-api-openapi.yml
Generated by API Evangelist Written by API Evangelist tooling for Drata's API. It is a proposal applied on top of the contract, not a document Drata publishes.
View Overlay File View on GitHub Overlay Specification

What the actions change

x-apievangelist-phrasing

Targets 5

$.info
$.paths['/workspaces/{workspaceId}/controls/{controlId}/owners'].get
$.paths['/workspaces/{workspaceId}/controls/{controlId}/owners'].put
$.paths['/workspaces/{workspaceId}/controls/{controlId}/owners'].post
$.paths['/workspaces/{workspaceId}/controls/{controlId}/owners/{ownerId}'].delete

OpenAPI Overlay

Raw ↑ 
# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Drata Control Owners API
  version: 1.0.0
extends: openapi/drata-control-owners-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: 4
- target: $.paths['/workspaces/{workspaceId}/controls/{controlId}/owners'].get
  update:
    x-apievangelist-phrasing:
      intent: List a control's owners
      effect: read
      questions:
      - Who owns a given control?
      - Can I check whether a particular user is among a control's owners?
      instructions:
      - text: List owners of control {control} in workspace {workspace}.
        slots:
          workspace: path.workspaceId
          control: path.controlId
      - text: Show who is responsible for control {control}.
        slots:
          control: path.controlId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/controls/{controlId}/owners'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace all owners of a control
      effect: write
      questions:
      - Can I set the full list of owners for a control in one go?
      - What happens to existing owners when I replace a control's owner list?
      instructions:
      - text: Set the owners of control {control} in workspace {workspace} to {owners}.
        slots:
          workspace: path.workspaceId
          control: path.controlId
          owners: requestBody.ownerUserIds
      - text: Replace every owner on control {control} with users {owners}.
        slots:
          control: path.controlId
          owners: requestBody.ownerUserIds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/controls/{controlId}/owners'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an owner to a control
      effect: write
      questions:
      - How do I add one more owner to a control?
      - Can a control have several owners?
      instructions:
      - text: Add user {owner} as an owner of control {control} in workspace {workspace}.
        slots:
          workspace: path.workspaceId
          control: path.controlId
          owner: requestBody.ownerId
      - text: Make {owner} an additional owner on control {control}.
        slots:
          owner: requestBody.ownerId
          control: path.controlId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/controls/{controlId}/owners/{ownerId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an owner from a control
      effect: destructive
      questions:
      - Can I take someone off as owner of a control?
      - What if a control owner leaves the company?
      instructions:
      - text: Remove owner {owner} from control {control} in workspace {workspace}.
        slots:
          workspace: path.workspaceId
          control: path.controlId
          owner: path.ownerId
      - text: Drop {owner} as an owner of control {control}.
        slots:
          owner: path.ownerId
          control: path.controlId
      method: generated
      generated: '2026-09-26'