API Evangelist conversational phrasing for Toast Labor Employees API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Toast Labor Employees API
  version: 1.0.0
extends: openapi/toast-employees-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 10
- target: $.paths['/employees'].get
  update:
    x-apievangelist-phrasing:
      intent: List restaurant employees
      effect: read
      questions:
      - Who are the employees on staff at a restaurant?
      - Can I fetch only a specific set of employees by their IDs?
      instructions:
      - text: List all employees at restaurant {restaurant}.
        slots:
          restaurant: header.Toast-Restaurant-External-ID
      - text: Get employees {ids} at restaurant {restaurant}.
        slots:
          ids: query.employeeIds
          restaurant: header.Toast-Restaurant-External-ID
      method: generated
      generated: '2026-10-01'
- target: $.paths['/employees'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a new employee
      effect: write
      questions:
      - How do I create a new employee record at a restaurant?
      - Can I add a staff member through the API instead of Toast Web?
      instructions:
      - text: Add a new employee record at restaurant {restaurant}.
        slots:
          restaurant: header.Toast-Restaurant-External-ID
      - text: Create an employee for restaurant {restaurant} with their name and job.
        slots:
          restaurant: header.Toast-Restaurant-External-ID
      method: generated
      generated: '2026-10-01'
- target: $.paths['/employees/{employeeId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up one employee
      effect: read
      questions:
      - What information does Toast hold for one particular employee?
      - Can I look up a single staff member's record by their ID?
      instructions:
      - text: Get the employee record for {employee}.
        slots:
          employee: path.employeeId
      - text: Show me employee {employee} at restaurant {restaurant}.
        slots:
          employee: path.employeeId
          restaurant: header.Toast-Restaurant-External-ID
      method: generated
      generated: '2026-10-01'
- target: $.paths['/employees/{employeeId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an employee record
      effect: destructive
      questions:
      - What happens to a staff member's login when their employee record is deleted?
      - Can a deleted employee still open new time entries?
      instructions:
      - text: Delete employee {employee} so they can no longer log in.
        slots:
          employee: path.employeeId
      - text: Remove employee {employee} from restaurant {restaurant}.
        slots:
          employee: path.employeeId
          restaurant: header.Toast-Restaurant-External-ID
      method: generated
      generated: '2026-10-01'
- target: $.paths['/employees/{employeeId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an employee's name or passcode
      effect: write
      questions:
      - How do I change an employee's name, chosen name or passcode?
      - Which employee fields can be edited with a partial update?
      instructions:
      - text: Update the name and passcode for employee {employee}.
        slots:
          employee: path.employeeId
      - text: Change employee {employee}'s chosen name at restaurant {restaurant}.
        slots:
          employee: path.employeeId
          restaurant: header.Toast-Restaurant-External-ID
      method: generated
      generated: '2026-10-01'
- target: $.paths['/employees/{employeeId}/externalId'].put
  update:
    x-apievangelist-phrasing:
      intent: Set or replace an employee's external ID
      effect: write
      questions:
      - How do I overwrite an employee's existing external identifier?
      - Can I add an external ID to an employee even if one is already set?
      instructions:
      - text: Replace the external identifier on employee {employee}.
        slots:
          employee: path.employeeId
      - text: Overwrite employee {employee}'s external ID with a new value.
        slots:
          employee: path.employeeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/employees/{employeeId}/externalId'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an external ID to an employee
      effect: write
      questions:
      - Can I attach an external identifier to an employee who does not have one yet?
      - Why does adding a second external ID to the same employee fail?
      instructions:
      - text: Attach a first external identifier to employee {employee}.
        slots:
          employee: path.employeeId
      - text: Give employee {employee} an external ID for the first time.
        slots:
          employee: path.employeeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/employees/{employeeId}/unarchive'].put
  update:
    x-apievangelist-phrasing:
      intent: Unarchive an employee
      effect: write
      questions:
      - How do I restore an archived employee so they can sign into the POS again?
      - Can an unarchived employee sign in to Toast Web?
      instructions:
      - text: Unarchive employee {employee} at restaurant {restaurant}.
        slots:
          employee: path.employeeId
          restaurant: header.Toast-Restaurant-External-ID
      - text: Restore archived employee {employee} so they can sign into the POS.
        slots:
          employee: path.employeeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/employees/{employeeId}/jobs'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace the jobs assigned to an employee
      effect: write
      questions:
      - How do I change which jobs an employee is assigned to?
      - Does replacing an employee's job list affect jobs defined at the restaurant group level?
      instructions:
      - text: Replace the job list for employee {employee}.
        slots:
          employee: path.employeeId
      - text: Set the jobs for employee {employee} at restaurant {restaurant} to this list.
        slots:
          employee: path.employeeId
          restaurant: header.Toast-Restaurant-External-ID
      method: generated
      generated: '2026-10-01'
- target: $.paths['/employees/{employeeId}/wageOverrides'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace an employee's wage overrides
      effect: write
      questions:
      - Can I set a different hourly wage for an employee on a specific job?
      - What happens to existing wage overrides when I send a new list?
      instructions:
      - text: Replace the wage overrides for employee {employee}'s jobs.
        slots:
          employee: path.employeeId
      - text: Set a new wage for employee {employee} on their assigned jobs.
        slots:
          employee: path.employeeId
      method: generated
      generated: '2026-10-01'