Netlify · OpenAPI Overlay 1.0.0

API Evangelist conversational phrasing for Netlify's API documentation Build API

6 actions 6 updates phrasing extends openapi/netlify-build-api-openapi.yml

Generated by API Evangelist Written by API Evangelist tooling for Netlify's API. It is a proposal applied on top of the contract, not a document Netlify publishes.

View Overlay File View on GitHub Overlay Specification

What the actions change

x-apievangelist-phrasing

Targets 6

$.info

$.paths['/sites/{site_id}/builds'].get

$.paths['/sites/{site_id}/builds'].post

$.paths['/builds/{build_id}'].get

$.paths['/builds/{build_id}/start'].post

$.paths['/{account_id}/builds/status'].get

OpenAPI Overlay

# 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 Build API
  version: 1.0.0
extends: openapi/netlify-build-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['/sites/{site_id}/builds'].get
  update:
    x-apievangelist-phrasing:
      intent: List a site's builds
      effect: read
      questions:
      - What builds have run for my site?
      - Can I page through a site's build history?
      instructions:
      - text: List builds for site {site}.
        slots:
          site: path.site_id
      - text: Show recent builds on site {site}.
        slots:
          site: path.site_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sites/{site_id}/builds'].post
  update:
    x-apievangelist-phrasing:
      intent: Trigger a build for a site
      effect: write
      questions:
      - How do I trigger a new build of my Netlify site?
      - Can I clear the build cache when starting a build?
      - Why hasn't my requested build started right away?
      instructions:
      - text: Start a build for site {site}.
        slots:
          site: path.site_id
      - text: Build branch {branch} of site {site} with the cache cleared.
        slots:
          branch: query.branch
          site: path.site_id
      - text: Trigger a build on site {site} titled {title}.
        slots:
          site: path.site_id
          title: query.title
      method: generated
      generated: '2026-09-26'
- target: $.paths['/builds/{build_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a build
      effect: read
      questions:
      - What's the status of a particular build?
      - Can I see whether a build finished or failed?
      instructions:
      - text: Get build {build}.
        slots:
          build: path.build_id
      - text: Check whether build {build} is done.
        slots:
          build: path.build_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/builds/{build_id}/start'].post
  update:
    x-apievangelist-phrasing:
      intent: Report that a build has started
      effect: write
      questions:
      - How does a build runner signal that a build has begun?
      - Can I record the buildbot version when a build starts?
      instructions:
      - text: Mark build {build} as started.
        slots:
          build: path.build_id
      - text: Report build {build} started on buildbot version {version}.
        slots:
          build: path.build_id
          version: query.buildbot_version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{account_id}/builds/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a team's build capacity status
      effect: read
      questions:
      - How many builds are running or queued for my team?
      - Is my team out of concurrent build capacity?
      instructions:
      - text: Show build status for account {account}.
        slots:
          account: path.account_id
      - text: Check how much build capacity team {account} is using.
        slots:
          account: path.account_id
      method: generated
      generated: '2026-09-26'