API Evangelist conversational phrasing for Netlify's API documentation Deploy 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 Deploy API
  version: 1.0.0
extends: openapi/netlify-deploy-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: 13
- target: $.paths['/sites/{site_id}/deploys'].get
  update:
    x-apievangelist-phrasing:
      intent: List a site's deploys
      effect: read
      questions:
      - How do I see the deploy history for my site?
      - Can I filter deploys to only production or only a specific branch?
      - Which deploys on my site are in an error state?
      instructions:
      - text: List deploys for site {site}.
        slots:
          site: path.site_id
      - text: List deploys on site {site} from branch {branch}.
        slots:
          site: path.site_id
          branch: query.branch
      - text: Show deploys for site {site} in state {state}.
        slots:
          site: path.site_id
          state: query.state
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sites/{site_id}/deploys'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new deploy for a site
      effect: write
      questions:
      - How do I deploy files to my Netlify site through the API?
      - Can I create a draft deploy instead of publishing to production?
      - Is it possible to deploy a zip file of my site?
      instructions:
      - text: Create a new deploy for site {site}.
        slots:
          site: path.site_id
      - text: Create a draft deploy on site {site} for branch {branch}.
        slots:
          site: path.site_id
          branch: requestBody.branch
      - text: Deploy site {site} with the title {title}.
        slots:
          site: path.site_id
          title: query.title
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sites/{site_id}/deploys/{deploy_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a deploy scoped to a site
      effect: read
      questions:
      - Can I look up a deploy's details within a specific site?
      - What state is a given deploy of my site in?
      instructions:
      - text: Get deploy {deploy} of site {site}.
        slots:
          site: path.site_id
          deploy: path.deploy_id
      - text: Show the status of deploy {deploy} under site {site}.
        slots:
          site: path.site_id
          deploy: path.deploy_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sites/{site_id}/deploys/{deploy_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an existing site deploy
      effect: write
      questions:
      - Can I add files to a deploy I already created?
      - How do I attach a commit ref to an existing deploy?
      instructions:
      - text: Update deploy {deploy} on site {site} with new files.
        slots:
          site: path.site_id
          deploy: path.deploy_id
      - text: Set commit ref {commit} on deploy {deploy} of site {site}.
        slots:
          commit: query.commit_ref
          deploy: path.deploy_id
          site: path.site_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sites/{site_id}/deploys/{deploy_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a deploy from a site
      effect: destructive
      questions:
      - Can I delete a specific deploy from my site's history?
      - Is removing a deploy under a site permanent?
      instructions:
      - text: Delete deploy {deploy} from site {site}.
        slots:
          site: path.site_id
          deploy: path.deploy_id
      - text: Remove deploy {deploy} in the history of site {site}.
        slots:
          site: path.site_id
          deploy: path.deploy_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/deploys/{deploy_id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a running deploy
      effect: destructive
      questions:
      - How do I stop a deploy that's still in progress?
      - Can I cancel a deploy that is taking too long?
      instructions:
      - text: Cancel deploy {deploy}.
        slots:
          deploy: path.deploy_id
      - text: Stop the in-progress deploy {deploy}.
        slots:
          deploy: path.deploy_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sites/{site_id}/deploys/{deploy_id}/restore'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore a previous deploy as live
      effect: write
      questions:
      - Can I republish an older deploy of my site?
      - How do I make a past deploy the live version again?
      instructions:
      - text: Restore deploy {deploy} as the live version of site {site}.
        slots:
          site: path.site_id
          deploy: path.deploy_id
      - text: Republish old deploy {deploy} on site {site}.
        slots:
          site: path.site_id
          deploy: path.deploy_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sites/{site_id}/rollback'].put
  update:
    x-apievangelist-phrasing:
      intent: Roll back a site to its previous deploy
      effect: write
      questions:
      - Can I quickly undo my latest production deploy?
      - What's the fastest way to go back to the previously published deploy?
      instructions:
      - text: Roll back site {site} to the previous deploy.
        slots:
          site: path.site_id
      - text: Undo the latest publish on site {site}.
        slots:
          site: path.site_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/deploys/{deploy_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a deploy by its ID
      effect: read
      questions:
      - Can I look up a deploy with just its deploy ID and no site?
      - Where do I check a deploy's state if I only have its ID?
      instructions:
      - text: Get deploy {deploy} by ID.
        slots:
          deploy: path.deploy_id
      - text: Look up deploy {deploy} without a site ID.
        slots:
          deploy: path.deploy_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/deploys/{deploy_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a deploy by its ID
      effect: destructive
      questions:
      - Can I delete a deploy knowing only its deploy ID?
      - Is there a way to remove a deploy without specifying the site?
      instructions:
      - text: Delete deploy {deploy} by ID.
        slots:
          deploy: path.deploy_id
      - text: Remove deploy {deploy} without referencing its site.
        slots:
          deploy: path.deploy_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/deploys/{deploy_id}/validations_report'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a deploy's validations report
      effect: write
      questions:
      - How do I record secrets scan results on a deploy?
      - Can I update the validations report for a deploy?
      instructions:
      - text: Update the validations report for deploy {deploy}.
        slots:
          deploy: path.deploy_id
      - text: Attach secrets scan results {scan} to deploy {deploy}.
        slots:
          scan: requestBody.secrets_scan
          deploy: path.deploy_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/deploys/{deploy_id}/lock'].post
  update:
    x-apievangelist-phrasing:
      intent: Lock a deploy to stop auto publishing
      effect: write
      questions:
      - Can I pin my site to one deploy so new builds don't auto-publish?
      - How do I lock the currently published deploy?
      instructions:
      - text: Lock deploy {deploy}.
        slots:
          deploy: path.deploy_id
      - text: Pin deploy {deploy} so later deploys are not auto-published.
        slots:
          deploy: path.deploy_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/deploys/{deploy_id}/unlock'].post
  update:
    x-apievangelist-phrasing:
      intent: Unlock a deploy to resume auto publishing
      effect: write
      questions:
      - How do I turn auto publishing back on after locking a deploy?
      - Can I unlock a deploy I pinned earlier?
      instructions:
      - text: Unlock deploy {deploy}.
        slots:
          deploy: path.deploy_id
      - text: Release the lock on deploy {deploy} so new deploys publish again.
        slots:
          deploy: path.deploy_id
      method: generated
      generated: '2026-09-26'