API docs by Redocly

Snapd REST API (0.1)

Download OpenAPI specification:

License: GPL-3.0

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.

Snap and Snapcraft documentation

Assertions

List and add assertion types.

Get the list of assertion types

Retrieves a list of all known assertion types in the system.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

Attempt to add or replace an assertion

Requires a valid assertion with a signature signed by a verifiable public key. The body of the request provides the assertion to add. If replacing an existing assertion the new must be consistent with and its prerequisite.

Authorizations:
PeerAuth
Request Body schema: application/x.ubuntu.assertion
required

The raw assertion text to add to the database.

string <binary>

A raw assertion string.

Responses

Response samples

Content type
application/json
{
  • "status-code": 400,
  • "status": "Bad Request",
  • "type": "error",
  • "result": {
    }
}

Get assertions of a given type

Get all the assertions in the system assertion database of the given type. Assertions can be filtered by providing assertion header keys as query parameters (e.g., ?username=canonical). The response is a stream of assertions separated by double newlines. 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.

path Parameters
assertion-type
required
string
Example: account

The type of assertion to retrieve.

query Parameters
remote
boolean
Default: false

When using remote, a primary key must be associated with the request assertion type. These mappings are as below account -> account-id account-key -> public-key-sha3-384 base-declaration -> series confdb-schema -> account-id AND name model -> series AND brand-id AND model preseed -> series AND brand-id AND model AND system_label repair -> brand-id AND repair-id serial -> brand-id AND model AND serial snap-build -> snap-sha3-384 snap-declaration -> series AND snap-id snap-developer -> snap-id AND publisher-id snap-resource-revision -> snap-id AND resource-name AND resource-sha3-384 AND provenance snap-resource-pair -> snap-id AND resource-name AND resource-revision AND snap-revision AND provenance snap-revision -> snap-sha3-384 AND provenance store -> store system-user -> brand-id AND email validation -> series AND snap-id AND approved-snap-id AND approved-snap-revision validation-set -> series AND account-id AND name AND sequence

Some assertion types do not have a definite authority set account-key-request -> public-key-sha3-384 confdb-control -> brand-id AND model AND serial device-session-request -> brand_id AND model AND serial serial-request - N/A

json
boolean
Default: false

If true, the response is formatted as a JSON object containing the headers of the assertions instead of the default signed assertion stream format.

Responses

Response samples

Content type
No sample

Get the active model assertion

Retrieves the active model assertion for the system. The model assertion describes a snap-based device.

Read more about model assertions on the Ubuntu Core documentation.

Responses

Response samples

Content type
application/json
{
  • "status-code": 404,
  • "status": "Not Found",
  • "type": "error",
  • "result": {
    }
}

Replace the model assertion

Replaces the current model assertion, potentially triggering a remodel of the system.

The endpoint accepts two different content types depending on the use case:

  • application/json: For a standard (online) remodel where the system will fetch required snaps from the store.
  • multipart/form-data: For an offline remodel, where the new model assertion and all required snaps and other files are provided directly in the request.
Read more about offline remodeling on the Ubuntu Core documentation.
Authorizations:
PeerAuth
Request Body schema:
required

The new model assertion and, for offline remodels, any required files (snaps, etc.).

assertion
required
string

A string containing the full, signed model assertion.

Responses

Request samples

