# 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 Shadows API
  version: 1.0.0
extends: openapi/here-shadows-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: 9
- target: $.paths['/shadows/v2/health'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the Shadows service health
      effect: read
      questions:
      - Is the HERE Tracking Shadows service up right now?
      - Can I ping the Shadows service before sending it requests?
      instructions:
      - text: Check the health of the Shadows service.
      - text: Tell me whether the Shadows service is healthy.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shadows/v2/version'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the Shadows service version
      effect: read
      questions:
      - What version of the Shadows service is deployed?
      - Which build of the Shadows service am I talking to?
      instructions:
      - text: Get the version of the Shadows service.
      - text: Show me which Shadows service version is running.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shadows/v2/{trackingId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a device's full shadow
      effect: read
      questions:
      - What is the last reported and desired state of a device?
      - Can I see a device shadow for a shipment ID?
      instructions:
      - text: Get the shadow of device {trackingId}.
        slots:
          trackingId: path.trackingId
      - text: Show both reported and desired shadows for tracker {trackingId}.
        slots:
          trackingId: path.trackingId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shadows/v2/{trackingId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Set a device's desired shadow
      effect: write
      questions:
      - How do I push new configuration to a device through its shadow?
      - Can I update the reported shadow myself?
      instructions:
      - text: Set the desired shadow of device {trackingId} to {desired}.
        slots:
          trackingId: path.trackingId
          desired: requestBody.desired
      - text: Change tracker {trackingId}'s desired settings to {desired}.
        slots:
          trackingId: path.trackingId
          desired: requestBody.desired
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shadows/v2/{trackingId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Clear a device's shadow
      effect: destructive
      questions:
      - Can I clear only the desired part of a device shadow?
      - What empties a device's reported and desired shadows?
      instructions:
      - text: Clear the shadow of device {trackingId}.
        slots:
          trackingId: path.trackingId
      - text: Clear only the desired shadow of {trackingId} with desired={desired}.
        slots:
          trackingId: path.trackingId
          desired: query.desired
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shadows/v2/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Get shadows for many devices at once
      effect: read
      questions:
      - Can I fetch shadows for up to 100 devices in one request?
      - Which device shadows changed since a given time?
      instructions:
      - text: Get shadows for this batch of devices.
      - text: Get shadows of these devices modified after {after}.
        slots:
          after: query.after
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shadows/v2/{trackingId}/{state}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a device's reported or desired state
      effect: read
      questions:
      - Can I fetch just the reported state of a device?
      - What does the desired state object of a tracker contain?
      instructions:
      - text: Get the {state} state of device {trackingId}.
        slots:
          state: path.state
          trackingId: path.trackingId
      - text: Show tracker {trackingId}'s {state} shadow only.
        slots:
          trackingId: path.trackingId
          state: path.state
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shadows/v2/{trackingId}/{state}/{selector}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read one property from a device shadow
      effect: read
      questions:
      - Can I read a single property like battery level from a device shadow?
      - How do I use a JSON selector to get one shadow value?
      instructions:
      - text: Get {selector} from the {state} shadow of device {trackingId}.
        slots:
          selector: path.selector
          state: path.state
          trackingId: path.trackingId
      - text: Read property {selector} of tracker {trackingId}'s {state} state.
        slots:
          selector: path.selector
          trackingId: path.trackingId
          state: path.state
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shadows/v4'].get
  update:
    x-apievangelist-phrasing:
      intent: List all device shadows in a project
      effect: read
      questions:
      - Where are all my project's devices right now according to their shadows?
      - Can I list device shadows within a bounding box?
      instructions:
      - text: List all device shadows in project {projectId}.
        slots:
          projectId: query.projectId
      - text: List project shadows inside {bbox} modified after {after}.
        slots:
          bbox: query.bbox
          after: query.after
      method: generated
      generated: '2026-10-01'