API Evangelist conversational phrasing for HERE Tracking Shipments API

# 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 Shipments API
  version: 1.0.0
extends: openapi/here-shipments-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['/shipments/v4/health'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the Shipments service health
      effect: read
      questions:
      - Is the HERE Tracking Shipments service up right now?
      - Can I ping the Shipments service before sending it requests?
      instructions:
      - text: Check the health of the Shipments service.
      - text: Tell me whether the Shipments service is healthy.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shipments/v4/version'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the Shipments service version
      effect: read
      questions:
      - What version of the Shipments service is deployed?
      - Which build of the Shipments service am I talking to?
      instructions:
      - text: Get the version of the Shipments service.
      - text: Show me which Shipments service version is running.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shipments/v4'].get
  update:
    x-apievangelist-phrasing:
      intent: List shipments in a project
      effect: read
      questions:
      - Which shipments are currently in progress?
      - Can I find shipments by external order ID?
      instructions:
      - text: List all shipments in project {projectId}.
        slots:
          projectId: query.projectId
      - text: Find shipments with status {status}.
        slots:
          status: query.status
      - text: Find the shipment for order {extOrderId}.
        slots:
          extOrderId: query.extOrderId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shipments/v4'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a shipment with segments
      effect: write
      questions:
      - How do I set up a multi-leg shipment with a tracker on each leg?
      - Can a shipment start automatically when created?
      instructions:
      - text: Create shipment {name} with segments {segments}.
        slots:
          name: requestBody.name
          segments: requestBody.segments
      - text: Create a shipment for order {extOrderId} with segments {segments} and autostart {autoStart}.
        slots:
          extOrderId: requestBody.extOrderId
          segments: requestBody.segments
          autoStart: requestBody.autoStart
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shipments/v4'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete every shipment in a project
      effect: destructive
      questions:
      - Can I delete all shipments in a project at once?
      - What confirmation does wiping every shipment require?
      instructions:
      - text: Delete all shipments in project {projectId} with x-confirm {confirm}.
        slots:
          projectId: query.projectId
          confirm: header.x-confirm
      - text: Remove every shipment, confirming with {confirm}.
        slots:
          confirm: header.x-confirm
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shipments/v4/{shipmentId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one shipment's details
      effect: read
      questions:
      - What is the status of a particular shipment?
      - Can I see all segments of one shipment?
      instructions:
      - text: Get shipment {shipmentId}.
        slots:
          shipmentId: path.shipmentId
      - text: Show the status and segments of shipment {shipmentId}.
        slots:
          shipmentId: path.shipmentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shipments/v4/{shipmentId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one shipment and its data
      effect: destructive
      questions:
      - Does deleting a shipment also remove its events and associations?
      - Can I delete a single shipment?
      instructions:
      - text: Delete shipment {shipmentId}.
        slots:
          shipmentId: path.shipmentId
      - text: Remove shipment {shipmentId} with all its data.
        slots:
          shipmentId: path.shipmentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shipments/v4/{shipmentId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a shipment's details
      effect: write
      questions:
      - Can I change a shipment's name or status after creating it?
      - Does updating segments replace the whole segment list?
      instructions:
      - text: Update shipment {shipmentId}.
        slots:
          shipmentId: path.shipmentId
      - text: Partially update the details of shipment {shipmentId}.
        slots:
          shipmentId: path.shipmentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shipments/v4/{shipmentId}/{segmentId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one shipment segment
      effect: read
      questions:
      - What are the details of one leg of a shipment?
      - Which tracker is assigned to a specific shipment segment?
      instructions:
      - text: Get segment {segmentId} of shipment {shipmentId}.
        slots:
          segmentId: path.segmentId
          shipmentId: path.shipmentId
      - text: Show leg {segmentId} in shipment {shipmentId}.
        slots:
          segmentId: path.segmentId
          shipmentId: path.shipmentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shipments/v4/{shipmentId}/{segmentId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update one shipment segment
      effect: write
      questions:
      - Can I reassign a different tracker to one leg of a shipment?
      - How does changing a segment status affect the other segments?
      instructions:
      - text: Set segment {segmentId} of shipment {shipmentId} to status {status}.
        slots:
          segmentId: path.segmentId
          shipmentId: path.shipmentId
          status: requestBody.status
      - text: Assign tracker {trackingId} to segment {segmentId} of {shipmentId}.
        slots:
          trackingId: requestBody.trackingId
          segmentId: path.segmentId
          shipmentId: path.shipmentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shipments/v4/{trackingId}/segments'].get
  update:
    x-apievangelist-phrasing:
      intent: List shipment segments assigned to a device
      effect: read
      questions:
      - Which shipment legs is a tracker assigned to?
      - Can I filter a device's segments by status?
      instructions:
      - text: List segments assigned to device {trackingId}.
        slots:
          trackingId: path.trackingId
      - text: Show tracker {trackingId}'s segments with status {status}.
        slots:
          trackingId: path.trackingId
          status: query.status
      method: generated
      generated: '2026-10-01'