# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for HERE Tracking Aliases API
  version: 1.0.0
extends: openapi/here-aliases-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: 11
- target: $.paths['/aliases/v2/health'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the Aliases service health
      effect: read
      questions:
      - Is the HERE Tracking Aliases service up right now?
      - Can I ping the Aliases service before sending it requests?
      instructions:
      - text: Check the health of the Aliases service.
      - text: Tell me whether the Aliases service is healthy.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/aliases/v2/version'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the Aliases service version
      effect: read
      questions:
      - What version of the Aliases service is deployed?
      - Which build of the Aliases service am I talking to?
      instructions:
      - text: Get the version of the Aliases service.
      - text: Show me which Aliases service version is running.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/aliases/v2'].get
  update:
    x-apievangelist-phrasing:
      intent: List all device aliases in a project
      effect: read
      questions:
      - Which aliases exist across all devices in my tracking project?
      - Can I find aliases whose external ID matches a wildcard pattern?
      - What aliases were created after a certain time in my project?
      instructions:
      - text: List every alias in project {projectId}.
        slots:
          projectId: query.projectId
      - text: Find project aliases of type {type} matching external ID pattern {externalId}.
        slots:
          type: query.type
          externalId: query.externalId
      - text: List project aliases created after {after}.
        slots:
          after: query.after
      method: generated
      generated: '2026-10-01'
- target: $.paths['/aliases/v2/{trackingId}'].get
  update:
    x-apievangelist-phrasing:
      intent: List all aliases of one device
      effect: read
      questions:
      - What aliases does a specific tracked device have?
      - Can I see every alias attached to a single tracking ID?
      instructions:
      - text: List all aliases of device {trackingId}.
        slots:
          trackingId: path.trackingId
      - text: Show device {trackingId}'s aliases, {count} at a time.
        slots:
          trackingId: path.trackingId
          count: query.count
      method: generated
      generated: '2026-10-01'
- target: $.paths['/aliases/v2/{trackingId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete every alias of a device
      effect: destructive
      questions:
      - Can I wipe all aliases from a device in one call?
      - What confirmation is needed to remove all of a device's aliases?
      instructions:
      - text: Delete all aliases of device {trackingId}, confirming with x-confirm {confirm}.
        slots:
          trackingId: path.trackingId
          confirm: header.x-confirm
      - text: Remove every alias, of every type, from device {trackingId}.
        slots:
          trackingId: path.trackingId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/aliases/v2/{trackingId}/{type}'].get
  update:
    x-apievangelist-phrasing:
      intent: List a device's aliases of one type
      effect: read
      questions:
      - Which aliases of a particular type does a device have?
      - Can I list just one kind of alias for a tracking ID?
      instructions:
      - text: List aliases of type {type} for device {trackingId}.
        slots:
          type: path.type
          trackingId: path.trackingId
      - text: Show device {trackingId}'s {type} aliases only.
        slots:
          trackingId: path.trackingId
          type: path.type
      method: generated
      generated: '2026-10-01'
- target: $.paths['/aliases/v2/{trackingId}/{type}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a device's aliases of one type
      effect: destructive
      questions:
      - Can I remove only the aliases of a single type from a device?
      - Is it possible to clear one alias type while keeping the others on a device?
      instructions:
      - text: Wipe only the {type}-type aliases on {trackingId}, passing x-confirm {confirm}.
        slots:
          type: path.type
          trackingId: path.trackingId
          confirm: header.x-confirm
      - text: Clear the {type} aliases from device {trackingId}, keeping other alias types.
        slots:
          type: path.type
          trackingId: path.trackingId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/aliases/v2/trackingId'].get
  update:
    x-apievangelist-phrasing:
      intent: Find the device that owns an alias
      effect: read
      questions:
      - Which tracking ID does a given external ID map to?
      - If I only know a device's alias, can I look up its tracking ID?
      instructions:
      - text: Get the tracking ID for alias {externalId} of type {type}.
        slots:
          externalId: query.externalId
          type: query.type
      - text: Resolve {type} alias {externalId} in project {projectId} to a tracking ID.
        slots:
          type: query.type
          externalId: query.externalId
          projectId: query.projectId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/aliases/v2/{trackingId}/{type}/{externalId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Add one alias to a device
      effect: write
      questions:
      - How do I give a tracked device a friendly external ID?
      - Does an alias have to be unique within a project?
      instructions:
      - text: Create alias {externalId} of type {type} for device {trackingId}.
        slots:
          externalId: path.externalId
          type: path.type
          trackingId: path.trackingId
      - text: Tag device {trackingId} with the single {type} alias {externalId}.
        slots:
          trackingId: path.trackingId
          type: path.type
          externalId: path.externalId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/aliases/v2/{trackingId}/{type}/{externalId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one specific alias of a device
      effect: destructive
      questions:
      - Can I remove just one alias from a device and keep the rest?
      - What happens if I delete a single external ID alias?
      instructions:
      - text: Delete alias {externalId} of type {type} from device {trackingId}.
        slots:
          externalId: path.externalId
          type: path.type
          trackingId: path.trackingId
      - text: Remove the single {type} alias {externalId} on device {trackingId}.
        slots:
          type: path.type
          externalId: path.externalId
          trackingId: path.trackingId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/aliases/v2/{trackingId}/batch'].put
  update:
    x-apievangelist-phrasing:
      intent: Add several aliases to a device at once
      effect: write
      questions:
      - Can I create multiple aliases for one device in a single request?
      - Is there a bulk way to assign aliases to a tracker?
      instructions:
      - text: Create aliases {aliases} for device {trackingId} in one batch.
        slots:
          aliases: requestBody.aliases
          trackingId: path.trackingId
      - text: Bulk-add the aliases {aliases} to device {trackingId}.
        slots:
          aliases: requestBody.aliases
          trackingId: path.trackingId
      method: generated
      generated: '2026-10-01'