Content type
{
  • "assertion": "type: model\nauthority-id: generic\nseries: 16\nbrand-id: generic\nmodel: generic-classic\nclassic: true\ntimestamp: 2025-10-03T10:40:00.0Z\nsign-key-sha3-384: d-JcZF9nD9eBw7bwMnH61x-bklnQOhQud1Is6o_cn2wTj8EYDi9musrIT9z2MdAa\nAcLBXAQAAQ[...]"
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Get the current serial assertion

Retrieves the current serial assertion for the system. The serial assertion is a statement used to bind a device identity to it's public key, provided by the store.

Read more about serial assertions on the Ubuntu Core documentation.

Responses

Response samples

Content type
application/json
{
  • "status-code": 404,
  • "status": "Not Found",
  • "type": "error",
  • "result": {
    }
}

Perform an action on the serial assertion

Performs an asynchronous action on the current serial assertion by sending a JSON command. The only supported action is forget, which causes the system to unregister its current serial and prepare for a new one.

Read more about offline remodeling on the Ubuntu Core documentation.
Authorizations:
PeerAuth
Request Body schema: application/json
required

A JSON object specifying the action to perform on the serial.

action
required
string
Value: "forget"

The action to perform on the serial assertion.

no-registration-until-reboot
boolean
Default: false

If true, delays device registration until the next reboot.

Responses

Request samples

Content type
application/json
{
  • "action": "forget",
  • "no-registration-until-reboot"": true
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Asynchronous

Return the reference to a change that will occur in the background.

Modify aliases

Modify aliases by performing an 'alias', 'unalias', or 'prefer' action.

Authorizations:
PeerAuth
Request Body schema: application/json
required

The action to perform on an alias.

action
required
string
Enum: "alias" "unalias" "prefer"

The action to perform on the alias.

snap
string

The snap name to modify (optional for unalias).

app
string

The app to modify (optional).

alias
required
string

The alias to modify.

Responses

Request samples

Content type
application/json
{
  • "action": "alias",
  • "snap": "moon-buggy",
  • "app": "string",
  • "alias": "foo"
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Modify attributes of applications

Perform actions like start, stop, or restart on snap applications, typically services.

Authorizations:
PeerAuth
Request Body schema: application/json
required

The action to perform on one or more applications.

action
required
string

The action to perform.

names
required
Array of strings

A list of names of snaps (e.g. "lxd") or specific apps (e.g. "lxd.daemon") to operate on.

scope
Array of strings
object
names
Array of strings
selector
string
Enum: "userX" "self" "all"

Internally converted to an integer by the servers marshalling/unmarshalling process

enable
boolean
Default: false

Arranges to have the service start at system boot.

Responses

Request samples

Content type
application/json
Example
{
  • "action": "start",
  • "names": [
    ],
  • "enable": true
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Get configurations from confdb

Retrieves configuration values from confdb.

Authorizations:
PeerAuth
path Parameters
account
required
string
confdb-schema
required
string
view
required
string
query Parameters
keys
string

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.

Responses

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Set configurations in confdb

Sets configuration values in confdb.

Authorizations:
PeerAuth
path Parameters
account
required
string
confdb-schema
required
string
view
required
string
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "office.ssid": "foo",
  • "password": null
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Issue an action to the interface system

Used to connect and disconnect interfaces. Issues a command to the interface system to operate on the specified plug and slot.

Authorizations:
PeerAuth
Request Body schema: application/json
required

Parameters for the interface action.

action
string
Enum: "connect" "disconnect"

Action to perform.

forget
boolean

Used with the 'disconnect' action. Ensures the system does not reestablish the connection going forward.

Array of objects (Slot) = 1 items
Array (= 1 items)
snap
string

The name of the snap providing the slot.

slot
string

The name of the slot itself.

interface
string

The interface name for the slot.

object

A static map of the slot's attributes. These are attributes that belong to the slot

apps
Array of strings

A list of apps associated with this slot.

label
string

The display label for the slot.

Array of objects (PlugRef)

A list of plugs connected to this slot.

Array of objects (Plug) = 1 items
Array (= 1 items)
snap
string

The name of the snap providing the plug.

plug
string

The name of the plug itself.

interface
string

The interface name for the plug.

object

A static map of the plug's attributes. These are attributes that belong to the plug

apps
Array of strings

A list of apps associated with this plug.

label
string

The display label for the plug.

Array of objects (SlotRef)

A list of slots this plug is connected to.

Responses

Request samples

Content type
application/json
{
  • "action": "connect",
  • "forget": true,
  • "slots": [
    ],
  • "plugs": [
    ]
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Replace the model assertion

Replaces the current model assertion, potentially triggering a remodel of the system.

The endpoint accepts two different content types depending on the use case:

  • application/json: For a standard (online) remodel where the system will fetch required snaps from the store.
  • multipart/form-data: For an offline remodel, where the new model assertion and all required snaps and other files are provided directly in the request.
Read more about offline remodeling on the Ubuntu Core documentation.
Authorizations:
PeerAuth
Request Body schema:
required

The new model assertion and, for offline remodels, any required files (snaps, etc.).

assertion
required
string

A string containing the full, signed model assertion.

Responses

Request samples

Content type
{
  • "assertion": "type: model\nauthority-id: generic\nseries: 16\nbrand-id: generic\nmodel: generic-classic\nclassic: true\ntimestamp: 2025-10-03T10:40:00.0Z\nsign-key-sha3-384: d-JcZF9nD9eBw7bwMnH61x-bklnQOhQud1Is6o_cn2wTj8EYDi9musrIT9z2MdAa\nAcLBXAQAAQ[...]"
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Perform an action on the serial assertion

Performs an asynchronous action on the current serial assertion by sending a JSON command. The only supported action is forget, which causes the system to unregister its current serial and prepare for a new one.

Read more about offline remodeling on the Ubuntu Core documentation.
Authorizations:
PeerAuth
Request Body schema: application/json
required

A JSON object specifying the action to perform on the serial.

action
required
string
Value: "forget"

The action to perform on the serial assertion.

no-registration-until-reboot
boolean
Default: false

If true, delays device registration until the next reboot.

Responses

Request samples

Content type
application/json
{
  • "action": "forget",
  • "no-registration-until-reboot"": true
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Manage quota groups

Create, modify, or remove a quota group.

Authorizations:
PeerAuth
Request Body schema: application/json
required
action
required
string
Enum: "ensure" "remove"
required
object (QuotaGroup)

Defines a quota group for one or more snaps.

group-name
required
string

The name of the quota group.

subgroups
Array of strings

lists any subgroups this quota group contains.

parent
string

Contains the parent quota group name, if this group is a subgroup.

snaps
Array of strings

Lists any snaps that belong to this quota group.

services
string

Only for a subgroup, lists specific services belonging to a snap in the parent group.

object

The types and values of limits defined for this quota group.

memory
integer <int64>

Memory usage limit in bytes.

cpu
string

Includes percentage as a limit.

cpu-set
string

Per-cpu limits, with cpus listing included cores.

threads
integer

Maximum number of threads for this quota group.

object

Number of messages logged per time period.

object

Contains the current usage of memory and task quotas

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "action": "ensure",
  • "quota-group": {
    }
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Manage snaps

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.

Authorizations:
PeerAuth
Request Body schema:
required

The body of the JSON request.

action
required
string
Enum: "install" "refresh" "remove" "revert" "hold" "unhold" "enable" "disable" "switch" "snapshot"
snaps
Array of strings
quota-group
string

The quota group the snap belongs to.

unaliased
boolean
prefer
boolean

Cannot be used with 'unaliased'

classic
boolean

Whether the snap uses classic confinement or not.

devmode
boolean

Whether the snap should be installed in developer mode or not.

jailmode
boolean

Set to true to install the snap in jail mode. Only non-classic snaps can be placed in jail mode.

ignore-running
boolean
components
string <map[string][]string>

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.

transaction
string
Enum: "per-snap" "all-snaps"

Responses

Request samples

Content type
{
  • "action": "install",
  • "snaps": [
    ],
  • "quota-group": "string",
  • "unaliased": true,
  • "prefer": true,
  • "classic": true,
  • "devmode": true,
  • "jailmode": true,
  • "ignore-running": true,
  • "components": "{ \"firefox\": [\"firefox+comp\"]}",
  • "transaction": "per-snap"
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Manage a specific snap

Perform an action (install, refresh, remove, etc.) on a single, specific snap.

Authorizations:
PeerAuth
path Parameters
name
required
string

The name of the snap.

Request Body schema: application/json
required

The action and options for the snap.

action
required
string
Enum: "install" "refresh" "remove" "revert" "enable" "disable" "switch" "hold" "unhold"
channel
string

The channel to use for the action.

revision
string

A specific revision to install or revert to.

classic
boolean
devmode
boolean
purge
boolean

If true, don't save a snapshot of data on removal.

terminate
boolean

If true, kill running processes before removal.

components
Array of strings

Responses

Request samples

Content type
application/json
{
  • "action": "install",
  • "channel": "beta",
  • "revision": "string",
  • "classic": true,
  • "devmode": true,
  • "purge": true,
  • "terminate": true,
  • "components": [
    ]
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Set snap configuration

Set the configuration details for an installed snap. Use 'system' as the name to set system options.

Authorizations:
PeerAuth
path Parameters
name
required
string

The name of the snap or the reserved name 'system'.

Request Body schema: application/json
required

A JSON map of configuration keys and values. Dotted keys can be used. Use a null value to unset an option.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "conf-key1": "conf-value1",
  • "dotted.key": "conf-value2",
  • "key-to-unset": null
}

Response samples

Content type
application/json
{
  • "status-code": 400,
  • "status": "Bad Request",
  • "type": "error",
  • "result": {
    }
}

Manipulate or import a snapshot

Performs an action on a snapshot set, such as restoring, checking, forgetting, or importing from a data stream.

Authorizations:
PeerAuth
Request Body schema:
required

The action to perform. Can be a JSON object for manipulation or a binary stream for import.

action
required
string
Enum: "restore" "check" "forget"
set
required
integer

The ID of the snapshot set to operate on.

snaps
Array of strings

An array of snap names to restrict the action to.

users
Array of strings

An array of user names to restrict the action to (disallowed for 'forget').

Responses

Request samples

Content type
{
  • "action": "restore",
  • "set": 0,
  • "snaps": [
    ],
  • "users": [
    ]
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Perform an action on the current recovery system or create a new one

Perform an action such as 'reboot', 'install' on the current active recovery system, or 'create' a new recovery system.

Authorizations:
PeerAuth
Request Body schema: application/json
required
One of
action
required
string
Value: "create"
label
required
string

A unique label for the new recovery system.

validation-sets
Array of strings

A list of validation set strings to use for creating the system.

test-system
boolean
Default: false

If true, creates the system as a test system.

mark-default
boolean
Default: false

If true, marks the new system as the default recovery system.

offline
boolean
Default: false

If true, performs the creation in offline mode.

Responses

Request samples

Content type
application/json
Example
{
  • "action": "create",
  • "label": "string",
  • "validation-sets": [
    ],
  • "test-system": false,
  • "mark-default": false,
  • "offline": false
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

AuthenticationRequired

Access is restricted to the root user.

Modify aliases

Modify aliases by performing an 'alias', 'unalias', or 'prefer' action.

Authorizations:
PeerAuth
Request Body schema: application/json
required

The action to perform on an alias.

action
required
string
Enum: "alias" "unalias" "prefer"

The action to perform on the alias.

snap
string

The snap name to modify (optional for unalias).

app
string

The app to modify (optional).

alias
required
string

The alias to modify.

Responses

Request samples

Content type
application/json
{
  • "action": "alias",
  • "snap": "moon-buggy",
  • "app": "string",
  • "alias": "foo"
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Modify attributes of applications

Perform actions like start, stop, or restart on snap applications, typically services.

Authorizations:
PeerAuth
Request Body schema: application/json
required

The action to perform on one or more applications.

action
required
string

The action to perform.

names
required
Array of strings

A list of names of snaps (e.g. "lxd") or specific apps (e.g. "lxd.daemon") to operate on.

scope
Array of strings
object
names
Array of strings
selector
string
Enum: "userX" "self" "all"

Internally converted to an integer by the servers marshalling/unmarshalling process

enable
boolean
Default: false

Arranges to have the service start at system boot.

Responses

Request samples

Content type
application/json
Example
{
  • "action": "start",
  • "names": [
    ],
  • "enable": true
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Attempt to add or replace an assertion

Requires a valid assertion with a signature signed by a verifiable public key. The body of the request provides the assertion to add. If replacing an existing assertion the new must be consistent with and its prerequisite.

Authorizations:
PeerAuth
Request Body schema: application/x.ubuntu.assertion
required

The raw assertion text to add to the database.

string <binary>

A raw assertion string.

Responses

Response samples

Content type
application/json
{
  • "status-code": 400,
  • "status": "Bad Request",
  • "type": "error",
  • "result": {
    }
}

Get all changes

Retrieves a list of all changes in progress or completed on the system.

Authorizations:
PeerAuth
query Parameters
select
string
Default: "in-progress"
Enum: "all" "in-progress" "ready"

Limit which changes are returned.

for
string

Optional snap name to limit results to.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": [
    ]
}

Get the status of a change

Retrieves the current status of a specific background change by its ID.

Authorizations:
PeerAuth
path Parameters
id
required
string

The ID of the change to retrieve.

Responses

Response samples

Content type
application/json
{
  • "id": "73",
  • "kind": "auto-refresh",
  • "summary": "Auto-refresh snaps \"core22\", \"firefox\"",
  • "status": "Abort",
  • "tasks": [
    ],
  • "ready": true,
  • "spawn-time": "2019-08-24T14:15:22Z",
  • "ready-time": "2019-08-24T14:15:22Z",
  • "err": "string",
  • "data": { },
  • "log": [
    ]
}

Abort a change

Aborts a change that is currently in progress.

Authorizations:
PeerAuth
path Parameters
id
required
string

The ID of the change to retrieve.

Request Body schema: application/json
required
action
required
string
Value: "abort"

Responses

Request samples

Content type
application/json
{
  • "action": "abort"
}

Response samples

Content type
application/json
{
  • "id": "73",
  • "kind": "auto-refresh",
  • "summary": "Auto-refresh snaps \"core22\", \"firefox\"",
  • "status": "Abort",
  • "tasks": [
    ],
  • "ready": true,
  • "spawn-time": "2019-08-24T14:15:22Z",
  • "ready-time": "2019-08-24T14:15:22Z",
  • "err": "string",
  • "data": { },
  • "log": [
    ]
}

Create cohort keys

Creates a set of cohort keys for a given set of snaps.

Authorizations:
PeerAuth
Request Body schema: application/json
required
action
required
string
Value: "create"
snaps
required
Array of strings

An array of snap names to create cohorts for.

Responses

Request samples

Content type
application/json
{
  • "action": "create",
  • "snaps": [
    ]
}

Response samples

Content type
application/json
{
  • "cohorts": {
    }
}

Get configurations from confdb

Retrieves configuration values from confdb.

Authorizations:
PeerAuth
path Parameters
account
required
string
confdb-schema
required
string
view
required
string
query Parameters
keys
string

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.

Responses

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Set configurations in confdb

Sets configuration values in confdb.

Authorizations:
PeerAuth
path Parameters
account
required
string
confdb-schema
required
string
view
required
string
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "office.ssid": "foo",
  • "password": null
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Find snaps in the store

Finds snaps or components in the store that match the search criteria and are compatible with the host system. In order for the user to be authorized to use this route, they must be logged in via 'snap-login', hence being tagged as both OpenAccess and AuthenticationRequired. PeerAuth is not listed here as sudo is not required to interact with the route.

query Parameters
q
string

Search for packages 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 packages.

name
string

An exact name to search for. Supports '*' as a wildcard at the end. Cannot be used together with q. This is meant for things like auto-completion.

scope
string
Value: "wide"

If set to 'wide', broadens the search to include non-stable packages.

section
string

The name of a store section to search within. Use GET /v2/sections to get the names of the sections.

select
string
Enum: "refresh" "private"

Alter the collection searched. refresh - search refreshable snaps. Cannot be used with q, nor name. private - search private snaps (by default, find only searches public snaps). Cannot be used with name, only q (for now at least).

common-id
string
Example: common-id=org.videolan.vlc

Search for packages using the common-id attribute. This is often the application name used by other packaging formats.

Responses

Response samples

Content type
application/json
[]

Issue an action to the interface system

Used to connect and disconnect interfaces. Issues a command to the interface system to operate on the specified plug and slot.

Authorizations:
PeerAuth
Request Body schema: application/json
required

Parameters for the interface action.

action
string
Enum: "connect" "disconnect"

Action to perform.

forget
boolean

Used with the 'disconnect' action. Ensures the system does not reestablish the connection going forward.

Array of objects (Slot) = 1 items
Array (= 1 items)
snap
string

The name of the snap providing the slot.

slot
string

The name of the slot itself.

interface
string

The interface name for the slot.

object

A static map of the slot's attributes. These are attributes that belong to the slot

apps
Array of strings

A list of apps associated with this slot.

label
string

The display label for the slot.

Array of objects (PlugRef)

A list of plugs connected to this slot.

Array of objects (Plug) = 1 items
Array (= 1 items)
snap
string

The name of the snap providing the plug.

plug
string

The name of the plug itself.

interface
string

The interface name for the plug.

object

A static map of the plug's attributes. These are attributes that belong to the plug

apps
Array of strings

A list of apps associated with this plug.

label
string

The display label for the plug.

Array of objects (SlotRef)

A list of slots this plug is connected to.

Responses

Request samples

Content type
application/json
{
  • "action": "connect",
  • "forget": true,
  • "slots": [
    ],
  • "plugs": [
    ]
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Authenticate user with snapd and store

Authenticates a user with Snapd and the store using their credentials. Credentials are saved to the ~/.snap/auth.json file and further communication is made with these credentials.

Authorizations:
PeerAuth
Request Body schema: application/json
required
email
required
string <email> .@.*\..

The email associated with the desired account.

password
required
string <password>

The password associated with the email address.

otp
string

A one-time password for two-factor authentication.

Responses

Request samples

Content type
application/json
{
  • "email": "random.user@emailaddr.com",
  • "password": "password1234!",
  • "otp": "123456"
}

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

Log user out of snapd and the store

Logs the currently authenticated user out of snapd and the store.

Authorizations:
PeerAuth
header Parameters
Authorization
string <Authorization: Macaroon <the-macaroon>>

The authorization to remove from the system.

Responses

Response samples

Content type
application/json
{
  • "status-code": 400,
  • "status": "Bad Request",
  • "type": "error",
  • "result": {
    }
}

Get log contents

Retrieves log contents from the snapd daemon. The response is a stream of newline-delimited JSON objects.

Authorizations:
PeerAuth
query Parameters
follow
boolean
Default: false

If set, returns log entries as they occur, streaming the response.

n
integer
Default: 10

Number of log entries to return.

names
string
Example: names=multipass,lxd

Comma-separated list of snap names to filter by.

Responses

Response samples

Content type
application/x-ndjson
{
  • "timestamp": "2025-09-11T15:10:22.264675Z",
  • "message": "Failed to get https://cloud-images.ubuntu.com/releases/streams/v1/index.json",
  • "sid": "multipassd",
  • "pid": "2062"
}

Replace the model assertion

Replaces the current model assertion, potentially triggering a remodel of the system.

The endpoint accepts two different content types depending on the use case:

  • application/json: For a standard (online) remodel where the system will fetch required snaps from the store.
  • multipart/form-data: For an offline remodel, where the new model assertion and all required snaps and other files are provided directly in the request.
Read more about offline remodeling on the Ubuntu Core documentation.
Authorizations:
PeerAuth
Request Body schema:
required

The new model assertion and, for offline remodels, any required files (snaps, etc.).

assertion
required
string

A string containing the full, signed model assertion.

Responses

Request samples

Content type
{
  • "assertion": "type: model\nauthority-id: generic\nseries: 16\nbrand-id: generic\nmodel: generic-classic\nclassic: true\ntimestamp: 2025-10-03T10:40:00.0Z\nsign-key-sha3-384: d-JcZF9nD9eBw7bwMnH61x-bklnQOhQud1Is6o_cn2wTj8EYDi9musrIT9z2MdAa\nAcLBXAQAAQ[...]"
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Perform an action on the serial assertion

Performs an asynchronous action on the current serial assertion by sending a JSON command. The only supported action is forget, which causes the system to unregister its current serial and prepare for a new one.

Read more about offline remodeling on the Ubuntu Core documentation.
Authorizations:
PeerAuth
Request Body schema: application/json
required

A JSON object specifying the action to perform on the serial.

action
required
string
Value: "forget"

The action to perform on the serial assertion.

no-registration-until-reboot
boolean
Default: false

If true, delays device registration until the next reboot.

Responses

Request samples

Content type
application/json
{
  • "action": "forget",
  • "no-registration-until-reboot"": true
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Manage quota groups

Create, modify, or remove a quota group.

Authorizations:
PeerAuth
Request Body schema: application/json
required
action
required
string
Enum: "ensure" "remove"
required
object (QuotaGroup)

Defines a quota group for one or more snaps.

group-name
required
string

The name of the quota group.

subgroups
Array of strings

lists any subgroups this quota group contains.

parent
string

Contains the parent quota group name, if this group is a subgroup.

snaps
Array of strings

Lists any snaps that belong to this quota group.

services
string

Only for a subgroup, lists specific services belonging to a snap in the parent group.

object

The types and values of limits defined for this quota group.

memory
integer <int64>

Memory usage limit in bytes.

cpu
string

Includes percentage as a limit.

cpu-set
string

Per-cpu limits, with cpus listing included cores.

threads
integer

Maximum number of threads for this quota group.

object

Number of messages logged per time period.

object

Contains the current usage of memory and task quotas

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "action": "ensure",
  • "quota-group": {
    }
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Run snapctl command

Executes a 'snapctl' command within a given context. This route uses the socket /run/snapd-snap.socket. This is intended to be used only from within a snap itself.

Authorizations:
PeerAuth
Request Body schema: application/json
required

The context and arguments for the snapctl command.

context-id
required
string

The context ID for this call. The context ID is passed to hooks through the $SNAP_COOKIE environment variable. The 'snapctl' command passes this automatically. For hooks that are calling the endpoint manually, the responsibility falls on the binary to retrieve the context ID itself.

args
required
Array of strings

A list of arguments to pass to snapctl.

stdin
string

If args is fde-setup-result, provides stdin to the context.

Responses

Request samples

Content type
application/json
{
  • "context-id": "ABCDEF",
  • "args": [
    ],
  • "stdin": "string"
}

Response samples

Content type
application/json
{
  • "stdout": "string",
  • "stderr": "string"
}

Manage snaps

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.

Authorizations:
PeerAuth
Request Body schema:
required

The body of the JSON request.

action
required
string
Enum: "install" "refresh" "remove" "revert" "hold" "unhold" "enable" "disable" "switch" "snapshot"
snaps
Array of strings
quota-group
string

The quota group the snap belongs to.

unaliased
boolean
prefer
boolean

Cannot be used with 'unaliased'

classic
boolean

Whether the snap uses classic confinement or not.

devmode
boolean

Whether the snap should be installed in developer mode or not.

jailmode
boolean

Set to true to install the snap in jail mode. Only non-classic snaps can be placed in jail mode.

ignore-running
boolean
components
string <map[string][]string>

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.

transaction
string
Enum: "per-snap" "all-snaps"

Responses

Request samples

Content type
{
  • "action": "install",
  • "snaps": [
    ],
  • "quota-group": "string",
  • "unaliased": true,
  • "prefer": true,
  • "classic": true,
  • "devmode": true,
  • "jailmode": true,
  • "ignore-running": true,
  • "components": "{ \"firefox\": [\"firefox+comp\"]}",
  • "transaction": "per-snap"
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Manage a specific snap

Perform an action (install, refresh, remove, etc.) on a single, specific snap.

Authorizations:
PeerAuth
path Parameters
name
required
string

The name of the snap.

Request Body schema: application/json
required

The action and options for the snap.

action
required
string
Enum: "install" "refresh" "remove" "revert" "enable" "disable" "switch" "hold" "unhold"
channel
string

The channel to use for the action.

revision
string

A specific revision to install or revert to.

classic
boolean
devmode
boolean
purge
boolean

If true, don't save a snapshot of data on removal.

terminate
boolean

If true, kill running processes before removal.

components
Array of strings

Responses

Request samples

Content type
application/json
{
  • "action": "install",
  • "channel": "beta",
  • "revision": "string",
  • "classic": true,
  • "devmode": true,
  • "purge": true,
  • "terminate": true,
  • "components": [
    ]
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Get snap configuration

Retrieve configuration details for an installed snap. Use 'system' as the name to get system options.

Authorizations:
PeerAuth
path Parameters
name
required
string

The name of the snap or the reserved name 'system'.

query Parameters
keys
string

A comma-separated list of keys to retrieve. Dotted keys can be used for nested values.

Responses

Response samples

Content type
application/json
{ }

Set snap configuration

Set the configuration details for an installed snap. Use 'system' as the name to set system options.

Authorizations:
PeerAuth
path Parameters
name
required
string

The name of the snap or the reserved name 'system'.

Request Body schema: application/json
required

A JSON map of configuration keys and values. Dotted keys can be used. Use a null value to unset an option.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "conf-key1": "conf-value1",
  • "dotted.key": "conf-value2",
  • "key-to-unset": null
}

Response samples

Content type
application/json
{
  • "status-code": 400,
  • "status": "Bad Request",
  • "type": "error",
  • "result": {
    }
}

Manipulate or import a snapshot

Performs an action on a snapshot set, such as restoring, checking, forgetting, or importing from a data stream.

Authorizations:
PeerAuth
Request Body schema:
required

The action to perform. Can be a JSON object for manipulation or a binary stream for import.

action
required
string
Enum: "restore" "check" "forget"
set
required
integer

The ID of the snapshot set to operate on.

snaps
Array of strings

An array of snap names to restrict the action to.

users
Array of strings

An array of user names to restrict the action to (disallowed for 'forget').

Responses

Request samples

Content type
{
  • "action": "restore",
  • "set": 0,
  • "snaps": [
    ],
  • "users": [
    ]
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Export a snapshot set

Retrieves a snapshot set as a downloadable tar archive (.tgz). The response body is a binary stream.

Authorizations:
PeerAuth
path Parameters
set-id
required
integer
Example: 2

The ID of the snapshot set to export.

Responses

Response samples

Content type
application/json
{
  • "status-code": 400,
  • "status": "Bad Request",
  • "type": "error",
  • "result": {
    }
}

Get system recovery key

Retrieve LUKS encryption keys when using full disk encryption on Ubuntu Core.

Authorizations:
PeerAuth

Responses

Response samples

Content type
application/json
{
  • "result": {
    }
}

Manage system recovery keys

Removes and resets LUKS encryption keys when using full disk encryption on Ubuntu Core devices.

Authorizations:
PeerAuth
Request Body schema: application/json
required
action
required
string
Value: "remove"

The only supported action is 'remove'.

Responses

Request samples

Content type
application/json
{
  • "action": "remove"
}

Response samples

Content type
application/json
{
  • "status-code": 400,
  • "status": "Bad Request",
  • "type": "error",
  • "result": {
    }
}

Perform an action on the current recovery system or create a new one

Perform an action such as 'reboot', 'install' on the current active recovery system, or 'create' a new recovery system.

Authorizations:
PeerAuth
Request Body schema: application/json
required
One of
action
required
string
Value: "create"
label
required
string

A unique label for the new recovery system.

validation-sets
Array of strings

A list of validation set strings to use for creating the system.

test-system
boolean
Default: false

If true, creates the system as a test system.

mark-default
boolean
Default: false

If true, marks the new system as the default recovery system.

offline
boolean
Default: false

If true, performs the creation in offline mode.

Responses

Request samples

Content type
application/json
Example
{
  • "action": "create",
  • "label": "string",
  • "validation-sets": [
    ],
  • "test-system": false,
  • "mark-default": false,
  • "offline": false
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Get details for a specific recovery system

Retrieves detailed information for a single recovery system, including storage encryption status and available actions.

Authorizations:
PeerAuth
path Parameters
label
required
string

The label of the recovery system.

Responses

Response samples

Content type
application/json
{
  • "current": true,
  • "label": "string",
  • "brand": {
    },
  • "model": { },
  • "actions": [
    ],
  • "available-optional": {
    },
  • "volumes": [
    ],
  • "storage-encryption": {
    }
}

Perform an action on a specific recovery system

Perform an action on the recovery system identified by its label. The required parameters in the request body depend on the specified action.

Authorizations:
PeerAuth
path Parameters
label
required
string

The label of the recovery system.

Request Body schema: application/json
required
One of
action
required
string
Value: "do"
mode
required
string

The mode of the action to perform (e.g., 'recover', 'run').

title
string

The title of the custom action to perform.

Responses

Request samples

Content type
application/json
Example
{
  • "action": "do",
  • "mode": "string",
  • "title": "string"
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Get all enabled validation sets

Retrieves a list of all enabled validation sets on the system.

Read more about validation sets on the Canonical Snapcraft documentation.
Authorizations:
PeerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a specific validation set

Retrieves a single validation set by its account ID and name.

Authorizations:
PeerAuth
path Parameters
account-id
required
string
Example: ABCDEF12345678900987654321FEDCBA

The developer account ID for the validation set.

name
required
string
Example: myset1

The name of the validation set.

Responses

Response samples

Content type
application/json
{
  • "account-id": "string",
  • "name": "string",
  • "mode": "monitor",
  • "pinned-at": 0,
  • "sequence": 0,
  • "valid": true
}

Manage a specific validation set

Apply or forget a specific validation set.

Authorizations:
PeerAuth
path Parameters
account-id
required
string
Example: ABCDEF12345678900987654321FEDCBA

The developer account ID for the validation set.

name
required
string
Example: myset1

The name of the validation set.

Request Body schema: application/json
required
action
required
string
Enum: "apply" "forget"

The operation to perform on the validation set.

mode
string
Enum: "monitor" "enforce"

The mode to enable for the validation set. Required when action is 'apply'.

sequence
integer

When using 'apply': an optional sequence number to pin. When using 'forget': an optional sequence number to match before forgetting.

Responses

Request samples

Content type
application/json
{
  • "action": "apply",
  • "mode": "monitor",
  • "sequence": 1
}

Response samples

Content type
application/json
{
  • "account-id": "ABCDEF12345678900987654321FEDCBA",
  • "mode": "monitor",
  • "name": "myset1",
  • "pinned-at": 1,
  • "sequence": 1,
  • "valid": true
}

Respond to warnings

Warnings can only be acknowledged to clear them, but they may reoccur Acknowledging warnings does not fix the underlying cause.

Authorizations:
PeerAuth
Request Body schema: application/json
required
action
required
string
Value: "okay"
timestamp
required
string <date-time>

Time to clear warnings before (RFC3339 UTC format).

Responses

Request samples

Content type
application/json
{
  • "action": "okay",
  • "timestamp": "2025-09-08T17:29:40.829324752Z"
}

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": 0
}

Changes

Interact with changes.

Get all changes

Retrieves a list of all changes in progress or completed on the system.

Authorizations:
PeerAuth
query Parameters
select
string
Default: "in-progress"
Enum: "all" "in-progress" "ready"

Limit which changes are returned.

for
string

Optional snap name to limit results to.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": [
    ]
}

Get the status of a change

Retrieves the current status of a specific background change by its ID.

Authorizations:
PeerAuth
path Parameters
id
required
string

The ID of the change to retrieve.

Responses

Response samples

Content type
application/json
{
  • "id": "73",
  • "kind": "auto-refresh",
  • "summary": "Auto-refresh snaps \"core22\", \"firefox\"",
  • "status": "Abort",
  • "tasks": [
    ],
  • "ready": true,
  • "spawn-time": "2019-08-24T14:15:22Z",
  • "ready-time": "2019-08-24T14:15:22Z",
  • "err": "string",
  • "data": { },
  • "log": [
    ]
}

Abort a change

Aborts a change that is currently in progress.

Authorizations:
PeerAuth
path Parameters
id
required
string

The ID of the change to retrieve.

Request Body schema: application/json
required
action
required
string
Value: "abort"

Responses

Request samples

Content type
application/json
{
  • "action": "abort"
}

Response samples

Content type
application/json
{
  • "id": "73",
  • "kind": "auto-refresh",
  • "summary": "Auto-refresh snaps \"core22\", \"firefox\"",
  • "status": "Abort",
  • "tasks": [
    ],
  • "ready": true,
  • "spawn-time": "2019-08-24T14:15:22Z",
  • "ready-time": "2019-08-24T14:15:22Z",
  • "err": "string",
  • "data": { },
  • "log": [
    ]
}

Experimental

Interact with experimental features.

Get configurations from confdb

Retrieves configuration values from confdb.

Authorizations:
PeerAuth
path Parameters
account
required
string
confdb-schema
required
string
view
required
string
query Parameters
keys
string

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.

Responses

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Set configurations in confdb

Sets configuration values in confdb.

Authorizations:
PeerAuth
path Parameters
account
required
string
confdb-schema
required
string
view
required
string
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "office.ssid": "foo",
  • "password": null
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Retrieve all outstanding prompts

Retrieves a list of all outstanding access request prompts.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a prompt by ID

Retrieves the details of a single prompt specified by its unique ID.

path Parameters
id
required
string

The unique identifier of the prompt to retrieve.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "snap": "string",
  • "interface": "home",
  • "constraints": {
    }
}

Reply to a prompt

Submit a reply (allow or deny) to an outstanding prompt, potentially creating a new rule.

path Parameters
id
required
string

The unique identifier of the prompt to which to reply.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Request Body schema: application/json
required
action
required
string
Enum: "allow" "deny"
lifespan
required
string
Enum: "single" "timespan" "session" "forever"

The lifespan for which the decision applies.

single: the decision only applies to the prompt with the given ID

timespan: the decision creates a rule which applies for the duration specified by the duration field or until it is deleted

session: the decision creates a rule which applies until the user logs out (specifically, until the systemd user session ends)

forever: the decision creates a rule which applies until it is deleted

duration
string <Go duration>

The duration for which the decision applies. Required if lifespan is timespan, otherwise must be omitted.

Read more about how Go handles time and durations in the official Go Time package documentation.
required
PromptingReplyConstraintsCamera (object) or PromptingReplyConstraintsHome (object)
One of
permissions
required
Array of strings
Items Value: "access"

The permissions applied to requests to access cameras via the camera interface.

Responses

Request samples

Content type
application/json
{
  • "action": "allow",
  • "lifespan": "single",
  • "duration": "7h30m",
  • "constraints": {
    }
}

Response samples

Content type
application/json
[
  • "string"
]

Retrieve all rules

Retrieves a list of all prompting rules, with optional filtering.

query Parameters
snap
string

Only retrieve rules which apply to the given snap.

interface
string

Only retrieve rules which apply to the given interface.

user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or remove rules

Create a new access rule or remove a set of existing rules based on a selector.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Request Body schema: application/json
required
One of
action
required
string
Value: "add"

The action to perform on the rules endpoint.

required
object
snap
string

The snap for which to add the rule.

interface
string

The interface for which to add the rule.

PromptingConstraintsCamera (object) or PromptingConstraintsHome (object)
One of
required
object

A map from permission name to the information about that permission.

Responses

Request samples

Content type
application/json
Example
{
  • "action": "add",
  • "rule": {
    }
}

Response samples

Content type
application/json
[ ]

Retrieve a rule by ID

Retrieves the details of a single rule specified by its unique ID.

path Parameters
id
required
string

The unique identifier of the rule to retrieve.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "user": 0,
  • "snap": "string",
  • "interface": "camera",
  • "constraints": {
    }
}

Patch or remove a rule by ID

Update or remove an existing rule specified by its unique ID.

path Parameters
id
required
string

The unique identifier of the rule to patch or remove.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Request Body schema: application/json
required
One of
action
required
string
Value: "patch"

The action to perform on the rule with the given ID.

required
object
PromptingPatchConstraintsCamera (object) or PromptingPatchConstraintsHome (object)
One of
object

A map from permission name to the information about that permission.

Any permissions omitted from this map are left unchanged from the existing rule.

To remove a permission from the existing rule, map the permission name to null.

Responses

Request samples

Content type
application/json
Example
{
  • "action": "patch",
  • "rule": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "user": 0,
  • "snap": "string",
  • "interface": "camera",
  • "constraints": {
    }
}

Interfaces

Display and manage interactions between snaps.

Get all interface connections

Retrieves the connection status of all plugs and slots on the system.

query Parameters
snap
string

Limit results to a given snap name.

select
string
Enum: "" "all"

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

interface
string

Limit results to a specific interface name.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

Get available interfaces

Retrieves the available interfaces and their associated metadata.

query Parameters
select
string
Enum: "all" "connected"

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
boolean

If set to true, slot information will be returned.

plugs
boolean

If set to true, plug information will be returned.

doc
boolean

If set to true, interface documentation will be returned.

names
string
Example: names=content

Interfaces that match the list of comma-separated names will be returned. The parameter matches against the name of the interface, not the name of snaps, plugs, or slots.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

Issue an action to the interface system

Used to connect and disconnect interfaces. Issues a command to the interface system to operate on the specified plug and slot.

Authorizations:
PeerAuth
Request Body schema: application/json
required

Parameters for the interface action.

action
string
Enum: "connect" "disconnect"

Action to perform.

forget
boolean

Used with the 'disconnect' action. Ensures the system does not reestablish the connection going forward.

Array of objects (Slot) = 1 items
Array (= 1 items)
snap
string

The name of the snap providing the slot.

slot
string

The name of the slot itself.

interface
string

The interface name for the slot.

object

A static map of the slot's attributes. These are attributes that belong to the slot

apps
Array of strings

A list of apps associated with this slot.

label
string

The display label for the slot.

Array of objects (PlugRef)

A list of plugs connected to this slot.

Array of objects (Plug) = 1 items
Array (= 1 items)
snap
string

The name of the snap providing the plug.

plug
string

The name of the plug itself.

interface
string

The interface name for the plug.

object

A static map of the plug's attributes. These are attributes that belong to the plug

apps
Array of strings

A list of apps associated with this plug.

label
string

The display label for the plug.

Array of objects (SlotRef)

A list of slots this plug is connected to.

Responses

Request samples

Content type
application/json
{
  • "action": "connect",
  • "forget": true,
  • "slots": [
    ],
  • "plugs": [
    ]
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Retrieve all outstanding prompts

Retrieves a list of all outstanding access request prompts.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a prompt by ID

Retrieves the details of a single prompt specified by its unique ID.

path Parameters
id
required
string

The unique identifier of the prompt to retrieve.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "snap": "string",
  • "interface": "home",
  • "constraints": {
    }
}

Reply to a prompt

Submit a reply (allow or deny) to an outstanding prompt, potentially creating a new rule.

path Parameters
id
required
string

The unique identifier of the prompt to which to reply.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Request Body schema: application/json
required
action
required
string
Enum: "allow" "deny"
lifespan
required
string
Enum: "single" "timespan" "session" "forever"

The lifespan for which the decision applies.

single: the decision only applies to the prompt with the given ID

timespan: the decision creates a rule which applies for the duration specified by the duration field or until it is deleted

session: the decision creates a rule which applies until the user logs out (specifically, until the systemd user session ends)

forever: the decision creates a rule which applies until it is deleted

duration
string <Go duration>

The duration for which the decision applies. Required if lifespan is timespan, otherwise must be omitted.

Read more about how Go handles time and durations in the official Go Time package documentation.
required
PromptingReplyConstraintsCamera (object) or PromptingReplyConstraintsHome (object)
One of
permissions
required
Array of strings
Items Value: "access"

The permissions applied to requests to access cameras via the camera interface.

Responses

Request samples

Content type
application/json
{
  • "action": "allow",
  • "lifespan": "single",
  • "duration": "7h30m",
  • "constraints": {
    }
}

Response samples

Content type
application/json
[
  • "string"
]

Retrieve all rules

Retrieves a list of all prompting rules, with optional filtering.

query Parameters
snap
string

Only retrieve rules which apply to the given snap.

interface
string

Only retrieve rules which apply to the given interface.

user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or remove rules

Create a new access rule or remove a set of existing rules based on a selector.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Request Body schema: application/json
required
One of
action
required
string
Value: "add"

The action to perform on the rules endpoint.

required
object
snap
string

The snap for which to add the rule.

interface
string

The interface for which to add the rule.

PromptingConstraintsCamera (object) or PromptingConstraintsHome (object)
One of
required
object

A map from permission name to the information about that permission.

Responses

Request samples

Content type
application/json
Example
{
  • "action": "add",
  • "rule": {
    }
}

Response samples

Content type
application/json
[ ]

Retrieve a rule by ID

Retrieves the details of a single rule specified by its unique ID.

path Parameters
id
required
string

The unique identifier of the rule to retrieve.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "user": 0,
  • "snap": "string",
  • "interface": "camera",
  • "constraints": {
    }
}

Patch or remove a rule by ID

Update or remove an existing rule specified by its unique ID.

path Parameters
id
required
string

The unique identifier of the rule to patch or remove.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Request Body schema: application/json
required
One of
action
required
string
Value: "patch"

The action to perform on the rule with the given ID.

required
object
PromptingPatchConstraintsCamera (object) or PromptingPatchConstraintsHome (object)
One of
object

A map from permission name to the information about that permission.

Any permissions omitted from this map are left unchanged from the existing rule.

To remove a permission from the existing rule, map the permission name to null.

Responses

Request samples

Content type
application/json
Example
{
  • "action": "patch",
  • "rule": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "user": 0,
  • "snap": "string",
  • "interface": "camera",
  • "constraints": {
    }
}

Notices

Interact with notices.

Retrieve system notices

Retrieves notices for the current user and any public notices, with optional filtering.

query Parameters
types
Array of strings (NoticeType)
Items Enum: "change-update" "warning" "refresh-inhibit" "snap-run-inhibit" "interfaces-requests-prompt" "interfaces-requests-rule-update"

If types is specified, only return notices with types matching the given types. The types parameter can include multiple types, notices matching any of the types are returned.

keys
Array of strings
Example: keys=-

If specified, only return notices with one of the given keys.

after
string <date-time>
Example: after=2025-09-08T17:29:40.829324752Z

If specified, only return notices with a 'last-repeated' field greater than the specified time, in RFC3339 UTC format.

timeout
string
Example: timeout=7m30s

If there are notices matching the filter which have already been recorded, these notices are returned immediately. Otherwise, if timeout is specified, wait up to the given duration for any new notices matching the filter to be recorded. This allows the user to use long-polling to be notified immediately when a new notice is recorded.

user-id
integer
Example: user-id=1000

Admin only. Instead of returning notices associated with the user who initiated the API request, return notices associated with the given UID. Public notices are still returned, as before. Cannot be used with the 'users' parameter.

users
string
Value: "all"

Admin only. Value must be 'all'. Return notices associated with all users, instead of just the user which initiated the API request. Cannot be used with the 'user-id' parameter.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": [
    ]
}

Create a notice

Create a notice. Currently, this can only be used to create notices of type 'snap-run-inhibit'. Only the 'snap' command is allowed to create notices of that type.

Request Body schema: application/json
required
action
required
string
Value: "add"

The action to perform.

key
required
string

The key of the notice to add.

type
required
string
Value: "snap-run-inhibit"

The type of the notice to add.

Responses

Request samples

Content type
application/json
{
  • "action": "add",
  • "key": "string",
  • "type": "snap-run-inhibit"
}

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

Retrieve a specific system notice

Retrieves a single notice by its unique ID.

path Parameters
id
required
string
Example: 74

The unique ID of the notice to retrieve.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

OpenAccess

Do not require the user to authenticate.

Get the available app aliases

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

List available apps

Lists applications available from installed snaps. Can be filtered by services or snap names.

query Parameters
global
boolean

Defaults to true for the root user to preserve normal behavior and match snapctl functionality.

select
string
Value: "service"
Example: select=service

Limit which apps are returned.

names
string
Example: names=spotify, lxd

Comma-separated list of snap names to get apps for.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

Get the list of assertion types

Retrieves a list of all known assertion types in the system.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

Get assertions of a given type

Get all the assertions in the system assertion database of the given type. Assertions can be filtered by providing assertion header keys as query parameters (e.g., ?username=canonical). The response is a stream of assertions separated by double newlines. 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.

path Parameters
assertion-type
required
string
Example: account

The type of assertion to retrieve.

query Parameters
remote
boolean
Default: false

When using remote, a primary key must be associated with the request assertion type. These mappings are as below account -> account-id account-key -> public-key-sha3-384 base-declaration -> series confdb-schema -> account-id AND name model -> series AND brand-id AND model preseed -> series AND brand-id AND model AND system_label repair -> brand-id AND repair-id serial -> brand-id AND model AND serial snap-build -> snap-sha3-384 snap-declaration -> series AND snap-id snap-developer -> snap-id AND publisher-id snap-resource-revision -> snap-id AND resource-name AND resource-sha3-384 AND provenance snap-resource-pair -> snap-id AND resource-name AND resource-revision AND snap-revision AND provenance snap-revision -> snap-sha3-384 AND provenance store -> store system-user -> brand-id AND email validation -> series AND snap-id AND approved-snap-id AND approved-snap-revision validation-set -> series AND account-id AND name AND sequence

Some assertion types do not have a definite authority set account-key-request -> public-key-sha3-384 confdb-control -> brand-id AND model AND serial device-session-request -> brand_id AND model AND serial serial-request - N/A

json
boolean
Default: false

If true, the response is formatted as a JSON object containing the headers of the assertions instead of the default signed assertion stream format.

Responses

Response samples

Content type
No sample

Get all interface connections

Retrieves the connection status of all plugs and slots on the system.

query Parameters
snap
string

Limit results to a given snap name.

select
string
Enum: "" "all"

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

interface
string

Limit results to a specific interface name.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

Find snaps in the store

Finds snaps or components in the store that match the search criteria and are compatible with the host system. In order for the user to be authorized to use this route, they must be logged in via 'snap-login', hence being tagged as both OpenAccess and AuthenticationRequired. PeerAuth is not listed here as sudo is not required to interact with the route.

query Parameters
q
string

Search for packages 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 packages.

name
string

An exact name to search for. Supports '*' as a wildcard at the end. Cannot be used together with q. This is meant for things like auto-completion.

scope
string
Value: "wide"

If set to 'wide', broadens the search to include non-stable packages.

section
string

The name of a store section to search within. Use GET /v2/sections to get the names of the sections.

select
string
Enum: "refresh" "private"

Alter the collection searched. refresh - search refreshable snaps. Cannot be used with q, nor name. private - search private snaps (by default, find only searches public snaps). Cannot be used with name, only q (for now at least).

common-id
string
Example: common-id=org.videolan.vlc

Search for packages using the common-id attribute. This is often the application name used by other packaging formats.

Responses

Response samples

Content type
application/json
[]

Get a snap's icon

Retrieves the icon for a snap that is installed on the system. The response is the raw content of the icon file. The Content-Disposition header will specify the filename.

path Parameters
name
required
string

The name of the snap to get the icon for.

Responses

Response samples

Content type
application/json
{
  • "status-code": 404,
  • "status": "Not Found",
  • "type": "error",
  • "result": {
    }
}

Get available interfaces

Retrieves the available interfaces and their associated metadata.

query Parameters
select
string
Enum: "all" "connected"

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
boolean

If set to true, slot information will be returned.

plugs
boolean

If set to true, plug information will be returned.

doc
boolean

If set to true, interface documentation will be returned.

names
string
Example: names=content

Interfaces that match the list of comma-separated names will be returned. The parameter matches against the name of the interface, not the name of snaps, plugs, or slots.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

Retrieve all outstanding prompts

Retrieves a list of all outstanding access request prompts.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a prompt by ID

Retrieves the details of a single prompt specified by its unique ID.

path Parameters
id
required
string

The unique identifier of the prompt to retrieve.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "snap": "string",
  • "interface": "home",
  • "constraints": {
    }
}

Reply to a prompt

Submit a reply (allow or deny) to an outstanding prompt, potentially creating a new rule.

path Parameters
id
required
string

The unique identifier of the prompt to which to reply.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Request Body schema: application/json
required
action
required
string
Enum: "allow" "deny"
lifespan
required
string
Enum: "single" "timespan" "session" "forever"

The lifespan for which the decision applies.

single: the decision only applies to the prompt with the given ID

timespan: the decision creates a rule which applies for the duration specified by the duration field or until it is deleted

session: the decision creates a rule which applies until the user logs out (specifically, until the systemd user session ends)

forever: the decision creates a rule which applies until it is deleted

duration
string <Go duration>

The duration for which the decision applies. Required if lifespan is timespan, otherwise must be omitted.

Read more about how Go handles time and durations in the official Go Time package documentation.
required
PromptingReplyConstraintsCamera (object) or PromptingReplyConstraintsHome (object)
One of
permissions
required
Array of strings
Items Value: "access"

The permissions applied to requests to access cameras via the camera interface.

Responses

Request samples

Content type
application/json
{
  • "action": "allow",
  • "lifespan": "single",
  • "duration": "7h30m",
  • "constraints": {
    }
}

Response samples

Content type
application/json
[
  • "string"
]

Retrieve all rules

Retrieves a list of all prompting rules, with optional filtering.

query Parameters
snap
string

Only retrieve rules which apply to the given snap.

interface
string

Only retrieve rules which apply to the given interface.

user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or remove rules

Create a new access rule or remove a set of existing rules based on a selector.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Request Body schema: application/json
required
One of
action
required
string
Value: "add"

The action to perform on the rules endpoint.

required
object
snap
string

The snap for which to add the rule.

interface
string

The interface for which to add the rule.

PromptingConstraintsCamera (object) or PromptingConstraintsHome (object)
One of
required
object

A map from permission name to the information about that permission.

Responses

Request samples

Content type
application/json
Example
{
  • "action": "add",
  • "rule": {
    }
}

Response samples

Content type
application/json
[ ]

Retrieve a rule by ID

Retrieves the details of a single rule specified by its unique ID.

path Parameters
id
required
string

The unique identifier of the rule to retrieve.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "user": 0,
  • "snap": "string",
  • "interface": "camera",
  • "constraints": {
    }
}

Patch or remove a rule by ID

Update or remove an existing rule specified by its unique ID.

path Parameters
id
required
string

The unique identifier of the rule to patch or remove.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Request Body schema: application/json
required
One of
action
required
string
Value: "patch"

The action to perform on the rule with the given ID.

required
object
PromptingPatchConstraintsCamera (object) or PromptingPatchConstraintsHome (object)
One of
object

A map from permission name to the information about that permission.

Any permissions omitted from this map are left unchanged from the existing rule.

To remove a permission from the existing rule, map the permission name to null.

Responses

Request samples

Content type
application/json
Example
{
  • "action": "patch",
  • "rule": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "user": 0,
  • "snap": "string",
  • "interface": "camera",
  • "constraints": {
    }
}

Get the active model assertion

Retrieves the active model assertion for the system. The model assertion describes a snap-based device.

Read more about model assertions on the Ubuntu Core documentation.

Responses

Response samples

Content type
application/json
{
  • "status-code": 404,
  • "status": "Not Found",
  • "type": "error",
  • "result": {
    }
}

Get the current serial assertion

Retrieves the current serial assertion for the system. The serial assertion is a statement used to bind a device identity to it's public key, provided by the store.

Read more about serial assertions on the Ubuntu Core documentation.

Responses

Response samples

Content type
application/json
{
  • "status-code": 404,
  • "status": "Not Found",
  • "type": "error",
  • "result": {
    }
}

Retrieve system notices

Retrieves notices for the current user and any public notices, with optional filtering.

query Parameters
types
Array of strings (NoticeType)
Items Enum: "change-update" "warning" "refresh-inhibit" "snap-run-inhibit" "interfaces-requests-prompt" "interfaces-requests-rule-update"

If types is specified, only return notices with types matching the given types. The types parameter can include multiple types, notices matching any of the types are returned.

keys
Array of strings
Example: keys=-

If specified, only return notices with one of the given keys.

after
string <date-time>
Example: after=2025-09-08T17:29:40.829324752Z

If specified, only return notices with a 'last-repeated' field greater than the specified time, in RFC3339 UTC format.

timeout
string
Example: timeout=7m30s

If there are notices matching the filter which have already been recorded, these notices are returned immediately. Otherwise, if timeout is specified, wait up to the given duration for any new notices matching the filter to be recorded. This allows the user to use long-polling to be notified immediately when a new notice is recorded.

user-id
integer
Example: user-id=1000

Admin only. Instead of returning notices associated with the user who initiated the API request, return notices associated with the given UID. Public notices are still returned, as before. Cannot be used with the 'users' parameter.

users
string
Value: "all"

Admin only. Value must be 'all'. Return notices associated with all users, instead of just the user which initiated the API request. Cannot be used with the 'user-id' parameter.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": [
    ]
}

Create a notice

Create a notice. Currently, this can only be used to create notices of type 'snap-run-inhibit'. Only the 'snap' command is allowed to create notices of that type.

Request Body schema: application/json
required
action
required
string
Value: "add"

The action to perform.

key
required
string

The key of the notice to add.

type
required
string
Value: "snap-run-inhibit"

The type of the notice to add.

Responses

Request samples

Content type
application/json
{
  • "action": "add",
  • "key": "string",
  • "type": "snap-run-inhibit"
}

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

Retrieve a specific system notice

Retrieves a single notice by its unique ID.

path Parameters
id
required
string
Example: 74

The unique ID of the notice to retrieve.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

Get all quota groups

Retrieves a list of all quota groups and their constraints.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a specific quota group

Retrieves the details for a single quota group by its name, or returns an error.

path Parameters
group-name
required
string

The name of the quota group.

Responses

Response samples

Content type
application/json
{
  • "group-name": "logmem",
  • "subgroups": [
    ],
  • "parent": "string",
  • "snaps": [
    ],
  • "services": "string",
  • "constraints": {
    },
  • "current": { }
}

Get store sections

Retrieves the list of available sections in the Snap Store.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": [
    ]
}

List installed snaps

Lists snaps installed on the system, including their components.

query Parameters
select
string
Default: "enabled"
Enum: "all" "enabled" "refresh-inhibited"

Filter which revisions of snaps are returned.

snaps
string

A comma-separated list of snap names to filter by.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get details for an installed snap

Retrieves details for a specific snap installed on the system.

path Parameters
name
required
string

The name of the snap.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "base": "core20",
  • "channel": "string",
  • "common-ids": [
    ],
  • "confinement": "classic",
  • "contact": "string",
  • "description": "string",
  • "developer": "string",
  • "devmode": true,
  • "download-size": 0,
  • "icon": "http://example.com",
  • "license": "string",
  • "private": true,
  • "revision": "string",
  • "status": "active",
  • "store-url": "http://example.com",
  • "summary": "string",
  • "title": "string",
  • "type": "app",
  • "version": "string",
  • "website": "http://example.com",
  • "categories": [
    ],
  • "links": {},
  • "media": [],
  • "publisher": {
    },
  • "apps": [
    ],
  • "install-date": "string",
  • "installed-size": 0,
  • "trymode": true,
  • "jailmode": true,
  • "tracking-channel": "stable",
  • "refresh-inhibit": {
    },
  • "refresh-failures": {
    },
  • "components": [
    ]
}

Get a list of snapshots

Retrieves a list containing metadata for all snapshot sets stored on the system.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": [
    ]
}

