Snapd REST API

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.

As snapd development progresses, changes that are deemed backwards-compatible, such as adding methods or verbs, will not change an endpoint. Conversely, significant updates may necessitate a new endpoint being created.

The snapd REST API includes the following components:
aliases: get and modify app aliases apps: list and modify apps and their attributes
assertions: list and add assertion types changes: return the state and abort changes
configuration: get and set snap options connections: list all interface connections
find: find snaps in the store icons: retrieve the icon for an installed snap
interfaces: list interfaces and their metadata login: log user into the store
logout: logout user from the store logs: retrieve log contents
sections: request store sections snapctl: run the snapctl comment
snaps: list and manage installed snaps snapshots: manipulate, import and export snapshots
systems: list and activate recovery systems system-info: return host configuration
validation-sets: list and manage validation-sets warnings: returns snapd warnings
users: create, remove and query accounts

GET /

Reserved for human-readable content describing the service.

GET /v2/aliases

  • Description: Get the available app aliases.
  • Access: open
  • Operation: sync
  • Return: Dict containing the aliases for each snap.

Response

Example:

{
    "snap":
    {
        "alias1":
        {
            "command": "snap.app",
            "status": "auto",
            "auto": "app"
        },
        "alias2":
        {
            "command": "foo",
            "status": "manual",
            "manual": "app1"
            "manual": "app2"
        }
    }
}

The result dict is keyed by snap names. Each snap entry is a dict of aliases keyed by alias name:

   "lxd": {
      "lxc": {
        "command": "lxd.lxc",
        "status": "auto",
        "auto": "lxc"
      }
    }

Alias Fields

  • command: The full command this alias runs.
  • status: Alias status, one of auto, manual or disabled.
  • auto: the app the alias is for as assigned by an assertion (optional).
  • manual: the app the alias is for if status is manual (optional). Overrides auto.

POST /v2/aliases

  • Description: Modify aliases.
  • Access: authenticated
  • Operation: async
  • Return: background operation or standard error.

Request

Example:

{
    "action": "alias",
    "snap": "moon-buggy",
    "alias": "foo"
}

Fields

  • action: Either alias, unalias or prefer.
  • snap: Snap name to modify (optional for unalias).
  • app: App to modify (optional).
  • alias: Alias to modify.

GET /v2/apps

  • Description: List available apps.
  • Access: open
  • Operation: sync
  • Return: list of apps available

Parameters

select

Limit which apps are returned. One of:

  • service: Return only services.

names

Comma separated list of snaps to get apps for.

Response

Example:

[
    {
        "snap": "spotify",
        "name": "spotify",
        "desktop-file": "/path/to/file.desktop",
    },
   {
      "snap": "lxd",
      "name": "daemon",
      "daemon": "simple",
      "enabled": true,
      "activators": [
        {
          "Name": "unix",
          "Type": "socket",
          "Active": true,
          "Enabled": true
        }
      ]
    }
]

Fields

  • snap: the snap providing the app (optional)
  • name: the name of the app.
  • desktop-file: the desktop file for the app (optional).
  • daemon: the daemon type, if a service (optional).
  • enabled: true if an enabled service (optional).
  • active: true if an active service (optional).
  • common-id: common ID associated with this app (optional).

POST /v2/apps

  • Description: Modify attributes of applications.
  • Access: authenticated
  • Operation: async
  • Return: Background operation or standard error.

Request

Example:

{
    "action": "stop",
    "names": ["lxd"]
}

Fields

  • names: a list of names of snaps (e.g. multipass, meaning “all apps in this snap”) or apps (e.g. multipass.multipassd) to operate on. Cannot be empty.
  • action: The action to perform. Must be one of stop, start, or restart. As these actions only work for services, the names given must resolve to at least one service.
  • enable: a boolean (optional, defaults to false), when action is start, arranges to have the service start at system start.
  • disable: a boolean (optional, defaults to false), when action is stop, arranges to no longer start the service at system start.
  • reload: a boolean (optional, defaults to false), when action is restart, try to reload the service instead of restarting, if it supports it – otherwise, restart.

GET /v2/assertions

  • Description: Get the list of assertion types.
  • Access: open
  • Operation: sync
  • Return: list of assertion types

Response

Example:

 {
    "types": [
      "account",
      "account-key",
      "account-key-request",
      "base-declaration",
      "device-session-request",
      "model",
      "repair",
      "serial",
      "serial-request",
      "snap-build",
      "snap-declaration",
      "snap-developer",
      "snap-revision",
      "store",
      "system-user",
      "validation",
      "validation-set"
    ]
}

GET /v2/assertions/[assertionType]

  • Description: Get all the assertions in the system assertion database of the given type
  • Access: open
  • Operation: sync
  • Return: stream of assertions

The response is a stream of assertions separated by double newlines. The X-Ubuntu-Assertions-Count header is set to the number of returned assertions, 0 or more.

Assertions can be filtered on header values using parameters, e.g. GET /v2/assertions/account?username=canonical will return all account assertions where type=account and username=canonical.

Example:

type: account
authority-id: canonical
account-id: canonical
display-name: Canonical
timestamp: 2016-04-01T00:00:00.0Z
username: canonical
validation: certified
sign-key-sha3-384: <key>

<signature>

Note, to determine the boundary between assertions, the headers need to be decoded to check if each assertion contains a body.

Retrieve a snap-declaration assertion

An assertion type of snap-declaration can also be used to retrieve a remote snap-declaration assertion for a given snap-id. This can also be accomplished from within the snap environment:

$SNAP/usr/bin/curl -sS -X GET --unix-socket /run/snapd.socket "http://localhost/v2/assertions/snap-declaration?series=16&remote=true&snap-id=OHILDGdP7v0yZmkQnvGyXnGD5t2mZZ1g"

The above command generates output similar to the following:

