# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Google Dialogflow Versions API
  version: 1.0.0
extends: openapi/google-dialogflow-versions-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: 27
- target: $.paths['/v3/projects/{projectsId}/locations/{locationsId}/agents/{agentsId}/playbooks/{playbooksId}/versions/{versionsId}:restore'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore a playbook to a saved version
      effect: write
      questions:
      - Can I roll a Dialogflow CX playbook back to an earlier saved version?
      - What happens to my current playbook when I restore an older snapshot of it?
      instructions:
      - text: Restore playbook {playbook} on agent {agent} to version {version} (project {project}, location {location}).
        slots:
          playbook: path.playbooksId
          agent: path.agentsId
          version: path.versionsId
          project: path.projectsId
          location: path.locationsId
      - text: Roll playbook {playbook} back to its saved version {version}.
        slots:
          playbook: path.playbooksId
          version: path.versionsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/projects/{projectsId}/locations/{locationsId}/agents/{agentsId}/playbooks/{playbooksId}/versions/{versionsId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a saved playbook version
      effect: read
      questions:
      - Where can I see what a specific saved version of my playbook contains?
      - Can I inspect an old playbook snapshot without restoring it?
      instructions:
      - text: Show me version {version} of playbook {playbook} on agent {agent} in project {project}, location {location}.
        slots:
          version: path.versionsId
          playbook: path.playbooksId
          agent: path.agentsId
          project: path.projectsId
          location: path.locationsId
      - text: Fetch the details of playbook snapshot {version} for playbook {playbook}.
        slots:
          version: path.versionsId
          playbook: path.playbooksId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/projects/{projectsId}/locations/{locationsId}/agents/{agentsId}/playbooks/{playbooksId}/versions/{versionsId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a saved playbook version
      effect: destructive
      questions:
      - Can I remove a playbook version snapshot I no longer need?
      - Is deleting an old playbook version permanent?
      instructions:
      - text: Delete version {version} of playbook {playbook} on agent {agent} (project {project}, location {location}).
        slots:
          version: path.versionsId
          playbook: path.playbooksId
          agent: path.agentsId
          project: path.projectsId
          location: path.locationsId
      - text: Remove the stale playbook snapshot {version} from playbook {playbook}.
        slots:
          version: path.versionsId
          playbook: path.playbooksId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/projects/{projectsId}/locations/{locationsId}/agents/{agentsId}/playbooks/{playbooksId}/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: List saved versions of a playbook
      effect: read
      questions:
      - Which saved versions exist for one of my CX playbooks?
      - How do I page through every snapshot taken of a playbook?
      instructions:
      - text: List all saved versions of playbook {playbook} on agent {agent} in project {project}, location {location}.
        slots:
          playbook: path.playbooksId
          agent: path.agentsId
          project: path.projectsId
          location: path.locationsId
      - text: Show the first {page_size} snapshots of playbook {playbook}.
        slots:
          page_size: query.pageSize
          playbook: path.playbooksId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/projects/{projectsId}/locations/{locationsId}/agents/{agentsId}/playbooks/{playbooksId}/versions'].post
  update:
    x-apievangelist-phrasing:
      intent: Save a new version of a playbook
      effect: write
      questions:
      - How do I snapshot a playbook before I start editing it?
      - Can I attach a description when saving a playbook version?
      instructions:
      - text: Create a new version of playbook {playbook} on agent {agent} in project {project}, location {location}.
        slots:
          playbook: path.playbooksId
          agent: path.agentsId
          project: path.projectsId
          location: path.locationsId
      - text: Snapshot playbook {playbook} with the note {description}.
        slots:
          playbook: path.playbooksId
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/projects/{projectsId}/locations/{locationsId}/agents/{agentsId}/tools/{toolsId}/versions/{versionsId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a saved tool version
      effect: read
      questions:
      - Can I look at an earlier saved version of an agent tool's definition?
      - Where do I find what a particular tool snapshot looked like?
      instructions:
      - text: Get version {version} of tool {tool} on agent {agent} in project {project}, location {location}.
        slots:
          version: path.versionsId
          tool: path.toolsId
          agent: path.agentsId
          project: path.projectsId
          location: path.locationsId
      - text: Show me tool snapshot {version} for tool {tool}.
        slots:
          version: path.versionsId
          tool: path.toolsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/projects/{projectsId}/locations/{locationsId}/agents/{agentsId}/tools/{toolsId}/versions/{versionsId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a saved tool version
      effect: destructive
      questions:
      - Can I delete a tool version even if something still references it?
      - Is there a force option when removing an old tool snapshot?
      instructions:
      - text: Delete version {version} of tool {tool} on agent {agent} (project {project}, location {location}).
        slots:
          version: path.versionsId
          tool: path.toolsId
          agent: path.agentsId
          project: path.projectsId
          location: path.locationsId
      - text: Force-delete tool snapshot {version} of tool {tool} even if it is referenced.
        slots:
          version: path.versionsId
          tool: path.toolsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/projects/{projectsId}/locations/{locationsId}/agents/{agentsId}/tools/{toolsId}/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: List saved versions of a tool
      effect: read
      questions:
      - What versions have been saved for one of my agent's tools?
      - Is there a way to page through the history of a tool's snapshots?
      instructions:
      - text: List the saved versions of tool {tool} on agent {agent} in project {project}, location {location}.
        slots:
          tool: path.toolsId
          agent: path.agentsId
          project: path.projectsId
          location: path.locationsId
      - text: Show {page_size} tool snapshots at a time for tool {tool}.
        slots:
          page_size: query.pageSize
          tool: path.toolsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/projects/{projectsId}/locations/{locationsId}/agents/{agentsId}/tools/{toolsId}/versions'].post
  update:
    x-apievangelist-phrasing:
      intent: Save a new version of a tool
      effect: write
      questions:
      - How do I take a snapshot of an agent tool before changing it?
      - Can I give a tool version its own display name?
      instructions:
      - text: Create a new version of tool {tool} on agent {agent} in project {project}, location {location}.
        slots:
          tool: path.toolsId
          agent: path.agentsId
          project: path.projectsId
          location: path.locationsId
      - text: Save tool {tool} as a version named {display_name}.
        slots:
          tool: path.toolsId
          display_name: requestBody.displayName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/projects/{projectsId}/locations/{locationsId}/agents/{agentsId}/tools/{toolsId}/versions/{versionsId}:restore'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore a tool to a saved version
      effect: write
      questions:
      - Can I revert an agent tool to a previously saved version?
      - What does restoring a tool snapshot do to the live tool definition?
      instructions:
      - text: Restore tool {tool} on agent {agent} to its version {version} (project {project}, location {location}).
        slots:
          tool: path.toolsId
          agent: path.agentsId
          version: path.versionsId
          project: path.projectsId
          location: path.locationsId
      - text: Revert tool {tool} to saved snapshot {version}.
        slots:
          tool: path.toolsId
          version: path.versionsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/projects/{projectsId}/locations/{locationsId}/agents/{agentsId}/flows/{flowsId}/versions/{versionsId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a flow version
      effect: read
      questions:
      - How can I view the details of one specific version of a CX flow?
      - Can I check the training state of a flow version?
      instructions:
      - text: Get flow version {version} of flow {flow} on agent {agent} in project {project}, location {location}.
        slots:
          version: path.versionsId
          flow: path.flowsId
          agent: path.agentsId
          project: path.projectsId
          location: path.locationsId
      - text: Show me the state and description of flow {flow} version {version}.
        slots:
          flow: path.flowsId
          version: path.versionsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/projects/{projectsId}/locations/{locationsId}/agents/{agentsId}/flows/{flowsId}/versions/{versionsId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a flow version
      effect: destructive
      questions:
      - Can I delete a flow version that I no longer deploy anywhere?
      - Is removing an old version of a flow reversible?
      instructions:
      - text: Delete version {version} of flow {flow} on agent {agent} (project {project}, location {location}).
        slots:
          version: path.versionsId
          flow: path.flowsId
          agent: path.agentsId
          project: path.projectsId
          location: path.locationsId
      - text: Remove obsolete flow version {version} from flow {flow}.
        slots:
          version: path.versionsId
          flow: path.flowsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/projects/{projectsId}/locations/{locationsId}/agents/{agentsId}/flows/{flowsId}/versions/{versionsId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a flow version's details
      effect: write
      questions:
      - Can I rename or re-describe a flow version after it was created?
      - Which fields of an existing flow version am I allowed to change?
      instructions:
      - text: Update the description of flow {flow} version {version} on agent {agent} (project {project}, location {location}) to {description}.
        slots:
          flow: path.flowsId
          version: path.versionsId
          agent: path.agentsId
          project: path.projectsId
          location: path.locationsId
          description: requestBody.description
      - text: Rename flow version {version} of flow {flow} to {display_name}.
        slots:
          version: path.versionsId
          flow: path.flowsId
          display_name: requestBody.displayName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/projects/{projectsId}/locations/{locationsId}/agents/{agentsId}/flows/{flowsId}/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: List versions of a flow
      effect: read
      questions:
      - Which versions have been cut from one of my CX flows?
      - Can I see the version history of a flow page by page?
      instructions:
      - text: List every version of flow {flow} on agent {agent} in project {project}, location {location}.
        slots:
          flow: path.flowsId
          agent: path.agentsId
          project: path.projectsId
          location: path.locationsId
      - text: Show the next page of flow {flow} versions using token {page_token}.
        slots:
          flow: path.flowsId
          page_token: query.pageToken
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/projects/{projectsId}/locations/{locationsId}/agents/{agentsId}/flows/{flowsId}/versions'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a version of a flow
      effect: write
      questions:
      - How do I freeze the current state of a flow as a new version?
      - Can I label a new flow version with a display name before deploying it?
      instructions:
      - text: Create a new version of flow {flow} on agent {agent} in project {project}, location {location}.
        slots:
          flow: path.flowsId
          agent: path.agentsId
          project: path.projectsId
          location: path.locationsId
      - text: Cut a version of flow {flow} called {display_name}.
        slots:
          flow: path.flowsId
          display_name: requestBody.displayName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/projects/{projectsId}/locations/{locationsId}/agents/{agentsId}/flows/{flowsId}/versions/{versionsId}:load'].post
  update:
    x-apievangelist-phrasing:
      intent: Load a flow version into the draft
      effect: write
      questions:
      - How do I bring an older flow version back into the draft flow?
      - Can loading a flow version also override agent-level resources like intents?
      instructions:
      - text: Load version {version} of flow {flow} into the draft on agent {agent} (project {project}, location {location}).
        slots:
          version: path.versionsId
          flow: path.flowsId
          agent: path.agentsId
          project: path.projectsId
          location: path.locationsId
      - text: Load flow {flow} version {version} into draft and set override of agent resources to {allow_override}.
        slots:
          flow: path.flowsId
          version: path.versionsId
          allow_override: requestBody.allowOverrideAgentResources
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/projects/{projectsId}/locations/{locationsId}/agents/{agentsId}/flows/{flowsId}/versions/{versionsId}:compareVersions'].post
  update:
    x-apievangelist-phrasing:
      intent: Compare two versions of a flow
      effect: read
      questions:
      - What changed between two versions of the same CX flow?
      - Can I diff a flow version against another one for a specific language?
      instructions:
      - text: Compare flow {flow} version {version} with {target_version} on agent {agent} (project {project}, location {location}).
        slots:
          flow: path.flowsId
          version: path.versionsId
          target_version: requestBody.targetVersion
          agent: path.agentsId
          project: path.projectsId
          location: path.locationsId
      - text: Diff flow {flow} version {version} against {target_version} in language {language_code}.
        slots:
          flow: path.flowsId
          version: path.versionsId
          target_version: requestBody.targetVersion
          language_code: requestBody.languageCode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/agent/versions/{versionsId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an ES agent version in a region
      effect: read
      questions:
      - Can I look up one version of my regional Dialogflow ES agent?
      - Where do I see the status of an agent version stored in a specific location?
      instructions:
      - text: Get ES agent version {version} for project {project} in location {location}.
        slots:
          version: path.versionsId
          project: path.projectsId
          location: path.locationsId
      - text: Show the status and number of regional agent version {version} in {location} for project {project}.
        slots:
          version: path.versionsId
          location: path.locationsId
          project: path.projectsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/agent/versions/{versionsId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an ES agent version in a region
      effect: destructive
      questions:
      - Can I delete a version of my regional ES agent?
      - Is it permanent when I remove an agent version from a regional location?
      instructions:
      - text: Delete ES agent version {version} for project {project} in location {location}.
        slots:
          version: path.versionsId
          project: path.projectsId
          location: path.locationsId
      - text: Remove the regional agent version {version} stored in {location} for project {project}.
        slots:
          version: path.versionsId
          location: path.locationsId
          project: path.projectsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/agent/versions/{versionsId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an ES agent version in a region
      effect: write
      questions:
      - Can I change the description on a regional ES agent version?
      - Which fields of a regional agent version can I edit after creating it?
      instructions:
      - text: Set the description of ES agent version {version} in location {location}, project {project}, to {description}.
        slots:
          version: path.versionsId
          location: path.locationsId
          project: path.projectsId
          description: requestBody.description
      - text: Update regional agent version {version} in {location} for project {project} with mask {update_mask}.
        slots:
          version: path.versionsId
          location: path.locationsId
          project: path.projectsId
          update_mask: query.updateMask
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/agent/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: List ES agent versions in a region
      effect: read
      questions:
      - What versions exist for my ES agent in a particular region?
      - Can I page through the agent versions kept in one location?
      instructions:
      - text: List ES agent versions for project {project} in location {location}.
        slots:
          project: path.projectsId
          location: path.locationsId
      - text: Show {page_size} regional agent versions per page in {location} for project {project}.
        slots:
          page_size: query.pageSize
          location: path.locationsId
          project: path.projectsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/agent/versions'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an ES agent version in a region
      effect: write
      questions:
      - How do I snapshot my regional ES agent as a new version?
      - Can I add a description when creating a version of an agent in a specific location?
      instructions:
      - text: Create a new ES agent version for project {project} in location {location}.
        slots:
          project: path.projectsId
          location: path.locationsId
      - text: Snapshot the regional agent in {location} for project {project} with description {description}.
        slots:
          location: path.locationsId
          project: path.projectsId
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/agent/versions/{versionsId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a version of the default ES agent
      effect: read
      questions:
      - Can I fetch one version of the ES agent in my project's default location?
      - How can I see the status of an agent version on my global ES agent?
      instructions:
      - text: Get version {version} of the global ES agent in project {project}.
        slots:
          version: path.versionsId
          project: path.projectsId
      - text: Fetch default-location agent version {version} for project {project}.
        slots:
          version: path.versionsId
          project: path.projectsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/agent/versions/{versionsId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a version of the default ES agent
      effect: destructive
      questions:
      - Can I delete a version of my global ES agent?
      - Does removing a default-location agent version affect environments using it?
      instructions:
      - text: Delete version {version} of the global ES agent in project {project}.
        slots:
          version: path.versionsId
          project: path.projectsId
      - text: Remove default-location agent version {version} from project {project}.
        slots:
          version: path.versionsId
          project: path.projectsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/agent/versions/{versionsId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a version of the default ES agent
      effect: write
      questions:
      - Can I edit the description on a version of my global ES agent?
      - What can I change on an existing default-location agent version?
      instructions:
      - text: Change the description of global ES agent version {version} in project {project} to {description}.
        slots:
          version: path.versionsId
          project: path.projectsId
          description: requestBody.description
      - text: Patch default-location agent version {version} for project {project} using mask {update_mask}.
        slots:
          version: path.versionsId
          project: path.projectsId
          update_mask: query.updateMask
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/agent/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: List versions of the default ES agent
      effect: read
      questions:
      - Which versions exist for my global ES agent?
      - Is there a paged list of default-location agent versions in a project?
      instructions:
      - text: List all versions of the global ES agent in project {project}.
        slots:
          project: path.projectsId
      - text: Show default-location agent versions for project {project}, {page_size} per page.
        slots:
          project: path.projectsId
          page_size: query.pageSize
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/agent/versions'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a version of the default ES agent
      effect: write
      questions:
      - How do I save my global ES agent as a new version?
      - Can I describe what changed when I version the default-location agent?
      instructions:
      - text: Create a new version of the global ES agent in project {project}.
        slots:
          project: path.projectsId
      - text: Version the default-location agent for project {project} with description {description}.
        slots:
          project: path.projectsId
          description: requestBody.description
      method: generated
      generated: '2026-10-01'