Get the list of recovery systems

Retrieves a list of all available recovery systems on the device.

Responses

Response samples

Content type
application/json
{
  • "systems": [
    ]
}

Get system information

Retrieves a dictionary of server configuration and environment information.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

Get system warnings

Retrieves the current warnings in snapd.

query Parameters
select
string
Default: "pending"
Enum: "" "all" "pending"

Retrieve specific warnings. The default only shows pending warnings. All shows warnings that haven't expired or been cleaned.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": [
    ]
}

Prompting

Interact with the prompting system.

Retrieve all outstanding prompts

Retrieves a list of all outstanding access request prompts.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a prompt by ID

Retrieves the details of a single prompt specified by its unique ID.

path Parameters
id
required
string

The unique identifier of the prompt to retrieve.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "snap": "string",
  • "interface": "home",
  • "constraints": {
    }
}

Reply to a prompt

Submit a reply (allow or deny) to an outstanding prompt, potentially creating a new rule.

path Parameters
id
required
string

The unique identifier of the prompt to which to reply.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Request Body schema: application/json
required
action
required
string
Enum: "allow" "deny"
lifespan
required
string
Enum: "single" "timespan" "session" "forever"

The lifespan for which the decision applies.

single: the decision only applies to the prompt with the given ID

timespan: the decision creates a rule which applies for the duration specified by the duration field or until it is deleted

