# 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 Labels API
  version: 1.0.0
extends: openapi/here-labels-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['/labels/v4/health'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the Labels service health
      effect: read
      questions:
      - Is the HERE Tracking Labels service up right now?
      - Can I ping the Labels service before sending it requests?
      instructions:
      - text: Check the health of the Labels service.
      - text: Tell me whether the Labels service is healthy.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/labels/v4/version'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the Labels service version
      effect: read
      questions:
      - What version of the Labels service is deployed?
      - Which build of the Labels service am I talking to?
      instructions:
      - text: Get the version of the Labels service.
      - text: Show me which Labels service version is running.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/labels/v4/{resourceType}'].get
  update:
    x-apievangelist-phrasing:
      intent: List labels across a resource type
      effect: read
      questions:
      - What labels are used on all my devices or geofences?
      - Can I find resources of a type that carry certain labels?
      instructions:
      - text: List all labels on {resourceType} resources.
        slots:
          resourceType: path.resourceType
      - text: Find {resourceType} resources labelled {labels}.
        slots:
          resourceType: path.resourceType
          labels: query.labels
      method: generated
      generated: '2026-10-01'
- target: $.paths['/labels/v4/{resourceType}/keys'].get
  update:
    x-apievangelist-phrasing:
      intent: List label keys for a resource type
      effect: read
      questions:
      - Which label keys exist for a resource type?
      - What label names have been used on my devices?
      instructions:
      - text: List the label keys used on {resourceType} resources.
        slots:
          resourceType: path.resourceType
      - text: Show label keys for {resourceType} in project {projectId}.
        slots:
          resourceType: path.resourceType
          projectId: query.projectId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/labels/v4/{resourceType}/keys/{key}/values'].get
  update:
    x-apievangelist-phrasing:
      intent: List values used for a label key
      effect: read
      questions:
      - What values has a particular label key been given?
      - Can I see all values of one label across a resource type?
      instructions:
      - text: List values of label {key} on {resourceType} resources.
        slots:
          key: path.key
          resourceType: path.resourceType
      - text: Show every value used for key {key} on {resourceType}.
        slots:
          key: path.key
          resourceType: path.resourceType
      method: generated
      generated: '2026-10-01'
- target: $.paths['/labels/v4/{resourceType}/{resourceId}'].get
  update:
    x-apievangelist-phrasing:
      intent: List labels on one resource
      effect: read
      questions:
      - Which labels are attached to a specific device?
      - What tags does one resource carry?
      instructions:
      - text: List labels on {resourceType} {resourceId}.
        slots:
          resourceType: path.resourceType
          resourceId: path.resourceId
      - text: Show the labels of resource {resourceId} of type {resourceType}.
        slots:
          resourceId: path.resourceId
          resourceType: path.resourceType
      method: generated
      generated: '2026-10-01'
- target: $.paths['/labels/v4/{resourceType}/{resourceId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove every label from a resource
      effect: destructive
      questions:
      - Can I strip all labels from a resource in one call?
      - What clears every tag from a device?
      instructions:
      - text: Delete all labels on {resourceType} {resourceId}.
        slots:
          resourceType: path.resourceType
          resourceId: path.resourceId
      - text: Clear every label from resource {resourceId} of type {resourceType}.
        slots:
          resourceId: path.resourceId
          resourceType: path.resourceType
      method: generated
      generated: '2026-10-01'
- target: $.paths['/labels/v4/{resourceType}/{resourceId}/{key}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a resource's labels with one key
      effect: destructive
      questions:
      - Can I remove all labels with a given key from a resource?
      - What deletes one label key, whatever its values, from a device?
      instructions:
      - text: Delete labels with key {key} from {resourceType} {resourceId}.
        slots:
          key: path.key
          resourceType: path.resourceType
          resourceId: path.resourceId
      - text: Remove every {key} label, any value, from resource {resourceId} ({resourceType}).
        slots:
          key: path.key
          resourceId: path.resourceId
          resourceType: path.resourceType
      method: generated
      generated: '2026-10-01'
- target: $.paths['/labels/v4/{resourceType}/{resourceId}/{key}/{value}'].put
  update:
    x-apievangelist-phrasing:
      intent: Add a label to a resource
      effect: write
      questions:
      - How do I tag a device with a key-value label?
      - Can I attach a single label to a geofence?
      instructions:
      - text: Label {resourceType} {resourceId} with {key}={value}.
        slots:
          resourceType: path.resourceType
          resourceId: path.resourceId
          key: path.key
          value: path.value
      - text: Add label {key}:{value} to resource {resourceId} of type {resourceType}.
        slots:
          key: path.key
          value: path.value
          resourceId: path.resourceId
          resourceType: path.resourceType
      method: generated
      generated: '2026-10-01'
- target: $.paths['/labels/v4/{resourceType}/{resourceId}/{key}/{value}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove one key-value label from a resource
      effect: destructive
      questions:
      - Can I delete just one key and value pair from a resource's labels?
      - What removes a single exact label from a device?
      instructions:
      - text: Delete label {key}={value} from {resourceType} {resourceId}.
        slots:
          key: path.key
          value: path.value
          resourceType: path.resourceType
          resourceId: path.resourceId
      - text: Remove only the {key}:{value} label on resource {resourceId} ({resourceType}).
        slots:
          key: path.key
          value: path.value
          resourceId: path.resourceId
          resourceType: path.resourceType
      method: generated
      generated: '2026-10-01'
- target: $.paths['/labels/v4/{resourceType}/{resourceId}/batch'].put
  update:
    x-apievangelist-phrasing:
      intent: Add several labels to a resource at once
      effect: write
      questions:
      - Can I attach multiple labels to a resource in a single request?
      - Is there a bulk way to tag a device?
      instructions:
      - text: Add labels {labels} to {resourceType} {resourceId}.
        slots:
          labels: requestBody.labels
          resourceType: path.resourceType
          resourceId: path.resourceId
      - text: Bulk-label resource {resourceId} of type {resourceType} with {labels}.
        slots:
          resourceId: path.resourceId
          resourceType: path.resourceType
          labels: requestBody.labels
      method: generated
      generated: '2026-10-01'