API Evangelist conversational phrasing for Buildkite REST Builds API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Buildkite REST Builds API
  version: 1.0.0
extends: openapi/buildkite-com-builds-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: 5
- target: $.paths['/organizations/{org}/pipelines/{pipeline}/builds'].get
  update:
    x-apievangelist-phrasing:
      intent: List builds for a pipeline
      effect: read
      questions:
      - How do I see the recent builds of one of my pipelines?
      - What builds have run on a given pipeline lately?
      instructions:
      - text: List builds for pipeline {pipeline} in organization {org}.
        slots:
          org: path.org
          pipeline: path.pipeline
      - text: Show me the build history of {pipeline}.
        slots:
          pipeline: path.pipeline
      method: generated
      generated: '2026-10-01'
- target: $.paths['/organizations/{org}/pipelines/{pipeline}/builds'].post
  update:
    x-apievangelist-phrasing:
      intent: Trigger a new build of a pipeline
      effect: write
      questions:
      - How do I trigger a new build through the Buildkite API?
      - Can I kick off a pipeline run from a script instead of pushing a commit?
      instructions:
      - text: Start a new build of pipeline {pipeline} in {org}.
        slots:
          org: path.org
          pipeline: path.pipeline
      - text: Trigger a fresh run of the {pipeline} pipeline.
        slots:
          pipeline: path.pipeline
      method: generated
      generated: '2026-10-01'
- target: $.paths['/organizations/{org}/pipelines/{pipeline}/builds/{number}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one build by number
      effect: read
      questions:
      - What's the state of a specific build number?
      - Can I fetch a single build to see its jobs and whether it passed?
      instructions:
      - text: Get build {number} of pipeline {pipeline} in {org}.
        slots:
          org: path.org
          pipeline: path.pipeline
          number: path.number
      - text: Show me whether build {number} of {pipeline} passed or failed.
        slots:
          number: path.number
          pipeline: path.pipeline
      method: generated
      generated: '2026-10-01'
- target: $.paths['/organizations/{org}/pipelines/{pipeline}/builds/{number}/cancel'].put
  update:
    x-apievangelist-phrasing:
      intent: Cancel a running build
      effect: destructive
      questions:
      - How do I cancel a build that's still running?
      - Can I stop a scheduled build before its jobs start?
      instructions:
      - text: Cancel build {number} of pipeline {pipeline} in {org}.
        slots:
          org: path.org
          pipeline: path.pipeline
          number: path.number
      - text: Stop the in-progress build {number} on {pipeline}.
        slots:
          number: path.number
          pipeline: path.pipeline
      method: generated
      generated: '2026-10-01'
- target: $.paths['/organizations/{org}/pipelines/{pipeline}/builds/{number}/rebuild'].put
  update:
    x-apievangelist-phrasing:
      intent: Rebuild a previous build
      effect: write
      questions:
      - How do I re-run an entire build with the same commit and settings?
      - Can I rebuild a finished build as a new build?
      instructions:
      - text: Rebuild build {number} of pipeline {pipeline} in {org}.
        slots:
          org: path.org
          pipeline: path.pipeline
          number: path.number
      - text: Run build {number} of {pipeline} again as a new build.
        slots:
          number: path.number
          pipeline: path.pipeline
      method: generated
      generated: '2026-10-01'