session: the decision creates a rule which applies until the user logs out (specifically, until the systemd user session ends)

forever: the decision creates a rule which applies until it is deleted

duration
string <Go duration>

The duration for which the decision applies. Required if lifespan is timespan, otherwise must be omitted.

Read more about how Go handles time and durations in the official Go Time package documentation.
required
PromptingReplyConstraintsCamera (object) or PromptingReplyConstraintsHome (object)
One of
permissions
required
Array of strings
Items Value: "access"

The permissions applied to requests to access cameras via the camera interface.

Responses

Request samples

Content type
application/json
{
  • "action": "allow",
  • "lifespan": "single",
  • "duration": "7h30m",
  • "constraints": {
    }
}

Response samples

Content type
application/json
[
  • "string"
]

Retrieve all rules

Retrieves a list of all prompting rules, with optional filtering.

query Parameters
snap
string

Only retrieve rules which apply to the given snap.

interface
string

Only retrieve rules which apply to the given interface.

user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or remove rules

Create a new access rule or remove a set of existing rules based on a selector.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Request Body schema: application/json
required
One of
action
required
string
Value: "add"

The action to perform on the rules endpoint.

required
object
snap
string

The snap for which to add the rule.

interface
string

The interface for which to add the rule.

PromptingConstraintsCamera (object) or PromptingConstraintsHome (object)
One of
required
object

