# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for v2 Stream API
  version: 1.0.0
extends: openapi/here-stream-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: 7
- target: $.paths['/layers/{layerId}/subscribe'].post
  update:
    x-apievangelist-phrasing:
      intent: Subscribe to a stream layer
      effect: write
      questions:
      - How do I start consuming messages from a stream layer?
      - Can I subscribe in parallel mode for more throughput?
      instructions:
      - text: Subscribe to stream layer {layer_id}.
        slots:
          layer_id: path.layerId
      - text: Subscribe to stream layer {layer_id} in {mode} mode as consumer {consumer_id}.
        slots:
          layer_id: path.layerId
          mode: query.mode
          consumer_id: query.consumerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/subscribe'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a stream layer subscription
      effect: destructive
      questions:
      - How do I unsubscribe from a stream layer when I'm done?
      - Is a subscription ID required to delete a parallel-mode subscription?
      instructions:
      - text: Delete my subscription to stream layer {layer_id}.
        slots:
          layer_id: path.layerId
      - text: Unsubscribe {subscription_id} from stream layer {layer_id}.
        slots:
          subscription_id: query.subscriptionId
          layer_id: path.layerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/partitions'].get
  update:
    x-apievangelist-phrasing:
      intent: Read messages from a stream layer
      effect: read
      questions:
      - How do I read the latest messages from a stream layer I subscribed to?
      - What happens to stream messages larger than 1 MB when I consume them?
      instructions:
      - text: Consume messages from stream layer {layerId}.
        slots:
          layerId: path.layerId
      - text: Read data from {layerId} using subscription {subscriptionId} in {mode} mode.
        slots:
          layerId: path.layerId
          subscriptionId: query.subscriptionId
          mode: query.mode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/layers/{layerId}/endpoint'].get
  update:
    x-apievangelist-phrasing:
      intent: Get Kafka consumer endpoint details for a layer
      effect: read
      questions:
      - Can I consume a stream layer directly from Kafka brokers?
      - Which bootstrap servers and group ID prefix should my consumer use?
      instructions:
      - text: Get the Kafka consumer endpoint for stream layer {layer_id}.
        slots:
          layer_id: path.layerId
      - text: Show the broker URLs for consuming layer {layer_id}, internal servers {internal}.
        slots:
          layer_id: path.layerId
          internal: query.internal
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/{type}/endpoint'].get
  update:
    x-apievangelist-phrasing:
      intent: Get Kafka producer or consumer settings for a layer
      effect: read
      questions:
      - Where do I get the Kafka settings to produce data into a stream layer?
      - Are producer and consumer endpoint properties different?
      instructions:
      - text: Give me the connection properties to act as a {type} on layer {layer_id}.
        slots:
          type: path.type
          layer_id: path.layerId
      - text: Show producer broker settings for layer {layer_id} using type {type}.
        slots:
          layer_id: path.layerId
          type: path.type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/offsets'].put
  update:
    x-apievangelist-phrasing:
      intent: Commit the offsets of messages I've read
      effect: write
      questions:
      - Why should I commit offsets after reading stream data?
      - How does my app resume reading from the right place after a failure?
      instructions:
      - text: Commit offsets {offsets} on stream layer {layer_id}.
        slots:
          offsets: requestBody.offsets
          layer_id: path.layerId
      - text: Save my read position {offsets} for subscription {subscription_id} on layer {layer_id}.
        slots:
          offsets: requestBody.offsets
          subscription_id: query.subscriptionId
          layer_id: path.layerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/seek'].put
  update:
    x-apievangelist-phrasing:
      intent: Move the read pointer to a chosen offset
      effect: write
      questions:
      - Can I replay a stream layer from an earlier offset?
      - Is it possible to skip ahead to a specific message position?
      instructions:
      - text: Seek stream layer {layer_id} to offsets {offsets}.
        slots:
          layer_id: path.layerId
          offsets: requestBody.offsets
      - text: Rewind subscription {subscription_id} on layer {layer_id} to offsets {offsets}.
        slots:
          subscription_id: query.subscriptionId
          layer_id: path.layerId
          offsets: requestBody.offsets
      method: generated
      generated: '2026-09-26'