# 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 Items API
  version: 1.0.0
extends: openapi/power-query-items-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: 8
- target: $.paths['/workspaces/{workspaceId}/dataflows'].get
  update:
    x-apievangelist-phrasing:
      intent: List the dataflows in a workspace
      effect: read
      questions:
      - How do I see every dataflow that lives in one of my Fabric workspaces?
      - Can I list only the dataflows inside a particular folder and its subfolders?
      - What permission do I need to enumerate the Power Query dataflows in a workspace?
      instructions:
      - text: List all dataflows in workspace {workspaceId}.
        slots:
          workspaceId: path.workspaceId
      - text: List the dataflows in workspace {workspaceId} under folder {rootFolderId}, including nested folders.
        slots:
          workspaceId: path.workspaceId
          rootFolderId: query.rootFolderId
      - text: Get the next page of dataflows in workspace {workspaceId} using token {continuationToken}.
        slots:
          workspaceId: path.workspaceId
          continuationToken: query.continuationToken
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/dataflows'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new dataflow in a workspace
      effect: write
      questions:
      - How do I create a new Dataflow in a Fabric workspace through the API?
      - Does my workspace need a Fabric capacity before I can add a dataflow to it?
      - Can I create a dataflow with its mashup definition already filled in?
      instructions:
      - text: Create a new dataflow in workspace {workspaceId}.
        slots:
          workspaceId: path.workspaceId
      - text: Add a dataflow with a supplied definition to workspace {workspaceId}.
        slots:
          workspaceId: path.workspaceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/dataflows/{dataflowId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the properties of a dataflow
      effect: read
      questions:
      - How can I look up the name and description of a single dataflow by its ID?
      - What properties does the API return for one specific dataflow?
      instructions:
      - text: Show me the properties of dataflow {dataflowId} in workspace {workspaceId}.
        slots:
          dataflowId: path.dataflowId
          workspaceId: path.workspaceId
      - text: Fetch the details of dataflow {dataflowId}.
        slots:
          dataflowId: path.dataflowId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/dataflows/{dataflowId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a dataflow
      effect: destructive
      questions:
      - How do I remove a dataflow I no longer need from a workspace?
      - Can a deleted dataflow be recovered, or can I delete it permanently?
      instructions:
      - text: Delete dataflow {dataflowId} from workspace {workspaceId}.
        slots:
          dataflowId: path.dataflowId
          workspaceId: path.workspaceId
      - text: Delete dataflow {dataflowId} with hardDelete set to {hardDelete} so it cannot be recovered.
        slots:
          dataflowId: path.dataflowId
          hardDelete: query.hardDelete
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/dataflows/{dataflowId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename or redescribe a dataflow
      effect: write
      questions:
      - How do I rename an existing dataflow or change its description?
      - Which dataflow properties can I edit without touching its queries?
      instructions:
      - text: Rename dataflow {dataflowId} in workspace {workspaceId}.
        slots:
          dataflowId: path.dataflowId
          workspaceId: path.workspaceId
      - text: Change the description on dataflow {dataflowId}.
        slots:
          dataflowId: path.dataflowId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/dataflows/{dataflowId}/getDefinition'].post
  update:
    x-apievangelist-phrasing:
      intent: Export a dataflow's definition
      effect: read
      questions:
      - How can I export the full definition of a dataflow, including its mashup queries?
      - Is the sensitivity label included when I pull a dataflow's public definition?
      - Can I choose the format the dataflow definition comes back in?
      instructions:
      - text: Get the public definition of dataflow {dataflowId} in workspace {workspaceId}.
        slots:
          dataflowId: path.dataflowId
          workspaceId: path.workspaceId
      - text: Export dataflow {dataflowId}'s definition in {format} format.
        slots:
          dataflowId: path.dataflowId
          format: query.format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/dataflows/{dataflowId}/updateDefinition'].post
  update:
    x-apievangelist-phrasing:
      intent: Replace a dataflow's definition
      effect: write
      questions:
      - How do I overwrite the queries and mashup definition of an existing dataflow?
      - Can updating a dataflow's definition also update its metadata from a .platform file?
      instructions:
      - text: Override the definition of dataflow {dataflowId} in workspace {workspaceId} with new mashup content.
        slots:
          dataflowId: path.dataflowId
          workspaceId: path.workspaceId
      - text: Replace dataflow {dataflowId}'s definition and set updateMetadata to {updateMetadata} to apply the .platform file.
        slots:
          dataflowId: path.dataflowId
          updateMetadata: query.updateMetadata
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/dataflows/{dataflowId}/parameters'].get
  update:
    x-apievangelist-phrasing:
      intent: List the parameters defined in a dataflow
      effect: read
      questions:
      - What parameters has a dataflow author defined that I can pass values for?
      - Can I discover a dataflow's parameters before I run it?
      instructions:
      - text: List the parameters defined in dataflow {dataflowId} in workspace {workspaceId}.
        slots:
          dataflowId: path.dataflowId
          workspaceId: path.workspaceId
      - text: Get the next page of parameters for dataflow {dataflowId} with token {continuationToken}.
        slots:
          dataflowId: path.dataflowId
          continuationToken: query.continuationToken
      method: generated
      generated: '2026-09-26'