A map from permission name to the information about that permission.

Responses

Request samples

Content type
application/json
Example
{
  • "action": "add",
  • "rule": {
    }
}

Response samples

Content type
application/json
[ ]

Retrieve a rule by ID

Retrieves the details of a single rule specified by its unique ID.

path Parameters
id
required
string

The unique identifier of the rule to retrieve.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "user": 0,
  • "snap": "string",
  • "interface": "camera",
  • "constraints": {
    }
}

Patch or remove a rule by ID

Update or remove an existing rule specified by its unique ID.

path Parameters
id
required
string

The unique identifier of the rule to patch or remove.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Request Body schema: application/json
required
One of
action
required
string
Value: "patch"

The action to perform on the rule with the given ID.

required
object
PromptingPatchConstraintsCamera (object) or PromptingPatchConstraintsHome (object)
One of
object

A map from permission name to the information about that permission.

Any permissions omitted from this map are left unchanged from the existing rule.

To remove a permission from the existing rule, map the permission name to null.

Responses

Request samples

Content type
application/json
Example
{
  • "action": "patch",
  • "rule": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "user": 0,
  • "snap": "string",
  • "interface": "camera",
  • "constraints": {
    }
}

Root

Requires the user to authenticate with root access.

Get user accounts

Get information on user accounts on the system.

Authorizations:
PeerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Manage users

Create or remove local users on the system.

Authorizations:
PeerAuth
Request Body schema: application/json
required
action
required
string
Enum: "create" "remove"
email
string <email>
username
string
sudoer
boolean
Default: false

Whether the user can escalate to root privileges or not.

known
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "action": "create",
  • "email": "user@example.com",
  • "username": "string",
  • "sudoer": false,
  • "known": false
}

Response samples

Content type
application/json
[
  • {
    }
]

Snaps

Interact with snaps.

Get a snap's icon

Retrieves the icon for a snap that is installed on the system. The response is the raw content of the icon file. The Content-Disposition header will specify the filename.

path Parameters
name
required
string

The name of the snap to get the icon for.

Responses

Response samples

Content type
application/json
{
  • "status-code": 404,
  • "status": "Not Found",
  • "type": "error",
  • "result": {
    }
}

Run snapctl command

Executes a 'snapctl' command within a given context. This route uses the socket /run/snapd-snap.socket. This is intended to be used only from within a snap itself.

Authorizations:
PeerAuth
Request Body schema: application/json
required

The context and arguments for the snapctl command.

context-id
required
string

The context ID for this call. The context ID is passed to hooks through the $SNAP_COOKIE environment variable. The 'snapctl' command passes this automatically. For hooks that are calling the endpoint manually, the responsibility falls on the binary to retrieve the context ID itself.

args
required
Array of strings

A list of arguments to pass to snapctl.

stdin
string

If args is fde-setup-result, provides stdin to the context.

Responses

Request samples

Content type
application/json
{
  • "context-id": "ABCDEF",
  • "args": [
    ],
  • "stdin": "string"
}

Response samples

Content type
application/json
{
  • "stdout": "string",
  • "stderr": "string"
}

List installed snaps

Lists snaps installed on the system, including their components.

query Parameters
select
string
Default: "enabled"
Enum: "all" "enabled" "refresh-inhibited"

Filter which revisions of snaps are returned.

snaps
string

A comma-separated list of snap names to filter by.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Manage snaps

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.

