# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for THEOlive Engines API
  version: 1.0.0
extends: openapi/dolby-engines-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: 9
- target: $.paths['/channels/{id}/engines'].get
  update:
    x-apievangelist-phrasing:
      intent: List a channel's engines
      effect: read
      questions:
      - Which encoding engines are attached to my channel?
      - Can I page through a channel's engines with a cursor?
      instructions:
      - text: List engines on channel {channel_id}.
        slots:
          channel_id: path.id
      - text: Show the first {limit} engines of channel {channel_id}.
        slots:
          limit: query.limit
          channel_id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/channels/{id}/engines'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an engine for a channel
      effect: write
      questions:
      - How do I add an encoding engine to a channel in a specific region?
      - Can I enable DRM, Dolby Vision or Atmos when creating a channel engine?
      instructions:
      - text: Create engine {name} on channel {channel_id} in {region} at {quality} quality.
        slots:
          channel_id: path.id
          name: requestBody.name
          region: requestBody.region
          quality: requestBody.quality
      - text: Add engine {name} to channel {channel_id} in {region}, quality {quality}, with Atmos {atmos}.
        slots:
          channel_id: path.id
          atmos: requestBody.atmos
          name: requestBody.name
          region: requestBody.region
          quality: requestBody.quality
      method: generated
      generated: '2026-10-01'
- target: $.paths['/engines/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an engine's details
      effect: read
      questions:
      - What region and quality is a particular engine configured for?
      - Can I look up a single engine by its ID?
      instructions:
      - text: Show engine {engine_id}.
        slots:
          engine_id: path.id
      - text: Fetch the configuration of engine {engine_id}.
        slots:
          engine_id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/engines/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an engine
      effect: destructive
      questions:
      - How do I remove an engine I no longer need?
      - Can an engine be deleted by ID?
      instructions:
      - text: Delete engine {engine_id}.
        slots:
          engine_id: path.id
      - text: Remove engine {engine_id} permanently.
        slots:
          engine_id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/engines/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an engine's settings
      effect: write
      questions:
      - Can I change the quality or region of an existing engine?
      - How do I switch DRM on for an engine I already created?
      instructions:
      - text: Change engine {engine_id} quality to {quality}.
        slots:
          engine_id: path.id
          quality: requestBody.quality
      - text: Move engine {engine_id} to region {region}.
        slots:
          engine_id: path.id
          region: requestBody.region
      - text: Turn DRM to {drm} on engine {engine_id}.
        slots:
          drm: requestBody.drm
          engine_id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/engines/{id}/start'].post
  update:
    x-apievangelist-phrasing:
      intent: Start an engine
      effect: write
      questions:
      - How do I start encoding on an engine?
      - Can I kick off an engine run on demand?
      instructions:
      - text: Start engine {engine_id}.
        slots:
          engine_id: path.id
      - text: Spin up engine {engine_id} now.
        slots:
          engine_id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/engines/{id}/stop'].post
  update:
    x-apievangelist-phrasing:
      intent: Stop a running engine
      effect: destructive
      questions:
      - How do I stop an engine that's currently running?
      - Can I halt an engine run on demand?
      instructions:
      - text: Stop engine {engine_id}.
        slots:
          engine_id: path.id
      - text: Shut down the running engine {engine_id}.
        slots:
          engine_id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/engines/{id}/last-run'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an engine's most recent run
      effect: read
      questions:
      - When did an engine last run, and how did that run go?
      - Can I see only the latest run of an engine?
      instructions:
      - text: Get the last run of engine {engine_id}.
        slots:
          engine_id: path.id
      - text: Show the most recent run for engine {engine_id}.
        slots:
          engine_id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/engines/{id}/runs'].get
  update:
    x-apievangelist-phrasing:
      intent: List an engine's run history
      effect: read
      questions:
      - What's the full run history of an engine?
      - How many times has an engine been run?
      instructions:
      - text: List all runs of engine {engine_id}.
        slots:
          engine_id: path.id
      - text: Show the run history for engine {engine_id}.
        slots:
          engine_id: path.id
      method: generated
      generated: '2026-10-01'