The local REST API exposed by snapd over a Unix domain socket on every Ubuntu system running snaps. Enables local clients and tools to query snap state, install / refresh / remove snaps, manage interfaces and connections, and read system information.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/snapd-rest-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.0.3
info:
title: Snapd REST API
license:
name: GPL-3.0
url: https://www.gnu.org/licenses/gpl-3.0.txt
version: '1.0'
description: |
The REST API provides access to snapd's state and many of its key functions,
as listed below.
For general information on how to use the API, including how to access it,
its requests and responses, results fields and error types, see [Using the
REST API](https://snapcraft.io/docs/how-to-guides/snap-development/use-the-rest-api/).
servers:
- url: unix:///run/snapd.socket
description: |-
Local snapd socket access. Unless otherwise specified, routes appear on
this socket.
- url: unix:///run/snapd-snap.socket
description: Snapd socket access for snaps
tags:
- name: Assertions
description: List and add assertion types.
- name: Asynchronous
description: Return the reference to a change that will occur in the background.
- name: AuthenticationRequired
description: Access is restricted to the root user.
- name: Changes
description: Interact with changes.
- name: Experimental
description: Interact with experimental features.
- name: Interfaces
description: Display and manage interactions between snaps.
- name: Notices
description: Interact with notices.
- name: OpenAccess
description: Do not require the user to authenticate.
- name: Prompting
description: Interact with the prompting system.
- name: Root
description: Requires the user to authenticate with root access.
- name: Snaps
description: Interact with snaps.
- name: Store
description: Interact with the store.
- name: Synchronous
description: Return the complete response synchronously.
- name: Systems
description: Interact with system configuration.
- name: Users
description: Manage user accounts and authentication.
- name: Validation Sets
description: Interact with validation sets.
- name: Warnings
description: Retrieve recorded warnings.
externalDocs:
url: https://snapcraft.io/docs
description: Snap and Snapcraft documentation
paths:
/v2/aliases:
get:
operationId: getAliases
summary: Get the available app aliases
tags:
- Apps
- OpenAccess
- Synchronous
security: []
responses:
'200':
description: A dictionary containing the aliases for each snap.
content:
application/json:
schema:
type: object
properties:
status-code:
type: integer
description: |
The status-code property contains the HTTP response value.
enum:
- 200
status:
type: string
description: |
The status property contains the textual representation of the 'status-code' property.
For the 'status-code' equal to 200, the 'status' is always 'OK'
enum:
- OK
type:
type: string
description: |
The type property indicates that this is a synchronous API response and the whole content
is now available. The result of the API call is in the result object. The value is always
'sync'.
enum:
- sync
result:
type: object
description: |
The result object contains information about all the aliases in the system.
additionalProperties:
type: object
description: |
Each top-level property is a snap instance name. Typically snap instance is
the name of the snap, except when parallel-instances as used and the snap name
is followed by an underscore and then the instance key.
additionalProperties:
type: object
description: |
Each top-level property under the snap name above, is the name of the actual alias.
The alias is visible as a top-level command and is exposed on PATH in the system.
required:
- command
- status
properties:
command:
type: string
description: |
The name of the snap entry-point executable invoked by this alias.
This is typically the name of the snap followed by dot and then the name
of the application within the snap. It may also be just the name of the snap.
status:
type: string
description: |
Status describes the status of the alias. The value 'manual' indicates that the
status was created manually by the user. The status 'disabled' indicates the user
manually removed the alias (it will not be re-created automatically by snapd).
The status 'auto' indicates that the alias was created automatically by snapd.
enum:
- auto
- manual
- disabled
auto:
type: string
description: |
The app the alias is for as assigned by an assertion
manual:
type: string
description: |
The app the alias is for if status is manual.
Overrides auto
4XX:
$ref: '#/components/responses/InternalError'
post:
tags:
- Apps
- Asynchronous
- AuthenticationRequired
summary: Modify aliases
description: Modify aliases by performing an 'alias', 'unalias', or 'prefer' action.
operationId: modifyAliases
security:
- PeerAuth: []
requestBody:
description: The action to perform on an alias.
required: true
content:
application/json:
schema:
type: object
required:
- action
- alias
properties:
action:
type: string
description: The action to perform on the alias.
enum:
- alias
- unalias
- prefer
snap:
type: string
description: The snap name to modify (optional for unalias).
example: moon-buggy
app:
type: string
description: The app to modify (optional).
alias:
type: string
description: The alias to modify.
example: foo
responses:
'202':
$ref: '#/components/responses/Accepted'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessDenied'
'409':
$ref: '#/components/responses/Conflict'
/v2/apps:
get:
tags:
- Apps
- OpenAccess
- Synchronous
summary: List available apps
description: Lists applications available from installed snaps. Can be filtered by services or snap names.
operationId: listApps
security: []
parameters:
- name: global
in: query
description: Defaults to true for the root user to preserve normal behavior and match snapctl functionality.
schema:
type: boolean
- name: select
in: query
description: Limit which apps are returned.
schema:
type: string
enum:
- service
example: service
- name: names
in: query
description: Comma-separated list of snap names to get apps for.
schema:
type: string
example: spotify, lxd
responses:
'200':
description: A synchronous response containing the connection status of plugs and slots.
content:
application/json:
schema:
type: object
properties:
status-code:
type: integer
enum:
- 200
status:
type: string
enum:
- OK
type:
type: string
enum:
- sync
result:
$ref: '#/components/schemas/App'
4XX:
$ref: '#/components/responses/InternalError'
post:
tags:
- Apps
- Asynchronous
- AuthenticationRequired
summary: Modify attributes of applications
description: Perform actions like start, stop, or restart on snap applications, typically services.
operationId: modifyApps
security:
- PeerAuth: []
requestBody:
description: The action to perform on one or more applications.
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/AppActionStart'
- $ref: '#/components/schemas/AppActionStop'
- $ref: '#/components/schemas/AppActionRestart'
discriminator:
propertyName: action
mapping:
start: '#/components/schemas/AppActionStart'
stop: '#/components/schemas/AppActionStop'
restart: '#/components/schemas/AppActionRestart'
responses:
'202':
$ref: '#/components/responses/Accepted'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessDenied'
'404':
$ref: '#/components/responses/NotFound'
/v2/assertions:
get:
tags:
- Assertions
- OpenAccess
- Synchronous
summary: Get the list of assertion types
description: Retrieves a list of all known assertion types in the system.
operationId: listAssertionTypes
security: []
responses:
'200':
description: A list of available assertion types.
content:
application/json:
schema:
type: object
properties:
status-code:
type: integer
enum:
- 200
status:
type: string
enum:
- OK
type:
type: string
enum:
- sync
result:
type: object
properties:
types:
type: array
items:
type: string
enum:
- account
- account-key
- account-key-request
- base-declaration
- confdb-control
- confdb-schema
- cluster
- device-session-request
- hardware-identity
- model
- preseed
- repair
- request-message
- response-message
- serial
- serial-request
- snap-build
- snap-declaration
- snap-developer
- snap-resource-pair
- snap-resource-revision
- snap-revision
- store
- system-user
- validation
- validation-set
4XX:
$ref: '#/components/responses/InternalError'
post:
tags:
- Assertions
- AuthenticationRequired
- Synchronous
summary: Attempt to add or replace an assertion
description: |-
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.
operationId: addAssertion
security:
- PeerAuth: []
requestBody:
description: The raw assertion text to add to the database.
required: true
content:
application/x.ubuntu.assertion:
schema:
type: string
description: A raw assertion string.
example: |
type: system-user
authority-id: canonical
series: 16
brand-id: canonical
...
sign-key-sha3-384: <key>
<signature>
responses:
'200':
description: The assertion was successfully added.
'400':
$ref: '#/components/responses/BadRequest'
/v2/assertions/{assertion-type}:
parameters:
- name: assertion-type
in: path
required: true
description: The type of assertion to retrieve.
schema:
type: string
example: account
get:
tags:
- Assertions
- OpenAccess
- Synchronous
summary: Get assertions of a given type
description: |-
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.
operationId: getAssertionsByType
security: []
parameters:
- name: remote
in: query
description: |-
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
schema:
type: boolean
default: false
- name: json
in: query
description: |-
If true, the response is formatted as a JSON object containing the
headers of the assertions instead of the default signed assertion
stream format.
schema:
type: boolean
default: false
responses:
'200':
description: |-
The response format depends on the `json` query parameter.
- By default (`json=false`), returns a stream of signed assertions.
- When `json=true`, returns a single JSON object.
headers:
X-Ubuntu-Assertions-Count:
description: |-
The total number of assertions returned in the stream.
(Only present for `application/x-ubuntu-assertion-stream` responses).
schema:
type: integer
content:
application/x-ubuntu-assertion-stream:
schema:
type: string
description: |-
A string containing one or more signed assertions, each separated
by double newlines. This is the default response format.
example: |
type: account
authority-id: canonical
account-id: canonical
display-name: canonical
timestamp: 2016-04-01T00:00:00.0Z
username: canonical
validation: certified
sign-key-sha3-384: <key>
<signature>
application/json:
schema:
$ref: '#/components/schemas/AssertionResult'
'400':
$ref: '#/components/responses/BadRequest'
/v2/changes:
get:
tags:
- AuthenticationRequired
- Changes
- Synchronous
summary: Get all changes
description: Retrieves a list of all changes in progress or completed on the system.
operationId: getChanges
security:
- PeerAuth: []
parameters:
- name: select
in: query
description: Limit which changes are returned.
schema:
type: string
enum:
- all
- in-progress
- ready
default: in-progress
- name: for
in: query
description: Optional snap name to limit results to.
schema:
type: string
responses:
'200':
description: |-
A synchronous response containing all the changes that have occurred,
and have not been garbage-collected yet.
content:
application/json:
schema:
type: object
properties:
status-code:
type: integer
enum:
- 200
status:
type: string
enum:
- OK
type:
type: string
enum:
- sync
result:
type: array
items:
$ref: '#/components/schemas/Change'
'400':
$ref: '#/components/responses/BadRequest'
/v2/changes/{id}:
parameters:
- name: id
in: path
required: true
description: The ID of the change to retrieve.
schema:
type: string
get:
tags:
- AuthenticationRequired
- Changes
- Synchronous
summary: Get the status of a change
description: Retrieves the current status of a specific background change by its ID.
operationId: getChangeById
security:
- PeerAuth: []
responses:
'200':
description: The current status of the change.
content:
application/json:
schema:
$ref: '#/components/schemas/Change'
'404':
$ref: '#/components/responses/NotFound'
post:
tags:
- AuthenticationRequired
- Changes
- Synchronous
summary: Abort a change
description: Aborts a change that is currently in progress.
operationId: abortChangeById
security:
- PeerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- action
properties:
action:
type: string
enum:
- abort
responses:
'200':
description: The change was successfully aborted. The response body contains the final state of the change.
content:
application/json:
schema:
$ref: '#/components/schemas/Change'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
/v2/cohorts:
post:
tags:
- AuthenticationRequired
- Synchronous
summary: Create cohort keys
description: Creates a set of cohort keys for a given set of snaps.
operationId: createCohorts
security:
- PeerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- action
- snaps
properties:
action:
type: string
enum:
- create
snaps:
type: array
description: An array of snap names to create cohorts for.
items:
type: string
example:
- libreoffice
- lxd
- multipass
responses:
'200':
description: A map of snap names to their newly created cohort keys.
content:
application/json:
schema:
type: object
required:
- cohorts
properties:
cohorts:
type: object
description: An object mapping each snap name to its corresponding cohort key string.
additionalProperties:
type: string
description: The generated cohort key for the snap.
example:
cohorts:
core24: MSBkd1RBaDdNWlowMXp5cmlPWkVycWQxSnluUUxpT0d2TSAxNzU5NDIxNjg0IDc3Yzk1ODllNDYxNzEwNDUwZWZiNjE5YjMwNmJiMzJlMmJiZTlkMzNmOGRlMmIwYmQzNmQ4ZWEyYjcwNGNmZmI=
snapd: MSBQTXJyVjRtbDh1V3VFVURCVDhkU0duS1VZYmV2VmhjNCAxNzU5NDIxNjg0IDU1YzdjZWRkZWJhNjFkNjIxMjU3ZTAwMDYxMjllZWJkYjE4N2Y3YTE0MTc0NmM2NjAyM2IyYWY4ZDY2MzRlZDU=
'400':
$ref: '#/components/responses/BadRequest'
/v2/confdb:
post:
tags:
- Experimental
- AuthenticationRequired
- Synchronous
summary: Delegate remote confdb management to operators
description: |-
Grants or withdraws an operator's ability to remotely manage confdb values
on the device.
Use the `delegate` action to allow an operator to remotely manage specific
confdb views using the specified authentication methods.
Use the `undelegate` action to withdraw this ability. Omit `views` or
`authentications` to withdraw all views or all authentication methods
respectively.
operationId: postConfdbControl
security:
- PeerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConfdbControlAction'
examples:
delegate:
summary: Delegate access to an operator
value:
action: delegate
operator-id: alice
authentications:
- operator-key
- store
views:
- bob/network/wifi-admin
- bob/network/wifi-state
undelegate:
summary: Withdraw all access from an operator
value:
action: undelegate
operator-id: alice
undelegatePartial:
summary: Withdraw access to specific views
value:
action: undelegate
operator-id: alice
authentications:
- store
views:
- bob/network/wifi-admin
responses:
'200':
description: The confdb-control assertion was updated successfully.
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum:
- sync
status-code:
type: integer
enum:
- 200
status:
type: string
enum:
- OK
result:
type: object
nullable: true
example: null
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessDenied'
/v2/confdb/{account}/{confdb-schema}/{view}:
parameters:
- name: account
in: path
required: true
schema:
type: string
example: system
- name: confdb-schema
in: path
required: true
schema:
type: string
example: network
- name: view
in: path
required: true
schema:
type: string
examples:
admin:
value: wifi-admin
summary: Write/control access
state:
value: wifi-state
summary: Read-only access
get:
tags:
- Asynchronous
- AuthenticationRequired
- Experimental
summary: Get configurations from confdb
description: Retrieves configuration values from confdb.
operationId: getConfdb
security:
- PeerAuth: []
parameters:
- name: keys
in: query
description: |-
A comma-separated list of configuration paths to read from. These paths
refer to rules defined in the view specified in the URL. If no list is
provided, the GET will match with all readable view rules and return any
stored values for those. If there are no stored configuration values for
a subset of the fields, those fields will be omitted from the result
object.
schema:
type: string
responses:
'202':
$ref: '#/components/responses/Accepted'
'400':
$ref: '#/components/responses/BadRequest'
put:
tags:
- Asynchronous
- AuthenticationRequired
- Experimental
summary: Set configurations in confdb
description: Sets configuration values in confdb.
operationId: setConfdb
security:
- PeerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- values
properties:
values:
type: object
description: |-
A map of configuration paths to JSON values to be set.
Use null to unset a value.
additionalProperties: true
example:
values:
office.ssid: foo
password: null
responses:
'202':
$ref: '#/components/responses/Accepted'
'400':
$ref: '#/components/responses/BadRequest'
/v2/connections:
get:
tags:
- Interfaces
- OpenAccess
- Synchronous
summary: Get all interface connections
description: Retrieves the connection status of all plugs and slots on the system.
operationId: getConnections
security: []
parameters:
- name: snap
in: query
description: Limit results to a given snap name.
schema:
type: string
- name: select
in: query
description: |-
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.
schema:
type: string
enum:
- ''
- all
- name: interface
in: query
description: Limit results to a specific interface name.
schema:
type: string
responses:
'200':
description: A synchronous response containing the connection status of plugs and slots.
content:
application/json:
schema:
type: object
properties:
status-code:
type: integer
enum:
- 200
status:
type: string
enum:
- OK
type:
type: string
enum:
- sync
result:
$ref: '#/components/schemas/ConnectionStatus'
'400':
$ref: '#/components/responses/BadRequest'
/v2/find:
get:
tags:
- AuthenticationRequired
- OpenAccess
- Store
- Synchronous
summary: Find snaps in the store
description: |-
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.
operationId: findSnaps
security: []
parameters:
- name: q
in: query
description: |-
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.
schema:
type: string
- name: name
in: query
description: |-
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.
schema:
type: string
- name: scope
in: query
description: If set to 'wide', broadens the search to include non-stable packages.
schema:
type: string
enum:
- wide
- name: section
in: query
description: |-
The name of a store section to search within.
Use GET /v2/sections to get the names of the sections.
schema:
type: string
- name: select
in: query
description: |-
Alter the collection searched.
refresh - search refreshable snaps. Cannot be used with q, no
# --- truncated at 32 KB (180 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/canonical/refs/heads/main/openapi/canonical-snapd-rest-api-openapi.yml