API Evangelist conversational phrasing for Kit 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 Kit Tags API
  version: 1.0.0
extends: openapi/convertkit-tags-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-02'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 11
- target: $.paths['/v4/bulk/tags'].post
  update:
    x-apievangelist-phrasing:
      intent: Create many tags at once
      effect: write
      questions:
      - Can I create a whole batch of new tags in one request?
      - Is there a callback when a bulk tag creation job completes?
      instructions:
      - text: 'Bulk create these tags: {tags}.'
        slots:
          tags: requestBody.tags
      - text: Create the tags {tags} in bulk and notify {callback_url} when done.
        slots:
          tags: requestBody.tags
          callback_url: requestBody.callback_url
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/bulk/tags/subscribers'].post
  update:
    x-apievangelist-phrasing:
      intent: Tag many subscribers at once
      effect: write
      questions:
      - How do I apply tags to thousands of subscribers in one go?
      - Do subscribers need to exist before I bulk-tag them?
      instructions:
      - text: 'Apply these taggings in bulk: {taggings}.'
        slots:
          taggings: requestBody.taggings
      - text: Bulk tag subscribers with {taggings} and post the result to {callback_url}.
        slots:
          taggings: requestBody.taggings
          callback_url: requestBody.callback_url
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/bulk/tags/subscribers'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove tags from many subscribers at once
      effect: destructive
      questions:
      - Can I strip tags from a large batch of subscribers in one request?
      - Is bulk untagging processed asynchronously?
      instructions:
      - text: Bulk remove tags from a batch of subscribers.
      - text: Untag many subscribers at once in a single bulk job.
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/tags'].get
  update:
    x-apievangelist-phrasing:
      intent: List tags
      effect: read
      questions:
      - What tags have I created for organizing subscribers?
      - How do I find a tag's id to use in other requests?
      instructions:
      - text: List all my tags.
      - text: Show my tags, {per_page} per page.
        slots:
          per_page: query.per_page
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/tags'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a tag
      effect: write
      questions:
      - How do I create a new tag for segmenting subscribers?
      - Can I add a single tag called something like Customer?
      instructions:
      - text: Create a tag named {name}.
        slots:
          name: requestBody.name
      - text: Add a new subscriber tag called {name}.
        slots:
          name: requestBody.name
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/tags/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename a tag
      effect: write
      questions:
      - Can I rename an existing tag without re-tagging everyone?
      - What's the way to fix a typo in a tag name?
      instructions:
      - text: Rename tag {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Change the name of existing tag {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/tags/{tag_id}/subscribers'].get
  update:
    x-apievangelist-phrasing:
      intent: List subscribers with a tag
      effect: read
      questions:
      - Who has a particular tag applied?
      - Can I see subscribers who were tagged after a certain date?
      instructions:
      - text: List subscribers tagged with {tag_id}.
        slots:
          tag_id: path.tag_id
      - text: Show subscribers who got tag {tag_id} after {tagged_after}.
        slots:
          tag_id: path.tag_id
          tagged_after: query.tagged_after
      - text: List tag {tag_id} subscribers with status {status}.
        slots:
          tag_id: path.tag_id
          status: query.status
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/tags/{tag_id}/subscribers'].post
  update:
    x-apievangelist-phrasing:
      intent: Tag a subscriber by email address
      effect: write
      questions:
      - How do I tag someone when I only know their email address?
      - Does a person have to be an existing subscriber before I tag their email?
      instructions:
      - text: Tag {email_address} with tag {tag_id}.
        slots:
          email_address: requestBody.email_address
          tag_id: path.tag_id
      - text: Apply tag {tag_id} to the subscriber whose email is {email_address}.
        slots:
          tag_id: path.tag_id
          email_address: requestBody.email_address
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/tags/{tag_id}/subscribers'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a tag from a subscriber by email
      effect: destructive
      questions:
      - How do I untag a subscriber using their email address rather than their id?
      - Can I detach a tag from someone by email when I don't have their subscriber id?
      instructions:
      - text: Remove tag {tag_id} from a subscriber identified by email.
        slots:
          tag_id: path.tag_id
      - text: Untag the subscriber's email address from tag {tag_id}.
        slots:
          tag_id: path.tag_id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/tags/{tag_id}/subscribers/{id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Tag a subscriber by id
      effect: write
      questions:
      - Can I apply a tag to a subscriber using their subscriber id?
      - What's the request for tagging one known subscriber id?
      instructions:
      - text: Tag subscriber id {id} with tag {tag_id}.
        slots:
          id: path.id
          tag_id: path.tag_id
      - text: Apply tag {tag_id} to subscriber {id} by their id.
        slots:
          tag_id: path.tag_id
          id: path.id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/tags/{tag_id}/subscribers/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a tag from a subscriber by id
      effect: destructive
      questions:
      - How do I take a tag off one subscriber when I have their subscriber id?
      - Can a tag be detached from a single subscriber id without affecting others?
      instructions:
      - text: Remove tag {tag_id} from subscriber id {id}.
        slots:
          tag_id: path.tag_id
          id: path.id
      - text: Untag subscriber {id} from tag {tag_id} by their id.
        slots:
          id: path.id
          tag_id: path.tag_id
      method: generated
      generated: '2026-10-02'