Canonical

Canonical changes and tasks API

The changes and tasks API from Canonical — 4 operation(s) for changes and tasks.

GitHub OpenAPI

Operations 5

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /v1/changes List changes · Get changes #
Ask an LLM
“Which changes are still in progress on my Pebble daemon?”
“Can I list only the changes that touched one service?”
Tell an agent
List changes with status {select}.
Show the changes for service {service}.
GET /v1/changes/{id} Get a specific change · Get a specific change #
Ask an LLM
“What is the status of a particular change and its tasks?”
“Did a given change finish or fail?”
Tell an agent
Show change {id}.
Get the status and tasks of change {id}.
POST /v1/changes/{id} Abort a change · Perform an action on a change #
Ask an LLM
“How do I abort a change that is still running?”
“Which actions can be performed on an existing change?”
Tell an agent destructive · confirm first
Abort change {id}.
Perform action {action} on change {id}.
GET /v1/changes/{id}/wait Wait for a change to finish · Wait for a change to complete #
Ask an LLM
“Can I block until a change completes instead of polling it?”
“What happens if a change does not finish within my timeout?”
Tell an agent
Wait for change {id} to complete.
Wait up to {timeout} for change {id} to finish.
GET /v1/tasks/{task-id}/websocket/{websocket-id} Connect to a task's websocket · Connect to a task's websocket #
Ask an LLM
“How do I attach to the websocket of a running exec task?”
“Can I stream a task's I/O over a websocket?”
Tell an agent
Connect to websocket {websocket_id} of task {task_id}.
Open the {websocket_id} websocket for task {task_id}.

Documentation

📖
Documentation
https://snapcraft.io/docs/reference/development/snapd-rest-api/
📖
Documentation
https://ubuntu.com/landscape/docs
📖
APIReference
https://documentation.ubuntu.com/landscape/reference/api/
📖
Documentation
https://documentation.ubuntu.com/lxd/latest/rest-api/
📖
APIReference
https://documentation.ubuntu.com/lxd/latest/api-extensions/
📖
Documentation
https://ubuntu.com/security/api/docs
📖
APIReference
https://ubuntu.com/security/api/spec.json
📖
Documentation
https://documentation.ubuntu.com/pebble/
📖
Documentation
https://canonical-testflinger.readthedocs-hosted.com/en/latest/
📖
Documentation
https://documentation.ubuntu.com/anbox-cloud/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/canonical/refs/heads/main/openapi/canonical-changes-and-tasks-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/canonical/refs/heads/main/json-schema/canonical-get-changes-response-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/canonical/refs/heads/main/json-schema/canonical-get-change-by-idresponse-schema.json

Other Resources

🔗
HowTo
https://snapcraft.io/docs/how-to-guides/snap-development/use-the-rest-api/
🔗
ReleaseNotes
https://documentation.ubuntu.com/landscape/reference/release-notes/
🔗
Portal
https://ubuntu.com/landscape
🔗
SourceCode
https://github.com/canonical/lxd
🔗
Portal
https://canonical.com/lxd
🔗
Portal
https://ubuntu.com/security
🔗
SourceCode
https://github.com/canonical/pebble
🔗
SourceCode
https://github.com/canonical/testflinger
🔗
SourceCode
https://github.com/canonical/hardware-api
🔗
Portal
https://ubuntu.com/certified
🔗
SourceCode
https://github.com/canonical/identity-platform-api
🔗
SourceCode
https://github.com/canonical/test_observer
🔗
Portal
https://canonical.com/anbox-cloud
🔗
SourceCode
https://github.com/canonical/cos-registration-server

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/canonical:canonical-changes-and-tasks-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

canonical-changes-and-tasks-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Pebble changes and tasks API
  version: v1
