# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for CloudBees CI REST API (Jenkins-compatible) Job API
  version: 1.0.0
extends: openapi/cloudbees-job-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: 8
- target: $.paths['/job/{name}/api/json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a job's metadata and build history
      effect: read
      questions:
      - How do I see a job's status and recent builds in CloudBees CI?
      - Is my job currently healthy, and what was its last build result?
      instructions:
      - text: Show the metadata for job {name}.
        slots:
          name: path.name
      - text: Get job {name}'s details, returning only {tree}.
        slots:
          name: path.name
          tree: query.tree
      - text: Fetch job {name}'s metadata at depth {depth}.
        slots:
          name: path.name
          depth: query.depth
      method: generated
      generated: '2026-10-01'
- target: $.paths['/job/{name}/build'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a build of a job with no parameters
      effect: write
      questions:
      - How do I kick off a job that takes no build parameters?
      - Can I trigger a plain build remotely using a job's trigger token?
      instructions:
      - text: Start a build of job {name} with no parameters.
        slots:
          name: path.name
      - text: Trigger a plain build of {name} using the remote token {token}.
        slots:
          name: path.name
          token: query.token
      method: generated
      generated: '2026-10-01'
- target: $.paths['/job/{name}/buildWithParameters'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a parameterized build of a job
      effect: write
      questions:
      - How do I run a job and pass it build parameters?
      - Can I launch a parameterized build remotely with a trigger token?
      instructions:
      - text: Run job {name} with the build parameters I give you.
        slots:
          name: path.name
      - text: Launch a parameterized build of {name} authorized by token {token}.
        slots:
          name: path.name
          token: query.token
      method: generated
      generated: '2026-10-01'
- target: $.paths['/job/{name}/{number}/api/json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a specific build of a job by number
      effect: read
      questions:
      - What was the result of a particular numbered build of my job?
      - 'Can I look up how long build #42 took and who started it?'
      instructions:
      - text: Show build {number} of job {name}.
        slots:
          name: path.name
          number: path.number
      - text: Get build number {number} of {name}, returning only {tree}.
        slots:
          name: path.name
          number: path.number
          tree: query.tree
      method: generated
      generated: '2026-10-01'
- target: $.paths['/job/{name}/lastSuccessfulBuild/api/json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the last successful build of a job
      effect: read
      questions:
      - When did my job last pass, and which build was it?
      - Which build of this job was the most recent green one?
      instructions:
      - text: Show the last successful build of job {name}.
        slots:
          name: path.name
      - text: Get {name}'s most recent passing build, limited to {tree}.
        slots:
          name: path.name
          tree: query.tree
      method: generated
      generated: '2026-10-01'
- target: $.paths['/job/{name}/config.xml'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a job's configuration XML
      effect: read
      questions:
      - How do I export a job's config.xml so I can back it up?
      - Where can I read the raw XML definition of an existing job?
      instructions:
      - text: Download the config.xml of job {name}.
        slots:
          name: path.name
      - text: Show me the current XML configuration for {name}.
        slots:
          name: path.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/job/{name}/config.xml'].post
  update:
    x-apievangelist-phrasing:
      intent: Replace a job's configuration XML
      effect: write
      questions:
      - How do I change an existing job's settings by uploading new config XML?
      - Can I push an edited config.xml back to a job?
      instructions:
      - text: Overwrite job {name}'s configuration with the XML I provide.
        slots:
          name: path.name
      - text: Upload this edited config.xml to job {name}.
        slots:
          name: path.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/job/{name}/doDelete'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete a job
      effect: destructive
      questions:
      - How do I permanently remove a job from the controller?
      - Can I delete an obsolete job through the API?
      instructions:
      - text: Delete job {name} from the controller.
        slots:
          name: path.name
      - text: Permanently remove the obsolete {name} job.
        slots:
          name: path.name
      method: generated
      generated: '2026-10-01'