# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Canonical Snap Store Device Snaps API
  version: 1.0.0
extends: openapi/canonical-snaps-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: 10
- target: $.paths['/v2/snaps/info/{name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get snap details
      effect: read
      questions:
      - Which channels and revisions are published for a snap?
      - Can I see a snap's tracks for one architecture?
      instructions:
      - text: Get info for snap {name} on series {series}.
        slots:
          name: path.name
          series: header.Snap-Device-Series
      - text: Show channels of snap {name} for architecture {architecture} on series {series}.
        slots:
          name: path.name
          architecture: query.architecture
          series: header.Snap-Device-Series
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/snaps/find'].get
  update:
    x-apievangelist-phrasing:
      intent: Find snaps
      effect: read
      questions:
      - How do I search the Snap Store by keyword?
      - Can I find only strictly confined snaps in a category?
      instructions:
      - text: Find snaps matching {q} for series {series}.
        slots:
          q: query.q
          series: header.Snap-Device-Series
      - text: Find snaps in category {category} with confinement {confinement} on series {series}.
        slots:
          category: query.category
          confinement: query.confinement
          series: header.Snap-Device-Series
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/snaps/refresh'].post
  update:
    x-apievangelist-phrasing:
      intent: Check which snaps need refreshing
      effect: read
      questions:
      - Which of my installed snaps have newer revisions available?
      - What refresh actions does the store return for my device's snaps?
      instructions:
      - text: Get refresh actions for installed snaps {context} on series {series}.
        slots:
          context: requestBody.context
          series: header.Snap-Device-Series
      - text: Run refresh actions {actions} for series {series}.
        slots:
          actions: requestBody.actions
          series: header.Snap-Device-Series
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/snaps/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search snaps (legacy v1)
      effect: read
      questions:
      - Does the older v1 snaps search endpoint still work?
      - Can I query snaps through the legacy v1 snaps search path?
      instructions:
      - text: Search snaps with the legacy v1 snaps endpoint for {q} on series {series}.
        slots:
          q: query.q
          series: header.Snap-Device-Series
      - text: Run a v1 snaps search for {q} with device series {series}.
        slots:
          q: query.q
          series: header.Snap-Device-Series
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/snaps/names'].get
  update:
    x-apievangelist-phrasing:
      intent: List snap names for autocomplete
      effect: read
      questions:
      - Can I get every snap name to drive autocomplete?
      - Where do I get the full list of snap names?
      instructions:
      - text: List all snap names for series {series}.
        slots:
          series: header.Snap-Device-Series
      - text: Fetch snap names for autocomplete on device series {series}.
        slots:
          series: header.Snap-Device-Series
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/snaps/sections'].get
  update:
    x-apievangelist-phrasing:
      intent: List store sections
      effect: read
      questions:
      - What sections or categories does the store group snaps into?
      - Which store sections can I browse?
      instructions:
      - text: List the store sections.
      - text: Show all snap store sections.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/snaps/auth/nonces'].post
  update:
    x-apievangelist-phrasing:
      intent: Request a device nonce
      effect: write
      questions:
      - How does a device get a nonce before authenticating to the store?
      - What is the first step of device authentication?
      instructions:
      - text: Request a device authentication nonce.
      - text: Get a fresh nonce for this device.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/snaps/auth/sessions'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a device session
      effect: write
      questions:
      - How does a device open an authenticated session with the store?
      - Can a registered device obtain a session macaroon?
      instructions:
      - text: Create a device session with the store.
      - text: Open a new authenticated device session.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/snaps/auth/devices'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a device
      effect: write
      questions:
      - How do I register a device with the store to get its serial?
      - Where does a new device submit its serial request?
      instructions:
      - text: Register this device with the store.
      - text: Submit a device registration request.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/snaps/auth/request-id'].post
  update:
    x-apievangelist-phrasing:
      intent: Get an authentication request ID
      effect: write
      questions:
      - How does a device get a request ID for registration?
      - Do I need a request ID before registering a device?
      instructions:
      - text: Get an authentication request ID.
      - text: Request a new request-id for device registration.
      method: generated
      generated: '2026-10-01'