# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Optimizely Dealers API
  version: 1.0.0
extends: openapi/optimizely-dealers-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: 15
- target: $.paths['/api/v1/admin/Dealers'].get
  update:
    x-apievangelist-phrasing:
      intent: List dealers in the admin console
      effect: read
      questions:
      - How can I pull the full dealer list as an admin, with filtering?
      - Can I count how many dealer records exist in a given state?
      instructions:
      - text: List all dealer records from the admin API.
      - text: List admin dealers matching {filter}, top {top}, ordered by {orderby}.
        slots:
          filter: query.$filter
          top: query.$top
          orderby: query.$orderby
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Dealers'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a dealer
      effect: write
      questions:
      - What address details are required when I add a new dealer location?
      - Can I set map coordinates for a dealer when creating it?
      instructions:
      - text: Create dealer {name} at {address1}, {city}, {state} {postalCode}.
        slots:
          name: requestBody.name
          address1: requestBody.address1
          city: requestBody.city
          state: requestBody.state
          postalCode: requestBody.postalCode
      - text: Add dealer {name} managed by {manager} with phone {phone}.
        slots:
          name: requestBody.name
          manager: requestBody.manager
          phone: requestBody.phone
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Dealers({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a dealer record by ID (admin)
      effect: read
      questions:
      - Can I fetch one dealer's full admin record by its GUID?
      - Which dealer fields can I select or expand in the admin lookup?
      instructions:
      - text: Get admin dealer record {id}.
        slots:
          id: path.id
      - text: Fetch dealer {id} from the admin API returning only {select}.
        slots:
          id: path.id
          select: query.$select
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Dealers({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a dealer record
      effect: write
      questions:
      - Can I overwrite an entire dealer record with a new address?
      - What's the full-replace call for a dealer?
      instructions:
      - text: Replace dealer {id} with name {name} and address {address1}.
        slots:
          id: path.id
          name: requestBody.name
          address1: requestBody.address1
      - text: Overwrite all fields of dealer {id}, setting city {city} and state {state}.
        slots:
          id: path.id
          city: requestBody.city
          state: requestBody.state
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Dealers({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a dealer
      effect: destructive
      questions:
      - How do I remove a single dealer that has closed?
      - Can I delete a dealer only if nobody changed it since I read it?
      instructions:
      - text: Delete dealer {id}.
        slots:
          id: path.id
      - text: Delete dealer {id} if its ETag is still {etag}.
        slots:
          id: path.id
          etag: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Dealers({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a dealer's details
      effect: write
      questions:
      - Can I change just a dealer's phone number without resending the address?
      - Is there a partial update for a dealer's website URL?
      instructions:
      - text: Update dealer {id} phone to {phone}.
        slots:
          id: path.id
          phone: requestBody.phone
      - text: Patch dealer {id} to set website URL {websiteUrl}.
        slots:
          id: path.id
          websiteUrl: requestBody.websiteUrl
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Dealers/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get default values for a new dealer
      effect: read
      questions:
      - What does a blank dealer template look like before I fill it in?
      - Which defaults are pre-populated on a new dealer?
      instructions:
      - text: Get the default dealer template.
      - text: Show pre-filled values for a new dealer record.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/dealers/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete several dealers at once
      effect: destructive
      questions:
      - Can I bulk delete a batch of dealers in one call?
      - Is there a way to remove many dealer locations by ID list?
      instructions:
      - text: Bulk delete dealers {ids}.
        slots:
          ids: query.ids
      - text: Remove the dealers in the list {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/dealers({key})/categories({categoryKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a category assigned to a dealer
      effect: read
      questions:
      - Can I check whether a product category is linked to a dealer?
      - Where do I read a single category on a dealer record?
      instructions:
      - text: Get category {categoryKey} on dealer {key}.
        slots:
          categoryKey: path.categoryKey
          key: path.key
      - text: Show dealer {key}'s linked category {categoryKey}.
        slots:
          key: path.key
          categoryKey: path.categoryKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/dealers({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a dealer
      effect: read
      questions:
      - Can I read an extra custom field stored on a dealer?
      - Where are custom attributes of a dealer kept?
      instructions:
      - text: Get custom property {custompropertyKey} on dealer {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      - text: Show dealer {key}'s custom field {custompropertyKey}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/dealers({key})/products({productKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a product carried by a dealer
      effect: read
      questions:
      - Can I confirm a specific product is associated with a dealer?
      - Which call returns one product on a dealer's record?
      instructions:
      - text: Get product {productKey} carried by dealer {key}.
        slots:
          productKey: path.productKey
          key: path.key
      - text: Show dealer {key}'s associated product {productKey}.
        slots:
          key: path.key
          productKey: path.productKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/dealers({key})/websites({websiteKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a website a dealer is assigned to
      effect: read
      questions:
      - Can I check which storefront website a dealer belongs to?
      - Which endpoint reads one website link on a dealer?
      instructions:
      - text: Get website {websiteKey} for dealer {key}.
        slots:
          websiteKey: path.websiteKey
          key: path.key
      - text: Show dealer {key}'s assigned website {websiteKey}.
        slots:
          key: path.key
          websiteKey: path.websiteKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/dealers'].get
  update:
    x-apievangelist-phrasing:
      intent: Find dealers near a location
      effect: read
      questions:
      - How do I find the dealers closest to a shopper's latitude and longitude?
      - Can I search storefront dealers by name within a set radius?
      - Is there a dealer locator that uses the default location?
      instructions:
      - text: Find dealers within {radius} of latitude {latitude}, longitude {longitude}.
        slots:
          radius: query.parameter.radius
          latitude: query.parameter.latitude
          longitude: query.parameter.longitude
      - text: Search the dealer locator for dealers named {name}.
        slots:
          name: query.parameter.name
      - text: Show nearby dealers around my default location.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/dealers/{dealerId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a dealer for the storefront
      effect: read
      questions:
      - Can a storefront page load one dealer's address and hours by ID?
      - What does the public dealer detail endpoint return?
      instructions:
      - text: Show storefront dealer {dealerId}.
        slots:
          dealerId: path.dealerId
      - text: Load dealer {dealerId}'s public details for the locator page.
        slots:
          dealerId: path.dealerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/dealers/getByPath'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a dealer by its URL path
      effect: read
      questions:
      - Can I resolve a dealer from its page URL segment?
      - Which call finds a dealer by path instead of ID?
      instructions:
      - text: Find the dealer at path {path}.
        slots:
          path: query.path
      - text: Resolve dealer page URL {path} to its dealer.
        slots:
          path: query.path
      method: generated
      generated: '2026-09-26'