# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Here Ingestion API
  version: 1.0.0
extends: openapi/here-ingestion-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: 12
- target: $.paths['/layers/{layerId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Stream raw data into a stream layer
      effect: write
      questions:
      - How do I send streaming data into a layer on the HERE platform?
      - Can I attach a message key so related records stay together in the stream?
      instructions:
      - text: Send this data to stream layer {layerId}.
        slots:
          layerId: path.layerId
      - text: Ingest a message into layer {layerId} with message key {X-HERE-Message-Key}.
        slots:
          layerId: path.layerId
          X-HERE-Message-Key: header.X-HERE-Message-Key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/partitions'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a list of partitions to a stream layer
      effect: write
      questions:
      - Can I push a batch of partitions into a stream layer in one request?
      - What batch size works best when ingesting partitions?
      instructions:
      - text: Send partitions {partitions} to stream layer {layerId}.
        slots:
          partitions: requestBody.partitions
          layerId: path.layerId
      - text: 'Ingest this batch of stream partitions into layer {layerId}: {partitions}.'
        slots:
          layerId: path.layerId
          partitions: requestBody.partitions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/sdiiMessageList'].post
  update:
    x-apievangelist-phrasing:
      intent: Send SDII vehicle sensor messages to a stream layer
      effect: write
      questions:
      - How do I upload SDII sensor messages from vehicles?
      - Does an SDII MessageList get split into individual messages on ingest?
      instructions:
      - text: Send this SDII MessageList to stream layer {layerId}.
        slots:
          layerId: path.layerId
      - text: Ingest SDII messages into layer {layerId} with checksum {X-HERE-Checksum}.
        slots:
          layerId: path.layerId
          X-HERE-Checksum: header.X-HERE-Checksum
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/health'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the v2 tracking ingestion service health
      effect: read
      questions:
      - Is the v2 device ingestion service up?
      - Can I health-check the v2 ingestion endpoint before devices send data?
      instructions:
      - text: Check the health of the v2 ingestion service.
      - text: Tell me whether v2 device ingestion is healthy.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/version'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the v2 tracking ingestion service version
      effect: read
      questions:
      - What version of the v2 ingestion service is running?
      - Which build does the v2 ingestion endpoint report?
      instructions:
      - text: Get the version of the v2 ingestion service.
      - text: Show the v2 ingestion service build.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/timestamp'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the server time for device clock sync
      effect: read
      questions:
      - What is the tracking server's current time for signing OAuth 1.0 requests?
      - Why do my devices need to sync with the server timestamp?
      instructions:
      - text: Get the current server timestamp.
      - text: Fetch server time so my device can sync its clock.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/token'].post
  update:
    x-apievangelist-phrasing:
      intent: Get a device access token
      effect: write
      questions:
      - How does a device authenticate and get an access token for sending telemetry?
      - Which credentials does a tracker use to request a token?
      instructions:
      - text: Request a device access token with authorization header {authorization}.
        slots:
          authorization: header.authorization
      - text: Authenticate my device using OAuth header {authorization}.
        slots:
          authorization: header.authorization
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/'].post
  update:
    x-apievangelist-phrasing:
      intent: Ingest device telemetry via the v2 endpoint
      effect: write
      questions:
      - Can devices still send telemetry to the older v2 ingestion endpoint?
      - Does the v2 ingestion endpoint return the device shadow?
      instructions:
      - text: Send telemetry through the legacy v2 endpoint with token {authorization}.
        slots:
          authorization: header.authorization
      - text: Ingest data via v2 using token {authorization}, async {async}.
        slots:
          authorization: header.authorization
          async: query.async
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/'].post
  update:
    x-apievangelist-phrasing:
      intent: Ingest telemetry for one device
      effect: write
      questions:
      - How does a device send GPS positions and sensor readings?
      - Can a device send WLAN or Bluetooth scans for positioning?
      instructions:
      - text: Ingest telemetry {data} for my device with token {authorization}.
        slots:
          data: requestBody.data
          authorization: header.authorization
      - text: Send device {id}'s readings {data} via v3 using {authorization}.
        slots:
          id: requestBody.id
          data: requestBody.data
          authorization: header.authorization
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/health'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the v3 tracking ingestion service health
      effect: read
      questions:
      - Is the v3 device ingestion service up?
      - Can I health-check the v3 ingestion endpoint?
      instructions:
      - text: Check the health of the v3 ingestion service.
      - text: Tell me whether v3 device ingestion is healthy.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/version'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the v3 tracking ingestion service version
      effect: read
      questions:
      - What version of the v3 ingestion service is running?
      - Which build does the v3 ingestion endpoint report?
      instructions:
      - text: Get the version of the v3 ingestion service.
      - text: Show the v3 ingestion service build.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Ingest telemetry for many devices at once
      effect: write
      questions:
      - Can a device owner send data for multiple devices in one request?
      - How do I ingest data on behalf of virtual devices in bulk?
      instructions:
      - text: Ingest batch telemetry {data} for multiple devices with token {authorization}.
        slots:
          data: requestBody.data
          authorization: header.authorization
      - text: 'Send data for several trackers at once: {data}, using {authorization}.'
        slots:
          data: requestBody.data
          authorization: header.authorization
      method: generated
      generated: '2026-10-01'