Netlify · OpenAPI Overlay 1.0.0

API Evangelist conversational phrasing for Netlify's API documentation Dev Server API

7 actions 7 updates phrasing extends openapi/netlify-dev-server-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 7

$.info

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

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

$.paths['/sites/{site_id}/dev_servers'].delete

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

$.paths['/sites/{site_id}/dev_servers/{dev_server_id}/activity'].post

$.paths['/sites/{site_id}/dev_servers/{dev_server_id}/state'].post

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 Dev Server API
  version: 1.0.0
extends: openapi/netlify-dev-server-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: 6
- target: $.paths['/sites/{site_id}/dev_servers'].get
  update:
    x-apievangelist-phrasing:
      intent: List a site's dev servers
      effect: read
      questions:
      - Which dev servers are running for my site?
      - Can I page through all dev servers on a site?
      instructions:
      - text: List dev servers for site {site}.
        slots:
          site: path.site_id
      - text: Show every dev server running on site {site}.
        slots:
          site: path.site_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/sites/{site_id}/dev_servers'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a dev server for a site
      effect: write
      questions:
      - How do I spin up a cloud dev server for my site?
      - Can I start a dev server on a specific branch?
      instructions:
      - text: Start a dev server for site {site}.
        slots:
          site: path.site_id
      - text: Create a dev server on site {site} for branch {branch}.
        slots:
          site: path.site_id
          branch: query.branch
      method: generated
      generated: '2026-10-01'
- target: $.paths['/sites/{site_id}/dev_servers'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a site's dev servers
      effect: destructive
      questions:
      - Can I shut down all dev servers for a site at once?
      - How do I remove the dev servers for just one branch?
      instructions:
      - text: Delete all dev servers for site {site}.
        slots:
          site: path.site_id
      - text: Remove dev servers on site {site} for branch {branch}.
        slots:
          site: path.site_id
          branch: query.branch
      method: generated
      generated: '2026-10-01'
- target: $.paths['/sites/{site_id}/dev_servers/{dev_server_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a dev server
      effect: read
      questions:
      - What state is my dev server in?
      - Can I look up one dev server's details?
      instructions:
      - text: Get dev server {server} on site {site}.
        slots:
          site: path.site_id
          server: path.dev_server_id
      - text: Check the status of dev server {server} for site {site}.
        slots:
          site: path.site_id
          server: path.dev_server_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/sites/{site_id}/dev_servers/{dev_server_id}/activity'].post
  update:
    x-apievangelist-phrasing:
      intent: Record activity on a dev server
      effect: write
      questions:
      - How do I keep a dev server from going idle?
      - Can I signal that a dev server is still in use?
      instructions:
      - text: Mark dev server {server} on site {site} as active.
        slots:
          site: path.site_id
          server: path.dev_server_id
      - text: Ping dev server {server} of site {site} to record activity.
        slots:
          site: path.site_id
          server: path.dev_server_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/sites/{site_id}/dev_servers/{dev_server_id}/state'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a dev server's state
      effect: write
      questions:
      - Can I report a dev server's new state or an error?
      - How is a dev server's state changed through the API?
      instructions:
      - text: Set dev server {server} on site {site} to state {state}.
        slots:
          server: path.dev_server_id
          site: path.site_id
          state: requestBody.state
      - text: Mark dev server {server} on site {site} as {state} with error {error}.
        slots:
          server: path.dev_server_id
          site: path.site_id
          state: requestBody.state
          error: requestBody.error
      method: generated
      generated: '2026-10-01'