# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Punchh Locations API
  version: 1.0.0
extends: openapi/punchh-locations-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: 16
- target: $.paths['/api2/mobile/locations/configuration'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a store location's configuration
      effect: read
      questions:
      - What configuration does a store location expose to the app or POS?
      - Can I read a location's settings using its location key?
      instructions:
      - text: Get the configuration for location key {location_key}.
        slots:
          location_key: requestBody.location_key
      - text: Show this store's location configuration.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/locations/{location_key}/diagnostic_logs'].post
  update:
    x-apievangelist-phrasing:
      intent: Send POS diagnostic logs for a location
      effect: write
      questions:
      - How do I report POS terminal diagnostics for a store to the loyalty platform?
      - Can I attach the POS type and MAC address when sending diagnostic logs?
      instructions:
      - text: Send diagnostic logs for location key {location_key}.
        slots:
          location_key: path.location_key
      - text: 'Log a {pos_type} terminal issue at location {location_key}: {description}.'
        slots:
          pos_type: requestBody.pos_type
          location_key: path.location_key
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/locations/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Find nearby store locations
      effect: read
      questions:
      - Which restaurant locations are closest to a guest's GPS position?
      - Can I search store locations by part of their name?
      instructions:
      - text: Find stores near latitude {latitude} and longitude {longitude}.
        slots:
          latitude: requestBody.latitude
          longitude: requestBody.longitude
      - text: Search locations whose name contains {name_like}, up to {max} results.
        slots:
          name_like: requestBody.name_like
          max: requestBody.max
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/locations'].get
  update:
    x-apievangelist-phrasing:
      intent: List a business's locations
      effect: read
      questions:
      - How do I get all store locations and their details for a business?
      - Can I page through locations or filter them by store number?
      instructions:
      - text: List locations starting from location {location_id}.
        slots:
          location_id: query.location_id
      - text: Get the location with store number {store_number}.
        slots:
          store_number: query.store_number
      - text: Show page {page} of locations, {per} per page.
        slots:
          page: query.page
          per: query.per
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/locations'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a store location
      effect: write
      questions:
      - What admin permission do I need to add a new store location?
      - Can I add a new restaurant location to the loyalty program by API?
      instructions:
      - text: Create a new store location with {location}.
        slots:
          location: requestBody.location
      - text: Add a restaurant location to the business.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/locations'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a store location immediately
      effect: destructive
      questions:
      - How do I remove a closed store location from the business right away?
      - Can I delete a location using its store number instead of its ID?
      instructions:
      - text: Delete location {location_id} now.
        slots:
          location_id: requestBody.location_id
      - text: Remove the store with number {store_number} from the business.
        slots:
          store_number: requestBody.store_number
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/locations'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit a store location
      effect: write
      questions:
      - Can I change a store location's details after it was created?
      - Is there a way to turn on the weekly redemption report for one location?
      instructions:
      - text: Update location {location_id} with {location}.
        slots:
          location_id: requestBody.location_id
          location: requestBody.location
      - text: Turn the weekly redemption report to {enabled} for store {store_number}.
        slots:
          enabled: requestBody.enable_weekly_redemption_report
          store_number: requestBody.store_number
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/location_groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List location groups and their stores
      effect: read
      questions:
      - Which location groups exist and which stores are in each?
      - Can one store belong to more than one location group?
      instructions:
      - text: List all location groups in the business.
      - text: Show the stores in location group {location_group_id}.
        slots:
          location_group_id: query.location_group_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/location_groups'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a location group
      effect: write
      questions:
      - How do I group stores together, for example by region?
      - Does a new location group need a first location when it's created?
      instructions:
      - text: Create location group {name} starting with location {location_id}.
        slots:
          name: requestBody.name
          location_id: requestBody.location_id
      - text: Make a new group named {name} with store {store_number}.
        slots:
          name: requestBody.name
          store_number: requestBody.store_number
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/location_groups'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a location group
      effect: destructive
      questions:
      - Does deleting a location group also delete its stores?
      - How do I remove a location group I no longer use?
      instructions:
      - text: Delete location group {location_group_id}.
        slots:
          location_group_id: requestBody.location_group_id
      - text: Remove the group {location_group_id} but keep its stores.
        slots:
          location_group_id: requestBody.location_group_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/location_groups'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename a location group
      effect: write
      questions:
      - Can I rename an existing location group?
      - What can be changed on a location group after it is created?
      instructions:
      - text: Rename location group {location_group_id} to {name}.
        slots:
          location_group_id: requestBody.location_group_id
          name: requestBody.name
      - text: Change the name of group {location_group_id} to {name}.
        slots:
          location_group_id: requestBody.location_group_id
          name: requestBody.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/location_groups/add_location'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a store to a location group
      effect: write
      questions:
      - How do I add another store to an existing location group?
      - Can I add a location to a group by its store number?
      instructions:
      - text: Add location {location_id} to group {location_group_id}.
        slots:
          location_id: requestBody.location_id
          location_group_id: requestBody.location_group_id
      - text: Put store {store_number} into location group {location_group_id}.
        slots:
          store_number: requestBody.store_number
          location_group_id: requestBody.location_group_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/location_groups/remove_location'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a store from a location group
      effect: destructive
      questions:
      - Can I take a store out of a location group without deleting the store?
      - What happens to a location after it's removed from a group?
      instructions:
      - text: Remove location {location_id} from group {location_group_id}.
        slots:
          location_id: requestBody.location_id
          location_group_id: requestBody.location_group_id
      - text: Take store {store_number} out of location group {location_group_id}.
        slots:
          store_number: requestBody.store_number
          location_group_id: requestBody.location_group_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/business_admins/authorizations'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke an admin's access to stores
      effect: destructive
      questions:
      - How do I stop a business admin from managing a particular store?
      - Can I remove an admin's access to a whole location group?
      instructions:
      - text: Revoke admin {admin_id}'s access to {business_admins}.
        slots:
          admin_id: requestBody.admin_id
          business_admins: requestBody.business_admins
      - text: Take away store access for admin {admin_id}.
        slots:
          admin_id: requestBody.admin_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/business_admins/authorizations'].patch
  update:
    x-apievangelist-phrasing:
      intent: Grant an admin access to stores
      effect: write
      questions:
      - How do I let a business admin manage a specific store or location group?
      - Can an admin be given access by store number?
      instructions:
      - text: Grant admin {admin_id} access to {business_admins}.
        slots:
          admin_id: requestBody.admin_id
          business_admins: requestBody.business_admins
      - text: Allow admin {admin_id} to manage additional locations.
        slots:
          admin_id: requestBody.admin_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/locations/destroy_async'].delete
  update:
    x-apievangelist-phrasing:
      intent: Queue a store location for deletion
      effect: destructive
      questions:
      - Is there a background way to delete a location that has a lot of data?
      - Can location deletion be queued instead of done immediately?
      instructions:
      - text: Queue location {location_id} for asynchronous deletion.
        slots:
          location_id: requestBody.location_id
      - text: Schedule deletion of location {location_id}, store {store_number}, in the background.
        slots:
          location_id: requestBody.location_id
          store_number: requestBody.store_number
      method: generated
      generated: '2026-10-01'