API Evangelist conversational phrasing for Netlify's API documentation Environment Variables 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 Environment Variables API
  version: 1.0.0
extends: openapi/netlify-environment-variables-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['/accounts/{account_id}/env'].get
  update:
    x-apievangelist-phrasing:
      intent: List environment variables for a team or site
      effect: read
      questions:
      - How do I see all environment variables for my team?
      - Can I list only the variables used in the production deploy context?
      - Which environment variables apply to a specific site in my account?
      instructions:
      - text: List environment variables for account {account}.
        slots:
          account: path.account_id
      - text: List env vars in account {account} for site {site}.
        slots:
          account: path.account_id
          site: query.site_id
      - text: Show env vars in account {account} for the {context} context.
        slots:
          account: path.account_id
          context: query.context_name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/accounts/{account_id}/env'].post
  update:
    x-apievangelist-phrasing:
      intent: Create environment variables
      effect: write
      questions:
      - How do I add new environment variables to my team?
      - Can I create environment variables scoped to one site?
      instructions:
      - text: Create environment variables in account {account}.
        slots:
          account: path.account_id
      - text: Add new env vars to site {site} in account {account}.
        slots:
          site: query.site_id
          account: path.account_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/sites/{site_id}/env'].get
  update:
    x-apievangelist-phrasing:
      intent: List a site's environment variables
      effect: read
      questions:
      - Can I get a site's environment variables without knowing the account ID?
      - What environment variables does my site have for deploy previews?
      instructions:
      - text: List environment variables for site {site}.
        slots:
          site: path.site_id
      - text: Show site {site}'s env vars in the {context} context.
        slots:
          site: path.site_id
          context: query.context_name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/accounts/{account_id}/env/{key}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one environment variable
      effect: read
      questions:
      - Can I read the values of a single environment variable?
      - What contexts is a particular env var set for?
      instructions:
      - text: Get environment variable {key} in account {account}.
        slots:
          account: path.account_id
          key: path.key
      - text: Show env var {key} in account {account} for site {site}.
        slots:
          key: path.key
          account: path.account_id
          site: query.site_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/accounts/{account_id}/env/{key}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace an environment variable and its values
      effect: write
      questions:
      - How do I overwrite all values of an existing environment variable?
      - Can I mark an env var as secret when updating it?
      instructions:
      - text: Replace all values of env var {key} in account {account}.
        slots:
          account: path.account_id
          key: path.key
      - text: Update env var {key} in account {account} to use scopes {scopes}.
        slots:
          key: path.key
          account: path.account_id
          scopes: requestBody.scopes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/accounts/{account_id}/env/{key}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an environment variable
      effect: destructive
      questions:
      - How do I remove an environment variable entirely?
      - Can I delete an env var from just one site?
      instructions:
      - text: Delete environment variable {key} from account {account}.
        slots:
          account: path.account_id
          key: path.key
      - text: Remove env var {key} for site {site} in account {account}.
        slots:
          key: path.key
          site: query.site_id
          account: path.account_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/accounts/{account_id}/env/{key}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Set an env var's value for one context
      effect: write
      questions:
      - Can I change an env var's value for only the production context?
      - Is it possible to set a different value for a branch deploy?
      instructions:
      - text: Set env var {key} in account {account} to {value} for context {context}.
        slots:
          key: path.key
          account: path.account_id
          value: requestBody.value
          context: requestBody.context
      - text: Set {key} in account {account} to {value} for branch {branch}.
        slots:
          key: path.key
          account: path.account_id
          value: requestBody.value
          branch: requestBody.context_parameter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/accounts/{account_id}/env/{key}/value/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one value of an environment variable
      effect: destructive
      questions:
      - Can I remove a single context value but keep the variable?
      - What removes just one of an env var's values?
      instructions:
      - text: Delete value {value_id} of env var {key} in account {account}.
        slots:
          value_id: path.id
          key: path.key
          account: path.account_id
      - text: Remove the value {value_id} from variable {key} in account {account}, keeping the rest.
        slots:
          value_id: path.id
          key: path.key
          account: path.account_id
      method: generated
      generated: '2026-10-01'