API Evangelist conversational phrasing for dotCMS REST Tag (v1) 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 Tag (v1) API
  version: 1.0.0
extends: openapi/dotcms-tag-v1-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/tags'].get
  update:
    x-apievangelist-phrasing:
      intent: List or search tags (v1, deprecated)
      effect: read
      questions:
      - How do I list all tags or search them by name on the old v1 tags API?
      - If no tags match on my site, does the v1 search fall back to global tags?
      instructions:
      - text: List all tags with the deprecated v1 endpoint.
      - text: Search v1 tags named like {name} on site {siteId}.
        slots:
          name: query.name
          siteId: query.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/tags'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename a tag or change its site (v1)
      effect: write
      questions:
      - How do I rename an existing tag using the v1 tags API?
      - Can I move a tag to a different site through the deprecated endpoint?
      instructions:
      - text: Rename tag {tagId} to {tagName} on site {siteId}.
        slots:
          tagId: requestBody.tagId
          tagName: requestBody.tagName
          siteId: requestBody.siteId
      - text: Update v1 tag {tagName} so it belongs to site {siteId}.
        slots:
          tagName: requestBody.tagName
          siteId: requestBody.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/tags'].post
  update:
    x-apievangelist-phrasing:
      intent: Create tags (v1, deprecated)
      effect: write
      questions:
      - How do I create a new tag with the v1 tags API?
      - Can a tag created through v1 be owned by a user or marked as a persona tag?
      instructions:
      - text: Create tag {name}.
        slots:
          name: requestBody.name
      - text: Create tag {name} on site {siteId} owned by user {ownerId}.
        slots:
          name: requestBody.name
          siteId: requestBody.siteId
          ownerId: requestBody.ownerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/tags/{tagId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a tag by id (v1)
      effect: destructive
      questions:
      - How do I delete a tag through the deprecated v1 API?
      - What permission do I need on tagged content to delete a tag?
      instructions:
      - text: Delete tag {tagId}.
        slots:
          tagId: path.tagId
      - text: Remove the orphan tag {tagId} using the v1 endpoint.
        slots:
          tagId: path.tagId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/tags/inode/{inode}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the tags attached to an inode (v1)
      effect: read
      questions:
      - Which tags are attached to a particular content version (inode)?
      - How do I read the tag-inode links for one inode?
      instructions:
      - text: Show the tags linked to inode {inode}.
        slots:
          inode: path.inode
      - text: List tag associations for inode {inode}.
        slots:
          inode: path.inode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/tags/inode/{inode}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unlink all tags from an inode (v1)
      effect: destructive
      questions:
      - How do I strip every tag off a content version at once?
      - Does removing an inode's tag links delete the tags themselves?
      instructions:
      - text: Remove all tag links from inode {inode}.
        slots:
          inode: path.inode
      - text: Untag inode {inode} completely.
        slots:
          inode: path.inode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/tags/{nameOrId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up tags by exact name or id (v1)
      effect: read
      questions:
      - How do I fetch a tag when I know its exact name or UUID?
      - Does the v1 lookup treat a UUID as an id and anything else as a name?
      instructions:
      - text: Look up the tag {nameOrId}.
        slots:
          nameOrId: path.nameOrId
      - text: Fetch tags exactly matching name or id {nameOrId}.
        slots:
          nameOrId: path.nameOrId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/tags/user/{userId}'].get
  update:
    x-apievangelist-phrasing:
      intent: List tags owned by a user (v1)
      effect: read
      questions:
      - Which tags are owned by a specific user?
      - Can I see the tags that were assigned to a user owner when created?
      instructions:
      - text: List tags owned by user {userId}.
        slots:
          userId: path.userId
      - text: Show the tags belonging to {userId}.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/tags/import'].post
  update:
    x-apievangelist-phrasing:
      intent: Import tags from a file (v1)
      effect: write
      questions:
      - How do I bulk import tags from a file?
      - Can I upload a tag list as multipart form data on the v1 API?
      instructions:
      - text: Import tags from this uploaded file.
      - text: Bulk load tags from the attached CSV with the v1 import.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/tags/tag/{nameOrId}/inode/{inode}'].put
  update:
    x-apievangelist-phrasing:
      intent: Attach a tag to an inode (v1)
      effect: write
      questions:
      - How do I tag a specific content version by its inode?
      - What happens if the tag name I link matches more than one tag?
      instructions:
      - text: Link tag {nameOrId} to inode {inode}.
        slots:
          nameOrId: path.nameOrId
          inode: path.inode
      - text: Tag inode {inode} with {nameOrId}.
        slots:
          inode: path.inode
          nameOrId: path.nameOrId
      method: generated
      generated: '2026-09-26'