type: snap-declaration
authority-id: canonical
revision: 4
series: 16
snap-id: OHILDGdP7v0yZmkQnvGyXnGD5t2mZZ1g
publisher-id: oXBKQ6XsXgTcTNVFH6NlFsTz7Epn2kvJ
snap-name: learnit
timestamp: 2016-09-05T18:41:31.767674Z
sign-key-sha3-384: BWDEoaqyr25nF5SNCvEv2v7QnM9QsfCc0PBMYD_i2NGSQ32EF2d4D0hqUel3m8ul

AcLBUgQAAQoABgUCV828WwAAI8YQAEsXwJUhIn4UGCZUQd99vcM8AYVi/Kjyh46ExiYfE198fgPG
5dmWYixeX5PeYSvfhjUF8dVc4l75nMM1nMh9USwnBOJghhl3bfJNOpmaZwW7e5/PS1Ejxjq7kl4p
9uN8h47Gk4p7wjQFu9kAow1d91hyWdwHAxbPbzW9T1X2NmUt2Wh5luFAk6RPW9GBG77ph7pREa51
WiMgK+J85/q8/s9xtjZNbl8vF+F9XY4IsR2IoudQBJSbi7xFQozUcKIuzLlDf/K7U6lgqZPQrgJE
1iMMzTU3PdtCEpEbpbPMlBOC3bXZ0Au2vWyYBebHH25IKmJT3M8E3czf/zyRQJWgE5U8ccRUM3FJ
7R2qqHsiIX8BrDe3Tj+Y72N+WdvZeLjz0M4loNk9r0yl/fLQWGRaj8LJFJk+S7J/u+wwlQblhskx
iPiStUuJSXl5hdJ8NI34i9RbpFcH4cXmJ79IYhcOe29ElxkCeytIthQBgJaFML8H33T0PVxmLn+p
tZp8IKnacrqXBxS/Eh5ToYEW5wuaNqynhalNlZD4ENSlKIV02P/WcPOgle1KIvtQfmYBsbPU4Elk
20H8FPpvBoOS8h5+m1oWPUdqwztXGK70fMqlYMtmY4qUhVRLkwg26BzlIW2VG0ZYAmyMDuWv1fq7
OHKHmYlGG/OLKomKGtqTWuVWqsGG

POST /v2/assertions

  • Description: Tries to add an assertion to the system assertion database.
  • Access: authenticated
  • Operation: sync
  • Return: 200 OK or an error

The body of the request provides the assertion to add. The assertion may also be a newer revision of a pre-existing assertion that it will replace.

To succeed the assertion must be valid, its signature verified with a known public key and the assertion consistent with and its prerequisite in the database.

Example:

POST /v2/assertions HTTP/1.1
Content-Type: application/x.ubuntu.assertion
<http-headers>

type: <type>
<assertion-headers>
sign-key-sha3-384: <key>

<signature>

GET /v2/changes/[id]

  • Description: Get the current status of a change.
  • Access: authenticated
  • Operation: sync
  • Return: Current status of change or standard error.

Response

Example:

{
    "id": "123",
    "kind": "make-lamington",
    "summary": "Make a tasty Lamington",
    "status": "Doing",
    "tasks": [
        {
            "id": "1353",
            "kind": "cut-cake",
            "summary": "Cut cake into pieces",
            "status": "Done",
            "progress":
            {
                "label": "Cutting piece",
                "done": 16,
                "total": 16
            },
            "spawn-time": "2017-01-23T12:00:44.806931498+13:00",
            "ready-time": "2017-01-23T12:00:45.001581654+13:00"
        },
        {
            "id": "1354",
            "kind": "dip",
            "summary": "Dip cake into chocolate",
            "status": "Doing",
            "progress":
            {
                "label": "Dipping piece",
                "done": 7,
                "total": 16
            },
            "spawn-time": "2017-01-23T12:00:44.806931498+13:00",
        },
        {
            "id": "1355",
            "kind": "coat",
            "summary": "Coating cake in desiccated coconut",
            "status": "Do",
            "progress":
            {
                 "label": "Coating piece",
                 "done": 0,
                 "total": 16
            },
            "spawn-time": "2017-01-23T12:00:44.806931498+13:00",
        },
    ],
    "ready": false,
    "spawn-time": "2017-01-23T12:00:44.806971766+13:00",
}

Fields

  • id: A unique ID for this change.
  • kind: A code describing what type of change this is.
  • summary: Human readable description of the change.
  • status: Summary status of the current combined task statuses (see below).
  • tasks: array of objects describing tasks in this change (optional, see below).
  • ready: true if this change has completed.
  • spawn-time: the time this change started in in RFC3339 UTC format with µs precision.
  • ready-time: the time this change completed in RFC3339 UTC format with µs precision. (omitted if not completed).
  • data: result of the change (optional, omitted until completed).
  • err: Human readable error description if transaction has failed (optional, omitted until completed).

Task Fields

  • id: A unique ID for this task.
  • kind: A code describing what type of task this is.
  • summary: Human readable description of the task.
  • status: One of the following status codes:
    • "Do" - Task ready to start.
    • "Doing" - Task in progress.
    • "Done" - Task is complete.
    • "Abort" - Task has been aborted.
    • "Undo" - Task needs to be undone.
    • "Undoing" - Task is being undone.
    • "Hold" - Task will not be run (probably due to failure of another task).
    • "Error" - Task completed with an error.
  • progress: object containing the current progress of this task. label is a human readable description of the progress, done and total are numbers showing the progress of this task.
  • spawn-time: the time this task was created in RFC3339 UTC format with µs precision.
  • ready-time: the time this task completed in RFC3339 UTC format with µs precision (omitted if not completed).

POST /v2/changes/[id]

  • Description: Abort a change in progress.
  • Access: authenticated
  • Operation: sync
  • Return: Current status of change or standard error.

Request

Example:

{
    "action": "abort"
}

Response

See return from GET.

GET /v2/changes

  • Description: Get all the changes in progress.
  • Access: authenticated
  • Operation: sync
  • Return: Current changes or standard error.

