Canonical

Canonical changes and tasks API

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

Documentation GitHub OpenAPI

Operations 5

GET /v1/changes Get changes #

GET /v1/changes/{id} Get a specific change #

POST /v1/changes/{id} Perform an action on a change #

GET /v1/changes/{id}/wait Wait for a change to complete #

GET /v1/tasks/{task-id}/websocket/{websocket-id} Connect to a task's websocket #

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-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

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:
    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
    taskInfoProgress:
      type: object
      properties:
        label:
          type: string
        done:
          type: integer
        total:
          type: integer
    GetChangesResponse:
      allOf:
      - $ref: '#/components/schemas/BaseResponse'
      - type: object
        properties:
          result:
            type: array
            items:
              $ref: '#/components/schemas/changeInfo'
    GetChangeByIDResponse:
      allOf:
      - $ref: '#/components/schemas/BaseResponse'
      - type: object
        properties:
          result:
            $ref: '#/components/schemas/changeInfo'
    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).

            '
    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