Canonical · OpenAPI Overlay 1.0.0

API Evangelist conversational phrasing for Pebble changes and tasks API

6 actions 6 updates phrasing extends openapi/canonical-changes-and-tasks-api-openapi.yml

Generated by API Evangelist Written by API Evangelist tooling for Canonical's API. It is a proposal applied on top of the contract, not a document Canonical publishes.

View Overlay File View on GitHub Overlay Specification

What the actions change

x-apievangelist-phrasing

Targets 6

$.info

$.paths['/v1/changes'].get

$.paths['/v1/changes/{id}'].get

$.paths['/v1/changes/{id}'].post

$.paths['/v1/changes/{id}/wait'].get

$.paths['/v1/tasks/{task-id}/websocket/{websocket-id}'].get

OpenAPI Overlay

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Pebble changes and tasks API
  version: 1.0.0
extends: openapi/canonical-changes-and-tasks-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: 5
- target: $.paths['/v1/changes'].get
  update:
    x-apievangelist-phrasing:
      intent: List changes
      effect: read
      questions:
      - Which changes are still in progress on my Pebble daemon?
      - Can I list only the changes that touched one service?
      instructions:
      - text: List changes with status {select}.
        slots:
          select: query.select
      - text: Show the changes for service {service}.
        slots:
          service: query.for
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/changes/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a specific change
      effect: read
      questions:
      - What is the status of a particular change and its tasks?
      - Did a given change finish or fail?
      instructions:
      - text: Show change {id}.
        slots:
          id: path.id
      - text: Get the status and tasks of change {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/changes/{id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Abort a change
      effect: destructive
      questions:
      - How do I abort a change that is still running?
      - Which actions can be performed on an existing change?
      instructions:
      - text: Abort change {id}.
        slots:
          id: path.id
      - text: Perform action {action} on change {id}.
        slots:
          action: requestBody.action
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/changes/{id}/wait'].get
  update:
    x-apievangelist-phrasing:
      intent: Wait for a change to finish
      effect: read
      questions:
      - Can I block until a change completes instead of polling it?
      - What happens if a change does not finish within my timeout?
      instructions:
      - text: Wait for change {id} to complete.
        slots:
          id: path.id
      - text: Wait up to {timeout} for change {id} to finish.
        slots:
          timeout: query.timeout
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/tasks/{task-id}/websocket/{websocket-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Connect to a task's websocket
      effect: read
      questions:
      - How do I attach to the websocket of a running exec task?
      - Can I stream a task's I/O over a websocket?
      instructions:
      - text: Connect to websocket {websocket_id} of task {task_id}.
        slots:
          websocket_id: path.websocket-id
          task_id: path.task-id
      - text: Open the {websocket_id} websocket for task {task_id}.
        slots:
          websocket_id: path.websocket-id
          task_id: path.task-id
      method: generated
      generated: '2026-10-01'