# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Conga Categories API
  version: 1.0.0
extends: openapi/conga-categories-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: 21
- target: $.paths['/categories'].get
  update:
    x-apievangelist-phrasing:
      intent: List categories
      effect: read
      questions:
      - Which product categories exist in my Conga catalog?
      - Can I filter categories by name or other supported fields?
      - How do I page through every category in the system?
      instructions:
      - text: List all categories in the catalog.
      - text: Show categories matching {filter}.
        slots:
          filter: query.filter
      - text: List categories, {limit} per page, page {page}.
        slots:
          limit: query.limit
          page: query.page
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories'].post
  update:
    x-apievangelist-phrasing:
      intent: Create categories in bulk
      effect: write
      questions:
      - Can I create several catalog categories in one request?
      - What structure is returned after adding new categories?
      instructions:
      - text: Create these new catalog categories in one bulk request.
      - text: Add a batch of categories from the details I provide.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete categories in bulk
      effect: destructive
      questions:
      - Is there a way to delete multiple categories by a list of IDs?
      - What happens to a list of categories when they're bulk-deleted?
      instructions:
      - text: Delete every category in this list of IDs.
      - text: Bulk-remove the categories I listed.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update categories in bulk
      effect: write
      questions:
      - Can I edit many categories in one request?
      - Which call changes fields on several categories together?
      instructions:
      - text: Bulk-update the listed categories with these details.
      - text: Apply changes to multiple categories in a single request.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories/{Id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one category record
      effect: read
      questions:
      - What does a single category record contain?
      - Can I include related records when retrieving one category by its ID?
      instructions:
      - text: Show the category record {category_id}.
        slots:
          category_id: path.Id
      - text: Fetch category record {category_id} with {includes}.
        slots:
          category_id: path.Id
          includes: query.includes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories/{Id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one category
      effect: destructive
      questions:
      - How do I delete a single category by ID?
      - Can I remove just one category without affecting others?
      instructions:
      - text: Delete category {category_id}.
        slots:
          category_id: path.Id
      - text: Remove only the category with ID {category_id}.
        slots:
          category_id: path.Id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories/{Id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update one category
      effect: write
      questions:
      - Can I edit one specific category record?
      - Which request renames or changes a single category by ID?
      instructions:
      - text: Update category {category_id} with these changes.
        slots:
          category_id: path.Id
      - text: Edit just the category record {category_id}.
        slots:
          category_id: path.Id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories/{categoryId}/price-lists'].get
  update:
    x-apievangelist-phrasing:
      intent: List price lists for a category
      effect: read
      questions:
      - Which price lists use a given category?
      - Can I page through the price lists linked to a category?
      instructions:
      - text: Show the price lists for category {category_id}.
        slots:
          category_id: path.categoryId
      - text: List price lists of category {category_id}, {limit} per page.
        slots:
          category_id: path.categoryId
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories/{category}/bulk'].post
  update:
    x-apievangelist-phrasing:
      intent: Nest several categories under a category
      effect: write
      questions:
      - Can I move multiple existing categories under another parent category at once?
      - What's the way to add a batch of source categories beneath one category?
      instructions:
      - text: Add the categories {source_categories} under category {category_id}.
        slots:
          source_categories: requestBody.SourceCategories
          category_id: path.category
      - text: Nest several existing categories beneath parent {category_id} in one call.
        slots:
          category_id: path.category
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories/{id}/add'].post
  update:
    x-apievangelist-phrasing:
      intent: Copy a category tree under another category
      effect: write
      questions:
      - Can I add an existing category with its child categories and product associations under a different category?
      - How do I bring one category's whole subtree beneath a destination category?
      instructions:
      - text: Add category {source_category} with its children and products under category {destination_id}.
        slots:
          source_category: requestBody.SourceCategory
          destination_id: path.id
      - text: Place one existing category tree under destination {destination_id}.
        slots:
          destination_id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories/{id}/products'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a category's product listing
      effect: read
      questions:
      - What product category entries come back for a category ID?
      - Can I page the products returned for one category record?
      instructions:
      - text: Show the product category for category {category_id}.
        slots:
          category_id: path.id
      - text: Get product category entries of {category_id}, page {page}.
        slots:
          category_id: path.id
          page: query.page
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories/{parentId}/product-categories'].get
  update:
    x-apievangelist-phrasing:
      intent: List product categories under a category
      effect: read
      questions:
      - Which product-category associations belong to a given parent category?
      - Can I filter the product categories of a category?
      instructions:
      - text: List product categories under parent {parent_id}.
        slots:
          parent_id: path.parentId
      - text: Show product categories of {parent_id} matching {filter}.
        slots:
          parent_id: path.parentId
          filter: query.filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories/{parentId}/product-categories'].post
  update:
    x-apievangelist-phrasing:
      intent: Create product categories under a category
      effect: write
      questions:
      - Can I associate several products with a category at once?
      - How are multiple product category records created beneath a parent?
      instructions:
      - text: Create product categories under parent category {parent_id}.
        slots:
          parent_id: path.parentId
      - text: Link these products to category {parent_id} as new product categories.
        slots:
          parent_id: path.parentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories/{parentId}/product-categories'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete product categories in bulk
      effect: destructive
      questions:
      - Can I remove several product associations from a category in one request?
      - What's removed when I bulk-delete product categories under a parent?
      instructions:
      - text: Delete the listed product categories under parent {parent_id}.
        slots:
          parent_id: path.parentId
      - text: Bulk-unlink products from category {parent_id}.
        slots:
          parent_id: path.parentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories/{parentId}/product-categories'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update product categories in bulk
      effect: write
      questions:
      - Can I edit several product category records under one parent at once?
      - Which request updates multiple product-category links together?
      instructions:
      - text: Bulk-update the product categories under parent {parent_id}.
        slots:
          parent_id: path.parentId
      - text: Apply these changes to many product categories of {parent_id}.
        slots:
          parent_id: path.parentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories/{parentId}/product-categories/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one product category
      effect: read
      questions:
      - What are the details of one product category association?
      - Can I look up a single product category by its ID under a parent?
      instructions:
      - text: Show product category {product_category_id} under parent {parent_id}.
        slots:
          product_category_id: path.id
          parent_id: path.parentId
      - text: Fetch the product category link {product_category_id} of {parent_id}.
        slots:
          product_category_id: path.id
          parent_id: path.parentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories/{parentId}/product-categories/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one product category
      effect: destructive
      questions:
      - How do I remove one product from a category by the product category ID?
      - Can I delete a single product-category link without touching others?
      instructions:
      - text: Delete product category {product_category_id} under {parent_id}.
        slots:
          product_category_id: path.id
          parent_id: path.parentId
      - text: Unlink just product category {product_category_id} from parent {parent_id}.
        slots:
          product_category_id: path.id
          parent_id: path.parentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories/{parentId}/product-categories/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update one product category
      effect: write
      questions:
      - Can I change a single product category association?
      - Which call edits one product-category link by ID?
      instructions:
      - text: Update product category {product_category_id} under parent {parent_id}.
        slots:
          product_category_id: path.id
          parent_id: path.parentId
      - text: Edit only the product category link {product_category_id} in {parent_id}.
        slots:
          product_category_id: path.id
          parent_id: path.parentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories/{categoryId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a category with its child categories
      effect: read
      questions:
      - How can I see a category and its child categories for a specific price list?
      - Can I control how deep the child category tree goes?
      instructions:
      - text: Show category {category_id} and its children for price list {price_list_id}.
        slots:
          category_id: path.categoryId
          price_list_id: header.pricelistid
      - text: Get the category tree under {category_id} to depth {depth}.
        slots:
          category_id: path.categoryId
          depth: query.depth
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories/{categoryId}/products'].get
  update:
    x-apievangelist-phrasing:
      intent: List active products in a category
      effect: read
      questions:
      - Which active products are sold in a category under a given price list?
      - Can I search products within a category by keyword?
      - Is currency conversion optional when browsing a category's products?
      instructions:
      - text: List active products in category {category_id} for price list {price_list_id}.
        slots:
          category_id: path.categoryId
          price_list_id: header.pricelistid
      - text: Search category {category_id} products for {query}.
        slots:
          category_id: path.categoryId
          query: query.query
      - text: Show products in category {category_id} for storefront {storefront_id}.
        slots:
          category_id: path.categoryId
          storefront_id: header.storeFrontId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories/{categoryId}/services'].post
  update:
    x-apievangelist-phrasing:
      intent: List service products in a category
      effect: read
      questions:
      - Which active service products are available in a category?
      - Can I fetch service products for a point-of-sale context?
      instructions:
      - text: List service products in category {category_id} for price list {price_list_id}.
        slots:
          category_id: path.categoryId
          price_list_id: header.pricelistid
      - text: Show services in category {category_id} for cart {cart_id}.
        slots:
          category_id: path.categoryId
          cart_id: header.cartId
      method: generated
      generated: '2026-10-01'