Returns an array containing all the changes that have occurred. Changes are returned in the same form as GET /v2/change/[id].

Parameters

select

Limit which changes are returned. One of:

  • all: All changes returned
  • in-progress: Only changes that are in progress are returned (default)
  • ready: Only changes that are ready

for

Optional snap name to limit results to.

GET /v2/connections

  • Description: Get all the interface connections.
  • Access: open
  • Operation: sync
  • Return: connection status of plugs and slots

Parameters

snap

Limit results to a given snap name.

select

When set to all, unconnected slots and plugs are included in the results. When unset or empty, the results include only those plugs and slots that are connected.

interface

Takes an interface name. When set, the results are limited to the selected interface.

Example

{
    "established": [
        {
            "slot": { "snap": "core", "slot": "home" },
            "plug": { "snap": "foo", "plug": "home" },
            "interface": "home",
        },
        {
            "slot": { "snap": "core", "slot": "network-control" },
            "plug": { "snap": "foo", "plug": "network-control" },
            "interface": "network-control",
            "manual": true
        }
    ],
    "undesired": [
        {
            "slot": { "snap": "core", "slot": "foo-data" },
            "plug": { "snap": "foo", "plug": "foo-data" },
            "interface": "content",
            "manual": true
        }
    ],
    "plugs": [
        {
            "snap": "foo",
            "slot": "home",
            "interface": "home",
            "connections": [
                { "snap": "core", "slot": "home" }
            ]
        },
        {
            "snap": "foo",
            "slot": "network-control",
            "interface": "network-control",
            "connections": [
                { "snap": "core", "slot": "network-control" }
            ]
        }
    ],
    "slots": [
        {
            "snap": "core",
            "slot": "home",
            "interface": "home",
            "connections": [
                { "snap": "foo", "plug": "home" }
            ]
        },
        {
            "snap": "core",
            "slot": "network-control",
            "interface": "network-control",
            "connections": [
                { "snap": "foo", "plug": "network-control" }
            ]
        }
    ]
}

Fields

  • established: Array of connections made with slots and plugs.
  • undesired: Array of connections that have been manually disconnected. These connections would otherwise be automatically made.
  • plugs: Array of connected plugs.
  • slots: Array of connected slots.

Fields for plugs / slots

  • snap: The snap this plug / slot is part of.
  • plug or slot: The name of this plug / slot.
  • interface: The interface this plug / slot uses.
  • attrs: Dict containing attributes for the interface in use. Attributes values can be of any type, e.g. boolean, strings etc.
  • label: Human readable description of plug / slot.
  • connections: List of current slots / plugs that are connected to this. Each connection contains the name of the snap and the connected slot / plug.

Connection fields

  • slot: Snap and slot name connected.
  • plug: Plug and slot name connected.
  • interface: Name of interface in use.
  • manual: Set to true if this interface was manually connected by a user.
  • gadget: Set to true if this interface was connected by the gadget snap.
  • slot-attrs: Object of slot attributes for this connection.
  • plug-attrs: Object of plug attributes for this connection.

GET /v2/find

  • Description: Find snaps in the store
  • Access: Open or authenticated
  • Operation: sync
  • Return: list of snaps in the store that match the search term and that the host system can handle

Parameters

name

Search for snaps whose name matches the given string. Can’t be used together with q . This is meant for things like autocompletion. The match is exact (i.e. find would return 0 or 1 results) unless the string ends in * .

q

Search for snaps that match the given string. Spaces between words are treated as logical AND operators. This is a weighted broad search, meant as the main interface to searching for snaps.

scope

If set to wide, the search results are broadened to include non-stable packages.

section

Section in the store to search. Use GET /v2/sections to get the names of the sections.

select

Alter the collection searched:

  • refresh: search refreshable snaps. Can’t be used with q, nor name.
  • private: search private snaps (by default, find only searches public snaps). Can’t be used with name, only q (for now at least).

snap-id

Search for snaps using the snap-id (formally common ID) snap app attribute.

Example

Request

http://localhost/v2/find\?q\=libreoffice | jq

Response

[
    {
      "id": "CpUkI0qPIIBVRsjy49adNq4D6Ra72y4v",
      "title": "LibreOffice",
      "summary": "LibreOffice is a powerful office suite including word processing and creation of spreadsheets, slideshows and databases",
      "description": "LibreOffice is a powerful and free office suite, used by millions of people around the world. Its clean interface and feature-rich tools help you unleash your creativity and enhance your productivity. LibreOffice includes several applications that make it the most versatile Free and Open Source office suite on the market: Writer (word processing), Calc (spreadsheets), Impress (presentations), Draw (vector graphics and flowcharts), Base (databases), and Math (formula editing).",
      "download-size": 436375552,
      "icon": "https://dashboard.snapcraft.io/site_media/appmedia/2016/06/LibreOffice-Initial-Artwork-Logo.png",
      "name": "libreoffice",
      "publisher": {
        "id": "canonical",
        "username": "canonical",
        "display-name": "Canonical",
        "validation": "verified"
      },
      "store-url": "https://snapcraft.io/libreoffice",
      "developer": "canonical",
      "status": "available",
      "type": "app",
      "base": "core18",
      "version": "6.4.4.2",
      "channel": "stable",
      "ignore-validation": false,
      "revision": "180",
      "confinement": "strict",
      "private": false,
      "devmode": false,
      "jailmode": false,
      "contact": "https://bugs.launchpad.net/ubuntu/+source/libreoffice/+bugs?field.tag=snap",
      "license": "MPL-2.0",
      "common-ids": [
        "libreoffice-draw.desktop",
        "libreoffice-impress.desktop",
        "libreoffice-writer.desktop",
        "libreoffice-math.desktop",
        "libreoffice-calc.desktop",
        "libreoffice-base.desktop"
      ],
      "website": "https://code.launchpad.net/~libreoffice/+git/libreoffice-snap",
      "media": [
        {
          "type": "icon",
          "url": "https://dashboard.snapcraft.io/site_media/appmedia/2016/06/LibreOffice-Initial-Artwork-Logo.png"
        },
        {
          "type": "banner",
          "url": "https://dashboard.snapcraft.io/site_media/appmedia/2019/12/LibreOffice-Banner_1IRAqHI.png",
          "width": 2100,
          "height": 700
        },
        {
          "type": "screenshot",
          "url": "https://dashboard.snapcraft.io/site_media/appmedia/2019/09/Screenshot-01-New-EN.png",
          "width": 1082,
          "height": 651
        },
        {
          "type": "screenshot",
          "url": "https://dashboard.snapcraft.io/site_media/appmedia/2019/09/Screenshot-04-New-EN.png",
          "width": 1080,
          "height": 648
        },
        {
          "type": "screenshot",
          "url": "https://dashboard.snapcraft.io/site_media/appmedia/2019/09/Screenshot-05-New-EN.png",
          "width": 1080,
          "height": 647
        },
        {
          "type": "screenshot",
          "url": "https://dashboard.snapcraft.io/site_media/appmedia/2019/09/Screenshot-06-New-EN.png",
          "width": 1080,
          "height": 647
        },
        {
          "type": "screenshot",
          "url": "https://dashboard.snapcraft.io/site_media/appmedia/2019/09/Screenshot-07-New-EN.png",
          "width": 1081,
          "height": 647
        }
      ],
      "install-date": "2020-06-02T17:25:50.864197657+01:00"
    }
]

