API Evangelist conversational phrasing for Admin API V1 Category Products API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Admin API V1 Category Products API
  version: 1.0.0
extends: openapi/optimizely-category-products-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: 9
- target: $.paths['/api/v1/admin/CategoryProducts'].get
  update:
    x-apievangelist-phrasing:
      intent: List product-to-category assignments
      effect: read
      questions:
      - Which products are assigned to which categories in my catalog?
      - Can I filter category assignments down to one category's products?
      - Which products have a primary category set?
      instructions:
      - text: List all product-to-category assignments.
      - text: Find category product links matching {filter}.
        slots:
          filter: query.$filter
      - text: Show the first {top} category assignments, skipping {skip}.
        slots:
          top: query.$top
          skip: query.$skip
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/CategoryProducts'].post
  update:
    x-apievangelist-phrasing:
      intent: Assign a product to a category
      effect: write
      questions:
      - How do I put a product into a catalog category?
      - Can I mark a category as the product's primary one when I assign it?
      instructions:
      - text: Assign product {productId} to category {categoryId}.
        slots:
          productId: requestBody.productId
          categoryId: requestBody.categoryId
      - text: Add product {productId} to category {categoryId} with primary flag {isPrimaryCategory}.
        slots:
          productId: requestBody.productId
          categoryId: requestBody.categoryId
          isPrimaryCategory: requestBody.isPrimaryCategory
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/CategoryProducts({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a product-to-category assignment
      effect: read
      questions:
      - What product and category does a given assignment record link?
      - Is a specific category assignment the product's primary category?
      instructions:
      - text: Get category product assignment {id}.
        slots:
          id: path.id
      - text: Show which product and category link record {id} connects.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/CategoryProducts({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a product-to-category assignment
      effect: write
      questions:
      - How do I overwrite a whole category assignment record?
      - Does replacing a category product link reset its primary flag if I omit it?
      instructions:
      - text: Replace category assignment {id} so it links product {productId} to category {categoryId}.
        slots:
          id: path.id
          productId: requestBody.productId
          categoryId: requestBody.categoryId
      - text: Overwrite category product record {id} in full with category {categoryId}.
        slots:
          id: path.id
          categoryId: requestBody.categoryId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/CategoryProducts({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a product from a category
      effect: destructive
      questions:
      - How do I take a product out of a category using its assignment ID?
      - Can I guard removing a category assignment with an ETag?
      instructions:
      - text: Delete category product assignment {id}.
        slots:
          id: path.id
      - text: Remove category link {id} only if its ETag is {etag}.
        slots:
          id: path.id
          etag: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/CategoryProducts({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a product-to-category assignment
      effect: write
      questions:
      - Can I make an existing category assignment the product's primary category?
      - How do I move an existing assignment to a different category?
      instructions:
      - text: Set the primary-category flag on assignment {id} to {isPrimaryCategory}.
        slots:
          id: path.id
          isPrimaryCategory: requestBody.isPrimaryCategory
      - text: Move category assignment {id} to category {categoryId}.
        slots:
          id: path.id
          categoryId: requestBody.categoryId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/CategoryProducts/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a blank category assignment template
      effect: read
      questions:
      - What default values does a new category product link start with?
      - Is there a template record for a product-to-category assignment?
      instructions:
      - text: Fetch the default category product template.
      - text: Show default values for a new product-to-category assignment.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/categoryproducts/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk remove products from categories
      effect: destructive
      questions:
      - How do I remove many category assignments in one call?
      - Can I delete a list of product-to-category links by ID?
      instructions:
      - text: Bulk delete category product assignments {ids}.
        slots:
          ids: query.ids
      - text: 'Remove these product-to-category links together: {ids}.'
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/categoryproducts({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a category assignment
      effect: read
      questions:
      - What value is stored in a custom property on a category product link?
      - Can I read one custom property of a product-to-category assignment?
      instructions:
      - text: Get custom property {custompropertyKey} on category product {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      - text: Show category assignment {key}'s custom property {custompropertyKey}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      method: generated
      generated: '2026-09-26'