API Evangelist conversational phrasing for Canonical Notices API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Canonical Notices API
  version: 1.0.0
extends: openapi/canonical-notices-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: 6
- target: $.paths['/v1/notices'].get
  update:
    x-apievangelist-phrasing:
      intent: List Pebble notices
      effect: read
      questions:
      - Which notices has the Pebble daemon recorded?
      - Can I filter Pebble notices to custom ones from a single user ID?
      instructions:
      - text: List Pebble notices of type {types}.
        slots:
          types: query.types
      - text: Show Pebble notices with key {keys} occurring after {after}.
        slots:
          keys: query.keys
          after: query.after
      - text: Wait {timeout} for Pebble notices for user {user_id}.
        slots:
          timeout: query.timeout
          user_id: query.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/notices'].post
  update:
    x-apievangelist-phrasing:
      intent: Record a custom Pebble notice
      effect: write
      questions:
      - How do I record my own custom notice in Pebble?
      - Can a Pebble notice carry extra JSON data and a repeat-after duration?
      instructions:
      - text: Record a Pebble {type} notice with key {key} using action {action}.
        slots:
          type: requestBody.type
          key: requestBody.key
          action: requestBody.action
      - text: Add Pebble notice {key} of type {type}, action {action}, repeatable after {repeat_after}.
        slots:
          key: requestBody.key
          type: requestBody.type
          action: requestBody.action
          repeat_after: requestBody.repeat-after
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/notices/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one Pebble notice
      effect: read
      questions:
      - What does a single Pebble notice contain?
      - Can I look up a Pebble notice by ID?
      instructions:
      - text: Show Pebble notice {id}.
        slots:
          id: path.id
      - text: Fetch the Pebble notice with ID {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/notices'].get
  update:
    x-apievangelist-phrasing:
      intent: List system notices
      effect: read
      questions:
      - What notices has snapd recorded for me recently?
      - Can I wait for new notices of a certain type with a timeout?
      - Is there a way to fetch only notices after a given time?
      instructions:
      - text: List notices of types {types} after {after}.
        slots:
          types: query.types
          after: query.after
      - text: Wait up to {timeout} for new notices with keys {keys}.
        slots:
          timeout: query.timeout
          keys: query.keys
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/notices'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a snap-run-inhibit notice
      effect: write
      questions:
      - Can I create a notice through the API, and which types are allowed?
      - How does the snap command record a snap-run-inhibit notice?
      instructions:
      - text: Create a {type} notice with key {key} and action {action}.
        slots:
          type: requestBody.type
          key: requestBody.key
          action: requestBody.action
      - text: Record a snap-run-inhibit notice for key {key} with type {type} and action {action}.
        slots:
          key: requestBody.key
          type: requestBody.type
          action: requestBody.action
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/notices/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one notice
      effect: read
      questions:
      - What does a specific notice contain?
      - Can I look up a notice by its ID?
      instructions:
      - text: Show notice {id}.
        slots:
          id: path.id
      - text: Get the details of notice {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'