# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Dataflow REST Background Jobs API
  version: 1.0.0
extends: openapi/power-query-background-jobs-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: 4
- target: $.paths['/workspaces/{workspaceId}/dataflows/{dataflowId}/jobs/execute/schedules'].post
  update:
    x-apievangelist-phrasing:
      intent: Schedule recurring refreshes of a dataflow
      effect: write
      questions:
      - How do I set up a recurring schedule that runs my dataflow automatically?
      - What is the maximum number of schedules a single dataflow can have?
      - Which workspace role do I need to put a dataflow run on a schedule?
      instructions:
      - text: Create an execute schedule for dataflow {dataflowId} in workspace {workspaceId}.
        slots:
          dataflowId: path.dataflowId
          workspaceId: path.workspaceId
      - text: Schedule dataflow {dataflowId} to run its execute job on a recurring timetable.
        slots:
          dataflowId: path.dataflowId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspaceId}/dataflows/{dataflowId}/jobs/applyChanges/schedules'].post
  update:
    x-apievangelist-phrasing:
      intent: Schedule recurring apply-changes jobs
      effect: write
      questions:
      - Can I schedule a dataflow's apply changes job to run on a recurring basis?
      - Does an apply changes schedule count toward the 20-schedule limit per dataflow?
      instructions:
      - text: Create an apply changes schedule for dataflow {dataflowId} in workspace {workspaceId}.
        slots:
          dataflowId: path.dataflowId
          workspaceId: path.workspaceId
      - text: Set up a recurring apply changes job on dataflow {dataflowId}.
        slots:
          dataflowId: path.dataflowId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspaceId}/dataflows/{dataflowId}/jobs/execute/instances'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a dataflow refresh right now
      effect: write
      questions:
      - How do I trigger a dataflow to run immediately instead of waiting for its schedule?
      - Do I need access to every connection the dataflow uses to start an on-demand run?
      instructions:
      - text: Run dataflow {dataflowId} in workspace {workspaceId} now as an on-demand execute job.
        slots:
          dataflowId: path.dataflowId
          workspaceId: path.workspaceId
      - text: Kick off an immediate refresh of dataflow {dataflowId}.
        slots:
          dataflowId: path.dataflowId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspaceId}/dataflows/{dataflowId}/jobs/applyChanges/instances'].post
  update:
    x-apievangelist-phrasing:
      intent: Apply pending dataflow changes on demand
      effect: write
      questions:
      - Can I run a dataflow's apply changes job once, right away, without a schedule?
      - What scope does an on-demand apply changes job for a dataflow require?
      instructions:
      - text: Run an on-demand apply changes job for dataflow {dataflowId} in workspace {workspaceId}.
        slots:
          dataflowId: path.dataflowId
          workspaceId: path.workspaceId
      - text: Apply the pending changes to dataflow {dataflowId} now.
        slots:
          dataflowId: path.dataflowId
      method: generated
      generated: '2026-10-01'