Authorizations:
PeerAuth
Request Body schema:
required

The body of the JSON request.

action
required
string
Enum: "install" "refresh" "remove" "revert" "hold" "unhold" "enable" "disable" "switch" "snapshot"
snaps
Array of strings
quota-group
string

The quota group the snap belongs to.

unaliased
boolean
prefer
boolean

Cannot be used with 'unaliased'

classic
boolean

Whether the snap uses classic confinement or not.

devmode
boolean

Whether the snap should be installed in developer mode or not.

jailmode
boolean

Set to true to install the snap in jail mode. Only non-classic snaps can be placed in jail mode.

ignore-running
boolean
components
string <map[string][]string>

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.

transaction
string
Enum: "per-snap" "all-snaps"

Responses

Request samples

Content type
{
  • "action": "install",
  • "snaps": [
    ],
  • "quota-group": "string",
  • "unaliased": true,
  • "prefer": true,
  • "classic": true,
  • "devmode": true,
  • "jailmode": true,
  • "ignore-running": true,
  • "components": "{ \"firefox\": [\"firefox+comp\"]}",
  • "transaction": "per-snap"
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Get details for an installed snap

Retrieves details for a specific snap installed on the system.

path Parameters
name
required
string

The name of the snap.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "base": "core20",
  • "channel": "string",
  • "common-ids": [
    ],
  • "confinement": "classic",
  • "contact": "string",
  • "description": "string",
  • "developer": "string",
  • "devmode": true,
  • "download-size": 0,
  • "icon": "http://example.com",
  • "license": "string",
  • "private": true,
  • "revision": "string",
  • "status": "active",
  • "store-url": "http://example.com",
  • "summary": "string",
  • "title": "string",
  • "type": "app",
  • "version": "string",
  • "website": "http://example.com",
  • "categories": [
    ],
  • "links": {},
  • "media": [],
  • "publisher": {
    },
  • "apps": [
    ],
  • "install-date": "string",
  • "installed-size": 0,
  • "trymode": true,
  • "jailmode": true,
  • "tracking-channel": "stable",
  • "refresh-inhibit": {
    },
  • "refresh-failures": {
    },
  • "components": [
    ]
}

Manage a specific snap

Perform an action (install, refresh, remove, etc.) on a single, specific snap.

Authorizations:
PeerAuth
path Parameters
name
required
string

The name of the snap.

Request Body schema: application/json
required

The action and options for the snap.

action
required
string
Enum: "install" "refresh" "remove" "revert" "enable" "disable" "switch" "hold" "unhold"
channel
string

The channel to use for the action.

revision
string

A specific revision to install or revert to.

classic
boolean
devmode
boolean
purge
boolean

If true, don't save a snapshot of data on removal.

terminate
boolean

If true, kill running processes before removal.

components
Array of strings

Responses

Request samples

Content type
application/json
{
  • "action": "install",
  • "channel": "beta",
  • "revision": "string",
  • "classic": true,
  • "devmode": true,
  • "purge": true,
  • "terminate": true,
  • "components": [
    ]
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Get snap configuration

Retrieve configuration details for an installed snap. Use 'system' as the name to get system options.

Authorizations:
PeerAuth
path Parameters
name
required
string

The name of the snap or the reserved name 'system'.

query Parameters
keys
string

A comma-separated list of keys to retrieve. Dotted keys can be used for nested values.

Responses

Response samples

Content type
application/json
{ }

Set snap configuration

Set the configuration details for an installed snap. Use 'system' as the name to set system options.

Authorizations:
PeerAuth
path Parameters
name
required
string

The name of the snap or the reserved name 'system'.

Request Body schema: application/json
required

A JSON map of configuration keys and values. Dotted keys can be used. Use a null value to unset an option.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "conf-key1": "conf-value1",
  • "dotted.key": "conf-value2",
  • "key-to-unset": null
}

Response samples

Content type
application/json
{
  • "status-code": 400,
  • "status": "Bad Request",
  • "type": "error",
  • "result": {
    }
}

Store

Interact with the store.

Find snaps in the store

Finds snaps or components in the store that match the search criteria and are compatible with the host system. In order for the user to be authorized to use this route, they must be logged in via 'snap-login', hence being tagged as both OpenAccess and AuthenticationRequired. PeerAuth is not listed here as sudo is not required to interact with the route.

query Parameters
q
string

Search for packages 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 packages.

name
string

An exact name to search for. Supports '*' as a wildcard at the end. Cannot be used together with q. This is meant for things like auto-completion.

scope
string
Value: "wide"

If set to 'wide', broadens the search to include non-stable packages.

section
string

The name of a store section to search within. Use GET /v2/sections to get the names of the sections.

select
string
Enum: "refresh" "private"

Alter the collection searched. refresh - search refreshable snaps. Cannot be used with q, nor name. private - search private snaps (by default, find only searches public snaps). Cannot be used with name, only q (for now at least).

common-id
string
Example: common-id=org.videolan.vlc

Search for packages using the common-id attribute. This is often the application name used by other packaging formats.

Responses

Response samples

Content type
application/json
[]

Authenticate user with snapd and store

Authenticates a user with Snapd and the store using their credentials. Credentials are saved to the ~/.snap/auth.json file and further communication is made with these credentials.

Authorizations:
PeerAuth
Request Body schema: application/json
required
email
required
string <email> .@.*\..

The email associated with the desired account.

password
required
string <password>

The password associated with the email address.

otp
string

A one-time password for two-factor authentication.

Responses

Request samples

Content type
application/json
{
  • "email": "random.user@emailaddr.com",
  • "password": "password1234!",
  • "otp": "123456"
}

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

Log user out of snapd and the store

Logs the currently authenticated user out of snapd and the store.

Authorizations:
PeerAuth
header Parameters
Authorization
string <Authorization: Macaroon <the-macaroon>>

The authorization to remove from the system.

Responses

Response samples

Content type
application/json
{
  • "status-code": 400,
  • "status": "Bad Request",
  • "type": "error",
  • "result": {
    }
}

Get store sections

Retrieves the list of available sections in the Snap Store.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": [
    ]
}

Synchronous

Return the complete response synchronously.

Get the available app aliases

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

List available apps

Lists applications available from installed snaps. Can be filtered by services or snap names.

query Parameters
global
boolean

Defaults to true for the root user to preserve normal behavior and match snapctl functionality.

select
string
Value: "service"
Example: select=service

Limit which apps are returned.

names
string
Example: names=spotify, lxd

Comma-separated list of snap names to get apps for.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

Get the list of assertion types

Retrieves a list of all known assertion types in the system.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

Attempt to add or replace an assertion

Requires a valid assertion with a signature signed by a verifiable public key. The body of the request provides the assertion to add. If replacing an existing assertion the new must be consistent with and its prerequisite.

Authorizations:
PeerAuth
Request Body schema: application/x.ubuntu.assertion
required

The raw assertion text to add to the database.

string <binary>

A raw assertion string.

Responses

Response samples

Content type
application/json
{
  • "status-code": 400,
  • "status": "Bad Request",
  • "type": "error",
  • "result": {
    }
}

Get assertions of a given type

Get all the assertions in the system assertion database of the given type. Assertions can be filtered by providing assertion header keys as query parameters (e.g., ?username=canonical). The response is a stream of assertions separated by double newlines. 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.

path Parameters
assertion-type
required
string
Example: account

The type of assertion to retrieve.

query Parameters
remote
boolean
Default: false

When using remote, a primary key must be associated with the request assertion type. These mappings are as below account -> account-id account-key -> public-key-sha3-384 base-declaration -> series confdb-schema -> account-id AND name model -> series AND brand-id AND model preseed -> series AND brand-id AND model AND system_label repair -> brand-id AND repair-id serial -> brand-id AND model AND serial snap-build -> snap-sha3-384 snap-declaration -> series AND snap-id snap-developer -> snap-id AND publisher-id snap-resource-revision -> snap-id AND resource-name AND resource-sha3-384 AND provenance snap-resource-pair -> snap-id AND resource-name AND resource-revision AND snap-revision AND provenance snap-revision -> snap-sha3-384 AND provenance store -> store system-user -> brand-id AND email validation -> series AND snap-id AND approved-snap-id AND approved-snap-revision validation-set -> series AND account-id AND name AND sequence

Some assertion types do not have a definite authority set account-key-request -> public-key-sha3-384 confdb-control -> brand-id AND model AND serial device-session-request -> brand_id AND model AND serial serial-request - N/A

json
boolean
Default: false

If true, the response is formatted as a JSON object containing the headers of the assertions instead of the default signed assertion stream format.

Responses

Response samples

Content type
No sample

Get all changes

Retrieves a list of all changes in progress or completed on the system.

Authorizations:
PeerAuth
query Parameters
select
string
Default: "in-progress"
Enum: "all" "in-progress" "ready"

Limit which changes are returned.

for
string

Optional snap name to limit results to.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": [
    ]
}

Get the status of a change

Retrieves the current status of a specific background change by its ID.

Authorizations:
PeerAuth
path Parameters
id
required
string

The ID of the change to retrieve.

Responses

Response samples

Content type
application/json
{
  • "id": "73",
  • "kind": "auto-refresh",
  • "summary": "Auto-refresh snaps \"core22\", \"firefox\"",
  • "status": "Abort",
  • "tasks": [
    ],
  • "ready": true,
  • "spawn-time": "2019-08-24T14:15:22Z",
  • "ready-time": "2019-08-24T14:15:22Z",
  • "err": "string",
  • "data": { },
  • "log": [
    ]
}

Abort a change

Aborts a change that is currently in progress.

Authorizations:
PeerAuth
path Parameters
id
required
string

The ID of the change to retrieve.

Request Body schema: application/json
required
action
required
string
Value: "abort"

Responses

Request samples

Content type
application/json
{
  • "action": "abort"
}

Response samples

Content type
application/json
{
  • "id": "73",
  • "kind": "auto-refresh",
  • "summary": "Auto-refresh snaps \"core22\", \"firefox\"",
  • "status": "Abort",
  • "tasks": [
    ],
  • "ready": true,
  • "spawn-time": "2019-08-24T14:15:22Z",
  • "ready-time": "2019-08-24T14:15:22Z",
  • "err": "string",
  • "data": { },
  • "log": [
    ]
}

Create cohort keys

Creates a set of cohort keys for a given set of snaps.

Authorizations:
PeerAuth
Request Body schema: application/json
required
action
required
string
Value: "create"
snaps
required
Array of strings

An array of snap names to create cohorts for.

Responses

Request samples

Content type
application/json
{
  • "action": "create",
  • "snaps": [
    ]
}

Response samples

Content type
application/json
{
  • "cohorts": {
    }
}

Get all interface connections

Retrieves the connection status of all plugs and slots on the system.

query Parameters
snap
string

Limit results to a given snap name.

select
string
Enum: "" "all"

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

interface
string

Limit results to a specific interface name.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

Find snaps in the store

Finds snaps or components in the store that match the search criteria and are compatible with the host system. In order for the user to be authorized to use this route, they must be logged in via 'snap-login', hence being tagged as both OpenAccess and AuthenticationRequired. PeerAuth is not listed here as sudo is not required to interact with the route.

query Parameters
q
string

Search for packages 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 packages.

name
string

An exact name to search for. Supports '*' as a wildcard at the end. Cannot be used together with q. This is meant for things like auto-completion.

scope
string
Value: "wide"

If set to 'wide', broadens the search to include non-stable packages.

section
string

The name of a store section to search within. Use GET /v2/sections to get the names of the sections.

select
string
Enum: "refresh" "private"

Alter the collection searched. refresh - search refreshable snaps. Cannot be used with q, nor name. private - search private snaps (by default, find only searches public snaps). Cannot be used with name, only q (for now at least).

common-id
string
Example: common-id=org.videolan.vlc

Search for packages using the common-id attribute. This is often the application name used by other packaging formats.

Responses

Response samples

Content type
application/json
[]

Get a snap's icon

Retrieves the icon for a snap that is installed on the system. The response is the raw content of the icon file. The Content-Disposition header will specify the filename.

path Parameters
name
required
string

The name of the snap to get the icon for.

Responses

Response samples

Content type
application/json
{
  • "status-code": 404,
  • "status": "Not Found",
  • "type": "error",
  • "result": {
    }
}

Get available interfaces

Retrieves the available interfaces and their associated metadata.

query Parameters
select
string
Enum: "all" "connected"

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
boolean

If set to true, slot information will be returned.

plugs
boolean

If set to true, plug information will be returned.

doc
boolean

If set to true, interface documentation will be returned.

names
string
Example: names=content

Interfaces that match the list of comma-separated names will be returned. The parameter matches against the name of the interface, not the name of snaps, plugs, or slots.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

Retrieve a prompt by ID

Retrieves the details of a single prompt specified by its unique ID.

path Parameters
id
required
string

The unique identifier of the prompt to retrieve.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "snap": "string",
  • "interface": "home",
  • "constraints": {
    }
}

Reply to a prompt

Submit a reply (allow or deny) to an outstanding prompt, potentially creating a new rule.

path Parameters
id
required
string

