API Evangelist conversational phrasing for Netlify's API documentation X Internal API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Netlify's API documentation X Internal API
  version: 1.0.0
extends: openapi/netlify-x-internal-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: 3
- target: $.paths['/sites/{site_id}/plugins/{package}'].put
  update:
    x-apievangelist-phrasing:
      intent: Pin a build plugin version
      effect: write
      questions:
      - Can I pin a build plugin to a specific version on my site?
      - How is a build plugin's pinned version changed?
      instructions:
      - text: Pin plugin {package} on site {site} to version {version}.
        slots:
          package: path.package
          site: path.site_id
          version: requestBody.pinned_version
      - text: Update build plugin {package} settings for site {site}.
        slots:
          package: path.package
          site: path.site_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sites/{site_id}/plugin_runs/latest'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the latest build plugin runs
      effect: read
      questions:
      - What happened the last time my build plugins ran?
      - Can I filter the latest plugin runs by state?
      instructions:
      - text: Get the latest runs of plugins {packages} on site {site}.
        slots:
          packages: query.packages
          site: path.site_id
      - text: Show recent runs of {packages} on site {site} in state {state}.
        slots:
          packages: query.packages
          site: path.site_id
          state: query.state
      method: generated
      generated: '2026-09-26'
- target: $.paths['/deploys/{deploy_id}/plugin_runs'].post
  update:
    x-apievangelist-phrasing:
      intent: Record a build plugin run on a deploy
      effect: write
      questions:
      - How does a build plugin report its result on a deploy?
      - Can a plugin run include a summary and details text?
      instructions:
      - text: Record a run of plugin {package} on deploy {deploy}.
        slots:
          package: requestBody.package
          deploy: path.deploy_id
      - text: Log plugin {package} run on deploy {deploy} with state {state} and summary {summary}.
        slots:
          package: requestBody.package
          deploy: path.deploy_id
          state: requestBody.state
          summary: requestBody.summary
      method: generated
      generated: '2026-09-26'