# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Adobe Experience Platform Data Collection Media Edge API
  version: 1.0.0
extends: openapi/adobe-launch-media-edge-api-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: 9
- target: $.paths['/ee/va/v1/sessionStart'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a media tracking session
      effect: write
      questions:
      - How do I begin tracking a video viewing session through the Edge Network?
      - Do I need the Streaming Media Collection add-on to start a media session?
      - Where does the session ID for later media events come from?
      instructions:
      - text: Start a media session on datastream {datastream} with {events}.
        slots:
          datastream: query.datastreamId
          events: requestBody.events
      - text: Open a new media tracking session for datastream {datastream} and give me the session ID.
        slots:
          datastream: query.datastreamId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ee/va/v1/play'].post
  update:
    x-apievangelist-phrasing:
      intent: Track a media play event
      effect: write
      questions:
      - How do I record that playback started or resumed in a media session?
      - Can I send a play event for a session that's already running?
      instructions:
      - text: Send a play event on datastream {datastream} with {events}.
        slots:
          datastream: query.datastreamId
          events: requestBody.events
      - text: Record that the viewer pressed play in the active session on datastream {datastream}.
        slots:
          datastream: query.datastreamId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ee/va/v1/ping'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a media session heartbeat
      effect: write
      questions:
      - How often should I ping a media session during playback?
      - What keeps a media session alive while the video is playing?
      instructions:
      - text: Send a ping for the active media session on datastream {datastream} with {events}.
        slots:
          datastream: query.datastreamId
          events: requestBody.events
      - text: Send the 10-second heartbeat ping to datastream {datastream}.
        slots:
          datastream: query.datastreamId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ee/va/v1/pauseStart'].post
  update:
    x-apievangelist-phrasing:
      intent: Track a media pause event
      effect: write
      questions:
      - How do I tell the Edge Network the viewer paused the video?
      - Can I track pauses within a media session?
      instructions:
      - text: Send a pause start event on datastream {datastream} with {events}.
        slots:
          datastream: query.datastreamId
          events: requestBody.events
      - text: Record that the viewer paused playback in the session on datastream {datastream}.
        slots:
          datastream: query.datastreamId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ee/va/v1/bufferStart'].post
  update:
    x-apievangelist-phrasing:
      intent: Track a media buffering event
      effect: write
      questions:
      - How do I report that a video started buffering?
      - Can buffering time be tracked in a media session?
      instructions:
      - text: Send a buffer start event on datastream {datastream} with {events}.
        slots:
          datastream: query.datastreamId
          events: requestBody.events
      - text: Record that playback began buffering in the session on datastream {datastream}.
        slots:
          datastream: query.datastreamId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ee/va/v1/bitrateChange'].post
  update:
    x-apievangelist-phrasing:
      intent: Track a media bitrate change
      effect: write
      questions:
      - How do I report when the stream quality switches to a different bitrate?
      - Can I track adaptive bitrate changes during playback?
      instructions:
      - text: Send a bitrate change event on datastream {datastream} with {events}.
        slots:
          datastream: query.datastreamId
          events: requestBody.events
      - text: Record that the stream bitrate changed in the session on datastream {datastream}.
        slots:
          datastream: query.datastreamId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ee/va/v1/error'].post
  update:
    x-apievangelist-phrasing:
      intent: Track a media playback error
      effect: write
      questions:
      - How do I report a player error inside a media session?
      - Can playback failures be tracked alongside other media events?
      instructions:
      - text: Send a media error event on datastream {datastream} with {events}.
        slots:
          datastream: query.datastreamId
          events: requestBody.events
      - text: Record that the player hit an error in the session on datastream {datastream}.
        slots:
          datastream: query.datastreamId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ee/va/v1/sessionComplete'].post
  update:
    x-apievangelist-phrasing:
      intent: Complete a media session
      effect: write
      questions:
      - How do I mark that a viewer watched the content all the way through?
      - What's the difference between completing and ending a media session?
      instructions:
      - text: Complete the media session on datastream {datastream} with {events}.
        slots:
          datastream: query.datastreamId
          events: requestBody.events
      - text: Mark the content as watched to completion on datastream {datastream}.
        slots:
          datastream: query.datastreamId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ee/va/v1/sessionEnd'].post
  update:
    x-apievangelist-phrasing:
      intent: End an abandoned media session
      effect: destructive
      questions:
      - How do I close a media session when the viewer leaves before the end?
      - Can I end tracking early for abandoned content?
      instructions:
      - text: End the media session on datastream {datastream} with {events}.
        slots:
          datastream: query.datastreamId
          events: requestBody.events
      - text: Close the session on datastream {datastream} because the viewer abandoned the video.
        slots:
          datastream: query.datastreamId
      method: generated
      generated: '2026-09-26'