# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Here Metadata API
  version: 1.0.0
extends: openapi/here-metadata-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: 29
- target: $.paths['/layerVersions'].get
  update:
    x-apievangelist-phrasing:
      intent: Get layer versions for a catalog version
      effect: read
      questions:
      - Which version of each layer was part of a given catalog version?
      - What happens if I ask for layer versions of a catalog version that does not exist?
      instructions:
      - text: Get the layer versions that make up catalog version {version}.
        slots:
          version: query.version
      - text: Show layer versions for catalog version {version} billed to tag {billingTag}.
        slots:
          version: query.version
          billingTag: query.billingTag
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/changes'].get
  update:
    x-apievangelist-phrasing:
      intent: Get partition changes in a version or time range
      effect: read
      questions:
      - Which partitions in a versioned layer changed between two catalog versions?
      - Can I see what changed in a volatile layer since a certain time?
      instructions:
      - text: Get partitions in layer {layerId} that changed between version {startVersion} and {endVersion}.
        slots:
          layerId: path.layerId
          startVersion: query.startVersion
          endVersion: query.endVersion
      - text: Show changes to volatile layer {layerId} since {sinceTime}.
        slots:
          layerId: path.layerId
          sinceTime: query.sinceTime
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/changes/parts'].get
  update:
    x-apievangelist-phrasing:
      intent: Split a layer's change query into parallel parts
      effect: read
      questions:
      - How can I fetch layer changes in parallel instead of one big query?
      - What part IDs should I use to divide a changes query across workers?
      instructions:
      - text: Get {numRequestedParts} part IDs for querying changes in layer {layerId} in parallel.
        slots:
          numRequestedParts: query.numRequestedParts
          layerId: path.layerId
      - text: Split the changes query for layer {layerId} into {numRequestedParts} parts.
        slots:
          layerId: path.layerId
          numRequestedParts: query.numRequestedParts
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/partitions'].get
  update:
    x-apievangelist-phrasing:
      intent: Get metadata for all partitions in a layer
      effect: read
      questions:
      - What partitions exist in a layer of my HERE catalog?
      - Can I read partition metadata as of an older catalog version?
      instructions:
      - text: List the partitions in layer {layerId}.
        slots:
          layerId: path.layerId
      - text: Get partition metadata for layer {layerId} at catalog version {version}.
        slots:
          layerId: path.layerId
          version: query.version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/partitions/parts'].get
  update:
    x-apievangelist-phrasing:
      intent: Split a layer's partition listing into parallel parts
      effect: read
      questions:
      - How do I list every partition of a huge layer using parallel requests?
      - Which part IDs divide a layer's partition metadata into chunks?
      instructions:
      - text: Get {numRequestedParts} part IDs for listing partitions of layer {layerId} in parallel.
        slots:
          numRequestedParts: query.numRequestedParts
          layerId: path.layerId
      - text: Divide the partition metadata of layer {layerId} into {numRequestedParts} parts.
        slots:
          layerId: path.layerId
          numRequestedParts: query.numRequestedParts
      method: generated
      generated: '2026-09-26'
