# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for dotCMS REST Categories API
  version: 1.0.0
extends: openapi/dotcms-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: 10
- target: $.paths['/api/v1/categories'].get
  update:
    x-apievangelist-phrasing:
      intent: List categories
      effect: read
      questions:
      - What top-level categories are set up in dotCMS?
      - Can I see how many child categories each category has?
      instructions:
      - text: List all categories.
      - text: List categories matching {filter} with child counts.
        slots:
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/categories'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an existing category
      effect: write
      questions:
      - How do I rename an existing category?
      - Can I change a category's key or keywords after it's created?
      instructions:
      - text: Rename category {inode} to {categoryName}.
        slots:
          inode: requestBody.inode
          categoryName: requestBody.categoryName
      - text: Update category {inode} named {categoryName} with keywords {keywords}.
        slots:
          inode: requestBody.inode
          categoryName: requestBody.categoryName
          keywords: requestBody.keywords
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/categories'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new category
      effect: write
      questions:
      - How do I add a new category to use for tagging content?
      - Can I create a subcategory under an existing parent?
      instructions:
      - text: Create a category called {categoryName}.
        slots:
          categoryName: requestBody.categoryName
      - text: Create subcategory {categoryName} under parent {parent} with key {key}.
        slots:
          categoryName: requestBody.categoryName
          parent: requestBody.parent
          key: requestBody.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/categories'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete categories and their descendants
      effect: destructive
      questions:
      - Does deleting a category also delete all of its subcategories?
      - What happens when I lack permission on one child of a category I delete?
      instructions:
      - text: Delete these categories and everything beneath them.
      - text: Remove the selected categories by inode and report any that failed.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/categories/_export'].get
  update:
    x-apievangelist-phrasing:
      intent: Export categories to CSV
      effect: read
      questions:
      - Can I download my category tree as a CSV?
      - Is it possible to export just the children of one parent category?
      instructions:
      - text: Export all categories to CSV.
      - text: Export categories under parent {contextInode} matching {filter}.
        slots:
          contextInode: query.contextInode
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/categories/{idOrKey}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a category by ID or key
      effect: read
      questions:
      - How do I look up a single category by its key?
      - Can I fetch one category and see how many children it has?
      instructions:
      - text: Get category {idOrKey}.
        slots:
          idOrKey: path.idOrKey
      - text: Show category {idOrKey} with its child count.
        slots:
          idOrKey: path.idOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/categories/children'].get
  update:
    x-apievangelist-phrasing:
      intent: List the children of a category
      effect: read
      questions:
      - What subcategories sit under a given parent category?
      - Can I get every descendant at all levels, not just direct children?
      instructions:
      - text: List the child categories of {inode}.
        slots:
          inode: query.inode
      - text: List all descendants of category {inode} at every level.
        slots:
          inode: query.inode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/categories/hierarchy'].post
  update:
    x-apievangelist-phrasing:
      intent: Get parent chains for several categories
      effect: read
      questions:
      - Which parent categories sit above each of these category keys?
      - Can I get the breadcrumb path for multiple categories in one call?
      instructions:
      - text: Get the parent hierarchy for category keys {keys}.
        slots:
          keys: requestBody.keys
      - text: Show the breadcrumb from top level down for categories {keys}.
        slots:
          keys: requestBody.keys
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/categories/_import'].post
  update:
    x-apievangelist-phrasing:
      intent: Import categories from a CSV file
      effect: write
      questions:
      - Can I import categories from a CSV and replace the existing ones?
      - What's the difference between merge and replace when importing categories?
      instructions:
      - text: Import categories from {file} using the {exportType} strategy.
        slots:
          file: requestBody.file
          exportType: requestBody.exportType
      - text: Merge categories from {file} under parent {contextInode}.
        slots:
          file: requestBody.file
          contextInode: requestBody.contextInode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/categories/_sort'].put
  update:
    x-apievangelist-phrasing:
      intent: Change the sort order of categories
      effect: write
      questions:
      - How do I reorder categories so they appear in a specific sequence?
      - Can I change the sort order of several subcategories at once?
      instructions:
      - text: Update the sort order of categories under {parentInode} to {categoryData}.
        slots:
          parentInode: requestBody.parentInode
          categoryData: requestBody.categoryData
      - text: Apply new sort positions {categoryData} to these categories.
        slots:
          categoryData: requestBody.categoryData
      method: generated
      generated: '2026-09-26'