# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Canonical Assertions API
  version: 1.0.0
extends: openapi/canonical-assertions-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['/v2/assertions/{type}/{primaryKey}'].get
  update:
    x-apievangelist-phrasing:
      intent: Fetch one assertion by its primary key
      effect: read
      questions:
      - Can I fetch a single signed assertion if I know its type and primary key?
      - Where do I get one specific account-key assertion by its key?
      instructions:
      - text: Fetch the {type} assertion with primary key {primary_key}.
        slots:
          type: path.type
          primary_key: path.primaryKey
      - text: Get the single signed assertion of type {type} keyed {primary_key}.
        slots:
          type: path.type
          primary_key: path.primaryKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/assertions'].get
  update:
    x-apievangelist-phrasing:
      intent: List known assertion types
      effect: read
      questions:
      - Which assertion types does snapd know about?
      - What kinds of signed assertions can the system database hold?
      instructions:
      - text: List every assertion type the system supports.
      - text: Show me the names of all known assertion types.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/assertions'].post
  update:
    x-apievangelist-phrasing:
      intent: Add or replace a signed assertion
      effect: write
      questions:
      - How do I add a signed assertion to the system's assertion database?
      - What signature does an assertion need before snapd will accept it?
      instructions:
      - text: Add this signed assertion to the system database.
      - text: Replace the existing assertion with this newer signed version.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/assertions/{assertion-type}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get assertions of a given type
      effect: read
      questions:
      - How do I fetch all assertions of one type, such as account-key?
      - Can I pull assertions from the store and get them back as JSON?
      instructions:
      - text: Get all assertions of type {assertion_type}.
        slots:
          assertion_type: path.assertion-type
      - text: Fetch {assertion_type} assertions from the store with remote {remote} as JSON {json}.
        slots:
          assertion_type: path.assertion-type
          remote: query.remote
          json: query.json
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/model'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the device's model assertion
      effect: read
      questions:
      - Which model assertion describes this snap-based device?
      - What brand and model is this Ubuntu Core device running as?
      instructions:
      - text: Show the active model assertion.
      - text: Tell me the model this device is configured as.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/model'].post
  update:
    x-apievangelist-phrasing:
      intent: Remodel the device with a new model assertion
      effect: write
      questions:
      - How do I remodel a device by supplying a new model assertion?
      - Can a remodel be done offline, with the snaps provided alongside?
      instructions:
      - text: Replace the model assertion with {assertion}.
        slots:
          assertion: requestBody.assertion
      - text: Remodel this device using new model assertion {assertion}.
        slots:
          assertion: requestBody.assertion
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/model/serial'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the device's serial assertion
      effect: read
      questions:
      - What serial assertion binds this device's identity to its key?
      - Has this device been registered and issued a serial by the store?
      instructions:
      - text: Show the current serial assertion.
      - text: Get this device's serial identity assertion.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/model/serial'].post
  update:
    x-apievangelist-phrasing:
      intent: Forget the device's serial registration
      effect: destructive
      questions:
      - How do I make a device forget its serial and register again?
      - Can I stop re-registration from happening until the next reboot?
      instructions:
      - text: Run serial action {action} to unregister this device.
        slots:
          action: requestBody.action
      - text: 'Forget the serial with action {action} and hold registration until reboot: {hold}.'
        slots:
          action: requestBody.action
          hold: requestBody.no-registration-until-reboot
      method: generated
      generated: '2026-09-26'