# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Platform REST Users API
  version: 1.0.0
extends: openapi/vendasta-users-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: 14
- target: $.paths['/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List platform users
      effect: read
      questions:
      - Which users belong to my partner account in Vendasta?
      - Can I find a user by their email address or a search term?
      - Is it possible to filter the user list by category?
      instructions:
      - text: List all users for partner {partner}.
        slots:
          partner: query.filter[partner.id]
      - text: Find the user whose email is {email}.
        slots:
          email: query.filter[email]
      - text: Search users matching {term}, {limit} per page.
        slots:
          term: query.filter[searchTerm]
          limit: query.page[limit]
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a user
      effect: write
      questions:
      - Can I add a new user account under my partner through the API?
      - What fields are mandatory when creating a new user?
      instructions:
      - text: Create a new user with the email and partner I give you.
      - text: Add a user record for {data}.
        slots:
          data: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users'].options
  update:
    x-apievangelist-phrasing:
      intent: Check allowed HTTP methods on the users collection
      effect: read
      questions:
      - Which HTTP verbs does the users collection endpoint accept for CORS preflight?
      - What does a browser preflight on the users list return?
      instructions:
      - text: Send a CORS preflight request to the users collection.
      - text: Show the allowed methods and headers for the users list endpoint.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's details
      effect: read
      questions:
      - How can I look up a single user's profile by ID?
      - What information comes back for one specific user?
      instructions:
      - text: Get user {id}.
        slots:
          id: path.id
      - text: Show me the details stored for user {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user
      effect: destructive
      questions:
      - Can I permanently delete a user and remove their personal data?
      - Once a user is deleted, can their ID be reused later?
      instructions:
      - text: Delete user {id}.
        slots:
          id: path.id
      - text: Remove user {id} and wipe their personal data.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a user
      effect: write
      questions:
      - Can I change just a few fields on an existing user without resending everything?
      - What happens to user fields I leave out of an update?
      instructions:
      - text: Update user {id} with {data}.
        slots:
          id: path.id
          data: requestBody.data
      - text: Edit the profile of user {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}'].options
  update:
    x-apievangelist-phrasing:
      intent: Check allowed HTTP methods on a single user
      effect: read
      questions:
      - Which HTTP verbs are permitted on an individual user resource?
      - What does a CORS preflight on one user's endpoint return?
      instructions:
      - text: Run a CORS preflight against user {id}.
        slots:
          id: path.id
      - text: Show which methods the single-user endpoint allows for {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/relationships/businessLocations'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's business locations
      effect: read
      questions:
      - Which business locations does a given user have access to?
      - Can I see every location a user is associated with?
      instructions:
      - text: List the business locations user {id} can access.
        slots:
          id: path.id
      - text: Show which locations are linked to user {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/relationships/businessLocations'].post
  update:
    x-apievangelist-phrasing:
      intent: Grant a user access to more locations
      effect: write
      questions:
      - Can I give a user access to additional business locations while keeping their current ones?
      - What happens if I grant a user a location they already have access to?
      instructions:
      - text: Add locations {data} to user {id}'s existing access.
        slots:
          id: path.id
          data: requestBody.data
      - text: 'Associate user {id} with these extra business locations: {data}.'
        slots:
          id: path.id
          data: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/relationships/businessLocations'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke a user's access to locations
      effect: destructive
      questions:
      - Can I remove a user's access to specific business locations?
      - What if I revoke a location the user never had access to?
      instructions:
      - text: Remove user {id}'s access to locations {data}.
        slots:
          id: path.id
          data: requestBody.data
      - text: 'Dissociate user {id} from these business locations: {data}.'
        slots:
          id: path.id
          data: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/relationships/businessLocations'].patch
  update:
    x-apievangelist-phrasing:
      intent: Replace a user's location access
      effect: write
      questions:
      - Can I overwrite a user's location access so they only see the locations I list?
      - Is there a way to reset which locations a user can reach in one call?
      instructions:
      - text: Set user {id}'s location access to exactly {data}.
        slots:
          id: path.id
          data: requestBody.data
      - text: Replace all of user {id}'s business locations with {data}.
        slots:
          id: path.id
          data: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/relationships/businessLocations'].options
  update:
    x-apievangelist-phrasing:
      intent: Check allowed methods on user-location links
      effect: read
      questions:
      - Which HTTP verbs does the user-to-location relationship endpoint support for CORS?
      - What does a preflight on a user's business-location links return?
      instructions:
      - text: Send a CORS preflight to the location relationships of user {id}.
        slots:
          id: path.id
      - text: Show the allowed methods for user {id}'s location-link endpoint.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/customFields'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's custom fields
      effect: read
      questions:
      - Can I read the custom field values set on a user?
      - Where do I find the extra partner-defined attributes stored on a user?
      instructions:
      - text: Get the custom fields for user {id}.
        slots:
          id: path.id
      - text: Show custom field values recorded on user {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/actions/sendWelcomeEmail'].get
  update:
    x-apievangelist-phrasing:
      intent: Send a welcome email to a user
      effect: write
      questions:
      - Can I trigger a welcome email to a user who was already created?
      - How do I resend the onboarding welcome message to an existing user?
      instructions:
      - text: Send the welcome email to user {id}.
        slots:
          id: path.id
      - text: Email user {id} their welcome message now.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'