Fields

  • base: the base snap this snap relies on (optional)
  • channel: the channel this snap is from.
  • channels: available channels to download. See below for fields. (only returned for searches with name parameter).
  • common-ids: common IDs used by the apps in this snap.
  • confinement: the confinement requested by the snap itself; one of strict, classic or devmode.
  • contact: the method of contacting the developer.
  • description: snap description.
  • developer: developer who created the snap (deprecated, use username from publisher instead).
  • download-size: how big the download will be in bytes.
  • epoch: the epoch of the application release. See Snap epochs for details.
  • icon: a url to the snap icon, possibly relative to this server.
  • id: unique ID for this snap.
  • license: an SPDX license expression.
  • name: the snap name.
  • private: true if this snap is only available to its author.
  • publisher: publisher information, made up of an id, username and display-name.
  • released-at: date when app was released.
  • resource: HTTP resource for this snap.
  • revision: a number representing the revision, as a base 10 string.
  • media: JSON array of media for this snap with each element consisting of a type , url and potentially a width and height for image media
         {
       "type": "icon",
       "url": "https://dashboard.snapcraft.io/site_media/appmedia/2016/06/LibreOffice-Initial-Artwork-Logo.png"
     },
     {
       "type": "banner",
       "url": "https://dashboard.snapcraft.io/site_media/appmedia/2019/12/LibreOffice-Banner_1IRAqHI.png",
       "width": 2100,
       "height": 700
     }

Channel Fields

  • channel: the channel this snap is from.
  • confinement: the confinement requested by the snap itself; one of strict, classic or devmode.
  • epoch: ?. Must be in the form of an integer.
  • released-at: date this revision was released into the channel in RFC3339 UTC format.
  • revision: a number representing the revision in this channel, as a base 10 string.
  • size: how big the download will be in bytes.
  • version: a string representing the version in this channel.

GET /v2/icons/[name]/icon

  • Description: Get an icon from a snap installed on the system. The response will be the raw contents of the icon file; the content-type will be set accordingly and the Content-Disposition header will specify the filename.

    This fetches the icon from the snap itself.

  • Access: open

This is not a standard return type.

GET /v2/interfaces

  • Description: Get the available interfaces and associated metadata.
  • Access: authenticated
  • Operation: sync
  • Return: an array of interface information

Parameters

select

Set to all to retrieve all interfaces, or connected to only return connected interfaces (if this parameter is omitted then the call returns the legacy format that should be no longer used).

slots

If true, then slot information is returned.

plugs

If true, then plug information is returned.

doc

If true then interface documentation is returned.

names

If given, then only interfaces that match the comma separated names are returned.

Example:

[
    {
        "name": "content",
        "summary": "allows sharing code and data with other snaps"
        "plugs": [
            { "snap": "foo", "plug": "foo-data" }
        ]
    },
    {
        "name": "home",
        "summary": "allows access to non-hidden files in the home directory",
        "plugs": [
            { "snap": "foo", "plug": "home" }
        ]
    },
    {
        "name": "network-control",
        "summary": "allows configuring networking and network namespaces"
        "plugs": [
            { "snap": "foo", "plug": "network-control" }
        ]
    }
]

Fields

  • name: Name of interface.
  • summary: Human-readable summary of interface (optional).
  • doc-url: URL to further documentation (optional).
  • plugs: Plugs using this interface (only if using plugs=true).
  • slots: Plugs using this interface (only if using slots=true).

POST /v2/interfaces

  • Description: Issue an action to the interface system.
  • Access: authenticated
  • Operation: async
  • Return: Background operation or standard error.

Example:

{
    "action": "connect",
    "slots": [{"snap": "canonical-pi2",   "slot": "pin-13"}],
    "plugs": [{"snap": "keyboard-lights", "plug": "capslock-led"}]
}

Fields

  • action: Action to perform, either "connect" or "disconnect".
  • plugs: Array of plugs to connect. Each plug is referred to by the snap it is part of and the name of the plug.
  • slots: Array of slots to connect to. Each slot is referred to by the snap it is part of and the name of the slot.

POST /v2/login

  • Description: Log user in the store.
  • Access: root
  • Operation: sync
  • Return: Dict with the authenticated user information or error.

Request

Example:

{
     "email": "foo@bar.com",
     "password": "swordfish",
     "otp": "123456"
}

Fields

  • email: The email address being logged in with. This must be a valid email address (also supported with legacy username field).
  • password: Password for this account.
  • otp: One time password for this account (optional). This field being wrong will generate the two-factor-required or two-factor-failed errors.

