API Evangelist conversational phrasing for Square Bookings API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Square Bookings API
  version: 1.0.0
extends: openapi/square-bookings-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: 13
- target: $.paths['/v2/bookings'].get
  update:
    x-apievangelist-phrasing:
      intent: List bookings
      effect: read
      questions:
      - How do I see all upcoming appointments for my business?
      - Can I list bookings for one team member within a date window?
      - Which bookings does a given customer have?
      instructions:
      - text: List bookings at location {location_id} starting between {start_at_min} and {start_at_max}.
        slots:
          location_id: query.location_id
          start_at_min: query.start_at_min
          start_at_max: query.start_at_max
      - text: Show bookings for team member {team_member_id}.
        slots:
          team_member_id: query.team_member_id
      - text: List every appointment booked by customer {customer_id}.
        slots:
          customer_id: query.customer_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/bookings'].post
  update:
    x-apievangelist-phrasing:
      intent: Book an appointment
      effect: write
      questions:
      - How do I schedule a new appointment for a customer in Square?
      - What must a new booking include, like location, start time and service?
      instructions:
      - text: Create booking {booking}.
        slots:
          booking: requestBody.booking
      - text: 'Book this appointment for the customer: {booking}.'
        slots:
          booking: requestBody.booking
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/bookings/availability/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Find open appointment slots
      effect: read
      questions:
      - What time slots are open for a service next week?
      - Can I check availability for a specific staff member before booking?
      instructions:
      - text: Search appointment availability for {query}.
        slots:
          query: requestBody.query
      - text: Find open booking slots matching {query}.
        slots:
          query: requestBody.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/bookings/bulk-retrieve'].post
  update:
    x-apievangelist-phrasing:
      intent: Fetch several bookings by ID
      effect: read
      questions:
      - Can I get the details of multiple appointments in one request?
      - Is there a way to retrieve a batch of bookings when I already have their IDs?
      instructions:
      - text: Get bookings {booking_ids}.
        slots:
          booking_ids: requestBody.booking_ids
      - text: 'Retrieve these appointments in one call: {booking_ids}.'
        slots:
          booking_ids: requestBody.booking_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/bookings/business-booking-profile'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the seller's booking profile
      effect: read
      questions:
      - What are my business's online booking settings?
      - Does my seller account allow customers to book online?
      instructions:
      - text: Show my business booking profile.
      - text: Get the seller-level booking settings.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/bookings/location-booking-profiles'].get
  update:
    x-apievangelist-phrasing:
      intent: List location booking profiles
      effect: read
      questions:
      - Which of my locations accept bookings?
      - Can I see booking profiles for every location?
      instructions:
      - text: List booking profiles for all my locations.
      - text: Show up to {limit} location booking profiles.
        slots:
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/bookings/location-booking-profiles/{location_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one location's booking profile
      effect: read
      questions:
      - What are the booking settings for one particular location?
      - Can I check whether a single location is set up for online booking?
      instructions:
      - text: Get the booking profile for location {location_id}.
        slots:
          location_id: path.location_id
      - text: Show booking settings of location {location_id}.
        slots:
          location_id: path.location_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/bookings/team-member-booking-profiles'].get
  update:
    x-apievangelist-phrasing:
      intent: List team member booking profiles
      effect: read
      questions:
      - Which staff members can take appointments at a location?
      - Can I list only team members who are bookable?
      instructions:
      - text: List bookable team members at location {location_id}.
        slots:
          location_id: query.location_id
      - text: 'Show team member booking profiles, bookable only: {bookable_only}.'
        slots:
          bookable_only: query.bookable_only
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/bookings/team-member-booking-profiles/bulk-retrieve'].post
  update:
    x-apievangelist-phrasing:
      intent: Fetch several team members' booking profiles
      effect: read
      questions:
      - Can I get booking profiles for a specific set of staff at once?
      - Is there a batch lookup for team member booking profiles by ID?
      instructions:
      - text: Get booking profiles for team members {team_member_ids}.
        slots:
          team_member_ids: requestBody.team_member_ids
      - text: 'Retrieve these staff booking profiles in one call: {team_member_ids}.'
        slots:
          team_member_ids: requestBody.team_member_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/bookings/team-member-booking-profiles/{team_member_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one team member's booking profile
      effect: read
      questions:
      - Is a particular staff member bookable online?
      - What does one team member's booking profile show?
      instructions:
      - text: Get the booking profile of team member {team_member_id}.
        slots:
          team_member_id: path.team_member_id
      - text: Check whether staff member {team_member_id} can be booked.
        slots:
          team_member_id: path.team_member_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/bookings/{booking_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an appointment's details
      effect: read
      questions:
      - How do I look up one appointment by its booking ID?
      - What time and service is a specific booking for?
      instructions:
      - text: Get booking {booking_id}.
        slots:
          booking_id: path.booking_id
      - text: Show details of appointment {booking_id}.
        slots:
          booking_id: path.booking_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/bookings/{booking_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Reschedule or change a booking
      effect: write
      questions:
      - How do I move an existing appointment to a new time?
      - Can I change the service or staff on a booking that already exists?
      instructions:
      - text: Update booking {booking_id} with {booking}.
        slots:
          booking_id: path.booking_id
          booking: requestBody.booking
      - text: 'Reschedule appointment {booking_id} to these details: {booking}.'
        slots:
          booking_id: path.booking_id
          booking: requestBody.booking
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/bookings/{booking_id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel an appointment
      effect: destructive
      questions:
      - How do I cancel a customer's appointment?
      - Do I need the booking version to cancel it?
      instructions:
      - text: Cancel booking {booking_id}.
        slots:
          booking_id: path.booking_id
      - text: Cancel appointment {booking_id} at version {booking_version}.
        slots:
          booking_id: path.booking_id
          booking_version: requestBody.booking_version
      method: generated
      generated: '2026-09-26'