# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Twilio - Studio Flows API
  version: 1.0.0
extends: openapi/twilio-flows-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: 19
- target: $.paths['/v2/Flows/{FlowSid}/Executions'].get
  update:
    x-apievangelist-phrasing:
      intent: List the executions of a Studio Flow
      effect: read
      questions:
      - Which executions has my Studio Flow run recently?
      - Can I filter a Flow's executions to a date range?
      instructions:
      - text: List the executions of Flow {flow_sid}.
        slots:
          flow_sid: path.FlowSid
      - text: Show executions of Flow {flow_sid} created between {from} and {to}.
        slots:
          flow_sid: path.FlowSid
          from: query.DateCreatedFrom
          to: query.DateCreatedTo
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/Flows/{FlowSid}/Executions'].post
  update:
    x-apievangelist-phrasing:
      intent: Trigger a Studio Flow for a contact
      effect: write
      questions:
      - How do I start a Studio Flow from my own code instead of an inbound message?
      - Can I pass custom variables into a Flow when I trigger it?
      instructions:
      - text: Trigger Flow {flow_sid} to {to} from {from}.
        slots:
          flow_sid: path.FlowSid
          to: requestBody.To
          from: requestBody.From
      - text: Start Flow {flow_sid} for {to} from number {from} with parameters {parameters}.
        slots:
          flow_sid: path.FlowSid
          to: requestBody.To
          from: requestBody.From
          parameters: requestBody.Parameters
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/Flows/{FlowSid}/Executions/{Sid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up one Flow execution
      effect: read
      questions:
      - Can I check the status of a single Studio Flow execution?
      - What does one execution record of a Flow tell me?
      instructions:
      - text: Show execution {sid} of Flow {flow_sid}.
        slots:
          sid: path.Sid
          flow_sid: path.FlowSid
      - text: Fetch the status of Flow {flow_sid} execution {sid}.
        slots:
          flow_sid: path.FlowSid
          sid: path.Sid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/Flows/{FlowSid}/Executions/{Sid}'].post
  update:
    x-apievangelist-phrasing:
      intent: End a running Flow execution
      effect: destructive
      questions:
      - Can I stop a Studio Flow execution that is stuck mid-flow?
      - Is ended the only status I can set on a running execution?
      instructions:
      - text: End execution {sid} of Flow {flow_sid}.
        slots:
          sid: path.Sid
          flow_sid: path.FlowSid
      - text: Set the status of Flow {flow_sid} execution {sid} to {status}.
        slots:
          flow_sid: path.FlowSid
          sid: path.Sid
          status: requestBody.Status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/Flows/{FlowSid}/Executions/{Sid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a Flow execution and its steps
      effect: destructive
      questions:
      - Can I delete an execution record along with all of its steps?
      - What's the way to purge an old Studio Flow execution from history?
      instructions:
      - text: Delete execution {sid} from Flow {flow_sid}.
        slots:
          sid: path.Sid
          flow_sid: path.FlowSid
      - text: Purge Flow {flow_sid} execution {sid} and every step in it.
        slots:
          flow_sid: path.FlowSid
          sid: path.Sid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/Flows/{FlowSid}/Executions/{ExecutionSid}/Context'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the latest context of a Flow execution
      effect: read
      questions:
      - Can I see the variables and widget data a Flow execution has collected so far?
      - Where do I read the most recent context for a whole execution?
      instructions:
      - text: Get the current context of execution {execution_sid} in Flow {flow_sid}.
        slots:
          execution_sid: path.ExecutionSid
          flow_sid: path.FlowSid
      - text: Show the collected variables for Flow {flow_sid} execution {execution_sid}.
        slots:
          flow_sid: path.FlowSid
          execution_sid: path.ExecutionSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/Flows/{FlowSid}/Executions/{ExecutionSid}/Steps'].get
  update:
    x-apievangelist-phrasing:
      intent: List the steps an execution went through
      effect: read
      questions:
      - Which widgets did a Flow execution pass through, in order?
      - Can I trace every step of a single Studio execution?
      instructions:
      - text: List the steps of execution {execution_sid} in Flow {flow_sid}.
        slots:
          execution_sid: path.ExecutionSid
          flow_sid: path.FlowSid
      - text: Trace every step Flow {flow_sid} took during execution {execution_sid}.
        slots:
          flow_sid: path.FlowSid
          execution_sid: path.ExecutionSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/Flows/{FlowSid}/Executions/{ExecutionSid}/Steps/{Sid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up one step of a Flow execution
      effect: read
      questions:
      - Can I inspect a single step of an execution by its SID?
      - What does one execution step record show about the widget transition?
      instructions:
      - text: Show step {sid} of execution {execution_sid} in Flow {flow_sid}.
        slots:
          sid: path.Sid
          execution_sid: path.ExecutionSid
          flow_sid: path.FlowSid
      - text: Fetch execution step {sid} from Flow {flow_sid} run {execution_sid}.
        slots:
          sid: path.Sid
          flow_sid: path.FlowSid
          execution_sid: path.ExecutionSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/Flows/{FlowSid}/Executions/{ExecutionSid}/Steps/{StepSid}/Context'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the context captured at one execution step
      effect: read
      questions:
      - Can I see what data a Flow held at one particular step?
      - Where do I read the context snapshot for a single execution step?
      instructions:
      - text: Get the context at step {step_sid} of execution {execution_sid} in Flow {flow_sid}.
        slots:
          step_sid: path.StepSid
          execution_sid: path.ExecutionSid
          flow_sid: path.FlowSid
      - text: Show the step-level context snapshot for step {step_sid} in Flow {flow_sid} run {execution_sid}.
        slots:
          step_sid: path.StepSid
          flow_sid: path.FlowSid
          execution_sid: path.ExecutionSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/Flows'].get
  update:
    x-apievangelist-phrasing:
      intent: List my Studio Flows
      effect: read
      questions:
      - Which Studio Flows exist on my account?
      - Can I page through all my Flows 50 at a time?
      instructions:
      - text: List all my Studio Flows.
      - text: Show my Flows {page_size} per page.
        slots:
          page_size: query.PageSize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/Flows'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new Studio Flow
      effect: write
      questions:
      - Can I create a Studio Flow from a JSON definition through the API?
      - Can I create a Flow as a draft rather than publishing it right away?
      instructions:
      - text: Create a Flow named {friendly_name} with status {status} from definition {definition}.
        slots:
          friendly_name: requestBody.FriendlyName
          status: requestBody.Status
          definition: requestBody.Definition
      - text: Create {friendly_name} as a new {status} Flow using {definition} with commit message {commit_message}.
        slots:
          friendly_name: requestBody.FriendlyName
          status: requestBody.Status
          definition: requestBody.Definition
          commit_message: requestBody.CommitMessage
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/Flows/{Sid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up one Studio Flow
      effect: read
      questions:
      - Can I retrieve a single Flow and its current definition?
      - Is a given Studio Flow published or still a draft?
      instructions:
      - text: Show Studio Flow {sid}.
        slots:
          sid: path.Sid
      - text: Fetch the current definition of Flow {sid}.
        slots:
          sid: path.Sid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/Flows/{Sid}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update or publish an existing Studio Flow
      effect: write
      questions:
      - Can I publish a draft Flow by changing its status?
      - Can I push a new JSON definition to a Flow that already exists?
      instructions:
      - text: Set existing Flow {sid} to status {status}.
        slots:
          sid: path.Sid
          status: requestBody.Status
      - text: Replace the definition of Flow {sid} with {definition} as {status} and note {commit_message}.
        slots:
          sid: path.Sid
          definition: requestBody.Definition
          status: requestBody.Status
          commit_message: requestBody.CommitMessage
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/Flows/{Sid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a Studio Flow
      effect: destructive
      questions:
      - Can I permanently delete a Studio Flow I no longer need?
      - How do I remove an unused Flow from my account?
      instructions:
      - text: Delete Studio Flow {sid}.
        slots:
          sid: path.Sid
      - text: Remove Flow {sid} from my account.
        slots:
          sid: path.Sid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/Flows/{Sid}/Revisions'].get
  update:
    x-apievangelist-phrasing:
      intent: List the revision history of a Flow
      effect: read
      questions:
      - Can I see every past revision of a Studio Flow?
      - Which versions of my Flow have been saved over time?
      instructions:
      - text: List the revisions of Flow {sid}.
        slots:
          sid: path.Sid
      - text: Show the saved version history for Flow {sid}.
        slots:
          sid: path.Sid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/Flows/{Sid}/Revisions/{Revision}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a specific revision of a Flow
      effect: read
      questions:
      - Can I pull up the latest published revision of a Flow?
      - Can I retrieve an older numbered revision of a Studio Flow?
      instructions:
      - text: Fetch revision {revision} of Flow {sid}.
        slots:
          revision: path.Revision
          sid: path.Sid
      - text: Show the LatestPublished revision of Flow {sid} as {revision}.
        slots:
          sid: path.Sid
          revision: path.Revision
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/Flows/Validate'].post
  update:
    x-apievangelist-phrasing:
      intent: Validate a Flow definition before saving
      effect: write
      questions:
      - Can I check a Flow JSON definition for errors without creating the Flow?
      - Is there a dry-run check for Studio Flow definitions?
      instructions:
      - text: Validate the Flow definition {definition} for {friendly_name} with status {status}.
        slots:
          definition: requestBody.Definition
          friendly_name: requestBody.FriendlyName
          status: requestBody.Status
      - text: Dry-run check Flow JSON {definition} named {friendly_name} as {status} before I save it.
        slots:
          definition: requestBody.Definition
          friendly_name: requestBody.FriendlyName
          status: requestBody.Status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/Flows/{Sid}/TestUsers'].get
  update:
    x-apievangelist-phrasing:
      intent: See who can test a Flow's draft
      effect: read
      questions:
      - Which test users are allowed to try the draft version of my Flow?
      - Can I check the test user list on a Studio Flow?
      instructions:
      - text: Show the test users for Flow {sid}.
        slots:
          sid: path.Sid
      - text: List who can test drafts of Flow {sid}.
        slots:
          sid: path.Sid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/Flows/{Sid}/TestUsers'].post
  update:
    x-apievangelist-phrasing:
      intent: Set who can test a Flow's draft
      effect: write
      questions:
      - Can I let specific identities test a draft Flow before it goes live?
      - Can I replace the test user list on a Studio Flow?
      instructions:
      - text: Set the test users on Flow {sid} to {test_users}.
        slots:
          sid: path.Sid
          test_users: requestBody.TestUsers
      - text: Allow {test_users} to test draft versions of Flow {sid}.
        slots:
          test_users: requestBody.TestUsers
          sid: path.Sid
      method: generated
      generated: '2026-09-26'