API Evangelist conversational phrasing for Optimizely Brands API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Optimizely Brands API
  version: 1.0.0
extends: openapi/optimizely-brands-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: 27
- target: $.paths['/api/v1/admin/Brands'].get
  update:
    x-apievangelist-phrasing:
      intent: List brands in the commerce admin
      effect: read
      questions:
      - How do I pull every brand record from the Optimizely Configured Commerce admin API?
      - Can I filter and sort the admin brand list, or page through it with top and skip?
      instructions:
      - text: List all brands in the admin console.
      - text: List admin brands matching the filter {filter}, sorted by {orderby}.
        slots:
          filter: query.$filter
          orderby: query.$orderby
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Brands'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new brand
      effect: write
      questions:
      - What fields do I need to set up a new brand, like logos, URL segment and SEO title?
      - Can I mark a newly created brand as sponsored and give it a search boost?
      instructions:
      - text: Create a brand named {name} with site URL {siteUrl} and URL segment {urlSegment}.
        slots:
          name: requestBody.name
          siteUrl: requestBody.siteUrl
          urlSegment: requestBody.urlSegment
      - text: Add a new brand {name} made by manufacturer {manufacturer} with page title {pageTitle}.
        slots:
          name: requestBody.name
          manufacturer: requestBody.manufacturer
          pageTitle: requestBody.pageTitle
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Brands({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one brand's admin record
      effect: read
      questions:
      - How can I look up a single brand's admin record by its ID?
      - Which related data can I expand when fetching one brand record from admin?
      instructions:
      - text: Show me the admin record for brand {id}.
        slots:
          id: path.id
      - text: Fetch admin brand {id} with {expand} expanded.
        slots:
          id: path.id
          expand: query.$expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Brands({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a brand record entirely
      effect: write
      questions:
      - Can I overwrite an existing brand with a complete new set of values?
      - What happens to brand fields I leave out when I replace the whole record?
      instructions:
      - text: Replace brand {id} with a full record named {name} at site URL {siteUrl}.
        slots:
          id: path.id
          name: requestBody.name
          siteUrl: requestBody.siteUrl
      - text: Overwrite every field of brand {id}, setting the meta description to {metaDescription}.
        slots:
          id: path.id
          metaDescription: requestBody.metaDescription
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Brands({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a single brand
      effect: destructive
      questions:
      - How do I remove one brand from the catalog by its ID?
      - Can I make a brand delete conditional on an ETag so I don't remove a changed record?
      instructions:
      - text: Delete brand {id}.
        slots:
          id: path.id
      - text: Delete brand {id} only if its ETag still matches {etag}.
        slots:
          id: path.id
          etag: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Brands({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update selected fields on a brand
      effect: write
      questions:
      - Can I change just a brand's sort order or logo alt text without resending everything?
      - How would I switch off the sponsored flag on an existing brand?
      instructions:
      - text: Patch brand {id} so its sort order is {sortOrder}.
        slots:
          id: path.id
          sortOrder: requestBody.sortOrder
      - text: Update brand {id} to set sponsored to {isSponsored} and search boost to {searchBoost}.
        slots:
          id: path.id
          isSponsored: requestBody.isSponsored
          searchBoost: requestBody.searchBoost
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Brands/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get default values for a new brand
      effect: read
      questions:
      - What default values does the admin API pre-fill for a brand before I create one?
      - Is there a blank brand template I can start from?
      instructions:
      - text: Get the default brand template from the admin API.
      - text: Show the pre-filled default values for a new brand.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Brands/Default.checkbrandspage(websiteId={websiteId})'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a website's brands page (OData function)
      effect: read
      questions:
      - How can I check whether a website has a brands page using the OData Default.checkbrandspage function?
      - Does the Default namespace checkbrandspage call tell me if a site's brand listing page exists?
      instructions:
      - text: Run the OData Default.checkbrandspage function for website {websiteId}.
        slots:
          websiteId: path.websiteId
      - text: Call the namespaced checkbrandspage operation to verify the brands page on site {websiteId}.
        slots:
          websiteId: path.websiteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Brands({id})/Default.unassignProductLinesProducts'].post
  update:
    x-apievangelist-phrasing:
      intent: Unassign chosen products from a brand's lines
      effect: write
      questions:
      - How do I detach specific products from a brand's product lines by passing their IDs?
      - Can I pick which products to unassign from a brand's product lines instead of all of them?
      instructions:
      - text: Unassign products {productIds} from the product lines of brand {id}.
        slots:
          productIds: requestBody.productIds
          id: path.id
      - text: Through the Default action, remove products {productIds} from brand {id}'s product lines.
        slots:
          productIds: requestBody.productIds
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/brands({key})/unassignProductLinesProducts'].post
  update:
    x-apievangelist-phrasing:
      intent: Unassign product-line products by brand key
      effect: write
      questions:
      - Is there a lowercase brands route that unassigns product-line products using just the brand key?
      - Can I call unassignProductLinesProducts with no product list in the body?
      instructions:
      - text: Call the brands({key}) unassignProductLinesProducts route with no request body.
        slots:
          key: path.key
      - text: Clear product-line product assignments for brand key {key} via the plain route.
        slots:
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/brands/checkbrandspage(websiteId={websiteId})'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a website's brands page (plain route)
      effect: read
      questions:
      - Is there a plain lowercase brands/checkbrandspage route to verify a website's brands page?
      - Can I check a site's brands page without the Default OData namespace in the URL?
      instructions:
      - text: Hit the plain brands/checkbrandspage route for website {websiteId}.
        slots:
          websiteId: path.websiteId
      - text: Use the non-namespaced route to check whether site {websiteId} has a brands page.
        slots:
          websiteId: path.websiteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/brands/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete several brands at once
      effect: destructive
      questions:
      - Can I bulk delete a batch of brands in a single call?
      - How do I pass a list of brand IDs to remove them together?
      instructions:
      - text: Bulk delete the brands with IDs {ids}.
        slots:
          ids: query.ids
      - text: Remove every brand in the list {ids} in one request.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/brands({key})/brandcategoryimages({brandcategoryimageKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a brand's category image
      effect: read
      questions:
      - How do I fetch one category image attached to a brand?
      - Where can I read the image a brand uses for a specific category tile?
      instructions:
      - text: Get brand category image {brandcategoryimageKey} for brand {key}.
        slots:
          brandcategoryimageKey: path.brandcategoryimageKey
          key: path.key
      - text: Show the category image record {brandcategoryimageKey} under brand {key}.
        slots:
          brandcategoryimageKey: path.brandcategoryimageKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/brands({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a brand
      effect: read
      questions:
      - Can I read a single custom property value stored on a brand?
      - Which custom attributes has my team attached to a given brand record?
      instructions:
      - text: Get custom property {custompropertyKey} on brand {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      - text: Show brand {key}'s custom property {custompropertyKey}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/brands({key})/productlines({productlineKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a brand's product line in admin
      effect: read
      questions:
      - How do I read one product line record under a brand in the admin API?
      - Can I select only certain fields of a brand's product line from admin?
      instructions:
      - text: Get admin product line {productlineKey} of brand {key}.
        slots:
          productlineKey: path.productlineKey
          key: path.key
      - text: Fetch the admin record for brand {key}'s product line {productlineKey}, selecting {select}.
        slots:
          key: path.key
          productlineKey: path.productlineKey
          select: query.$select
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/brands({key})/products({productKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a product linked to a brand in admin
      effect: read
      questions:
      - Can I confirm a particular product is linked to a brand through the admin API?
      - How do I open the admin record of one product under a brand?
      instructions:
      - text: Get admin product {productKey} under brand {key}.
        slots:
          productKey: path.productKey
          key: path.key
      - text: Look up product {productKey} in brand {key}'s admin product collection.
        slots:
          productKey: path.productKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/brands/{BrandId}/categories'].get
  update:
    x-apievangelist-phrasing:
      intent: List the storefront categories of a brand
      effect: read
      questions:
      - Which categories does a brand's products appear in on the storefront?
      - Can I limit how deep the brand category tree goes when listing it?
      instructions:
      - text: List the storefront categories for brand {BrandId}.
        slots:
          BrandId: path.BrandId
      - text: Show brand {BrandId}'s category tree down to depth {maximumDepth}.
        slots:
          BrandId: path.BrandId
          maximumDepth: query.parameter.maximumDepth
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/brands/{BrandId}/categories/{CategoryId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one category within a brand
      effect: read
      questions:
      - How do I get the details of a single category as it appears under a brand on the storefront?
      - Can I expand extra data on one brand category?
      instructions:
      - text: Get category {CategoryId} for brand {BrandId}.
        slots:
          CategoryId: path.CategoryId
          BrandId: path.BrandId
      - text: Show brand {BrandId}'s category {CategoryId} with {expand} expanded.
        slots:
          BrandId: path.BrandId
          CategoryId: path.CategoryId
          expand: query.parameter.expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/brands/{BrandId}/productlines/{ProductLineId}/products'].get
  update:
    x-apievangelist-phrasing:
      intent: List products in a brand's product line
      effect: read
      questions:
      - What products belong to a specific product line of a brand?
      - Can I filter a brand product line's products by price range or stocked items only?
      instructions:
      - text: List products in product line {ProductLineId} of brand {BrandId}.
        slots:
          ProductLineId: path.ProductLineId
          BrandId: path.BrandId
      - text: Show brand {BrandId} product line {ProductLineId} products priced between {minimumPrice} and {maximumPrice}.
        slots:
          BrandId: path.BrandId
          ProductLineId: path.ProductLineId
          minimumPrice: query.parameter.minimumPrice
          maximumPrice: query.parameter.maximumPrice
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/brands/{brandId}/products'].get
  update:
    x-apievangelist-phrasing:
      intent: Search all products of a brand
      effect: read
      questions:
      - How can a shopper browse every product a brand sells on the storefront?
      - Can I search within a brand's products by keyword and page through the results?
      instructions:
      - text: List all storefront products for brand {brandId}.
        slots:
          brandId: path.brandId
      - text: Search brand {brandId}'s products for {query}, page {page}.
        slots:
          brandId: path.brandId
          query: query.parameter.query
          page: query.parameter.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/brands/{BrandId}/categories/{CategoryId}/products'].get
  update:
    x-apievangelist-phrasing:
      intent: List a brand's products in one category
      effect: read
      questions:
      - Which of a brand's products fall inside a particular category?
      - Can I sort a brand's products within one category?
      instructions:
      - text: List brand {BrandId}'s products in category {CategoryId}.
        slots:
          BrandId: path.BrandId
          CategoryId: path.CategoryId
      - text: Show products for brand {BrandId} in category {CategoryId} sorted by {sort}.
        slots:
          BrandId: path.BrandId
          CategoryId: path.CategoryId
          sort: query.parameter.sort
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/brands'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse storefront brands
      effect: read
      questions:
      - How do I build an A-Z brand directory showing brands that start with a given letter?
      - Can I show brands from one manufacturer or in random order on the storefront?
      instructions:
      - text: List storefront brands whose names start with {startsWith}.
        slots:
          startsWith: query.parameter.startsWith
      - text: Show brands from manufacturer {manufacturer} in random order.
        slots:
          manufacturer: query.parameter.manufacturer
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/brands/{BrandId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a brand for the storefront
      effect: read
      questions:
      - How do I load a brand's details to render its storefront brand page?
      - Can I expand extra information when fetching a single storefront brand?
      instructions:
      - text: Get storefront brand {BrandId}.
        slots:
          BrandId: path.BrandId
      - text: Load brand {BrandId} for display with {expand} expanded.
        slots:
          BrandId: path.BrandId
          expand: query.parameter.expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/brands/getByPath'].get
  update:
    x-apievangelist-phrasing:
      intent: Find a brand by its URL path
      effect: read
      questions:
      - Can I resolve which brand a storefront URL path belongs to?
      - How do I look up a brand when I only have its page path?
      instructions:
      - text: Find the brand at URL path {path}.
        slots:
          path: query.path
      - text: Resolve the brand behind page path {path}.
        slots:
          path: query.path
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/brands/feederData'].get
  update:
    x-apievangelist-phrasing:
      intent: Get brand feeder data
      effect: read
      questions:
      - What does the brands feederData endpoint return for storefront widgets?
      - Is there a single call that feeds brand data into content blocks?
      instructions:
      - text: Get the brand feeder data.
      - text: Pull brands feederData for the storefront content widgets.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/brands/{BrandId}/productlines'].get
  update:
    x-apievangelist-phrasing:
      intent: List a brand's product lines
      effect: read
      questions:
      - What product lines does a brand offer on the storefront?
      - Can I show only featured or sponsored product lines for a brand?
      instructions:
      - text: List the product lines of brand {BrandId}.
        slots:
          BrandId: path.BrandId
      - text: Show only featured product lines for brand {BrandId}.
        slots:
          BrandId: path.BrandId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/brands/{BrandId}/productlines/{ProductLineId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one product line for the storefront
      effect: read
      questions:
      - How do I display the details of a single product line on a brand's storefront page?
      - Can I expand extra detail on one storefront product line?
      instructions:
      - text: Get storefront product line {ProductLineId} of brand {BrandId}.
        slots:
          ProductLineId: path.ProductLineId
          BrandId: path.BrandId
      - text: Load brand {BrandId}'s product line {ProductLineId} with {expand} expanded.
        slots:
          BrandId: path.BrandId
          ProductLineId: path.ProductLineId
          expand: query.parameter.expand
      method: generated
      generated: '2026-09-26'