API Evangelist conversational phrasing for Showpad 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 Showpad Tags API
  version: 1.0.0
extends: openapi/showpad-tags-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: 20
- target: $.paths['/tags.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List tags (legacy endpoint)
      effect: read
      questions:
      - Can I still list tags through the older tags.json endpoint?
      - How do I find a tag by external ID using the legacy list?
      instructions:
      - text: Using the legacy tags.json endpoint, list all tags.
      - text: With the older list endpoint, find tags with external ID {externalId}.
        slots:
          externalId: query.externalId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a tag (legacy endpoint)
      effect: write
      questions:
      - Is the old .json endpoint still usable for creating a tag?
      - Can I give a tag a description when creating it the legacy way?
      instructions:
      - text: Using the legacy create endpoint, create tag {name}.
        slots:
          name: requestBody.name
      - text: Via tags.json, create tag {name} described as {description}.
        slots:
          name: requestBody.name
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/count.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Count tags
      effect: read
      questions:
      - How many tags exist in our Showpad library?
      - What's the number of tags matching a given name?
      instructions:
      - text: Count all tags.
      - text: Count the tags named {name}.
        slots:
          name: query.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/description.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Describe the tag data model
      effect: read
      questions:
      - What fields does a tag object have in the legacy API?
      - Where can I see the allowed calls and parameters for tags?
      instructions:
      - text: Describe the tag model and its available API calls.
      - text: Show me the property definitions for the tag resource.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/{id1}/assets/{id2}.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Link or unlink a tag and asset via GET
      effect: write
      questions:
      - Is there a GET override for linking or unlinking from the tag's side?
      - Can I change a tag-to-asset assignment using the method parameter on the tag path?
      instructions:
      - text: From tag {id1}, use method {method} to change its link to asset {id2}.
        slots:
          method: query.method
          id1: path.id1
          id2: path.id2
      - text: Through GET on the tag path, apply {method} to tag {id1} and asset {id2}.
        slots:
          method: query.method
          id1: path.id1
          id2: path.id2
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/{id1}/assets/{id2}/link.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Tag an asset (from the tag side)
      effect: write
      questions:
      - How do I attach an asset to a tag using the tag's asset link endpoint?
      - Can I tag an asset by giving the tag ID first and then the asset ID?
      instructions:
      - text: On tag {id1}, link asset {id2}.
        slots:
          id1: path.id1
          id2: path.id2
      - text: Put asset {id2} under tag {id1} via the tag asset link.
        slots:
          id1: path.id1
          id2: path.id2
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/{id1}/assets/{id2}/unlink.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Untag an asset (from the tag side)
      effect: write
      questions:
      - How do I remove an asset from a tag through the tag's unlink endpoint?
      - Can I take one asset out of a tag without deleting either?
      instructions:
      - text: On tag {id1}, unlink asset {id2}.
        slots:
          id1: path.id1
          id2: path.id2
      - text: Take asset {id2} out of tag {id1} via the tag asset unlink.
        slots:
          id1: path.id1
          id2: path.id2
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/{id}.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a tag (legacy endpoint)
      effect: read
      questions:
      - Can I fetch one tag through the older .json endpoint?
      - What does the legacy single-tag response contain?
      instructions:
      - text: Using the legacy endpoint, get tag {id}.
        slots:
          id: path.id
      - text: Fetch tag {id} from tags/{id}.json.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/{id}.json'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a tag (legacy PUT)
      effect: write
      questions:
      - How do I rename a tag with a PUT on the legacy endpoint?
      - Can I move a tag to another division with a legacy PUT?
      instructions:
      - text: PUT a legacy update renaming tag {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: With legacy PUT, move tag {id} to division {divisionId}.
        slots:
          id: path.id
          divisionId: requestBody.divisionId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/{id}.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a tag (legacy POST .json)
      effect: write
      questions:
      - Is there a POST variant on the legacy .json path for editing a tag?
      - Can I change a tag's description through the old POST update?
      instructions:
      - text: Via legacy POST to tags/{id}.json, set the description to {description}.
        slots:
          id: path.id
          description: requestBody.description
      - text: Using the old POST .json update, set tag {id}'s external ID to {externalId}.
        slots:
          id: path.id
          externalId: requestBody.externalId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/{id}.json'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a tag (legacy endpoint)
      effect: destructive
      questions:
      - Can I still delete a tag with the legacy .json endpoint?
      - What's the older way to remove a tag by ID?
      instructions:
      - text: Using the legacy endpoint, delete tag {id}.
        slots:
          id: path.id
      - text: Remove tag {id} via tags/{id}.json.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/{id}/assets.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List assets with a tag
      effect: read
      questions:
      - Which assets are labeled with a particular tag?
      - Can I see only the shareable assets under one tag?
      instructions:
      - text: List the assets tagged with tag {id}.
        slots:
          id: path.id
      - text: Show {filetype} assets under tag {id}.
        slots:
          id: path.id
          filetype: query.filetype
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/{id}/assets.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new asset under a tag
      effect: write
      questions:
      - How do I upload a new asset that's already tagged?
      - Can I create an asset directly inside a tag in one call?
      instructions:
      - text: Create asset {name} under tag {id}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Upload {file} as a new asset tagged with tag {id}.
        slots:
          id: path.id
          file: requestBody.file
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/{id}/link.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Link related resources to a tag
      effect: write
      questions:
      - How do I attach several resources to a tag using a Link list?
      - Can I connect a tag to multiple resources at once?
      instructions:
      - text: Link the resources {Link} to tag {id}.
        slots:
          id: path.id
          Link: requestBody.Link
      - text: Attach {Link} to tag {id} as related resources.
        slots:
          id: path.id
          Link: requestBody.Link
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/{id}/unlink.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Unlink related resources from a tag
      effect: write
      questions:
      - How do I detach a list of resources from a tag?
      - Can I remove several resource links from one tag in a single call?
      instructions:
      - text: Unlink the resources {Link} from tag {id}.
        slots:
          id: path.id
          Link: requestBody.Link
      - text: Detach {Link} from tag {id}.
        slots:
          id: path.id
          Link: requestBody.Link
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags'].get
  update:
    x-apievangelist-phrasing:
      intent: List tags
      effect: read
      questions:
      - How do I list the tags available to me, filtered by division or tag category?
      - Can I find a tag by its exact name?
      instructions:
      - text: List tags in tag categories {tagCategoryIds}.
        slots:
          tagCategoryIds: query.tagCategoryIds
      - text: Find the tag whose exact name is {exactName}.
        slots:
          exactName: query.exactName
      - text: List tags in divisions {divisionIds}.
        slots:
          divisionIds: query.divisionIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a tag
      effect: write
      questions:
      - How do I create a new tag in a division?
      - Can I record which external service a new tag came from?
      instructions:
      - text: Create tag {name} in division {division}.
        slots:
          name: requestBody.name
          division: requestBody.division
      - text: Create tag {name} in division {division} from external service {externalServiceId}.
        slots:
          name: requestBody.name
          division: requestBody.division
          externalServiceId: requestBody.externalServiceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/{tagId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a tag
      effect: read
      questions:
      - How do I retrieve a single tag by its ID?
      - What details are returned for one tag?
      instructions:
      - text: Get tag {tagId}.
        slots:
          tagId: path.tagId
      - text: Show the details of tag {tagId}.
        slots:
          tagId: path.tagId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/{tagId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Rename a tag
      effect: write
      questions:
      - How do I rename an existing tag?
      - Is the name the only thing I can change when updating a tag?
      instructions:
      - text: Rename tag {tagId} to {name}.
        slots:
          tagId: path.tagId
          name: requestBody.name
      - text: Change the name of tag {tagId} to {name}.
        slots:
          tagId: path.tagId
          name: requestBody.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/{tagId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a tag
      effect: destructive
      questions:
      - How do I delete a tag we no longer use?
      - What happens to a tag when I remove it?
      instructions:
      - text: Delete tag {tagId}.
        slots:
          tagId: path.tagId
      - text: Remove tag {tagId} permanently.
        slots:
          tagId: path.tagId
      method: generated
      generated: '2026-10-01'