- target: $.paths['/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: List catalog versions
      effect: read
      questions:
      - What versions does my catalog have between two version numbers?
      - How many catalog versions can come back in a single call?
      instructions:
      - text: List catalog versions from {startVersion} to {endVersion}.
        slots:
          startVersion: query.startVersion
          endVersion: query.endVersion
      - text: Get details about catalog version {version}.
        slots:
          version: query.version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/versions/compatibles'].post
  update:
    x-apievangelist-phrasing:
      intent: Find catalog versions compatible with dependencies
      effect: read
      questions:
      - Which versions of this catalog were built against the same dependency versions I use?
      - Can I require a strict match on every listed dependency HRN when checking compatibility?
      instructions:
      - text: Find catalog versions compatible with dependencies {dependencies}.
        slots:
          dependencies: requestBody.dependencies
      - text: Return up to {limit} catalog versions that strictly match dependencies {dependencies}.
        slots:
          limit: query.limit
          dependencies: requestBody.dependencies
      method: generated
      generated: '2026-09-26'
- target: $.paths['/versions/latest'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the latest catalog version
      effect: read
      questions:
      - What is the newest version of my HERE catalog?
      - Has the catalog published anything newer than the version I last saw?
      instructions:
      - text: Get the latest catalog version, starting from version {startVersion}.
        slots:
          startVersion: query.startVersion
      - text: Check the most recent catalog version after {startVersion}.
        slots:
          startVersion: query.startVersion
      method: generated
      generated: '2026-09-26'
- target: $.paths['/versions/minimum'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the earliest available catalog version
      effect: read
      questions:
      - What is the oldest catalog version still available?
      - How far back can I read versions of this catalog?
      instructions:
      - text: Get the minimum available catalog version.
      - text: Show the earliest catalog version billed to {billingTag}.
        slots:
          billingTag: query.billingTag
      method: generated
      generated: '2026-09-26'
- target: $.paths['/versions/minimum'].post
  update:
    x-apievangelist-phrasing:
      intent: Set the earliest catalog version and drop older ones
      effect: destructive
      questions:
      - How do I delete all catalog versions older than a certain one?
      - Is raising the minimum catalog version reversible?
      instructions:
      - text: Set the catalog's minimum version to {version}, deleting all prior versions.
        slots:
          version: requestBody.version
      - text: Purge catalog versions before {version}.
        slots:
          version: requestBody.version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/info'].get
  update:
    x-apievangelist-phrasing:
      intent: List accepted values for map image parameters
      effect: read
      questions:
      - What PPI values and styles can I request for a map image?
      - Which parameter values does the map image service accept?
      instructions:
      - text: Show the accepted values for map image parameters like PPI and style.
      - text: List valid map image request options.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/politicalViews'].get
  update:
    x-apievangelist-phrasing:
      intent: List available geopolitical map views
      effect: read
      questions:
      - Which country-specific geopolitical views can a map image be rendered with?
      - Can I show disputed borders the way a particular country sees them?
      instructions:
      - text: List the available geopolitical views for map images.
      - text: Show which country political views I can request.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/features'].get
  update:
    x-apievangelist-phrasing:
      intent: List map features available per style
      effect: read
      questions:
      - Which optional map features can I turn on for each map style?
      - What features does a given style support in a map image request?
      instructions:
      - text: List the available map features for each style.
      - text: Show the per-style feature options for map images.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/languages'].get
  update:
    x-apievangelist-phrasing:
      intent: List available map label languages
      effect: read
      questions:
      - In which languages can map labels be rendered?
      - Does the map image service support labels in Japanese?
      instructions:
      - text: List the languages available for map labels.
      - text: Show supported map language codes per resource.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/copyright'].get
  update:
    x-apievangelist-phrasing:
      intent: Get map data copyright notices
      effect: read
      questions:
      - What copyright text do I have to display with HERE map images?
      - Which areas does each map copyright notice apply to?
      instructions:
      - text: Get the map copyright information with its bounding boxes.
      - text: Show the attribution text I must display for map data.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/metadata/v2/health'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the tracking Metadata service health
      effect: read
      questions:
      - Is the HERE Tracking Metadata service up right now?
      - Can I ping the tracking Metadata service before using it?
      instructions:
      - text: Check the health of the tracking Metadata service.
      - text: Tell me whether the tracking Metadata service is healthy.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/metadata/v2/version'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the tracking Metadata service version
      effect: read
      questions:
      - What version of the tracking Metadata service is deployed?
      - Which build of the tracking Metadata service am I calling?
      instructions:
      - text: Get the version of the tracking Metadata service.
      - text: Show which tracking Metadata service version is running.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/metadata/v2/devices/{trackingId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a device's or shipment's metadata
      effect: read
      questions:
      - What custom metadata is stored on a tracker or shipment?
      - Can I read the metadata object of a shipment by its ID?
      instructions:
      - text: Get the metadata of device {trackingId}.
        slots:
          trackingId: path.trackingId
      - text: Show custom metadata stored on tracker {trackingId}.
        slots:
          trackingId: path.trackingId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/metadata/v2/devices/{trackingId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Merge metadata into a device or shipment
      effect: write
      questions:
      - Can I add custom key-value metadata to a tracker?
      - Does updating device metadata merge with what's already there?
      instructions:
      - text: Merge new metadata into device {trackingId}.
        slots:
          trackingId: path.trackingId
      - text: Set custom metadata on tracker {trackingId}.
        slots:
          trackingId: path.trackingId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/metadata/v2/devices/{trackingId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete all metadata of a device or shipment
      effect: destructive
      questions:
      - Can I wipe all custom metadata from a tracker?
      - What removes a shipment's metadata entirely?
      instructions:
      - text: Delete all metadata of device {trackingId}.
        slots:
          trackingId: path.trackingId
      - text: Clear custom metadata from tracker {trackingId}.
        slots:
          trackingId: path.trackingId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/metadata/v2/devices/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Get metadata for many devices or shipments
      effect: read
      questions:
      - Can I fetch metadata for many trackers in a single request?
      - Is there a batch read for shipment metadata?
      instructions:
      - text: Get metadata for this batch of devices.
      - text: Fetch metadata for these trackers, {count} per page.
        slots:
          count: query.count
      method: generated
      generated: '2026-10-01'
- target: $.paths['/metadata/v2/geofences/{geofenceId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a geofence's metadata
      effect: read
      questions:
      - What custom metadata is attached to a geofence?
      - Can I read the metadata object of one geofence?
      instructions:
      - text: Get the metadata of geofence {geofenceId}.
        slots:
          geofenceId: path.geofenceId
      - text: Show custom metadata stored on geofence {geofenceId}.
        slots:
          geofenceId: path.geofenceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/metadata/v2/geofences/{geofenceId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Merge metadata into a geofence
      effect: write
      questions:
      - Can I attach custom key-value metadata to a geofence?
      - Does geofence metadata get merged or replaced on update?
      instructions:
      - text: Merge new metadata into geofence {geofenceId}.
        slots:
          geofenceId: path.geofenceId
      - text: Set custom metadata on geofence {geofenceId}.
        slots:
          geofenceId: path.geofenceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/metadata/v2/geofences/{geofenceId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete all metadata of a geofence
      effect: destructive
      questions:
      - Can I wipe the custom metadata from a geofence without deleting it?
      - What clears a geofence's metadata object?
      instructions:
      - text: Delete all metadata of geofence {geofenceId}.
        slots:
          geofenceId: path.geofenceId
      - text: Clear custom metadata from geofence {geofenceId}.
        slots:
          geofenceId: path.geofenceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/metadata/v2/geofences/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Get metadata for many geofences
      effect: read
      questions:
      - Can I fetch metadata for many geofences in one request?
      - Is there a batch read for geofence metadata?
      instructions:
      - text: Get metadata for this batch of geofences.
      - text: Fetch geofence metadata, {count} per page.
        slots:
          count: query.count
      method: generated
      generated: '2026-10-01'
- target: $.paths['/metadata/v2/sensorRules/{sensorRuleId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a sensor rule's metadata
      effect: read
      questions:
      - What custom metadata is attached to a sensor rule?
      - Can I read the metadata of one sensor rule?
      instructions:
      - text: Get the metadata of sensor rule {sensorRuleId}.
        slots:
          sensorRuleId: path.sensorRuleId
      - text: Show custom metadata stored on sensor rule {sensorRuleId}.
        slots:
          sensorRuleId: path.sensorRuleId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/metadata/v2/sensorRules/{sensorRuleId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Merge metadata into a sensor rule
      effect: write
      questions:
      - Can I attach custom metadata to a sensor rule?
      - Does sensor rule metadata merge with existing keys on update?
      instructions:
      - text: Merge new metadata into sensor rule {sensorRuleId}.
        slots:
          sensorRuleId: path.sensorRuleId
      - text: Set custom metadata on sensor rule {sensorRuleId}.
        slots:
          sensorRuleId: path.sensorRuleId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/metadata/v2/sensorRules/{sensorRuleId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete all metadata of a sensor rule
      effect: destructive
      questions:
      - Can I wipe the custom metadata from a sensor rule?
      - What clears a sensor rule's metadata object?
      instructions:
      - text: Delete all metadata of sensor rule {sensorRuleId}.
        slots:
          sensorRuleId: path.sensorRuleId
      - text: Clear custom metadata from sensor rule {sensorRuleId}.
        slots:
          sensorRuleId: path.sensorRuleId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/metadata/v2/sensorRules/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Get metadata for many sensor rules
      effect: read
      questions:
      - Can I fetch metadata for many sensor rules in one request?
      - Is there a batch read for sensor rule metadata?
      instructions:
      - text: Get metadata for this batch of sensor rules.
      - text: Fetch sensor rule metadata, {count} per page.
        slots:
          count: query.count
      method: generated
      generated: '2026-10-01'