The unique identifier of the prompt to which to reply.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Request Body schema: application/json
required
action
required
string
Enum: "allow" "deny"
lifespan
required
string
Enum: "single" "timespan" "session" "forever"

The lifespan for which the decision applies.

single: the decision only applies to the prompt with the given ID

timespan: the decision creates a rule which applies for the duration specified by the duration field or until it is deleted

session: the decision creates a rule which applies until the user logs out (specifically, until the systemd user session ends)

forever: the decision creates a rule which applies until it is deleted

duration
string <Go duration>

The duration for which the decision applies. Required if lifespan is timespan, otherwise must be omitted.

Read more about how Go handles time and durations in the official Go Time package documentation.
required
PromptingReplyConstraintsCamera (object) or PromptingReplyConstraintsHome (object)
One of
permissions
required
Array of strings
Items Value: "access"

The permissions applied to requests to access cameras via the camera interface.

Responses

Request samples

Content type
application/json
{
  • "action": "allow",
  • "lifespan": "single",
  • "duration": "7h30m",
  • "constraints": {
    }
}

Response samples

Content type
application/json
[
  • "string"
]

Retrieve all rules

Retrieves a list of all prompting rules, with optional filtering.

query Parameters
snap
string

Only retrieve rules which apply to the given snap.

interface
string

Only retrieve rules which apply to the given interface.

user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or remove rules

Create a new access rule or remove a set of existing rules based on a selector.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Request Body schema: application/json
required
One of
action
required
string
Value: "add"

The action to perform on the rules endpoint.

required
object
snap
string

The snap for which to add the rule.

interface
string

The interface for which to add the rule.

PromptingConstraintsCamera (object) or PromptingConstraintsHome (object)
One of
required
object

A map from permission name to the information about that permission.

Responses

Request samples

Content type
application/json
Example
{
  • "action": "add",
  • "rule": {
    }
}

Response samples

Content type
application/json
[ ]

Retrieve a rule by ID

Retrieves the details of a single rule specified by its unique ID.

path Parameters
id
required
string

The unique identifier of the rule to retrieve.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "user": 0,
  • "snap": "string",
  • "interface": "camera",
  • "constraints": {
    }
}

Patch or remove a rule by ID

Update or remove an existing rule specified by its unique ID.

path Parameters
id
required
string

The unique identifier of the rule to patch or remove.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Request Body schema: application/json
required
One of
action
required
string
Value: "patch"

The action to perform on the rule with the given ID.

required
object
PromptingPatchConstraintsCamera (object) or PromptingPatchConstraintsHome (object)
One of
object

A map from permission name to the information about that permission.

Any permissions omitted from this map are left unchanged from the existing rule.

To remove a permission from the existing rule, map the permission name to null.

Responses

Request samples

Content type
application/json
Example
{
  • "action": "patch",
  • "rule": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "user": 0,
  • "snap": "string",
  • "interface": "camera",
  • "constraints": {
    }
}

Authenticate user with snapd and store

Authenticates a user with Snapd and the store using their credentials. Credentials are saved to the ~/.snap/auth.json file and further communication is made with these credentials.

Authorizations:
PeerAuth
Request Body schema: application/json
required
email
required
string <email> .@.*\..

The email associated with the desired account.

password
required
string <password>

The password associated with the email address.

otp
string

A one-time password for two-factor authentication.

Responses

Request samples

Content type
application/json
{
  • "email": "random.user@emailaddr.com",
  • "password": "password1234!",
  • "otp": "123456"
}

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

Log user out of snapd and the store

Logs the currently authenticated user out of snapd and the store.

Authorizations:
PeerAuth
header Parameters
Authorization
string <Authorization: Macaroon <the-macaroon>>

The authorization to remove from the system.

Responses

Response samples

Content type
application/json
{
  • "status-code": 400,
  • "status": "Bad Request",
  • "type": "error",
  • "result": {
    }
}

Get log contents

Retrieves log contents from the snapd daemon. The response is a stream of newline-delimited JSON objects.

Authorizations:
PeerAuth
query Parameters
follow
boolean
Default: false

If set, returns log entries as they occur, streaming the response.

n
integer
Default: 10

Number of log entries to return.

names
string
Example: names=multipass,lxd

Comma-separated list of snap names to filter by.

Responses

Response samples

Content type
application/x-ndjson
{
  • "timestamp": "2025-09-11T15:10:22.264675Z",
  • "message": "Failed to get https://cloud-images.ubuntu.com/releases/streams/v1/index.json",
  • "sid": "multipassd",
  • "pid": "2062"
}

Get the active model assertion

Retrieves the active model assertion for the system. The model assertion describes a snap-based device.

Read more about model assertions on the Ubuntu Core documentation.

Responses

Response samples

Content type
application/json
{
  • "status-code": 404,
  • "status": "Not Found",
  • "type": "error",
  • "result": {
    }
}

Get the current serial assertion

Retrieves the current serial assertion for the system. The serial assertion is a statement used to bind a device identity to it's public key, provided by the store.

Read more about serial assertions on the Ubuntu Core documentation.

Responses

Response samples

Content type
application/json
{
  • "status-code": 404,
  • "status": "Not Found",
  • "type": "error",
  • "result": {
    }
}

Retrieve system notices

Retrieves notices for the current user and any public notices, with optional filtering.

query Parameters
types
Array of strings (NoticeType)
Items Enum: "change-update" "warning" "refresh-inhibit" "snap-run-inhibit" "interfaces-requests-prompt" "interfaces-requests-rule-update"

If types is specified, only return notices with types matching the given types. The types parameter can include multiple types, notices matching any of the types are returned.

keys
Array of strings
Example: keys=-

If specified, only return notices with one of the given keys.

after
string <date-time>
Example: after=2025-09-08T17:29:40.829324752Z

If specified, only return notices with a 'last-repeated' field greater than the specified time, in RFC3339 UTC format.

timeout
string
Example: timeout=7m30s

If there are notices matching the filter which have already been recorded, these notices are returned immediately. Otherwise, if timeout is specified, wait up to the given duration for any new notices matching the filter to be recorded. This allows the user to use long-polling to be notified immediately when a new notice is recorded.

user-id
integer
Example: user-id=1000

Admin only. Instead of returning notices associated with the user who initiated the API request, return notices associated with the given UID. Public notices are still returned, as before. Cannot be used with the 'users' parameter.

users
string
Value: "all"

Admin only. Value must be 'all'. Return notices associated with all users, instead of just the user which initiated the API request. Cannot be used with the 'user-id' parameter.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": [
    ]
}

Create a notice

Create a notice. Currently, this can only be used to create notices of type 'snap-run-inhibit'. Only the 'snap' command is allowed to create notices of that type.

Request Body schema: application/json
required
action
required
string
Value: "add"

The action to perform.

key
required
string

The key of the notice to add.

type
required
string
Value: "snap-run-inhibit"

The type of the notice to add.

Responses

Request samples

Content type
application/json
{
  • "action": "add",
  • "key": "string",
  • "type": "snap-run-inhibit"
}

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

Retrieve a specific system notice

Retrieves a single notice by its unique ID.

path Parameters
id
required
string
Example: 74

The unique ID of the notice to retrieve.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

Get all quota groups

Retrieves a list of all quota groups and their constraints.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a specific quota group

Retrieves the details for a single quota group by its name, or returns an error.

path Parameters
group-name
required
string

The name of the quota group.

Responses

Response samples

Content type
application/json
{
  • "group-name": "logmem",
  • "subgroups": [
    ],
  • "parent": "string",
  • "snaps": [
    ],
  • "services": "string",
  • "constraints": {
    },
  • "current": { }
}

Get store sections

Retrieves the list of available sections in the Snap Store.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": [
    ]
}

Run snapctl command

Executes a 'snapctl' command within a given context. This route uses the socket /run/snapd-snap.socket. This is intended to be used only from within a snap itself.

Authorizations:
PeerAuth
Request Body schema: application/json
required

The context and arguments for the snapctl command.

context-id
required
string

The context ID for this call. The context ID is passed to hooks through the $SNAP_COOKIE environment variable. The 'snapctl' command passes this automatically. For hooks that are calling the endpoint manually, the responsibility falls on the binary to retrieve the context ID itself.

args
required
Array of strings

A list of arguments to pass to snapctl.

stdin
string

If args is fde-setup-result, provides stdin to the context.

Responses

Request samples

Content type
application/json
{
  • "context-id": "ABCDEF",
  • "args": [
    ],
  • "stdin": "string"
}

Response samples

Content type
application/json
{
  • "stdout": "string",
  • "stderr": "string"
}

List installed snaps

Lists snaps installed on the system, including their components.

query Parameters
select
string
Default: "enabled"
Enum: "all" "enabled" "refresh-inhibited"

Filter which revisions of snaps are returned.

snaps
string

A comma-separated list of snap names to filter by.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get details for an installed snap

Retrieves details for a specific snap installed on the system.

path Parameters
name
required
string

The name of the snap.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "base": "core20",
  • "channel": "string",
  • "common-ids": [
    ],
  • "confinement": "classic",
  • "contact": "string",
  • "description": "string",
  • "developer": "string",
  • "devmode": true,
  • "download-size": 0,
  • "icon": "http://example.com",
  • "license": "string",
  • "private": true,
  • "revision": "string",
  • "status": "active",
  • "store-url": "http://example.com",
  • "summary": "string",
  • "title": "string",
  • "type": "app",
  • "version": "string",
  • "website": "http://example.com",
  • "categories": [
    ],
  • "links": {},
  • "media": [],
  • "publisher": {
    },
  • "apps": [
    ],
  • "install-date": "string",
  • "installed-size": 0,
  • "trymode": true,
  • "jailmode": true,
  • "tracking-channel": "stable",
  • "refresh-inhibit": {
    },
  • "refresh-failures": {
    },
  • "components": [
    ]
}

Get snap configuration

Retrieve configuration details for an installed snap. Use 'system' as the name to get system options.

Authorizations:
PeerAuth
path Parameters
name
required
string

The name of the snap or the reserved name 'system'.

query Parameters
keys
string

A comma-separated list of keys to retrieve. Dotted keys can be used for nested values.

Responses

Response samples

Content type
application/json
{ }

Get a list of snapshots

Retrieves a list containing metadata for all snapshot sets stored on the system.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": [
    ]
}

Export a snapshot set

Retrieves a snapshot set as a downloadable tar archive (.tgz). The response body is a binary stream.

Authorizations:
PeerAuth
path Parameters
set-id
required
integer
Example: 2

The ID of the snapshot set to export.

Responses

Response samples

Content type
application/json
{
  • "status-code": 400,
  • "status": "Bad Request",
  • "type": "error",
  • "result": {
    }
}

Get system recovery key

Retrieve LUKS encryption keys when using full disk encryption on Ubuntu Core.

Authorizations:
PeerAuth

Responses

Response samples

Content type
application/json
{
  • "result": {
    }
}

Manage system recovery keys

Removes and resets LUKS encryption keys when using full disk encryption on Ubuntu Core devices.

Authorizations:
PeerAuth
Request Body schema: application/json
required
action
required
string
Value: "remove"

The only supported action is 'remove'.

Responses

Request samples

Content type
application/json
{
  • "action": "remove"
}

Response samples

Content type
application/json
{
  • "status-code": 400,
  • "status": "Bad Request",
  • "type": "error",
  • "result": {
    }
}

Get the list of recovery systems

Retrieves a list of all available recovery systems on the device.

Responses

Response samples

Content type
application/json
{
  • "systems": [
    ]
}

Perform an action on the current recovery system or create a new one

Perform an action such as 'reboot', 'install' on the current active recovery system, or 'create' a new recovery system.

Authorizations:
PeerAuth
Request Body schema: application/json
required
One of
action
required
string
Value: "create"
label
required
string

A unique label for the new recovery system.

validation-sets
Array of strings

A list of validation set strings to use for creating the system.

test-system
boolean
Default: false

If true, creates the system as a test system.

mark-default
boolean
Default: false

If true, marks the new system as the default recovery system.

offline
boolean
Default: false

If true, performs the creation in offline mode.

Responses

Request samples

Content type
application/json
Example
{
  • "action": "create",
  • "label": "string",
  • "validation-sets": [
    ],
  • "test-system": false,
  • "mark-default": false,
  • "offline": false
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Get details for a specific recovery system

Retrieves detailed information for a single recovery system, including storage encryption status and available actions.

Authorizations:
PeerAuth
path Parameters
label
required
string

The label of the recovery system.

Responses

Response samples

Content type
application/json
{
  • "current": true,
  • "label": "string",
  • "brand": {
    },
  • "model": { },
  • "actions": [
    ],
  • "available-optional": {
    },
  • "volumes": [
    ],
  • "storage-encryption": {
    }
}

Get system information

Retrieves a dictionary of server configuration and environment information.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

Get user accounts

Get information on user accounts on the system.

Authorizations:
PeerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Manage users

Create or remove local users on the system.

Authorizations:
PeerAuth
Request Body schema: application/json
required
action
required
string
Enum: "create" "remove"
email
string <email>
username
string
sudoer
boolean
Default: false

Whether the user can escalate to root privileges or not.

known
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "action": "create",
  • "email": "user@example.com",
  • "username": "string",
  • "sudoer": false,
  • "known": false
}

