# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Azure DevOps Builds Build Definitions API
  version: 1.0.0
extends: openapi/microsoft-azure-devops-build-definitions-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: 5
- target: $.paths['/build/definitions'].get
  update:
    x-apievangelist-phrasing:
      intent: List build definitions
      effect: read
      questions:
      - What build pipeline definitions exist in my Azure DevOps project?
      - Can I filter build definitions by name or folder path?
      - Which build definitions have had builds since a given date?
      instructions:
      - text: List all build definitions in the project.
      - text: List build definitions named {name} under folder {path}.
        slots:
          name: query.name
          path: query.path
      - text: Show build definitions built after {builtAfter}.
        slots:
          builtAfter: query.builtAfter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/build/definitions'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a build definition
      effect: write
      questions:
      - How do I set up a new classic build definition with its repository, process and agent queue?
      - Can I create a build definition by cloning an existing one?
      instructions:
      - text: Create a build definition named {name} for repository {repository} using queue {queue} and process {process}.
        slots:
          name: requestBody.name
          repository: requestBody.repository
          queue: requestBody.queue
          process: requestBody.process
      - text: Create a new build definition by cloning definition {definitionToCloneId}.
        slots:
          definitionToCloneId: query.definitionToCloneId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/build/definitions/{definitionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a build definition's configuration
      effect: read
      questions:
      - Where can I see the steps, triggers and variables configured on one build definition?
      - Can I view an older revision of a build definition?
      instructions:
      - text: Show me build definition {definitionId}.
        slots:
          definitionId: path.definitionId
      - text: Get revision {revision} of build definition {definitionId}.
        slots:
          revision: query.revision
          definitionId: path.definitionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/build/definitions/{definitionId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a build definition
      effect: write
      questions:
      - How do I change the triggers or variables on an existing build definition?
      - Why does saving a build definition fail when the revision number is out of date?
      instructions:
      - text: Update build definition {definitionId} with new variables {variables}.
        slots:
          definitionId: path.definitionId
          variables: requestBody.variables
      - text: Rename existing build definition {definitionId} to {name}.
        slots:
          definitionId: path.definitionId
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/build/definitions/{definitionId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a build definition
      effect: destructive
      questions:
      - Can I remove a build definition that I no longer use?
      - What happens to a build definition's existing builds when I delete the definition?
      instructions:
      - text: Delete build definition {definitionId}.
        slots:
          definitionId: path.definitionId
      - text: Remove the obsolete build definition {definitionId} from the project.
        slots:
          definitionId: path.definitionId
      method: generated
      generated: '2026-09-26'