tags:
- name: changes and tasks
paths:
  /v1/changes:
    get:
      summary: Get changes
      tags:
      - changes and tasks
      description: Fetch information for the specified changes.
      parameters:
      - name: select
        in: query
        description: Filter changes by status.
        schema:
          type: string
          enum:
          - all
          - in-progress
          - ready
          default: in-progress
      - name: for
        in: query
        description: Filter changes for a specific service name.
        schema:
          type: string
      responses:
        '200':
          description: Information about changes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetChangesResponse'
              example:
                type: sync
                status-code: 200
                status: OK
                result:
                - id: '4'
                  kind: stop
                  summary: Stop service "svc1" and 1 more
                  status: Done
                  tasks:
                  - id: '7'
                    kind: stop
                    summary: Stop service "svc1"
                    status: Done
                    progress:
                      label: ''
                      done: 1
                      total: 1
                    spawn-time: '2024-12-27T10:08:14.399194229+08:00'
                    ready-time: '2024-12-27T10:08:14.429319813+08:00'
                  - id: '8'
                    kind: stop
                    summary: Stop service "svc2"
                    status: Done
                    progress:
                      label: ''
                      done: 1
                      total: 1
                    spawn-time: '2024-12-27T10:08:14.399199354+08:00'
                    ready-time: '2024-12-27T10:08:14.432387271+08:00'
                  ready: true
                  spawn-time: '2024-12-27T10:08:14.399202521+08:00'
                  ready-time: '2024-12-27T10:08:14.432389313+08:00'
      operationId: getV1Changes
      x-operation-id-source: derived
  /v1/changes/{id}:
    get:
      summary: Get a specific change
      tags:
      - changes and tasks
      description: Fetch information about a Change given its ID.
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the change.
        schema:
          type: string
      responses:
        '200':
          description: Information about the change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetChangeByIDResponse'
              example:
                type: sync
                status-code: 200
                status: OK
                result:
                  id: '38'
                  kind: autostart
                  summary: Autostart service "svc1" and 1 more
                  status: Done
                  tasks:
                  - id: '54'
                    kind: start
                    summary: Start service "svc1"
                    status: Done
                    progress:
                      label: ''
                      done: 1
                      total: 1
                    spawn-time: '2024-12-27T12:31:26.673287868+08:00'
                    ready-time: '2024-12-27T12:31:27.681780702+08:00'
                  ready: true
                  spawn-time: '2024-12-27T12:31:26.673297951+08:00'
                  ready-time: '2024-12-27T12:31:27.686371869+08:00'
      operationId: getV1ChangesById
      x-operation-id-source: derived
    post:
      summary: Perform an action on a change
      tags:
      - changes and tasks
      description: Perform an action on a change. Currently the only supported action is "abort".
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the change.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  description: The action to perform on the change.
                  enum:
                  - abort
      responses:
        '200':
          description: Change aborted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetChangeByIDResponse'
              example:
                type: sync
                status-code: 200
                status: OK
                result:
                  id: '8'
                  kind: perform-check
                  summary: Perform HTTP check "check1"
                  status: Abort
                  tasks:
                  - id: '14'
                    kind: perform-check
                    summary: Perform HTTP check "check1"
                    status: Abort
                    progress:
                      label: ''
                      done: 1
                      total: 1
                    spawn-time: '2024-12-27T10:15:31.390053104+08:00'
                  ready: false
                  spawn-time: '2024-12-27T10:15:31.390062521+08:00'
      operationId: postV1ChangesById
      x-operation-id-source: derived
  /v1/changes/{id}/wait:
    get:
      summary: Wait for a change to complete
      description: 'Wait for the change to be finished.


        If the wait operation succeeds, the result will have the "err" field set to an appropriate error message if the change itself had an error.'
      tags:
      - changes and tasks
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
        description: The ID of the change to wait for.
      - in: query
        name: timeout
        schema:
          type: string
        description: 'Optional timeout (a [duration](#duration)).

          If specified, wait till the change is ready or a timeout occurs, whichever is first.

          If not specified or zero, wait indefinitely until the change is ready.

          '
      responses:
        '200':
          description: Wait for a change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetChangeByIDResponse'
              example:
                type: sync
                status-code: 200
                status: OK
                result:
                  id: '38'
                  kind: autostart
                  summary: Autostart service "svc1" and 1 more
                  status: Done
                  tasks:
                  - id: '54'
                    kind: start
                    summary: Start service "svc1"
                    status: Done
                    progress:
                      label: ''
                      done: 1
                      total: 1
                    spawn-time: '2024-12-27T12:31:26.673287868+08:00'
                    ready-time: '2024-12-27T12:31:27.681780702+08:00'
                  ready: true
                  spawn-time: '2024-12-27T12:31:26.673297951+08:00'
                  ready-time: '2024-12-27T12:31:27.686371869+08:00'
      operationId: getV1ChangesByIdWait
      x-operation-id-source: derived
  /v1/tasks/{task-id}/websocket/{websocket-id}:
    get:
      summary: Connect to a task's websocket
      tags:
      - changes and tasks
      description: Establish a websocket connection to a specific task.
      parameters:
      - in: path
        name: task-id
        schema:
          type: string
        required: true
        description: The ID of the task.
      - in: path
        name: websocket-id
        schema:
          type: string
        required: true
        description: The ID of the websocket.
        enum:
        - control
        - stderr
        - stdio
      responses:
        '101':
          description: 'The connection is upgraded to the websocket protocol and the websocket connection is established.


            The full websocket protocol is not documented. For details, see the [Python client code](https://github.com/canonical/operator/blob/main/ops/pebble.py#L1818).

            '
          content:
            application/json:
              example: null
      operationId: getV1TasksByTaskIdWebsocketByWebsocketId
      x-operation-id-source: derived
components:
  schemas:
    taskInfo:
      type: object
      properties:
        id:
          type: string
        kind:
          type: string
        summary:
          type: string
        status:
          type: string
        log:
          type: array
          items:
            type: string
        progress:
          $ref: '#/components/schemas/taskInfoProgress'
        spawn-time:
          type: string
          format: date-time
          description: spawn-time is a [time](#time).
        ready-time:
          type: string
          format: date-time
          description: ready-time is a [time](#time).
        data:
          type: object
          additionalProperties:
            type: string
            format: json-string
    changeInfo:
      type: object
      properties:
        id:
          type: string
        kind:
          type: string
        summary:
          type: string
        status:
          type: string
        tasks:
          type: array
          items:
            $ref: '#/components/schemas/taskInfo'
        ready:
          type: boolean
        err:
          type: string
        spawn-time:
          type: string
          format: date-time
          description: spawn-time is a [time](#time).
        ready-time:
          type: string
          format: date-time
          description: ready-time is a [time](#time).
        data:
          type: object
          additionalProperties:
            type: string
            format: json-string
    BaseResponse:
      type: object
      properties:
        type:
          type: string
          description: Response type, "sync".
        status-code:
          type: integer
          description: HTTP response status code.
        status:
          type: string
          description: 'The description of the HTTP status code.


            See the [IANA list](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).

            '
    taskInfoProgress:
      type: object
      properties:
        label:
          type: string
        done:
          type: integer
        total:
          type: integer
    GetChangeByIDResponse:
      allOf:
      - $ref: '#/components/schemas/BaseResponse'
      - type: object
        properties:
          result:
            $ref: '#/components/schemas/changeInfo'
    GetChangesResponse:
      allOf:
      - $ref: '#/components/schemas/BaseResponse'
      - type: object
        properties:
          result:
            type: array
            items:
              $ref: '#/components/schemas/changeInfo'