API Evangelist conversational phrasing for Drata Personnel 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 Personnel API
  version: 1.0.0
extends: openapi/drata-personnel-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: 11
- target: $.paths['/personnel'].get
  update:
    x-apievangelist-phrasing:
      intent: List personnel records
      effect: read
      questions:
      - Which employees on our personnel roster are out of compliance right now?
      - Can I page through the full personnel list filtered by employment status?
      instructions:
      - text: List all personnel records with employment status {employmentStatus}.
        slots:
          employmentStatus: query.employmentStatus[]
      - text: Page through the personnel roster where overall compliance status is {complianceStatus}.
        slots:
          complianceStatus: query.complianceStatus[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/personnel-search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search personnel across all workspaces
      effect: read
      questions:
      - How do I find a person by name or email across every workspace I can access?
      - Which people in any workspace are missing MFA or security training?
      - Can a search across all workspaces return facet counts by compliance status?
      instructions:
      - text: Search every workspace for personnel matching {q}.
        slots:
          q: query.q
      - text: Find personnel in all workspaces whose disk encryption status is {diskEncryptionStatus}.
        slots:
          diskEncryptionStatus: query.diskEncryptionStatus[]
      - text: Across all workspaces, find people whose last name starts with {lastName}.
        slots:
          lastName: query.lastName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/personnel-search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search personnel within one workspace
      effect: read
      questions:
      - Can I search the people in a single workspace by first name prefix?
      - Which people in one specific workspace haven't completed HIPAA training?
      instructions:
      - text: Search workspace {workspaceId} for personnel matching {q}.
        slots:
          workspaceId: path.workspaceId
          q: query.q
      - text: In workspace {workspaceId}, find people whose background check status is {bgCheckStatus}.
        slots:
          workspaceId: path.workspaceId
          bgCheckStatus: query.bgCheckStatus[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/personnel/{personnelId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one person's personnel record
      effect: read
      questions:
      - How do I pull up a single employee's personnel record using their email?
      - What does Drata hold on file for one specific person?
      instructions:
      - text: Get the personnel record for {personnelId}.
        slots:
          personnelId: path.personnelId
      - text: Show personnel {personnelId} with {expand} expanded.
        slots:
          personnelId: path.personnelId
          expand: query.expand[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/personnel/{personnelId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a person's employment details
      effect: write
      questions:
      - How do I record the separation date for someone who left the company?
      - Will editing a person's start date by hand stop HRIS sync from overwriting it?
      - Can I note why a personnel record is marked as not a real person?
      instructions:
      - text: Set the separation date of personnel {personnelId} to {separatedAt}.
        slots:
          personnelId: path.personnelId
          separatedAt: requestBody.separatedAt
      - text: Change the employment status of {personnelId} to {employmentStatus}.
        slots:
          personnelId: path.personnelId
          employmentStatus: requestBody.employmentStatus
      - text: Update the start date for personnel {personnelId} to {startedAt}.
        slots:
          personnelId: path.personnelId
          startedAt: requestBody.startedAt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/personnel/actions'].post
  update:
    x-apievangelist-phrasing:
      intent: Reset personnel IdP/HRIS sync
      effect: write
      questions:
      - How can I restore automatic identity provider updates after editing people manually?
      - Is it possible to reset HRIS sync for every person at once?
      instructions:
      - text: Run the {action} action on personnel {personnelIds}.
        slots:
          action: requestBody.action
          personnelIds: requestBody.personnelIds
      - text: Reset IdP and HRIS sync for all personnel.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/scoped-personnel-groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List groups in a workspace's personnel scope
      effect: read
      questions:
      - Which personnel groups are currently in scope for a workspace?
      - What teams decide who counts as personnel in a given workspace?
      instructions:
      - text: List the personnel groups scoped to workspace {workspaceId}.
        slots:
          workspaceId: path.workspaceId
      - text: Show the scoped groups for workspace {workspaceId}, {size} per page.
        slots:
          workspaceId: path.workspaceId
          size: query.size
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/scoped-personnel-groups'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a workspace's scoped personnel groups
      effect: write
      questions:
      - Can I set the exact list of groups in a workspace's personnel scope in one call?
      - What happens to scoped groups I leave out when I overwrite the whole scope?
      instructions:
      - text: Replace the personnel scope of workspace {workspaceId} with groups {groupIds}.
        slots:
          workspaceId: path.workspaceId
          groupIds: requestBody.groupIds
      - text: Make {groupIds} the only groups in scope for workspace {workspaceId}.
        slots:
          workspaceId: path.workspaceId
          groupIds: requestBody.groupIds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/scoped-personnel-groups'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a group to a workspace's personnel scope
      effect: write
      questions:
      - How do I add one more team to a workspace's personnel scope?
      - What error comes back if the group I'm adding to the scope is already assigned?
      instructions:
      - text: Add group {groupId} to the personnel scope of workspace {workspaceId}.
        slots:
          workspaceId: path.workspaceId
          groupId: requestBody.groupId
      - text: Bring personnel group {groupId} into scope for workspace {workspaceId}.
        slots:
          workspaceId: path.workspaceId
          groupId: requestBody.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/scoped-personnel-groups/{groupId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a group from a workspace's personnel scope
      effect: destructive
      questions:
      - Can I take a single department out of a workspace's scope without resending the full list?
      - Which call drops just one group from a workspace's personnel scope?
      instructions:
      - text: Remove group {groupId} from workspace {workspaceId}'s personnel scope.
        slots:
          workspaceId: path.workspaceId
          groupId: path.groupId
      - text: Take personnel group {groupId} out of scope for workspace {workspaceId}.
        slots:
          workspaceId: path.workspaceId
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/scoped-personnel-counts'].get
  update:
    x-apievangelist-phrasing:
      intent: Count personnel in a workspace's scope
      effect: read
      questions:
      - How many people are reachable through a workspace's scoped groups?
      - Can I compare a workspace's scoped headcount with the total IdP-connected personnel?
      instructions:
      - text: Count the scoped personnel for workspace {workspaceId}.
        slots:
          workspaceId: path.workspaceId
      - text: Get scoped versus IdP-connected personnel totals for workspace {workspaceId}.
        slots:
          workspaceId: path.workspaceId
      method: generated
      generated: '2026-09-26'