Response

Example:

{
    "id": 1,
    "username": "user1",
    "email": "user1@example.com",
    "macaroon": "serialized-store-macaroon",
    "discharges": ["discharge-for-macaroon-authentication"]
}

Fields

  • id: Unique ID for this user account.
  • email: Email address associated with this account.
  • username: Local username associated with this account (optional).
  • macaroon: Serialized macaroon to be passed back in the HTTP Authorization header.
  • discharges: Array of serialized discharges to be passed back in the HTTP Authorization header.

POST /v2/logout

  • Description: Log user out of the store.
  • Access: authenticated
  • Operation: sync
  • Return: 200 OK or an error.

GET /v2/logs

  • Description: Get log contents.
  • Access: open
  • Operation: sync
  • Return: A sequence of log messages.

Parameters

n

Number of entries to return or all for all entries. Defaults to 10 entries.

follow

If set then returns log entries as they occur.

Response

Example:

HTTP/1.1 200 OK
Content-Type: application/json-seq
<http-headers>

<0x1E>{"timestamp":"2017-11-06T02:13:29.707407Z","message":"Thing occurred","sid":"service1","pid":"1000"}
<0x1E>{"timestamp":"2017-11-06T02:13:29.708319Z","message":"Other thing occurred","sid":"service1","pid":"1000"}

GET /v2/sections

  • Description: Get the store sections.
  • Access: open
  • Operation: sync
  • Return: An array containing the store section names.

Response

Example:

[
   "featured",
   "database",
   "ops",
   "messaging",
   "media",
   "internet-of-things"
]

POST /v2/snapctl

  • Description: Run snapctl command.
  • Access: authenticated
  • Operation: sync
  • Return: Command output or standard error.

Request

Example:

{
    "context-id": "ABCDEF",
    "args": [ "get", "username" ]
}

Fields

  • context-id: Context for this call.
  • args: Arguments to snapctl.

Response

Example:

{
    "stdout": "username",
    "stderr": ""
}

Fields

  • stdout: Data written to stdout from snapctl command.
  • stderr: Data written to stderr from snapctl command.

GET /v2/snaps

  • Description: List installed snaps.
  • Access: open
  • Operation: sync
  • Return: list of snaps installed on the system, as for /v2/find.

Parameters

select

Filter snaps to return information about:

  • all: show all snap revisions installed.
  • enabled: show only revisions of snaps that are active (default).

snaps

Return only information for the given snaps. Snap names are separated by commas.

Response

Example:

[{
      "apps": [{"name": "moon-buggy"}]
      "channel": "stable"
      "confinement": "strict"
      "description": "Moon-buggy is a simple character graphics game, where you drive some kind of car across the moon's surface.  Unfortunately there are dangerous craters there.  Fortunately your car can jump over them!\r\n",
      "developer": "dholbach",
      "devmode": false,
      "icon": "",
      "id": "2kkitQurgOkL3foImG4wDwn9CIANuHlt",
      "install-date": "2016-05-17T09:36:53+12:00",
      "installed-size": 90112,
      "license": "GPL-2.0+",
      "name": "moon-buggy",
      "private": false,
      "resource": "/v2/snaps/moon-buggy",
      "revision": "11",
      "status": "active",
      "summary": "Drive a car across the moon",
      "trymode": false,
      "type": "app",
      "version": "1.0.51.11"
    }, {
      "summary": "The ubuntu-core OS snap",
      "description": "A secure, minimal transactional OS for devices and containers.",
      "icon": "",                  // core might not have an icon
      "installed-size": 67784704,
      "install-date": "2016-03-08T11:29:21Z",
      "name": "core",
      "developer": "canonical",
      "resource": "/v2/snaps/ubuntu-core",
      "status": "active",
      "type": "core",
      "update-available": 247,
      "version": "241",
      "revision": 99,
      "channel": "stable",
}]

Fields

In addition to the fields described in /v2/find:

  • apps: JSON array of apps the snap provides. See below for fields.
  • broken: a string describing if this snap is not working (optional).
  • devmode: true if the snap is currently installed in development mode.
  • installed-size: how much space the snap itself (not its data) uses.
  • install-date: the date and time when the snap was installed in RFC3339 UTC format.
  • jailmode: true if the app is currently installed in jail mode.
  • mounted-from: path the snap is mounted from, which is a .snap file for installed snaps and a directory for snaps in try mode.
  • status: can be either installed or active (i.e. is current).
  • tracking-channel: the channel updates will be installed from.
  • trymode: true if the app was installed in try mode.

furthermore, channels, download-size, screenshots and tracks cannot occur in the output of /v2/snaps.

App Fields

  • name: Name of the app, i.e. the name of the executable.
  • aliases: A list of alias names for this app (optional).
  • common-id: A common ID associated with this app (optional).
  • daemon: The type of daemon this app is. One of “simple”, “forking”, “oneshot”, “dbus” or “notify” (optional, only applicable for daemons).
  • desktop-file: Path to desktop file for this app (optional).

POST /v2/snaps

  • Description: Install, refresh, revert, remove, hold, unhold, enable, disable, switch or snapshot snaps.
  • Access: authenticated
  • Operation: async
  • Return: Background operation or standard error.

Store Request

Example:

{
    "action": "refresh",
    "snaps": ["moon-buggy"]
}

Fields

  • action: Either install, refresh, remove, revert, hold, unhold, enable, disable or switch.
  • snaps: Array of snap names to perform action on (optional, interpreted as all snaps if not present for a refresh).
  • transaction: Optional string field, defaulting to per-snap if not present. If all-snaps is used, the action field will be performed such that the corresponding change will have a single transaction covering all the snaps. If in this case there is a failure for any snap, the state of all afected snaps will be fully reverted, even if for some snap the action has been successful. This field is valid for install and refresh actions. See Transactional updates for more details.
  • system-restart-immediate: If true, makes any system restart, needed by the action, immediate and without delay (requires snapd 2.52).

