API Evangelist conversational phrasing for Stoplight Versions API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Stoplight Versions API
  version: 1.0.0
extends: openapi/stoplight-versions-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['/versions/publish/anon'].post
  update:
    x-apievangelist-phrasing:
      intent: Publish API docs anonymously to api-docs.io
      effect: destructive
      questions:
      - Can I publish a Swagger or RAML spec as public docs without a Stoplight account?
      - If I publish docs anonymously, can I update or remove them later?
      - What URL do I get back after anonymously publishing a spec to api-docs.io?
      instructions:
      - text: Anonymously publish the Swagger spec at {url} to api-docs.io and give me the docs link.
        slots:
          url: requestBody.url
      - text: Publish this JSON spec {specData} as anonymous API documentation on api-docs.io.
        slots:
          specData: requestBody.specData
      method: generated
      generated: '2026-09-26'
- target: $.paths['/versions/{versionId}/export/{format}'].get
  update:
    x-apievangelist-phrasing:
      intent: Export an API version as OpenAPI, RAML or Stoplight
      effect: read
      questions:
      - How do I download my Stoplight API version as an OpenAPI YAML file?
      - Which export formats can I pull an API version out in, like RAML 1.0 or Swagger JSON?
      - What export format keeps the x-stoplight annotations if I want to re-import later?
      instructions:
      - text: Export API version {versionId} as {format}.
        slots:
          versionId: path.versionId
          format: path.format
      - text: Download version {versionId} as a RAML 1.0 YAML file.
        slots:
          versionId: path.versionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/versions/{versionId}/import'].put
  update:
    x-apievangelist-phrasing:
      intent: Import a spec into an existing API version
      effect: destructive
      questions:
      - How do I sync my externally maintained Swagger file into an existing Stoplight version?
      - Will importing a spec overwrite resources that already exist in my API version?
      - Can I import RAML from a URL instead of pasting the spec data?
      instructions:
      - text: Import the spec at {url} into API version {versionId}, overwriting matching resources.
        slots:
          url: requestBody.url
          versionId: path.versionId
      - text: Merge this spec {specData} into version {versionId} using import options {options}.
        slots:
          specData: requestBody.specData
          versionId: path.versionId
          options: requestBody.options
      method: generated
      generated: '2026-09-26'
- target: $.paths['/versions/{versionId}/publish'].post
  update:
    x-apievangelist-phrasing:
      intent: Re-publish docs for an API version
      effect: write
      questions:
      - Can my CI pipeline automatically re-publish the docs after I import a new spec?
      - Does re-publishing work for an API version that has never been published before?
      - How do I refresh published documentation using the publish settings already configured?
      instructions:
      - text: Re-publish the documentation for API version {versionId} with its existing settings.
        slots:
          versionId: path.versionId
      - text: Push a fresh publish of the docs for version {versionId}.
        slots:
          versionId: path.versionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/versions/{versionId}/unpublish'].put
  update:
    x-apievangelist-phrasing:
      intent: Unpublish the docs for an API version
      effect: destructive
      questions:
      - Can I take down the published documentation for one API version?
      - What happens to my hosted docs when I unpublish a Stoplight version?
      instructions:
      - text: Unpublish the documentation for API version {versionId}.
        slots:
          versionId: path.versionId
      - text: Take the docs for version {versionId} offline.
        slots:
          versionId: path.versionId
      method: generated
      generated: '2026-09-26'