# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Optimizely Categories API
  version: 1.0.0
extends: openapi/optimizely-categories-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: 26
- target: $.paths['/api/v1/admin/Categories'].get
  update:
    x-apievangelist-phrasing:
      intent: List product categories in the admin console
      effect: read
      questions:
      - How do I pull every product category from the Commerce admin API?
      - Can I filter and sort the admin category list, or only page through it?
      instructions:
      - text: List all product categories from the admin API.
      - text: Show the first {top} admin categories matching {filter}.
        slots:
          top: query.$top
          filter: query.$filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Categories'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new product category
      effect: write
      questions:
      - What fields are required when I add a new product category?
      - Can a new category be created under an existing parent category?
      instructions:
      - text: Create a category named {name} with URL segment {urlSegment}.
        slots:
          name: requestBody.name
          urlSegment: requestBody.urlSegment
      - text: Add a new category {name} under parent category {parentId}.
        slots:
          name: requestBody.name
          parentId: requestBody.parentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Categories({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one category by its id in the admin API
      effect: read
      questions:
      - How can I look up a single category record by its id as an admin?
      - What does the admin API return for one specific category?
      instructions:
      - text: Fetch admin category {id}.
        slots:
          id: path.id
      - text: Show me the full admin record for category {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Categories({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a category record entirely
      effect: write
      questions:
      - Can I overwrite every field of an existing category in one call?
      - What happens to fields I leave out when I fully replace a category?
      instructions:
      - text: Replace category {id} with a full record named {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Overwrite category {id} entirely, setting its page title to {pageTitle}.
        slots:
          id: path.id
          pageTitle: requestBody.pageTitle
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Categories({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a single category by id
      effect: destructive
      questions:
      - How do I delete one category by its id?
      - Does removing a single category support an If-Match concurrency check?
      instructions:
      - text: Delete category {id}.
        slots:
          id: path.id
      - text: Delete category {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/Categories({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update some fields on a category
      effect: write
      questions:
      - Can I change just a category's meta description without resending everything?
      - Is there a way to mark an existing category as featured?
      instructions:
      - text: Update the meta description of category {id} to {metaDescription}.
        slots:
          id: path.id
          metaDescription: requestBody.metaDescription
      - text: Mark category {id} as featured.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Categories/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get default values for a new category
      effect: read
      questions:
      - What default values does a brand-new category start with?
      - Is there a blank category template I can start from before creating one?
      instructions:
      - text: Get the default starting values for a new category.
      - text: Show me the empty category template the admin uses.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Categories/Default.archive'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive categories via the OData archive action
      effect: destructive
      questions:
      - How do I archive several categories using the OData archive action?
      - Can I hide categories without permanently deleting them through the Default.archive call?
      instructions:
      - text: Run the OData archive action on categories {ids}.
        slots:
          ids: query.ids
      - text: Archive categories {ids} with the Default.archive action call.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/categories({key})/categoryPersonas'].get
  update:
    x-apievangelist-phrasing:
      intent: List the personas assigned to a category
      effect: read
      questions:
      - Which personas are linked to a given category?
      - Can I include archived persona assignments when listing a category's personas?
      instructions:
      - text: List the category persona assignments for category {key}.
        slots:
          key: path.key
      - text: Show the personas for category {key} using archive filter {archiveFilter}.
        slots:
          key: path.key
          archiveFilter: query.archiveFilter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/categories/categoriesWithParents'].post
  update:
    x-apievangelist-phrasing:
      intent: Get categories together with their parent chain
      effect: read
      questions:
      - How can I get categories along with their parent categories in one response?
      - Is there a way to see the full parent hierarchy for my categories?
      instructions:
      - text: Fetch the categories with their parent categories included.
      - text: Return each category alongside its parent hierarchy.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/categories/archive'].delete
  update:
    x-apievangelist-phrasing:
      intent: Archive categories through the archive route
      effect: destructive
      questions:
      - Can I archive a batch of categories with a DELETE on the archive route?
      - What is the REST-style route for archiving categories by id list?
      instructions:
      - text: Archive categories {ids} using the categories/archive route.
        slots:
          ids: query.ids
      - text: Send the batch archive request for categories {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/categories/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete several categories at once
      effect: destructive
      questions:
      - How do I bulk delete multiple categories in one request?
      - Can I permanently remove a list of categories by their ids?
      instructions:
      - text: Bulk delete categories {ids}.
        slots:
          ids: query.ids
      - text: Permanently delete every category in the list {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/categories({key})/attributevalues({attributevalueKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an attribute value assigned to a category
      effect: read
      questions:
      - How do I read one attribute value attached to a category?
      - Can I check whether a specific attribute value belongs to a category?
      instructions:
      - text: Get attribute value {attributevalueKey} on category {key}.
        slots:
          key: path.key
          attributevalueKey: path.attributevalueKey
      - text: Show the attribute value {attributevalueKey} linked to category {key}.
        slots:
          key: path.key
          attributevalueKey: path.attributevalueKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/categories({key})/categoryattributetypes({categoryattributetypeKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an attribute type configured on a category
      effect: read
      questions:
      - Which attribute type settings apply to a given category?
      - Can I look up one category attribute type assignment by its key?
      instructions:
      - text: Get category attribute type {categoryattributetypeKey} for category {key}.
        slots:
          key: path.key
          categoryattributetypeKey: path.categoryattributetypeKey
      - text: Show how attribute type {categoryattributetypeKey} is configured on category {key}.
        slots:
          key: path.key
          categoryattributetypeKey: path.categoryattributetypeKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/categories({key})/categoryrelatedproducts({categoryrelatedproductKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a related product link on a category
      effect: read
      questions:
      - How can I see one related-product entry set up for a category?
      - What details are stored for a category's related product?
      instructions:
      - text: Get category related product {categoryrelatedproductKey} on category {key}.
        slots:
          key: path.key
          categoryrelatedproductKey: path.categoryrelatedproductKey
      - text: Show related-product entry {categoryrelatedproductKey} for category {key}.
        slots:
          key: path.key
          categoryrelatedproductKey: path.categoryrelatedproductKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/categories({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a category
      effect: read
      questions:
      - How do I read a custom property value stored on a category?
      - Can I fetch one specific custom field from a category record?
      instructions:
      - text: Get custom property {custompropertyKey} of category {key}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      - text: Show the value of custom property {custompropertyKey} on category {key}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/categories({key})/dealers({dealerKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a dealer associated with a category
      effect: read
      questions:
      - Which dealer record is tied to a particular category?
      - Can I confirm that a dealer is assigned to a category?
      instructions:
      - text: Get dealer {dealerKey} assigned to category {key}.
        slots:
          key: path.key
          dealerKey: path.dealerKey
      - text: Show the dealer {dealerKey} linked with category {key}.
        slots:
          key: path.key
          dealerKey: path.dealerKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/categories({key})/documents({documentKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a document attached to a category
      effect: read
      questions:
      - How do I retrieve a document attached to a category?
      - Can categories carry documents like spec sheets I can look up individually?
      instructions:
      - text: Get document {documentKey} attached to category {key}.
        slots:
          key: path.key
          documentKey: path.documentKey
      - text: Open the category document {documentKey} for category {key}.
        slots:
          key: path.key
          documentKey: path.documentKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/categories({key})/personas({personaKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one persona targeted by a category
      effect: read
      questions:
      - Can I look up a single persona that a category targets?
      - What persona details come back for one category persona key?
      instructions:
      - text: Get persona {personaKey} on category {key}.
        slots:
          key: path.key
          personaKey: path.personaKey
      - text: Show the single persona {personaKey} that category {key} targets.
        slots:
          key: path.key
          personaKey: path.personaKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/categories({key})/products({productKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a product assigned to a category
      effect: read
      questions:
      - How do I check a specific product inside a category?
      - Can I fetch one product through the category it belongs to?
      instructions:
      - text: Get product {productKey} within category {key}.
        slots:
          key: path.key
          productKey: path.productKey
      - text: Show product {productKey} as assigned to category {key}.
        slots:
          key: path.key
          productKey: path.productKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/categories({key})/specifications({specificationKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a specification on a category
      effect: read
      questions:
      - Where do I read a specification entry defined for a category?
      - Can a category have specifications I can retrieve one at a time?
      instructions:
      - text: Get specification {specificationKey} of category {key}.
        slots:
          key: path.key
          specificationKey: path.specificationKey
      - text: Show the specification {specificationKey} content for category {key}.
        slots:
          key: path.key
          specificationKey: path.specificationKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/categories({key})/subcategories({categoryKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a subcategory of a category
      effect: read
      questions:
      - How do I get one child subcategory under a parent category?
      - Can I confirm a category is a subcategory of another one?
      instructions:
      - text: Get subcategory {categoryKey} under category {key}.
        slots:
          key: path.key
          categoryKey: path.categoryKey
      - text: Show child category {categoryKey} of parent category {key}.
        slots:
          key: path.key
          categoryKey: path.categoryKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/categories({key})/taxexemptions({taxexemptionKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a tax exemption linked to a category
      effect: read
      questions:
      - Which tax exemption applies to products in a category?
      - Can I look up one tax exemption assigned to a category?
      instructions:
      - text: Get tax exemption {taxexemptionKey} on category {key}.
        slots:
          key: path.key
          taxexemptionKey: path.taxexemptionKey
      - text: Show tax exemption {taxexemptionKey} for category {key}.
        slots:
          key: path.key
          taxexemptionKey: path.taxexemptionKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/categories'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse the storefront category tree
      effect: read
      questions:
      - How do I get the category navigation tree for my storefront?
      - Can I limit how many levels deep the storefront category tree goes?
      - Is it possible to start the storefront tree from a particular category?
      instructions:
      - text: Get the storefront category tree down to depth {maxDepth}.
        slots:
          maxDepth: query.parameter.maxDepth
      - text: Load the storefront categories beneath category {startCategoryId}.
        slots:
          startCategoryId: query.parameter.startCategoryId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/categories/{categoryId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a category as shoppers see it on the storefront
      effect: read
      questions:
      - How do I load one category for display on the storefront?
      - What does a shopper-facing category record include?
      instructions:
      - text: Get storefront category {categoryId}.
        slots:
          categoryId: path.categoryId
      - text: Load the shopper-facing details for category {categoryId}.
        slots:
          categoryId: path.categoryId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/categories/feederData'].get
  update:
    x-apievangelist-phrasing:
      intent: Get category feeder data for a storefront widget
      effect: read
      questions:
      - What is category feeder data and how do I request it by type?
      - Can I pull the category feed that populates storefront widgets?
      instructions:
      - text: Get category feeder data of type {type}.
        slots:
          type: query.type
      - text: Load the {type} category feed for the storefront.
        slots:
          type: query.type
      method: generated
      generated: '2026-09-26'