API Evangelist conversational phrasing for v1 Query API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for v1 Query API
  version: 1.0.0
extends: openapi/here-query-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 4
- target: $.paths['/layers/{layerId}/changes'].get
  update:
    x-apievangelist-phrasing:
      intent: See recent changes to specific partitions
      effect: read
      questions:
      - Which of my partitions changed between two catalog versions?
      - Can I find partitions in a volatile layer that were modified since a certain time?
      instructions:
      - text: Show changes to partition {partition} in layer {layerId} between versions {startVersion} and {endVersion}.
        slots:
          partition: query.partition
          layerId: path.layerId
          startVersion: query.startVersion
          endVersion: query.endVersion
      - text: List changes to partition {partition} of volatile layer {layerId} since {sinceTime}.
        slots:
          partition: query.partition
          layerId: path.layerId
          sinceTime: query.sinceTime
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/partitions'].get
  update:
    x-apievangelist-phrasing:
      intent: Get metadata for chosen partitions
      effect: read
      questions:
      - How do I look up the data handle and version of specific partitions by ID?
      - Can I also get the data size and checksum of a partition?
      instructions:
      - text: Get metadata for partitions {partition} in layer {layerId}.
        slots:
          partition: query.partition
          layerId: path.layerId
      - text: Fetch partition {partition} metadata from {layerId} at catalog version {version} with {additionalFields}.
        slots:
          partition: query.partition
          layerId: path.layerId
          version: query.version
          additionalFields: query.additionalFields
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/versions/{version}/quadkeys/{quadKey}/depths/{depth}'].get
  update:
    x-apievangelist-phrasing:
      intent: Query tile index metadata in a versioned layer
      effect: read
      questions:
      - How do I find which HERE tile partitions exist under a quadkey in a versioned layer?
      - What does the depth setting do when querying a versioned tile index?
      instructions:
      - text: Get tile index metadata for quadkey {quadKey} to depth {depth} in layer {layerId} at version {version}.
        slots:
          quadKey: path.quadKey
          depth: path.depth
          layerId: path.layerId
          version: path.version
      - text: List versioned layer {layerId} partitions under tile {quadKey}, version {version}, depth {depth}.
        slots:
          layerId: path.layerId
          quadKey: path.quadKey
          version: path.version
          depth: path.depth
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/quadkeys/{quadKey}/depths/{depth}'].get
  update:
    x-apievangelist-phrasing:
      intent: Query tile index metadata in a volatile layer
      effect: read
      questions:
      - How do I find the partitions under a quadkey in a volatile layer?
      - Is there a tile index query for volatile layers that does not need a version?
      instructions:
      - text: Get volatile layer {layerId} index metadata for quadkey {quadKey} to depth {depth}.
        slots:
          layerId: path.layerId
          quadKey: path.quadKey
          depth: path.depth
      - text: List the latest volatile partitions under tile {quadKey} in {layerId}, depth {depth}.
        slots:
          quadKey: path.quadKey
          layerId: path.layerId
          depth: path.depth
      method: generated
      generated: '2026-09-26'