Canonical Asynchronous API

openapi: 3.2.0
info:
  title: Snapd REST Asynchronous API
  license:
    name: GPL-3.0
    url: https://www.gnu.org/licenses/gpl-3.0.txt
  version: '1.0'
  description: 'The REST API provides access to snapd''s state and many of its key functions,

    as listed below.


    For general information on how to use the API, including how to access it,

    its requests and responses, results fields and error types, see Using the

    REST API.'
servers:
- url: unix:///run/snapd.socket
  description: 'Local snapd socket access. Unless otherwise specified, routes appear on

    this socket.'
- url: unix:///run/snapd-snap.socket
  description: Snapd socket access for snaps
tags:
- name: Asynchronous
  description: Return the reference to a change that will occur in the background.
paths:
  /v2/confdb/{account}/{confdb-schema}/{view}:
    parameters:
    - name: account
      in: path
      required: true
      schema:
        type: string
      example: system
    - name: confdb-schema
      in: path
      required: true
      schema:
        type: string
      example: network
    - name: view
      in: path
      required: true
      schema:
        type: string
      examples:
        admin:
          value: wifi-admin
          summary: Write/control access
        state:
          value: wifi-state
          summary: Read-only access
    get:
      tags:
      - Asynchronous
      summary: Get configurations from confdb
      description: Retrieves configuration values from confdb.
      operationId: getConfdb
      security:
      - PeerAuth: []
      parameters:
      - name: keys
        in: query
        description: 'A comma-separated list of configuration paths to read from. These paths

          refer to rules defined in the view specified in the URL. If no list is

          provided, the GET will match with all readable view rules and return any

          stored values for those. If there are no stored configuration values for

          a subset of the fields, those fields will be omitted from the result

          object.'
        schema:
          type: string
      responses:
        '202':
          $ref: '#/components/responses/Accepted'
        '400':
          $ref: '#/components/responses/BadRequest'
    put:
      tags:
      - Asynchronous
      summary: Set configurations in confdb
      description: Sets configuration values in confdb.
      operationId: setConfdb
      security:
      - PeerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - values
              properties:
                values:
                  type: object
                  description: 'A map of configuration paths to JSON values to be set.

                    Use null to unset a value.'
                  additionalProperties: true
              example:
                values:
                  office.ssid: foo
                  password: null
      responses:
        '202':
          $ref: '#/components/responses/Accepted'
        '400':
          $ref: '#/components/responses/BadRequest'
  /v2/interfaces:
    post:
      tags:
      - Asynchronous
      summary: Issue an action to the interface system
      description: 'Used to connect and disconnect interfaces. Issues a command to the interface

        system to operate on the specified plug and slot.'
      operationId: postInterfaces
      security:
      - PeerAuth: []
      requestBody:
        description: Parameters for the interface action.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  description: Action to perform.
                  enum:
                  - connect
                  - disconnect
                forget:
                  type: boolean
                  description: 'Used with the ''disconnect'' action. Ensures the system does not

                    reestablish the connection going forward.

                    '
                slots:
                  type: array
                  minItems: 1
                  maxItems: 1
                  items:
                    $ref: '#/components/schemas/Slot'
                plugs:
                  type: array
                  minItems: 1
                  maxItems: 1
                  items:
                    $ref: '#/components/schemas/Plug'
      responses:
        '202':
          $ref: '#/components/responses/Accepted'
        '400':
          $ref: '#/components/responses/BadRequest'
  /v2/quotas:
    post:
      tags:
      - Asynchronous
      summary: Manage quota groups
      description: Create, modify, or remove a quota group.
      operationId: manageQuotaGroups
      security:
      - PeerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - action
              - quota-group
              properties:
                action:
                  type: string
                  enum:
                  - ensure
                  - remove
                quota-group:
                  $ref: '#/components/schemas/QuotaGroup'
      responses:
        '202':
          $ref: '#/components/responses/Accepted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/snaps:
    post:
      tags:
      - Asynchronous
      summary: Manage snaps
      description: 'Install, refresh, revert, remove, enable, disable, or perform other actions on snaps.

        This endpoint supports both standard JSON requests for store operations and multipart/form-data for sideloading snaps.'
      operationId: manageSnaps
      security:
      - PeerAuth: []
      requestBody:
        description: The body of the JSON request.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - action
              properties:
                action:
                  type: string
                  enum:
                  - install
                  - refresh
                  - remove
                  - revert
                  - hold
                  - unhold
                  - enable
                  - disable
                  - switch
                  - snapshot
                snaps:
                  type: array
                  items:
                    type: string
                quota-group:
                  type: string
                  description: The quota group the snap belongs to.
                unaliased:
                  type: boolean
                prefer:
                  type: boolean
                  description: Cannot be used with 'unaliased'
                classic:
                  type: boolean
                  description: Whether the snap uses classic confinement or not.
                devmode:
                  type: boolean
                  description: Whether the snap should be installed in developer mode or not.
                jailmode:
                  type: boolean
                  description: 'Set to true to install the snap in jail mode. Only non-classic

                    snaps can be placed in jail mode.'
                ignore-running:
                  type: boolean
                components:
                  type: string
                  description: 'This parameter is a mapping of a string to a string array. If a

                    snap is installed, it will install the requested components for

                    it. If the snap is not installed, the snap will be installed

                    along with requested components.'
                  format: map[string][]string
                  example: '{ "firefox": ["firefox+comp"]}'
                transaction:
                  type: string
                  enum:
                  - per-snap
                  - all-snaps
          multipart/form-data:
            schema:
              type: object
              properties:
                action:
                  type: string
                  enum:
                  - install
                  - try
                  default: install
                snap:
                  type: string
                  format: binary
                  description: 'The content of a .snap file. This field may because repeated

                    many times to act on multiple snaps.'
                snap-path:
                  type: string
                  description: 'The path to install the snap to. This parameter may only be used

                    with a single ''snap'' field.'
                name:
                  type: string
                  description: This parameter may only be used with a single 'snap' field.
                component-name:
                  type: string
                  description: This parameter may only be used with a single 'snap' field.
                transaction:
                  type: string
                  enum:
                  - per-snap
                  - all-snaps
                dangerous:
                  type: boolean
                  description: Whether to install the snap with the '--dangerous' flag or not.
                devmode:
                  type: boolean
                  description: Whether the snap should be installed in developer mode or not.
                quota-group:
                  type: string
                  description: The quota group the snap belongs to.
                ignore-running:
                  type: boolean
                jailmode:
                  type: boolean
                  description: 'Set to true to install the snap in jail mode. Only non-classic

                    snaps can be placed in jail mode.'
                classic:
                  type: boolean
                  description: Whether the snap uses classic confinement or not.
      responses:
        '202':
          $ref: '#/components/responses/Accepted'
        '400':
          $ref: '#/components/responses/BadRequest'
  /v2/snaps/{name}:
    parameters:
    - name: name
      in: path
      required: true
      description: The name of the snap.
      schema:
        type: string
    post:
      tags:
      - Asynchronous
      summary: Manage a specific snap
      description: Perform an action (install, refresh, remove, etc.) on a single, specific snap.
      operationId: manageSnapByName
      security:
      - PeerAuth: []
      requestBody:
        description: The action and options for the snap.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - action
              properties:
                action:
                  type: string
                  enum:
                  - install
                  - refresh
                  - remove
                  - revert
                  - enable
                  - disable
                  - switch
                  - hold
                  - unhold
                channel:
                  type: string
                  description: The channel to use for the action.
                  example: beta
                revision:
                  type: string
                  description: A specific revision to install or revert to.
                classic:
                  type: boolean
                devmode:
                  type: boolean
                purge:
                  type: boolean
                  description: If true, don't save a snapshot of data on removal.
                terminate:
                  type: boolean
                  description: If true, kill running processes before removal.
                components:
                  type: array
                  items:
                    type: string
      responses:
        '202':
          $ref: '#/components/responses/Accepted'
        '400':
          $ref: '#/components/responses/BadRequest'
  /v2/snaps/{name}/conf:
    put:
      tags:
      - Asynchronous
      summary: Set snap configuration
      description: Set the configuration details for an installed snap. Use 'system' as the name to set system options.
      operationId: setSnapConfig
      security:
      - PeerAuth: []
      parameters:
      - name: name
        in: path
        required: true
        description: The name of the snap or the reserved name 'system'.
        schema:
          type: string
      requestBody:
        required: true
        description: A JSON map of configuration keys and values. Dotted keys can be used. Use a null value to unset an option.
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
            example:
              conf-key1: conf-value1
              dotted.key: conf-value2
              key-to-unset: null
      responses:
        '202':
          description: The configuration update has been accepted and is being processed in the background.
        '400':
          $ref: '#/components/responses/BadRequest'
  /v2/snapshots:
    post:
      tags:
      - Asynchronous
      summary: Manipulate or import a snapshot
      description: Performs an action on a snapshot set, such as restoring, checking, forgetting, or importing from a data stream.
      operationId: manageSnapshots
      security:
      - PeerAuth: []
      requestBody:
        description: The action to perform. Can be a JSON object for manipulation or a binary stream for import.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Used for snapshot manipulation actions.
              required:
              - action
              - set
              properties:
                action:
                  type: string
                  enum:
                  - restore
                  - check
                  - forget
                set:
                  type: integer
                  description: The ID of the snapshot set to operate on.
                snaps:
                  type: array
                  description: An array of snap names to restrict the action to.
                  items:
                    type: string
                users:
                  type: array
                  description: An array of user names to restrict the action to (disallowed for 'forget').
                  items:
                    type: string
          application/x.snapd.snapshot:
            schema:
              type: string
              format: binary
              description: A tar archive of an exported snapshot, used only to import a snapshot with the 'import' action.
      responses:
        '202':
          $ref: '#/components/responses/Accepted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccessDenied'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    MalformedRequestError:
      type: object
      properties:
        message:
          type: string
          example: cannot decode request body into an alias action
    NoModelAssertionError:
      type: object
      description: The model assertion has not been created yet.
      properties:
        kind:
          type: string
          description: machine-readable definition of the error.
          enum:
          - assertion-not-found
        message:
          type: string
          description: Human-readable string describing the error.
          enum:
          - no model assertion yet
        value:
          type: string
          description: Value passed that triggered the error.
          enum:
          - model
    Slot:
      type: object
      description: Detailed information about a slot.
      properties:
        snap:
          type: string
          description: The name of the snap providing the slot.
        slot:
          type: string
          description: The name of the slot itself.
        interface:
          type: string
          description: The interface name for the slot.
        attrs:
          type: object
          additionalProperties: true
          description: 'A static map of the slot''s attributes.

            These are attributes that belong to the slot'
        apps:
          type: array
          items:
            type: string
          description: A list of apps associated with this slot.
        label:
          type: string
          description: The display label for the slot.
        connections:
          type: array
          items:
            $ref: '#/components/schemas/PlugRef'
          description: A list of plugs connected to this slot.
    ConfdbError:
      type: object
      description: An error occured while interacting with confdb.
      properties:
        kind:
          type: string
          description: machine-readable definition of the error.
          enum:
          - option-not-available
          - option-not-found
          - assertion-not-found
        message:
          type: string
          description: Human-readable string describing the error.
          example: 'cannot get ''ssid'' through canonical/network/wifi-setup: no data'
    Plug:
      type: object
      description: Detailed information about a plug.
      properties:
        snap:
          type: string
          description: The name of the snap providing the plug.
        plug:
          type: string
          description: The name of the plug itself.
        interface:
          type: string
          description: The interface name for the plug.
        attrs:
          type: object
          additionalProperties: true
          description: 'A static map of the plug''s attributes.

            These are attributes that belong to the plug'
        apps:
          type: array
          items:
            type: string
          description: A list of apps associated with this plug.
        label:
          type: string
          description: The display label for the plug.
        connections:
          type: array
          items:
            $ref: '#/components/schemas/SlotRef'
          description: A list of slots this plug is connected to.
    NoSerialAssertionError:
      type: object
      description: The serial assertion has not been created yet.
      properties:
        kind:
          type: string
          description: machine-readable definition of the error.
          enum:
          - assertion-not-found
        message:
          type: string
          description: Human-readable string describing the error.
          enum:
          - no serial assertion yet
        value:
          type: string
          description: Value passed that triggered the error.
          enum:
          - serial
    SlotRef:
      type: object
      description: A reference to a specific slot.
      properties:
        snap:
          type: string
          description: The name of the snap providing the slot.
        slot:
          type: string
          description: The name of the slot.
    UserNotFoundError:
      type: object
      properties:
        message:
          type: string
          example: 'cannot create user user@canonical.com: cannot find user user@canonical.com'
    PlugRef:
      type: object
      description: A reference to a specific plug.
      properties:
        snap:
          type: string
          description: The name of the snap providing the plug.
        plug:
          type: string
          description: The name of the plug.
    NoSSHKeysError:
      type: object
      properties:
        message:
          type: string
          example: 'cannot create user user@canonical.com: no ssh keys found'
    QuotaGroup:
      type: object
      description: Defines a quota group for one or more snaps.
      required:
      - group-name
      properties:
        group-name:
          type: string
          description: The name of the quota group.
          example: logmem
        subgroups:
          type: array
          items:
            type: string
          description: lists any subgroups this quota group contains.
        parent:
          type: string
          description: Contains the parent quota group name, if this group is a subgroup.
        snaps:
          type: array
          items:
            type: string
          description: Lists any snaps that belong to this quota group.
        services:
          type: string
          description: Only for a subgroup, lists specific services belonging to a snap in the parent group.
        constraints:
          type: object
          description: The types and values of limits defined for this quota group.
          properties:
            memory:
              type: integer
              format: int64
              description: Memory usage limit in bytes.
              example: 32768
            cpu:
              type: string
              description: Includes percentage as a limit.
            cpu-set:
              type: string
              description: Per-cpu limits, with cpus listing included cores.
            threads:
              type: integer
              description: Maximum number of threads for this quota group.
              example: 2
            journal:
              type: object
              description: Number of messages logged per time period.
              properties:
                size:
                  type: integer
                  format: int64
                rate-count:
                  type: integer
                rate-period:
                  type: integer
        current:
          type: object
          description: Contains the current usage of memory and task quotas
          additionalProperties: true
    NotFoundError:
      type: object
      properties:
        message:
          type: string
          example: no snapshot set with the given ID
    SnapNotInstalledError:
      type: object
      description: The snap does not exist on the system.
      properties:
        kind:
          type: string
          description: machine-readable definition of the error.
          enum:
          - snap-not-found
          - snap-not-installed
        message:
          type: string
          description: Human-readable string describing the error.
          example: no state entry for key
        value:
          type: string
          description: Value passed that triggered the error.
          example: firefox
  responses:
    AccessDenied:
      description: "Access Denied. The daemon/store cannot or will not process the request because \nthe user does not have the correct authorization from the system."
      content:
        application/json:
          schema:
            type: object
            properties:
              status-code:
                type: integer
                description: The HTTP status code.
                enum:
                - 401
              status:
                type: string
                description: The textual representation of the status code.
                enum:
                - Unauthorized
              type:
                type: string
                description: The type of response.
                enum:
                - error
              result:
                type: object
                properties:
                  kind:
                    type: string
                    description: A machine-readable string identifying the error type.
                    enum:
                    - login-required
                  message:
                    type: string
                    description: A human-readable error message.
                    enum:
                    - access denied
    BadRequest:
      description: 'Bad Request. The request could not be processed due to a client-side error.

        This can be due to malformed syntax or providing an entity that does not exist.'
      content:
        application/json:
          schema:
            type: object
            properties:
              status-code:
                type: integer
                enum:
                - 400
              status:
                type: string
                enum:
                - Bad Request
              type:
                type: string
                enum:
                - error
              result:
                oneOf:
                - $ref: '#/components/schemas/ConfdbError'
                - $ref: '#/components/schemas/MalformedRequestError'
                - $ref: '#/components/schemas/NoSSHKeysError'
                - $ref: '#/components/schemas/UserNotFoundError'
                - $ref: '#/components/schemas/SnapNotInstalledError'
    Accepted:
      description: The asynchronous request was accepted and is being processed.
      content:
        application/json:
          schema:
            type: object
            description: The response for an accepted asynchronous operation.
            properties:
              type:
                type: string
                enum:
                - async
              status-code:
                type: integer
                enum:
                - 202
              status:
                type: string
                enum:
                - Accepted
              change:
                type: string
                description: The ID of the background change that was initiated. This is a string because JSON only uses floats.
                example: '61'
              result:
                type:
                - object
                - 'null'
                description: For an accepted async operation, this is always null as the result is not yet available.
                example: null
    NotFound:
      description: 'Not Found. The requested resource could not be found.

        Can refer to either a local or remote resource'
      content:
        application/json:
          schema:
            type: object
            properties:
              status-code:
                type: integer
                enum:
                - 404
              status:
                type: string
                enum:
                - Not Found
              type:
                type: string
                enum:
                - error
              result:
                oneOf:
                - $ref: '#/components/schemas/NoModelAssertionError'
                - $ref: '#/components/schemas/NoSerialAssertionError'
                - $ref: '#/components/schemas/NotFoundError'
                - $ref: '#/components/schemas/UserNotFoundError'
                - $ref: '#/components/schemas/SnapNotInstalledError'
    Forbidden:
      description: 'Forbidden. The server understood the request but refuses to authorize it

        because the authenticated user lacks the necessary permissions for the target

        resource.'
      content:
        application/json:
          schema:
            type: object
            properties:
              status-code:
                type: integer
                enum:
                - 403
              status:
                type: string
                enum:
                - Forbidden
              type:
                type: string
                enum:
                - error
              result:
                type: object
                properties:
                  kind:
                    type: string
                    enum:
                    - auth-cancelled
                  message:
                    type: string
                    enum:
                    - cancelled
  securitySchemes:
    PeerAuth:
      type: apiKey
      in: header
      name: X-PEER-CREDENTIALS
      description: '**Unix Socket Peer Authentication**


        Authentication is not handled via traditional HTTP headers or tokens. Instead, it is managed at the operating system level using Unix domain socket peer credentials (e.g., `SO_PEERCRED` on Linux).


        **How It Works:**


        1.  The API server listens on a local Unix domain socket.

        2.  When a client connects to this socket, the server can ask the operating system kernel for the client process''s credentials.

        3.  The kernel securely provides the client''s User ID (UID), Group ID (GID), and Process ID (PID).


        Authorization decisions are then based on this trusted, kernel-provided UID. For example, access may be restricted to only the `root` user (UID 0).'
externalDocs:
  url: https://snapcraft.io/docs
  description: Snap and Snapcraft documentation