Hold only

The hold action holds, or postpones, snap updates for individual snaps, or for all snaps on the system, either indefinitely or for a specified period of time.

Requires snapd 2.58+.

Fields

  • hold-level: general or auto-refresh to target specific snap refreshes or automatic updates respectively.
  • time: Instant until which the refresh is held. Specified either in RFC3339 format or forever to postpone updates indefinitely. Time instants are always accepted even if they have already passed.

Similar functionality is provided by the snap refresh --hold command.

Sideload Request

Snaps can be sideloaded by passing the snap content in a multipart/form-data request with one or more files named “snap”.

Example:

POST /v2/snaps HTTP/1.1
Host:
Content-Type: multipart/form-data; boundary=foo
Content-Length: 20638

--foo
Content-Disposition: form-data; name="devmode"

true
--foo
Content-Disposition: form-data; name="snap"; filename="hello-world_27.snap"

<20480 bytes of snap file data>
--foo
Content-Disposition: form-data; name="snap"; filename="other-snap_1.snap"

<20480 bytes of snap file data>
--foo

The following fields are supported:

  • action: The action to perform, either install or try (optional, defaults to install).
  • classic: Put snaps in classic mode and disable security confinement if true (optional).
  • dangerous: Install the given snap files even if there are no pre-acknowledged signatures for them, meaning they are not verified and could be dangerous if true (optional, implied by devmode).
  • devmode: Put snaps in development mode and disable security confinement if true (optional).
  • jailmode: Put snaps in enforced confinement mode if true (optional).
  • system-restart-immediate: If true, makes any system restart, needed by the action, immediate and without delay (requires snapd 2.52).
  • snap: The contents of a snap file. Note that filename is required to be set but the value is not used. Content-Type is not required, but recommended. (optional, required if action is install)
  • snap-path: Directory to install in try mode (optional, required if action is try).

Snapshot creation

Example:

{
    "action": "snapshot",
    "snaps": ["snap1", "snap2"],
    "users": ["user1", "user1]
}

Fields

  • action: snapshot
  • snaps: Array of snap names whose data should be snapshotted.
  • users: Array of user names to whom snapshots are to be restricted (optional).

Result:

{
                "result": {"set-id": 42},
                "change": "999",
                "status-code": 202,
                "type": "async"
}

GET /v2/snaps/[name]

  • Description: Details for an installed snap.
  • Access: open
  • Operation: sync
  • Return: Snap details (as in /v2/snaps).

POST /v2/snaps/[name]

  • Description: Install, refresh, remove, revert, enable or disable.
  • Access: authenticated
  • Operation: async
  • Return: Background operation or standard error.

Request

Example:

{
    "action": "install",
    "channel": "beta"
}

Fields

  • action: Either install, refresh, remove, revert, enable, disable or switch.
  • channel: From which channel to pull the new package (and track henceforth). Channels are a means to discern the maturity of a package or the software it contains, although the exact meaning is left to the application developer. One of edge, beta, candidate, and stable which is the default. (optional, only applicable when action is install or refresh).
  • classic: Put snap in classic mode and disable security confinement if true (optional, only applicable with action set to install, refresh, revert).
  • devmode: Put snap in development mode and disable security confinement if true (optional, only applicable with action set to install, refresh, revert).
  • ignore-validation: Ignore validation by other snaps blocking the refresh if true (optional, only applicable with action set to refresh).
  • jailmode: Put snap in enforced confinement mode if true (optional, only applicable with action set to install, refresh, revert).
  • revision: Revision to install (optional, only applicable with action set to install, refresh or revert).
  • purge: Don’t save a snapshot with the snap’s data when removing if set to true (optional, only applicable with action set to remove).
  • system-restart-immediate: Make any system restart needed by the action immediate without delay if true (requires snapd 2.52).

GET /v2/snaps/[name]/conf

  • Description: Configuration details for an installed snap.
  • Access: authenticated
  • Operation: sync
  • Return: JSON map of configuration keys and values.

name can be the reserved name system to get system options.

Parameters

keys

Request the configuration values corresponding to the specific keys (comma-separated); dotted keys can be used to retrieve nested values .

PUT /v2/snaps/[name]/conf

  • Description: Set the configuration details for an installed snap.
  • Access: authenticated
  • Operation: async
  • Return: Background operation or standard error.

name can be the reserved name system to set system options.

Request

Example:

{
    "conf-key1": "conf-value1",
    "conf-key2": "conf-value2"
}

Keys can be dotted, the null value can be used to unset configuration options.

GET /v2/snapshots

  • Description: Get a list of snapshots
  • Access: open
  • Operation: sync
  • Return: List containing metadata for stored snapshots

Returns an array containing all the snapshot metadata stored on the system.

Response

Example:

{
  "type": "sync",
  "status-code": 200,
  "status": "OK",
  "result": [
    {
      "id": 40,
      "snapshots": [
        {
          "set": 40,
          "time": "2020-12-16T11:52:00.689328169Z",
          "snap": "<snap-name>",
          "revision": "x2",
          "epoch": {
            "read": [
              0
            ],
            "write": [
              0
            ]
          },
          "summary": "",
          "version": "6.0",
          "sha3-384": {
            "archive.tgz": "31fcc9cce5b5cdc68aeb38e3ef3866f00174dba158bce23870962b7dee12c1ec49a434346f6e8c7a1209858fb95e8020",
            "user/<username>.tgz": "e19ab68a4aef50468667b873aefa83813919851b931b60782b0d8e4d6d12021402c757002ba3738855ed9e8da1268c50"
          },
          "size": 846235
        }
      ]
    }
  ]
}

GET /v2/snapshots/<set-id>/export

  • Description: Exports the snapshot with given set-id
  • Access: authenticated
  • Operation: sync
  • Return: stream of snapshot data

The set-id is the snapshot identifier retrieved either from the ‘snap saved’ command or GET /v2/snapshots.

The response has Content-Type: application/x.snapd.snapshot and Content-Length headers, plus the data stream which contains an uncompressed tar archive containing multiple zip files inside (one zip file for every snap included in the snapshot). The details of stream format might change, it is mainly intended for importing via POST /v2/snapshots.

POST /v2/snapshots

  • Description: Manipulate snapshots or import a snapshot
  • Access: authenticated
  • Operation: see each operation category
  • Return: see each operation category

Snapshots based on current installed snap data are created via POST /v2/snaps.

Snapshot manipulation

  • Description: Restore, check or forget a snapshot
  • Access: authenticated
  • Operation: async
  • Return: Background operation or standard error.

Example:

{
   "action": "restore",
   "set": 35,
   "snaps": ["snap1"],
   "users":  ["user1"],
}

Fields

  • action: Either restore, check or forget.
  • set: The id of the snapshot set to operate on.
  • snaps: Array of snap names to restrict the action to (optional).
  • users: Array of user names to restrict the action to (only for restore, optional).

Snapshot import

  • Operation: sync
  • Return: The set-id of the imported snapshot and names of the snaps

Request headers:

Content-Type: application/x.snapd.snapshot Content-Length: <size of the imported snapshot>

The request body should contain the snapshot data (i.e. a tar archive of an exported snapshot).

Response

Example:

{
 "type": "sync",
 "result": {
      "set": 42,
        "snaps": [
         "foo",
         "bar" 
      ]
  }
}

GET /v2/system-info

  • Description: Server configuration and environment information.
  • Access: open
  • Operation: sync
  • Return: Dict with the operating system’s key values.

Response

Example:

{
    "series": "16",
    "version": "2.0.17",
    "os-release": {
        "id": "ubuntu",
        "version-id": "17.04"
    },
    "on-classic": true,
    "managed": false,
    "kernel-version": "4.10.0-15-generic"
    "locations": {
        "snap-mount-dir": "/snap",
        "snap-bin-dir": "/snap/bin"
    },
    "refresh": {
        "last": "2018-06-26T08:45:00+12:00",
        "next": "2018-06-26T16:43:00+12:00",
        "timer": "00:00~24:00/4"
    },
    "confinement": "strict",
    "build-id": "efdd0b5e69b0742fa5e5bad0771df4d1df2459d1"
}

Fields

  • series: The core series in use.
  • version: The version of snapd.
  • os-release: Object containing release information as sourced from /etc/os-release. Contains id which is a unique ID for each OS and version-id which is a string describing the version of this OS.
  • on-classic: true if not running on a fully snap managed system.
  • managed: true if able to manage user accounts (?).
  • kernel-version: version of the kernel on this system.
  • store: the name of the store being used (optional, omitted if using the standard store).
  • locations: dict containing directory locations used by snapd (see below).
  • refresh: dict containing refresh times (optional, see below).
  • confinement: the level of confinement the system supports; either strict or partial.
  • build-id: a unique ID for this build of snapd.

Location fields

  • snap-mount-dir: directory where snaps are mounted in.
  • snap-bin-dir: directory where snap apps are run from.

Refresh fields

  • last: last time a refresh was performed (optional).
  • next: next time a refresh will be performed.
  • hold: time that refreshes will be applied (optional, if missing then applied immediately).
  • timer: times that updates are checked for.
  • schedule: schedule that updates are being checked with (legacy, replaced with timer).

GET /v2/systems

  • Description: Get the list of recovery systems
  • Access: open
  • Operation: sync
  • Return: list of recovery systems

Response

"systems": [
            {
                "actions": [
                    {
                        "mode": "install",
                        "title": "Reinstall"
                    },
                    {
                        "mode": "recover",
                        "title": "Recover"
                    },
                    {
                        "mode": "factory-reset",
                        "title": "Factory reset"
                    },
                    {
                        "mode": "run",
                        "title": "Run normally"
                    }
                ],
                "brand": {
                    "display-name": "Canonical",
                    "id": "canonical",
                    "username": "canonical",
                    "validation": "verified"
                },
                "current": true,
                "label": "20220518",
                "model": {
                    "brand-id": "canonical",
                    "display-name": "ubuntu-core-22-pi-arm64-dangerous",
                    "model": "ubuntu-core-22-pi-arm64-dangerous"
                }
            }
        ]

Fields

  • current: Current is true when the system running now was installed from this recovery system seed.
  • label: The label for this recovery system.
  • model: The model assertion information associated with this recovery system.
  • brand: The brand information associated with the model that this recovery system has.
  • actions: Actions available for this system.

Model assertion information fields

  • model: The model name from the model assertion.
  • brand-id: The brand-id from the model assertion.
  • display-name: The display name of the model from the model assertion.

Brand information fields

  • username: The username of the brand from the account assertion.
  • id: The account-id of the brand account assertion.
  • display-name: The display name of the brand from the account assertion.
  • validation: The validation status from the brand account assertion (see the brand account assertion docs for the valid values of this).

Action fields

  • mode: The mode that the system transitions to when executing the given action.
  • title: A user presentable description of taking this action.

POST /v2/systems

  • Description: Attempt to perform an action with the current active recovery system
  • Access: root
  • Operation: sync
  • Return: 200 OK or an error

Example response:

{
    "action": "do",
    "mode": "recover"
}

{
    "action": "do",
    "mode": "install",
}

{
    "action": "reboot",
    "mode": "run"
}

{
    "action": "do",
    "mode": "factory-reset"
}

Fields

  • action: Action to perform, which is either “reboot” or “do”. The “reboot” action will always reboot the device to the specified mode, even if the specified system and mode are the current system and mode.

    The “do” action is meant to consume fields of an action as provided in the actions list under the system in the response from a GET request to /v2/systems. Currently “mode” is the only such field, but there may be more fields added that correspond to additional details about the action that can be taken with the system. If the “do” action is provided for the current system and the current mode then no action is taken. For the current active recovery system, specifying a different mode from the current mode (and no other additional fields are specified with “do”), the actions “do” or “reboot” are equivalent.

  • mode: The mode to transition to. Modes “run” and “recover” are only available for the current active recovery system. The “install” and “factory-reset” modes are always available for all recovery systems and will trigger either a full system install or a re-initialisation of the device to its factory state, with both modes deleting all user and system data.

    See Recovery modes for more details on each supported recovery mode, what they do, and how they can be used.

POST /v2/systems/<system-label>

  • Description: Attempt to perform an action with the specified recovery system, identified by its label.
  • Access: root
  • Operation: sync
  • Return: 200 OK or an error
  • Same fields and usage as POST to /v2/systems/

GET /v2/users

  • Description: Get information on user accounts.
  • Access: root
  • Operation: sync
  • Return: Array of user account information.

Response

Example:

[
    {
        "email": "first-name.last-name@example.com",
        "id": 1,
        "username": "lp-username2"
    },
    {
        "email": "other.name@example.com",
        "id": 2,
        "username": "user2"
    },
]

Fields

  • email: Email address associated with this account.
  • id: Unique ID for this user account.
  • username: Local username associated with this account (optional).

POST /v2/users

  • Description: Create or remove local users
  • Access: root
  • Operation: sync
  • Return: List of objects with the created user details

Request

Example:

{
    "action": "create",
    "username": "demo_user",
    "email": "demo@exampledomain.com",
    "sudoer": false
}

Fields

  • action: action to perform, either “create” or “remove”.
  • email: the email of the user to create or remove.
  • username: the username of the user to create or remove.
  • sudoer: if true, adds “sudo” access to a created user.
  • known: if true, use the local system-user assertions to create the user (see assertions.md for details about the system-user assertion).
  • force-managed: force adding the user even if the device is already managed.
  • automatic: if true, permits managed devices to create users via the API without generating an error. The system.users.create.automatic system option also needs to be set to false.

As a special case: if email is empty and known is set to true, the command will create users for all system-user assertions that are valid for this device.

Response

Example:

[
    {
        "username": "mvo",
        "ssh-keys": ["key1","key2"]
    }
]

Fields

  • id: the id of the user
  • username: the username of the user.
  • ssh-keys: a list of strings with the ssh keys that got added.

GET /v2/validation-sets

  • Description: Get all enabled validation sets
  • Access: authenticated
  • Operation: sync
  • Return: list of validation sets

Response

Example:

[
                {
            "account-id": "xSfWAGdL56BoQxuuvIM90pbFNMq23t1f",
            "name": "bar",
            "mode": "monitor",
            "pinned-at": 2,
            "sequence": 3,
            "valid": false
        },
                {
            "account-id": "xSfWAGdL56BoQxuuvIM90pbFNMq23t1f",
            "name": "baz",
            "mode": "enforce",
            "sequence": 1,
            "valid": true
        }
]

Fields

  • account-id: identifier for the developer account (creator of the validation-set).
  • name: name of the validation set.
  • mode: mode of the validation set in the system, either “monitor” or enforce".
  • pinned-at: only set (greater than 0) if the validation set is pinned at a specific sequence number.
  • sequence: current sequence value of the validation set assertion.
  • valid: reports whether the validation set is valid for the currently installed snaps.

GET /v2/validation-sets/[account-id]/[name]

  • Access: authenticated
  • Operation: sync
  • Return: either a single validation-set dict, or an error

Response

Example:

{
     "account-id": "xSfWAGdL56BoQxuuvIM90pbFNMq23t1f",
     "name": "bar",
     "mode": "monitor",
     "pinned-at": 2,
     "sequence": 3,
     "valid": false
},

For a description of the fields returned by this request, see GET /v2/validation-sets above.

POST /v2/validation-sets/[account-id]/[name]

  • Access: authenticated
  • Operation: sync
  • Return: 200 OK or an error

Request

Example:

{
    "action": "apply",
    "mode": "monitor"
    "sequence": 3
}

Fields

  • action: action to perform. Must be either “apply” or “forget”.
  • mode: only for the “apply” action. This specified the mode to enable for the validation-set. Can be either “monitor” or “enforce”.
  • sequence: an optional sequence number to pin at with “apply”. If passed with “forget”, then the validation set will only be forgotten if it is pinned at the given sequence (404 error will be returned if pinned at a different sequence).

GET /v2/warnings

  • Description: Get the warnings in snapd.
  • Access: open
  • Operation: sync
  • Return: List containing the warning messages

Response

Example:

[
    {
        "message": "hello world",
        "first-seen": "2017-01-23T12:00:44.806931498+13:00",
        "last-seen": "2017-01-23T12:00:44.806931498+13:00"
    },
    {
        "message": "hello again",
        "first-seen": "2017-01-23T12:00:44.806931498+13:00",
        "last-seen": "2017-01-23T12:00:44.806931498+13:00",
        "delete-after": "1h30m"
    },
]

Warning Fields

  • message: Message for this warning.
  • first-seen: The first time one of these messages was created in RFC3339 UTC format.
  • last-seen: The last time one of these messages was created in RFC3339 UTC format.
  • last-shown: The last time one of these messages was shown to the user in RFC3339 UTC format (optional).
  • delete-after: How much time since one of these was last seen should we drop the message (optional).
  • repeat-after: How much time since one of these was last shown should we repeat it (optional).

The durations are in the form “72h3m0.5s” or “1us” or “1ns”.

POST /v2/warnings

  • Description: Respond to warnings.
  • Access: authenticated
  • Operation: sync
  • Return: 200 OK or an error.

Request

Example:

{
    "action": "okay",
    "timestamp": "2017-01-23T12:00:44.806931498+13:00"
}

Fields

  • action: Must be okay.
  • timestamp: time to clear warnings before in RFC3339 UTC format.

Last updated 4 days ago.

Help improve this document in the forum.