Response samples

Content type
application/json
[
  • {
    }
]

Get all enabled validation sets

Retrieves a list of all enabled validation sets on the system.

Read more about validation sets on the Canonical Snapcraft documentation.
Authorizations:
PeerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a specific validation set

Retrieves a single validation set by its account ID and name.

Authorizations:
PeerAuth
path Parameters
account-id
required
string
Example: ABCDEF12345678900987654321FEDCBA

The developer account ID for the validation set.

name
required
string
Example: myset1

The name of the validation set.

Responses

Response samples

Content type
application/json
{
  • "account-id": "string",
  • "name": "string",
  • "mode": "monitor",
  • "pinned-at": 0,
  • "sequence": 0,
  • "valid": true
}

Manage a specific validation set

Apply or forget a specific validation set.

Authorizations:
PeerAuth
path Parameters
account-id
required
string
Example: ABCDEF12345678900987654321FEDCBA

The developer account ID for the validation set.

name
required
string
Example: myset1

The name of the validation set.

Request Body schema: application/json
required
action
required
string
Enum: "apply" "forget"

The operation to perform on the validation set.

mode
string
Enum: "monitor" "enforce"

The mode to enable for the validation set. Required when action is 'apply'.

sequence
integer

When using 'apply': an optional sequence number to pin. When using 'forget': an optional sequence number to match before forgetting.

Responses

Request samples

Content type
application/json
{
  • "action": "apply",
  • "mode": "monitor",
  • "sequence": 1
}

Response samples

Content type
application/json
{
  • "account-id": "ABCDEF12345678900987654321FEDCBA",
  • "mode": "monitor",
  • "name": "myset1",
  • "pinned-at": 1,
  • "sequence": 1,
  • "valid": true
}

Get system warnings

Retrieves the current warnings in snapd.

query Parameters
select
string
Default: "pending"
Enum: "" "all" "pending"

Retrieve specific warnings. The default only shows pending warnings. All shows warnings that haven't expired or been cleaned.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": [
    ]
}

Respond to warnings

Warnings can only be acknowledged to clear them, but they may reoccur Acknowledging warnings does not fix the underlying cause.

Authorizations:
PeerAuth
Request Body schema: application/json
required
action
required
string
Value: "okay"
timestamp
required
string <date-time>

Time to clear warnings before (RFC3339 UTC format).

Responses

Request samples

Content type
application/json
{
  • "action": "okay",
  • "timestamp": "2025-09-08T17:29:40.829324752Z"
}

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": 0
}

Systems

Interact with system configuration.

Get the list of recovery systems

Retrieves a list of all available recovery systems on the device.

Responses

Response samples

Content type
application/json
{
  • "systems": [
    ]
}

Perform an action on the current recovery system or create a new one

Perform an action such as 'reboot', 'install' on the current active recovery system, or 'create' a new recovery system.

Authorizations:
PeerAuth
Request Body schema: application/json
required
One of
action
required
string
Value: "create"
label
required
string

A unique label for the new recovery system.

validation-sets
Array of strings

A list of validation set strings to use for creating the system.

test-system
boolean
Default: false

If true, creates the system as a test system.

mark-default
boolean
Default: false

If true, marks the new system as the default recovery system.

offline
boolean
Default: false

If true, performs the creation in offline mode.

Responses

Request samples

Content type
application/json
Example
{
  • "action": "create",
  • "label": "string",
  • "validation-sets": [
    ],
  • "test-system": false,
  • "mark-default": false,
  • "offline": false
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Get details for a specific recovery system

Retrieves detailed information for a single recovery system, including storage encryption status and available actions.

Authorizations:
PeerAuth
path Parameters
label
required
string

The label of the recovery system.

Responses

Response samples

Content type
application/json
{
  • "current": true,
  • "label": "string",
  • "brand": {
    },
  • "model": { },
  • "actions": [
    ],
  • "available-optional": {
    },
  • "volumes": [
    ],
  • "storage-encryption": {
    }
}

Perform an action on a specific recovery system

Perform an action on the recovery system identified by its label. The required parameters in the request body depend on the specified action.

Authorizations:
PeerAuth
path Parameters
label
required
string

The label of the recovery system.

Request Body schema: application/json
required
One of
action
required
string
Value: "do"
mode
required
string

The mode of the action to perform (e.g., 'recover', 'run').

title
string

The title of the custom action to perform.

Responses

Request samples

Content type
application/json
Example
{
  • "action": "do",
  • "mode": "string",
  • "title": "string"
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Get system information

Retrieves a dictionary of server configuration and environment information.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

Users

Manage user accounts and authentication.

Get user accounts

Get information on user accounts on the system.

Authorizations:
PeerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Manage users

Create or remove local users on the system.

Authorizations:
PeerAuth
Request Body schema: application/json
required
action
required
string
Enum: "create" "remove"
email
string <email>
username
string
sudoer
boolean
Default: false

Whether the user can escalate to root privileges or not.

known
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "action": "create",
  • "email": "user@example.com",
  • "username": "string",
  • "sudoer": false,
  • "known": false
}

Response samples

Content type
application/json
[
  • {
    }
]

Validation Sets

Interact with validation sets.

Get all enabled validation sets

Retrieves a list of all enabled validation sets on the system.

Read more about validation sets on the Canonical Snapcraft documentation.
Authorizations:
PeerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a specific validation set

Retrieves a single validation set by its account ID and name.

Authorizations:
PeerAuth
path Parameters
account-id
required
string
Example: ABCDEF12345678900987654321FEDCBA

The developer account ID for the validation set.

name
required
string
Example: myset1

The name of the validation set.

Responses

Response samples

Content type
application/json
{
  • "account-id": "string",
  • "name": "string",
  • "mode": "monitor",
  • "pinned-at": 0,
  • "sequence": 0,
  • "valid": true
}

Manage a specific validation set

Apply or forget a specific validation set.

Authorizations:
PeerAuth
path Parameters
account-id
required
string
Example: ABCDEF12345678900987654321FEDCBA

The developer account ID for the validation set.

name
required
string
Example: myset1

The name of the validation set.

Request Body schema: application/json
required
action
required
string
Enum: "apply" "forget"

The operation to perform on the validation set.

mode
string
Enum: "monitor" "enforce"

The mode to enable for the validation set. Required when action is 'apply'.

sequence
integer

When using 'apply': an optional sequence number to pin. When using 'forget': an optional sequence number to match before forgetting.

Responses

Request samples

Content type
application/json
{
  • "action": "apply",
  • "mode": "monitor",
  • "sequence": 1
}

Response samples

Content type
application/json
{
  • "account-id": "ABCDEF12345678900987654321FEDCBA",
  • "mode": "monitor",
  • "name": "myset1",
  • "pinned-at": 1,
  • "sequence": 1,
  • "valid": true
}

Warnings

Retrieve recorded warnings.

Get system warnings

Retrieves the current warnings in snapd.

query Parameters
select
string
Default: "pending"
Enum: "" "all" "pending"

Retrieve specific warnings. The default only shows pending warnings. All shows warnings that haven't expired or been cleaned.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": [
    ]
}

Respond to warnings

Warnings can only be acknowledged to clear them, but they may reoccur Acknowledging warnings does not fix the underlying cause.

Authorizations:
PeerAuth
Request Body schema: application/json
required
action
required
string
Value: "okay"
timestamp
required
string <date-time>

Time to clear warnings before (RFC3339 UTC format).

Responses

Request samples

Content type
application/json
{
  • "action": "okay",
  • "timestamp": "2025-09-08T17:29:40.829324752Z"
}

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": 0
}

Apps

Get the available app aliases

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

Modify aliases

Modify aliases by performing an 'alias', 'unalias', or 'prefer' action.

Authorizations:
PeerAuth
Request Body schema: application/json
required

The action to perform on an alias.

action
required
string
Enum: "alias" "unalias" "prefer"

The action to perform on the alias.

snap
string

The snap name to modify (optional for unalias).

app
string

The app to modify (optional).

alias
required
string

The alias to modify.

Responses

Request samples

Content type
application/json
{
  • "action": "alias",
  • "snap": "moon-buggy",
  • "app": "string",
  • "alias": "foo"
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

List available apps

Lists applications available from installed snaps. Can be filtered by services or snap names.

query Parameters
global
boolean

Defaults to true for the root user to preserve normal behavior and match snapctl functionality.

select
string
Value: "service"
Example: select=service

Limit which apps are returned.

names
string
Example: names=spotify, lxd

Comma-separated list of snap names to get apps for.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": {
    }
}

Modify attributes of applications

Perform actions like start, stop, or restart on snap applications, typically services.

Authorizations:
PeerAuth
Request Body schema: application/json
required

The action to perform on one or more applications.

action
required
string

The action to perform.

names
required
Array of strings

A list of names of snaps (e.g. "lxd") or specific apps (e.g. "lxd.daemon") to operate on.

scope
Array of strings
object
names
Array of strings
selector
string
Enum: "userX" "self" "all"

Internally converted to an integer by the servers marshalling/unmarshalling process

enable
boolean
Default: false

Arranges to have the service start at system boot.

Responses

Request samples

Content type
application/json
Example
{
  • "action": "start",
  • "names": [
    ],
  • "enable": true
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Sync

Retrieve all outstanding prompts

Retrieves a list of all outstanding access request prompts.

query Parameters
user-id
integer

Admin only: Specify a particular UID with which to identify when acting on the API, rather than the default, which is the UID of the client.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Quotas

Get all quota groups

Retrieves a list of all quota groups and their constraints.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Manage quota groups

Create, modify, or remove a quota group.

Authorizations:
PeerAuth
Request Body schema: application/json
required
action
required
string
Enum: "ensure" "remove"
required
object (QuotaGroup)

Defines a quota group for one or more snaps.

group-name
required
string

The name of the quota group.

subgroups
Array of strings

lists any subgroups this quota group contains.

parent
string

Contains the parent quota group name, if this group is a subgroup.

snaps
Array of strings

Lists any snaps that belong to this quota group.

services
string

Only for a subgroup, lists specific services belonging to a snap in the parent group.

object

The types and values of limits defined for this quota group.

memory
integer <int64>

Memory usage limit in bytes.

cpu
string

Includes percentage as a limit.

cpu-set
string

Per-cpu limits, with cpus listing included cores.

threads
integer

Maximum number of threads for this quota group.

object

Number of messages logged per time period.

object

Contains the current usage of memory and task quotas

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "action": "ensure",
  • "quota-group": {
    }
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Get a specific quota group

Retrieves the details for a single quota group by its name, or returns an error.

path Parameters
group-name
required
string

The name of the quota group.

Responses

Response samples

Content type
application/json
{
  • "group-name": "logmem",
  • "subgroups": [
    ],
  • "parent": "string",
  • "snaps": [
    ],
  • "services": "string",
  • "constraints": {
    },
  • "current": { }
}

Snapshots

Get a list of snapshots

Retrieves a list containing metadata for all snapshot sets stored on the system.

Responses

Response samples

Content type
application/json
{
  • "status-code": 200,
  • "status": "OK",
  • "type": "sync",
  • "result": [
    ]
}

Manipulate or import a snapshot

Performs an action on a snapshot set, such as restoring, checking, forgetting, or importing from a data stream.

Authorizations:
PeerAuth
Request Body schema:
required

The action to perform. Can be a JSON object for manipulation or a binary stream for import.

action
required
string
Enum: "restore" "check" "forget"
set
required
integer

The ID of the snapshot set to operate on.

snaps
Array of strings

An array of snap names to restrict the action to.

users
Array of strings

An array of user names to restrict the action to (disallowed for 'forget').

Responses

Request samples

Content type
{
  • "action": "restore",
  • "set": 0,
  • "snaps": [
    ],
  • "users": [
    ]
}

Response samples

Content type
application/json
{
  • "type": "async",
  • "status-code": 202,
  • "status": "Accepted",
  • "change": "61",
  • "result": null
}

Export a snapshot set

Retrieves a snapshot set as a downloadable tar archive (.tgz). The response body is a binary stream.

Authorizations:
PeerAuth
path Parameters
set-id
required
integer
Example: 2

The ID of the snapshot set to export.

Responses

Response samples

Content type
application/json
{
  • "status-code": 400,
  • "status": "Bad Request",
  • "type": "error",
  • "result": {
    }
}

System

Get system recovery key

Retrieve LUKS encryption keys when using full disk encryption on Ubuntu Core.

Authorizations:
PeerAuth

Responses

Response samples

Content type
application/json
{
  • "result": {
    }
}

Manage system recovery keys

Removes and resets LUKS encryption keys when using full disk encryption on Ubuntu Core devices.

Authorizations:
PeerAuth
Request Body schema: application/json
required
action
required
string
Value: "remove"

The only supported action is 'remove'.

Responses

Request samples

Content type
application/json
{
  • "action": "remove"
}

Response samples

Content type
application/json
{
  • "status-code": 400,
  • "status": "Bad Request",
  • "type": "error",
  • "result": {
    }
}