# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Snapd REST Authentication Required API
  version: 1.0.0
extends: openapi/canonical-authenticationrequired-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: 20
- target: $.paths['/v2/changes'].get
  update:
    x-apievangelist-phrasing:
      intent: List snapd changes in progress or completed
      effect: read
      questions:
      - What installs, refreshes and other changes is snapd running right now?
      - Can I filter the snapd change list to only in-progress or only finished work?
      - Which changes have touched a particular snap?
      instructions:
      - text: List snapd changes filtered to {select}.
        slots:
          select: query.select
      - text: Show all changes that involve snap {for}.
        slots:
          for: query.for
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/changes/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the status of one snapd change
      effect: read
      questions:
      - Has a specific snapd background change finished yet?
      - How do I check whether a snap install I kicked off succeeded?
      instructions:
      - text: Get the current status of snapd change {id}.
        slots:
          id: path.id
      - text: Tell me whether change {id} is done, still running or errored.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/changes/{id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Abort a snapd change in progress
      effect: destructive
      questions:
      - Can I stop a snap operation that's still running?
      - How do I cancel a stuck snapd change?
      instructions:
      - text: Abort snapd change {id} with action {action}.
        slots:
          id: path.id
          action: requestBody.action
      - text: Cancel the in-progress change {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/cohorts'].post
  update:
    x-apievangelist-phrasing:
      intent: Create cohort keys for snaps
      effect: write
      questions:
      - How do I generate cohort keys so several devices get the same snap revision?
      - Can I create cohort keys for a set of snaps at once?
      instructions:
      - text: Create cohort keys for snaps {snaps} using action {action}.
        slots:
          snaps: requestBody.snaps
          action: requestBody.action
      - text: Generate cohort keys for the snaps {snaps}.
        slots:
          snaps: requestBody.snaps
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/find'].get
  update:
    x-apievangelist-phrasing:
      intent: Search the store for snaps
      effect: read
      questions:
      - Which snaps in the store match a search term and work on this machine?
      - Can I browse store snaps by section, like games or development?
      - Is there a snap with an exact name available for my system?
      instructions:
      - text: Search the snap store for {q}.
        slots:
          q: query.q
      - text: Find the snap named exactly {name} in the store.
        slots:
          name: query.name
      - text: List store snaps in section {section}.
        slots:
          section: query.section
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/login'].post
  update:
    x-apievangelist-phrasing:
      intent: Log in to snapd and the store
      effect: write
      questions:
      - How do I sign in to snapd with my store account?
      - Does snapd login support a one-time password for two-factor accounts?
      instructions:
      - text: Log in to snapd as {email} with password {password}.
        slots:
          email: requestBody.email
          password: requestBody.password
      - text: Sign in {email} using password {password} and one-time code {otp}.
        slots:
          email: requestBody.email
          password: requestBody.password
          otp: requestBody.otp
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/logout'].post
  update:
    x-apievangelist-phrasing:
      intent: Log out of snapd and the store
      effect: write
      questions:
      - How do I sign the current user out of snapd?
      - Can I clear my store session from snapd?
      instructions:
      - text: Log me out of snapd and the store.
      - text: End the current snapd store session.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/logs'].get
  update:
    x-apievangelist-phrasing:
      intent: Read snap service logs
      effect: read
      questions:
      - Where can I read the logs for my snap services?
      - Can I follow snapd logs live as new lines arrive?
      - Is it possible to limit logs to the last few lines?
      instructions:
      - text: Show the last {n} log lines for {names}.
        slots:
          n: query.n
          names: query.names
      - text: Stream logs for {names} and keep following them.
        slots:
          names: query.names
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/snapctl'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a snapctl command from inside a snap
      effect: write
      questions:
      - How does a snap run snapctl commands through the snapd socket?
      - Can I pass stdin to a snapctl command over the API?
      instructions:
      - text: Run snapctl with arguments {args} in context {context-id}.
        slots:
          args: requestBody.args
          context-id: requestBody.context-id
      - text: Execute snapctl {args} for context {context-id}, feeding {stdin} as input.
        slots:
          args: requestBody.args
          context-id: requestBody.context-id
          stdin: requestBody.stdin
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/snaps/{name}/conf'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an installed snap's configuration
      effect: read
      questions:
      - What configuration options are set for an installed snap?
      - Can I read system-wide snap options too?
      instructions:
      - text: Show the configuration of snap {name}.
        slots:
          name: path.name
      - text: Get config keys {keys} for snap {name}.
        slots:
          keys: query.keys
          name: path.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/snapshots/{set-id}/export'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a snapshot set as an archive
      effect: read
      questions:
      - How do I download a snap snapshot so I can move it to another machine?
      - In what format does a snapshot export come back?
      instructions:
      - text: Export snapshot set {set-id} as a tar archive.
        slots:
          set-id: path.set-id
      - text: Download snapshot {set-id}.
        slots:
          set-id: path.set-id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/system/system-recovery-keys'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve the disk encryption recovery key
      effect: read
      questions:
      - Where do I find the LUKS recovery key on an encrypted Ubuntu Core device?
      - Can I fetch the full disk encryption keys through snapd?
      instructions:
      - text: Get the system recovery key for this Ubuntu Core device.
      - text: Show me the LUKS encryption recovery keys.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/system/system-recovery-keys'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove or reset disk encryption recovery keys
      effect: destructive
      questions:
      - How do I reset the LUKS recovery keys on Ubuntu Core?
      - Can I remove the recovery keys from an encrypted device?
      instructions:
      - text: Apply recovery key action {action} on this device.
        slots:
          action: requestBody.action
      - text: Reset the full disk encryption recovery keys using action {action}.
        slots:
          action: requestBody.action
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/systems'].post
  update:
    x-apievangelist-phrasing:
      intent: Act on the current recovery system or create one
      effect: write
      questions:
      - Can I reboot into or install from the currently active recovery system?
      - How do I create a brand-new recovery system on the device?
      instructions:
      - text: Create a new recovery system on this device.
      - text: Reboot using the current active recovery system.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/systems/{label}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get details of one recovery system
      effect: read
      questions:
      - Is storage encryption enabled on a given recovery system?
      - What actions can I take on a specific recovery system?
      instructions:
      - text: Show details and available actions for recovery system {label}.
        slots:
          label: path.label
      - text: Check the encryption status of recovery system {label}.
        slots:
          label: path.label
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/systems/{label}'].post
  update:
    x-apievangelist-phrasing:
      intent: Perform an action on a labeled recovery system
      effect: write
      questions:
      - Can I trigger an action on a specific recovery system by its label?
      - Which body fields are needed depends on the action, so what can a labeled system do?
      instructions:
      - text: Run an action against recovery system {label}.
        slots:
          label: path.label
      - text: Reboot into the recovery system labeled {label}.
        slots:
          label: path.label
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/validation-sets'].get
  update:
    x-apievangelist-phrasing:
      intent: List enabled validation sets
      effect: read
      questions:
      - Which validation sets are enabled on this system?
      - Can I see every validation set that's constraining my snaps?
      instructions:
      - text: List all enabled validation sets.
      - text: Show every validation set active on this device.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/validation-sets/{account-id}/{name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one validation set
      effect: read
      questions:
      - What does a particular validation set require?
      - How do I look up a validation set by account and name?
      instructions:
      - text: Show validation set {name} from account {account-id}.
        slots:
          name: path.name
          account-id: path.account-id
      - text: Get the details of {account-id}/{name}.
        slots:
          account-id: path.account-id
          name: path.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/validation-sets/{account-id}/{name}'].post
  update:
    x-apievangelist-phrasing:
      intent: Apply or forget a validation set
      effect: write
      questions:
      - Can I enforce a validation set or only monitor it?
      - How do I forget a validation set I no longer want?
      - Is it possible to pin a validation set to a specific sequence?
      instructions:
      - text: Apply validation set {account-id}/{name} in {mode} mode.
        slots:
          account-id: path.account-id
          name: path.name
          mode: requestBody.mode
      - text: Run action {action} on validation set {account-id}/{name} at sequence {sequence}.
        slots:
          action: requestBody.action
          account-id: path.account-id
          name: path.name
          sequence: requestBody.sequence
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/warnings'].post
  update:
    x-apievangelist-phrasing:
      intent: Acknowledge snapd warnings
      effect: write
      questions:
      - How do I clear snapd warnings I've already seen?
      - Does acknowledging a warning fix whatever caused it?
      instructions:
      - text: Acknowledge all snapd warnings up to {timestamp}.
        slots:
          timestamp: requestBody.timestamp
      - text: Apply action {action} to warnings as of {timestamp}.
        slots:
          action: requestBody.action
          timestamp: requestBody.timestamp
      method: generated
      generated: '2026-09-26'