API Evangelist conversational phrasing for Millicast Beta API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Millicast Beta API
  version: 1.0.0
extends: openapi/dolby-beta-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: 13
- target: $.paths['/api/v2/record_files/list'].get
  update:
    x-apievangelist-phrasing:
      intent: List media assets (legacy v2 record files)
      effect: read
      questions:
      - Which full recordings and clips do I have, through the older v2 record-files listing?
      - Can I filter the legacy v2 media asset list by status or stream name?
      instructions:
      - text: List page {page} of my media assets with {items_on_page} per page via the v2 record-files endpoint.
        slots:
          page: query.page
          items_on_page: query.itemsOnPage
      - text: Show v2 record-file media assets for stream {stream_name}, page {page}, {items_on_page} per page.
        slots:
          stream_name: requestBody.streamName
          page: query.page
          items_on_page: query.itemsOnPage
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/record_files/{mediaAssetId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a media asset and its download link (legacy)
      effect: read
      questions:
      - How do I get a download link for one recording through the v2 record-files endpoint?
      - Does reading a legacy v2 media asset return a CDN link once it's complete?
      instructions:
      - text: Read v2 media asset {media_asset_id} and give me its download link.
        slots:
          media_asset_id: path.mediaAssetId
      - text: Fetch the CDN link for completed media asset {media_asset_id} from the v2 record files API.
        slots:
          media_asset_id: path.mediaAssetId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/record_files/delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete several media assets (legacy v2)
      effect: destructive
      questions:
      - Can I delete multiple media assets in one call with the legacy v2 endpoint?
      - Why won't a media asset that's still processing delete?
      instructions:
      - text: Delete media assets {media_asset_ids} through the v2 record-files delete endpoint.
        slots:
          media_asset_ids: requestBody.mediaAssetIds
      - text: Remove completed or errored v2 media assets {media_asset_ids} from storage.
        slots:
          media_asset_ids: requestBody.mediaAssetIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/record_files/clip'].post
  update:
    x-apievangelist-phrasing:
      intent: Clip a recording between two times
      effect: write
      questions:
      - How do I cut a clip from a live stream recording with start and stop times?
      - What's the minimum length of a clip I can request?
      instructions:
      - text: Create a clip of stream {stream_name} starting at {start_time}.
        slots:
          stream_name: requestBody.streamName
          start_time: requestBody.startTime
      - text: Clip stream {stream_name} from {start_time} to {stop_time} and name it {clip_name}.
        slots:
          stream_name: requestBody.streamName
          start_time: requestBody.startTime
          stop_time: requestBody.stopTime
          clip_name: requestBody.clipName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/record_files/clip/{clipRequestId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the status of a clip request
      effect: read
      questions:
      - Has my clip request finished processing?
      - What does a single clip request look like when I look it up by ID?
      instructions:
      - text: Get clip request {clip_request_id}.
        slots:
          clip_request_id: path.clipRequestId
      - text: Check progress on clip request {clip_request_id}.
        slots:
          clip_request_id: path.clipRequestId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/record_files/clip/{clipRequestId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a clip request and its media
      effect: destructive
      questions:
      - Can I delete a clip request along with every media asset it produced?
      - Why can't I delete a clip request that's still in progress?
      instructions:
      - text: Delete clip request {clip_request_id} and its media assets.
        slots:
          clip_request_id: path.clipRequestId
      - text: Cancel and remove clip request {clip_request_id}.
        slots:
          clip_request_id: path.clipRequestId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/record_files/clip/list'].get
  update:
    x-apievangelist-phrasing:
      intent: List live clip requests
      effect: read
      questions:
      - What clip requests have been made against my live streams?
      - Can I filter clip requests by status or clip name?
      instructions:
      - text: List clip requests, page {page} with {items_on_page} per page.
        slots:
          page: query.page
          items_on_page: query.itemsOnPage
      - text: Show clip requests with status {status}, page {page}, {items_on_page} per page.
        slots:
          status: requestBody.status
          page: query.page
          items_on_page: query.itemsOnPage
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/record_files/clip/sources'].get
  update:
    x-apievangelist-phrasing:
      intent: List streams and time frames available to clip
      effect: read
      questions:
      - Which streams and time ranges can I still create clips from?
      - Is a particular stream's footage still available for clipping?
      instructions:
      - text: List clip sources available, page {page} with {items_on_page} per page.
        slots:
          page: query.page
          items_on_page: query.itemsOnPage
      - text: Show which time frames of stream {stream_name} can be clipped, page {page}, {items_on_page} per page.
        slots:
          stream_name: requestBody.streamName
          page: query.page
          items_on_page: query.itemsOnPage
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/record_files/storage_profiles/validate'].post
  update:
    x-apievangelist-phrasing:
      intent: Validate third-party storage permissions
      effect: write
      questions:
      - How can I confirm my own cloud bucket lets recordings be uploaded to it?
      - What do I do with the validation ID returned when checking third-party storage?
      instructions:
      - text: Validate third-party storage setup {storage} for media uploads.
        slots:
          storage: requestBody.storage
      - text: Start a permissions check on my external storage bucket.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/record_files/clip/sources/expiry'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the clip source expiry rule
      effect: read
      questions:
      - How long is stream footage kept available for clipping on my account?
      - What's the current account-level clip source expiry rule?
      instructions:
      - text: Show my account's clip source expiry rule.
      - text: Tell me how long published streams stay clippable.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/record_files/clip/sources/expiry'].post
  update:
    x-apievangelist-phrasing:
      intent: Change the clip source expiry rule
      effect: write
      questions:
      - Can I extend how long streams remain available for creating clips?
      - What happens to streams published outside a new clip expiry period?
      instructions:
      - text: Set the clip source expiry rule to {expiry}.
        slots:
          expiry: requestBody.expiry
      - text: Change how long streams stay clippable to {expiry}.
        slots:
          expiry: requestBody.expiry
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/record_files/clip/sources/expiry'].delete
  update:
    x-apievangelist-phrasing:
      intent: Reset clip source expiry to the default
      effect: destructive
      questions:
      - Can I drop my custom clip source expiry and go back to the system default?
      - Will removing the clip expiry rule delete older stream data right away?
      instructions:
      - text: Delete my custom clip source expiry rule.
      - text: Revert clip source expiry to the system default.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/record_files/clip/sources/delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete clip sources
      effect: destructive
      questions:
      - How do I remove stream footage so it can no longer be clipped?
      - Can I delete several clip sources by ID at once?
      instructions:
      - text: Delete clip sources {clip_source_ids}.
        slots:
          clip_source_ids: requestBody.clipSourceIds
      - text: Remove clippable footage for clip source IDs {clip_source_ids}.
        slots:
          clip_source_ids: requestBody.clipSourceIds
      method: generated
      generated: '2026-10-01'