# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Square Labor API
  version: 1.0.0
extends: openapi/square-labor-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: 16
- target: $.paths['/v2/labor/break-types'].get
  update:
    x-apievangelist-phrasing:
      intent: List break types for a business
      effect: read
      questions:
      - What kinds of breaks have we set up for staff at each location?
      - Can I see only the break templates defined for one location?
      instructions:
      - text: List all break types.
      - text: Show the break types configured at location {location_id}.
        slots:
          location_id: query.location_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/labor/break-types'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a break type template
      effect: write
      questions:
      - How do I set up a new paid or unpaid break template for employees?
      - What do I need to define a new break type, like a 30-minute lunch?
      instructions:
      - text: Create a new break type from {break_type}.
        slots:
          break_type: requestBody.break_type
      - text: Add a lunch break template described by {break_type} for our staff.
        slots:
          break_type: requestBody.break_type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/labor/break-types/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single break type
      effect: read
      questions:
      - What are the settings of one specific break type?
      - Can I look up the expected duration of a break template by its ID?
      instructions:
      - text: Get break type {id}.
        slots:
          id: path.id
      - text: Show me the details of break template {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/labor/break-types/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a break type template
      effect: write
      questions:
      - Can I change the name or length of an existing break type?
      - How do I make an existing break template paid instead of unpaid?
      instructions:
      - text: Update break type {id} with {break_type}.
        slots:
          id: path.id
          break_type: requestBody.break_type
      - text: Change break template {id} to match {break_type}.
        slots:
          id: path.id
          break_type: requestBody.break_type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/labor/break-types/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a break type
      effect: destructive
      questions:
      - Can I remove a break type even if shifts already reference it?
      - How do I get rid of a break template we no longer use?
      instructions:
      - text: Delete break type {id}.
        slots:
          id: path.id
      - text: Remove the break template {id} from our labor setup.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/labor/employee-wages'].get
  update:
    x-apievangelist-phrasing:
      intent: List employee wages (legacy)
      effect: read
      questions:
      - Where can I see hourly wages using the older employee wage records?
      - Can I filter legacy employee wage records to one employee?
      instructions:
      - text: List employee wages for employee {employee_id}.
        slots:
          employee_id: query.employee_id
      - text: Show all legacy employee wage records.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/labor/employee-wages/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a legacy employee wage record
      effect: read
      questions:
      - What does a single legacy EmployeeWage record contain?
      - Can I fetch one employee wage entry by its ID?
      instructions:
      - text: Get employee wage {id}.
        slots:
          id: path.id
      - text: Show legacy employee wage record {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/labor/shifts'].post
  update:
    x-apievangelist-phrasing:
      intent: Record a new shift for a team member
      effect: write
      questions:
      - How do I log a workday for a team member at a location?
      - What is required to create a shift with a start time?
      instructions:
      - text: Create a shift from {shift}.
        slots:
          shift: requestBody.shift
      - text: Log a new timecard shift for a team member using {shift}.
        slots:
          shift: requestBody.shift
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/labor/shifts/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search shifts by team member, location or status
      effect: read
      questions:
      - Which shifts are still open right now across my locations?
      - Can I find all shifts a team member worked in a date range?
      - Is there a way to filter shifts by workday or team member?
      instructions:
      - text: Search shifts matching {query}.
        slots:
          query: requestBody.query
      - text: Find open shifts, returning at most {limit}.
        slots:
          limit: requestBody.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/labor/shifts/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single shift
      effect: read
      questions:
      - What are the start, end and break details of one shift?
      - Can I retrieve a specific timecard shift by ID?
      instructions:
      - text: Get shift {id}.
        slots:
          id: path.id
      - text: Show the breaks and wage on shift {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/labor/shifts/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update or close a shift
      effect: write
      questions:
      - How do I clock someone out by closing their shift?
      - Can I add a break to a shift that is already in progress?
      instructions:
      - text: Update shift {id} with {shift}.
        slots:
          id: path.id
          shift: requestBody.shift
      - text: Close shift {id} by setting its end time in {shift}.
        slots:
          id: path.id
          shift: requestBody.shift
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/labor/shifts/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a shift
      effect: destructive
      questions:
      - Can I remove a shift that was recorded by mistake?
      - What happens when I delete a timecard shift?
      instructions:
      - text: Delete shift {id}.
        slots:
          id: path.id
      - text: Remove the mistaken shift {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/labor/team-member-wages'].get
  update:
    x-apievangelist-phrasing:
      intent: List team member wages
      effect: read
      questions:
      - What hourly rates are team members paid for their jobs?
      - Can I see the wages for just one team member?
      instructions:
      - text: List team member wages for {team_member_id}.
        slots:
          team_member_id: query.team_member_id
      - text: Show every team member wage record.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/labor/team-member-wages/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a team member wage record
      effect: read
      questions:
      - How can I see the pay rate on one specific team member wage entry?
      - Which job title and hourly rate belong to a given wage record?
      instructions:
      - text: Get team member wage {id}.
        slots:
          id: path.id
      - text: Show hourly rate and job for team member wage {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/labor/workweek-configs'].get
  update:
    x-apievangelist-phrasing:
      intent: List workweek configurations
      effect: read
      questions:
      - When does our business workweek start for overtime purposes?
      - Which workweek configuration is Square using for my account?
      instructions:
      - text: List workweek configs.
      - text: Show the workweek start day and time, up to {limit} configs.
        slots:
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/labor/workweek-configs/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Change the workweek start
      effect: write
      questions:
      - Can I change the day our workweek begins?
      - How do I move the workweek start time for overtime calculations?
      instructions:
      - text: Update workweek config {id} with {workweek_config}.
        slots:
          id: path.id
          workweek_config: requestBody.workweek_config
      - text: Set workweek config {id} to start on the day in {workweek_config}.
        slots:
          id: path.id
          workweek_config: requestBody.workweek_config
      method: generated
      generated: '2026-09-26'