API Evangelist conversational phrasing for Tenable 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 Tenable Tags API
  version: 1.0.0
extends: openapi/tenable-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: 17
- target: $.paths['/api/v1/t1/tags/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search tags with filters
      effect: read
      questions:
      - Can I search my organization's tags using filters and a text query?
      - Which tags match a given set of filter criteria in my exposure inventory?
      - Is the beta tag search endpoint able to sort and page results?
      instructions:
      - text: Search tags matching the text {query}.
        slots:
          query: requestBody.query
      - text: Search tags using filters {filters} and return {limit} results.
        slots:
          filters: requestBody.filters
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/t1/tags/properties'].get
  update:
    x-apievangelist-phrasing:
      intent: List tag properties usable as search filters
      effect: read
      questions:
      - What tag properties can I filter on when searching tags?
      - Which fields are available for building a tag search filter?
      instructions:
      - text: List the tag properties I can use as filters in a tag search.
      - text: Show me the filterable properties for the tag search endpoint.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/categories'].get
  update:
    x-apievangelist-phrasing:
      intent: List tag categories
      effect: read
      questions:
      - What tag categories exist in my Tenable Vulnerability Management account?
      - Can I filter tag categories by name and sort them?
      instructions:
      - text: List all my asset tag categories.
      - text: List the first {limit} tag categories sorted by {sort}.
        slots:
          limit: query.limit
          sort: query.sort
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/categories'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a tag category
      effect: write
      questions:
      - How do I create a new category to group my asset tags?
      - Can I give a tag category a description when I create it?
      instructions:
      - text: Create a tag category named {name}.
        slots:
          name: requestBody.name
      - text: Create tag category {name} with description {description}.
        slots:
          name: requestBody.name
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/categories/{tag_category_uuid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get details of one tag category
      effect: read
      questions:
      - What details are stored for a specific tag category?
      - Can I look up a single tag category by its UUID?
      instructions:
      - text: Get the details of tag category {tag_category_uuid}.
        slots:
          tag_category_uuid: path.tag_category_uuid
      - text: Show me the name and description of tag category {tag_category_uuid}.
        slots:
          tag_category_uuid: path.tag_category_uuid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/categories/{tag_category_uuid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename or redescribe a tag category
      effect: write
      questions:
      - Can I rename an existing tag category?
      - What permissions do I need to edit a tag category that already has tags in it?
      instructions:
      - text: Rename tag category {tag_category_uuid} to {name}.
        slots:
          tag_category_uuid: path.tag_category_uuid
          name: requestBody.name
      - text: Update tag category {tag_category_uuid} with name {name} and description {description}.
        slots:
          tag_category_uuid: path.tag_category_uuid
          name: requestBody.name
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/categories/{tag_category_uuid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a tag category and its values
      effect: destructive
      questions:
      - What happens to tag values and assets when I delete a whole tag category?
      - Can I remove a tag category I no longer use?
      instructions:
      - text: Delete tag category {tag_category_uuid} along with all its tag values.
        slots:
          tag_category_uuid: path.tag_category_uuid
      - text: Remove the tag category {tag_category_uuid} from my account.
        slots:
          tag_category_uuid: path.tag_category_uuid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/values'].get
  update:
    x-apievangelist-phrasing:
      intent: List tag values
      effect: read
      questions:
      - Which tag values have been defined across my categories?
      - Does the tag value list also include categories that have no values yet?
      - Can I do a wildcard text search across tag values?
      instructions:
      - text: List all my asset tag values.
      - text: List tag values whose fields contain {w}.
        slots:
          w: query.w
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/values'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a tag value in a category
      effect: write
      questions:
      - How do I add a new tag value under a category?
      - Will a tag category be created automatically if I name one that doesn't exist yet?
      - Can I create a dynamic tag with filter rules that applies itself to matching assets?
      instructions:
      - text: Create tag value {value} in category {category_name}.
        slots:
          value: requestBody.value
          category_name: requestBody.category_name
      - text: Create a dynamic tag value {value} in category {category_uuid} using rules {filters}.
        slots:
          value: requestBody.value
          category_uuid: requestBody.category_uuid
          filters: requestBody.filters
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/values/{tag_value_uuid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get details of one tag value
      effect: read
      questions:
      - What rules and access settings are attached to a specific tag value?
      - Can I fetch one tag value by its UUID?
      instructions:
      - text: Get the details of tag value {tag_value_uuid}.
        slots:
          tag_value_uuid: path.tag_value_uuid
      - text: Show me the dynamic rules defined on tag value {tag_value_uuid}.
        slots:
          tag_value_uuid: path.tag_value_uuid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/values/{tag_value_uuid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a tag value
      effect: write
      questions:
      - Can I change the rules on an existing dynamic tag value?
      - Is it possible to rename a tag value after assets already carry it?
      instructions:
      - text: Rename tag value {tag_value_uuid} to {value}.
        slots:
          tag_value_uuid: path.tag_value_uuid
          value: requestBody.value
      - text: Replace the dynamic rules on tag value {tag_value_uuid} with {filters}.
        slots:
          tag_value_uuid: path.tag_value_uuid
          filters: requestBody.filters
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/values/{tag_value_uuid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a single tag value
      effect: destructive
      questions:
      - Does deleting a tag value also strip it from every asset that has it?
      - Can I delete just one tag value without touching the rest of its category?
      instructions:
      - text: Delete tag value {tag_value_uuid}.
        slots:
          tag_value_uuid: path.tag_value_uuid
      - text: Remove the single tag value {tag_value_uuid} and unassign it from its assets.
        slots:
          tag_value_uuid: path.tag_value_uuid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/values/delete-requests'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete many tag values at once
      effect: destructive
      questions:
      - Can I delete a batch of tag values in one request?
      - What happens to a category when I bulk delete all of its tag values?
      instructions:
      - text: Bulk delete the tag values {values}.
        slots:
          values: requestBody.values
      - text: 'Delete these tag value UUIDs in one request: {values}.'
        slots:
          values: requestBody.values
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/assets/assignments'].post
  update:
    x-apievangelist-phrasing:
      intent: Add or remove tags on assets
      effect: write
      questions:
      - How do I tag a group of assets in one go?
      - Can I remove a tag from several assets at the same time?
      - Is assigning tags to assets processed as an asynchronous job?
      instructions:
      - text: Add tags {tags} to assets {assets}.
        slots:
          tags: requestBody.tags
          assets: requestBody.assets
      - text: Run tag action {action} for tags {tags} on assets {assets}.
        slots:
          action: requestBody.action
          tags: requestBody.tags
          assets: requestBody.assets
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/assets/{asset_uuid}/assignments'].get
  update:
    x-apievangelist-phrasing:
      intent: List tags assigned to an asset
      effect: read
      questions:
      - Which tags are currently assigned to a particular asset?
      - What does it return when an asset has no tags at all?
      instructions:
      - text: List the tags assigned to asset {asset_uuid}.
        slots:
          asset_uuid: path.asset_uuid
      - text: Show me every tag on asset {asset_uuid}.
        slots:
          asset_uuid: path.asset_uuid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/values/{tag_value_uuid}/exclusions'].get
  update:
    x-apievangelist-phrasing:
      intent: List assets excluded from a dynamic tag
      effect: read
      questions:
      - Which assets have been excluded from a dynamic tag's rules?
      - Can I filter dynamic tag exclusions by target type?
      instructions:
      - text: List the assets excluded from dynamic tag {tag_value_uuid}.
        slots:
          tag_value_uuid: path.tag_value_uuid
      - text: List exclusions of type {target_type} for tag {tag_value_uuid}.
        slots:
          target_type: query.target_type
          tag_value_uuid: path.tag_value_uuid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/assets/filters'].get
  update:
    x-apievangelist-phrasing:
      intent: List filters for dynamic tag rules
      effect: read
      questions:
      - What fields and operators can I use to write rules for a dynamic tag?
      - How many values can a dynamic tag rule match against?
      instructions:
      - text: List the asset filters available for building dynamic tag rules.
      - text: Show me the operators I can use in dynamic tag rules.
      method: generated
      generated: '2026-10-01'