API Evangelist conversational phrasing for dotCMS REST Tags API

# 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 Tags API
  version: 1.0.0
extends: openapi/dotcms-tags-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: 13
- target: $.paths['/api/v2/tags'].get
  update:
    x-apievangelist-phrasing:
      intent: List or search tags
      effect: read
      questions:
      - Which tags contain the word market?
      - Can I list only global tags, or only tags on one site?
      instructions:
      - text: Search tags matching {filter}.
        slots:
          filter: query.filter
      - text: List tags on site {site}, page {page}.
        slots:
          site: query.site
          page: query.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tags'].post
  update:
    x-apievangelist-phrasing:
      intent: Create one or more tags
      effect: write
      questions:
      - How do I create several tags in a single request?
      - What happens if I create a tag that already exists?
      instructions:
      - text: Create tags named summer-sale and holiday.
      - text: Add a new tag called press-release.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tags'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete several tags at once
      effect: destructive
      questions:
      - Can I delete a batch of tags by their IDs in one call?
      - Does bulk tag deletion fail if some IDs don't exist?
      instructions:
      - text: Delete all of these tags by ID in one go.
      - text: Bulk remove the unused tags from this list of IDs.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tags/{tagId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a single tag
      effect: destructive
      questions:
      - How do I delete one tag by its ID?
      - What permission is needed to remove a tag?
      instructions:
      - text: Delete tag {tagId}.
        slots:
          tagId: path.tagId
      - text: Remove the single tag with ID {tagId}.
        slots:
          tagId: path.tagId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tags/inode/{inode}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the tags on a content item
      effect: read
      questions:
      - What tags are attached to this piece of content?
      - Can I see tag relationships for a given content inode?
      instructions:
      - text: List the tags on content inode {inode}.
        slots:
          inode: path.inode
      - text: Show which tags are linked to {inode}.
        slots:
          inode: path.inode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tags/inode/{inode}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove all tags from a content item
      effect: destructive
      questions:
      - Can I strip every tag off a piece of content without deleting the tags?
      - Does unlinking tags from content delete the tags themselves?
      instructions:
      - text: Remove all tag associations from content {inode}.
        slots:
          inode: path.inode
      - text: Untag content {inode} completely but keep the tags.
        slots:
          inode: path.inode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tags/export/template'].get
  update:
    x-apievangelist-phrasing:
      intent: Download the CSV template for tag imports
      effect: read
      questions:
      - What format does a tag import CSV need to be in?
      - Is there a sample CSV I can fill in to import tags?
      instructions:
      - text: Download the tag import CSV template.
      - text: Get the example CSV with headers for importing tags.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tags/export'].get
  update:
    x-apievangelist-phrasing:
      intent: Export tags to CSV or JSON
      effect: read
      questions:
      - Can I export all my tags to a CSV file?
      - Is it possible to export only the tags for one site as JSON?
      instructions:
      - text: Export tags as {format}.
        slots:
          format: query.format
      - text: Export tags for site {siteId} matching {filter}.
        slots:
          siteId: query.siteId
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tags/{nameOrId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a tag by name or ID
      effect: read
      questions:
      - How do I look up a single tag by its name?
      - When two sites have the same tag name, how is the right one chosen?
      instructions:
      - text: Get tag {nameOrId}.
        slots:
          nameOrId: path.nameOrId
      - text: Look up tag {nameOrId} on site {siteId}.
        slots:
          nameOrId: path.nameOrId
          siteId: query.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tags/user/{userId}'].get
  update:
    x-apievangelist-phrasing:
      intent: List tags owned by a user
      effect: read
      questions:
      - Which tags belong to a particular user?
      - Can I see the tags linked to a user when they were created?
      instructions:
      - text: List tags owned by user {userId}.
        slots:
          userId: path.userId
      - text: Show the personal tags of {userId}.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tags/import'].post
  update:
    x-apievangelist-phrasing:
      intent: Import tags from a CSV file
      effect: write
      questions:
      - Can I bulk import tags from a spreadsheet?
      - Will a tag import tell me which CSV rows failed and why?
      instructions:
      - text: Import the tags in this CSV file.
      - text: Upload this tag CSV and report any rows that failed.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tags/tag/{nameOrId}/inode/{inode}'].put
  update:
    x-apievangelist-phrasing:
      intent: Attach a tag to a content item
      effect: write
      questions:
      - How do I tag a piece of content with an existing tag?
      - What happens if the tag name I link matches more than one tag?
      instructions:
      - text: Tag content {inode} with {nameOrId}.
        slots:
          inode: path.inode
          nameOrId: path.nameOrId
      - text: Link tag {nameOrId} to inode {inode}.
        slots:
          nameOrId: path.nameOrId
          inode: path.inode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tags/{idOrName}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename a tag or move it to another site
      effect: write
      questions:
      - Can I rename an existing tag?
      - How do I move a tag to a different site?
      instructions:
      - text: Rename tag {idOrName} to {tagName} on site {siteId}.
        slots:
          idOrName: path.idOrName
          tagName: requestBody.tagName
          siteId: requestBody.siteId
      - text: Reassign tag {idOrName} named {tagName} to site {siteId}.
        slots:
          idOrName: path.idOrName
          tagName: requestBody.tagName
          siteId: requestBody.siteId
      method: generated
      generated: '2026-09-26'