openapi: 3.2.0 info: title: Snapd REST Asynchronous API license: name: GPL-3.0 url: https://www.gnu.org/licenses/gpl-3.0.txt version: '1.0' description: 'The REST API provides access to snapd''s state and many of its key functions, as listed below. For general information on how to use the API, including how to access it, its requests and responses, results fields and error types, see Using the REST API.' servers: - url: unix:///run/snapd.socket description: 'Local snapd socket access. Unless otherwise specified, routes appear on this socket.' - url: unix:///run/snapd-snap.socket description: Snapd socket access for snaps tags: - name: Asynchronous description: Return the reference to a change that will occur in the background. paths: /v2/confdb/{account}/{confdb-schema}/{view}: parameters: - name: account in: path required: true schema: type: string example: system - name: confdb-schema in: path required: true schema: type: string example: network - name: view in: path required: true schema: type: string examples: admin: value: wifi-admin summary: Write/control access state: value: wifi-state summary: Read-only access get: tags: - Asynchronous summary: Get configurations from confdb description: Retrieves configuration values from confdb. operationId: getConfdb security: - PeerAuth: [] parameters: - name: keys in: query description: 'A comma-separated list of configuration paths to read from. These paths refer to rules defined in the view specified in the URL. If no list is provided, the GET will match with all readable view rules and return any stored values for those. If there are no stored configuration values for a subset of the fields, those fields will be omitted from the result object.' schema: type: string responses: '202': $ref: '#/components/responses/Accepted' '400': $ref: '#/components/responses/BadRequest' put: tags: - Asynchronous summary: Set configurations in confdb description: Sets configuration values in confdb. operationId: setConfdb security: - PeerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - values properties: values: type: object description: 'A map of configuration paths to JSON values to be set. Use null to unset a value.' additionalProperties: true example: values: office.ssid: foo password: null responses: '202': $ref: '#/components/responses/Accepted' '400': $ref: '#/components/responses/BadRequest' /v2/interfaces: post: tags: - Asynchronous summary: Issue an action to the interface system description: 'Used to connect and disconnect interfaces. Issues a command to the interface system to operate on the specified plug and slot.' operationId: postInterfaces security: - PeerAuth: [] requestBody: description: Parameters for the interface action. required: true content: application/json: schema: type: object properties: action: type: string description: Action to perform. enum: - connect - disconnect forget: type: boolean description: 'Used with the ''disconnect'' action. Ensures the system does not reestablish the connection going forward. ' slots: type: array minItems: 1 maxItems: 1 items: $ref: '#/components/schemas/Slot' plugs: type: array minItems: 1 maxItems: 1 items: $ref: '#/components/schemas/Plug' responses: '202': $ref: '#/components/responses/Accepted' '400': $ref: '#/components/responses/BadRequest' /v2/quotas: post: tags: - Asynchronous summary: Manage quota groups description: Create, modify, or remove a quota group. operationId: manageQuotaGroups security: - PeerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - action - quota-group properties: action: type: string enum: - ensure - remove quota-group: $ref: '#/components/schemas/QuotaGroup' responses: '202': $ref: '#/components/responses/Accepted' '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' /v2/snaps: post: tags: - Asynchronous summary: Manage snaps description: 'Install, refresh, revert, remove, enable, disable, or perform other actions on snaps. This endpoint supports both standard JSON requests for store operations and multipart/form-data for sideloading snaps.' operationId: manageSnaps security: - PeerAuth: [] requestBody: description: The body of the JSON request. required: true content: application/json: schema: type: object required: - action properties: action: type: string enum: - install - refresh - remove - revert - hold - unhold - enable - disable - switch - snapshot snaps: type: array items: type: string quota-group: type: string description: The quota group the snap belongs to. unaliased: type: boolean prefer: type: boolean description: Cannot be used with 'unaliased' classic: type: boolean description: Whether the snap uses classic confinement or not. devmode: type: boolean description: Whether the snap should be installed in developer mode or not. jailmode: type: boolean description: 'Set to true to install the snap in jail mode. Only non-classic snaps can be placed in jail mode.' ignore-running: type: boolean components: type: string description: 'This parameter is a mapping of a string to a string array. If a snap is installed, it will install the requested components for it. If the snap is not installed, the snap will be installed along with requested components.' format: map[string][]string example: '{ "firefox": ["firefox+comp"]}' transaction: type: string enum: - per-snap - all-snaps multipart/form-data: schema: type: object properties: action: type: string enum: - install - try default: install snap: type: string format: binary description: 'The content of a .snap file. This field may because repeated many times to act on multiple snaps.' snap-path: type: string description: 'The path to install the snap to. This parameter may only be used with a single ''snap'' field.' name: type: string description: This parameter may only be used with a single 'snap' field. component-name: type: string description: This parameter may only be used with a single 'snap' field. transaction: type: string enum: - per-snap - all-snaps dangerous: type: boolean description: Whether to install the snap with the '--dangerous' flag or not. devmode: type: boolean description: Whether the snap should be installed in developer mode or not. quota-group: type: string description: The quota group the snap belongs to. ignore-running: type: boolean jailmode: type: boolean description: 'Set to true to install the snap in jail mode. Only non-classic snaps can be placed in jail mode.' classic: type: boolean description: Whether the snap uses classic confinement or not. responses: '202': $ref: '#/components/responses/Accepted' '400': $ref: '#/components/responses/BadRequest' /v2/snaps/{name}: parameters: - name: name in: path required: true description: The name of the snap. schema: type: string post: tags: - Asynchronous summary: Manage a specific snap description: Perform an action (install, refresh, remove, etc.) on a single, specific snap. operationId: manageSnapByName security: - PeerAuth: [] requestBody: description: The action and options for the snap. required: true content: application/json: schema: type: object required: - action properties: action: type: string enum: - install - refresh - remove - revert - enable - disable - switch - hold - unhold channel: type: string description: The channel to use for the action. example: beta revision: type: string description: A specific revision to install or revert to. classic: type: boolean devmode: type: boolean purge: type: boolean description: If true, don't save a snapshot of data on removal. terminate: type: boolean description: If true, kill running processes before removal. components: type: array items: type: string responses: '202': $ref: '#/components/responses/Accepted' '400': $ref: '#/components/responses/BadRequest' /v2/snaps/{name}/conf: put: tags: - Asynchronous summary: Set snap configuration description: Set the configuration details for an installed snap. Use 'system' as the name to set system options. operationId: setSnapConfig security: - PeerAuth: [] parameters: - name: name in: path required: true description: The name of the snap or the reserved name 'system'. schema: type: string requestBody: required: true description: A JSON map of configuration keys and values. Dotted keys can be used. Use a null value to unset an option. content: application/json: schema: type: object additionalProperties: true example: conf-key1: conf-value1 dotted.key: conf-value2 key-to-unset: null responses: '202': description: The configuration update has been accepted and is being processed in the background. '400': $ref: '#/components/responses/BadRequest' /v2/snapshots: post: tags: - Asynchronous summary: Manipulate or import a snapshot description: Performs an action on a snapshot set, such as restoring, checking, forgetting, or importing from a data stream. operationId: manageSnapshots security: - PeerAuth: [] requestBody: description: The action to perform. Can be a JSON object for manipulation or a binary stream for import. required: true content: application/json: schema: type: object description: Used for snapshot manipulation actions. required: - action - set properties: action: type: string enum: - restore - check - forget set: type: integer description: The ID of the snapshot set to operate on. snaps: type: array description: An array of snap names to restrict the action to. items: type: string users: type: array description: An array of user names to restrict the action to (disallowed for 'forget'). items: type: string application/x.snapd.snapshot: schema: type: string format: binary description: A tar archive of an exported snapshot, used only to import a snapshot with the 'import' action. responses: '202': $ref: '#/components/responses/Accepted' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessDenied' '404': $ref: '#/components/responses/NotFound' components: schemas: QuotaGroup: type: object description: Defines a quota group for one or more snaps. required: - group-name properties: group-name: type: string description: The name of the quota group. example: logmem subgroups: type: array items: type: string description: lists any subgroups this quota group contains. parent: type: string description: Contains the parent quota group name, if this group is a subgroup. snaps: type: array items: type: string description: Lists any snaps that belong to this quota group. services: type: string description: Only for a subgroup, lists specific services belonging to a snap in the parent group. constraints: type: object description: The types and values of limits defined for this quota group. properties: memory: type: integer format: int64 description: Memory usage limit in bytes. example: 32768 cpu: type: string description: Includes percentage as a limit. cpu-set: type: string description: Per-cpu limits, with cpus listing included cores. threads: type: integer description: Maximum number of threads for this quota group. example: 2 journal: type: object description: Number of messages logged per time period. properties: size: type: integer format: int64 rate-count: type: integer rate-period: type: integer current: type: object description: Contains the current usage of memory and task quotas additionalProperties: true NoSerialAssertionError: type: object description: The serial assertion has not been created yet. properties: kind: type: string description: machine-readable definition of the error. enum: - assertion-not-found message: type: string description: Human-readable string describing the error. enum: - no serial assertion yet value: type: string description: Value passed that triggered the error. enum: - serial NotFoundError: type: object properties: message: type: string example: no snapshot set with the given ID SnapNotInstalledError: type: object description: The snap does not exist on the system. properties: kind: type: string description: machine-readable definition of the error. enum: - snap-not-found - snap-not-installed message: type: string description: Human-readable string describing the error. example: no state entry for key value: type: string description: Value passed that triggered the error. example: firefox NoSSHKeysError: type: object properties: message: type: string example: 'cannot create user user@canonical.com: no ssh keys found' NoModelAssertionError: type: object description: The model assertion has not been created yet. properties: kind: type: string description: machine-readable definition of the error. enum: - assertion-not-found message: type: string description: Human-readable string describing the error. enum: - no model assertion yet value: type: string description: Value passed that triggered the error. enum: - model Plug: type: object description: Detailed information about a plug. properties: snap: type: string description: The name of the snap providing the plug. plug: type: string description: The name of the plug itself. interface: type: string description: The interface name for the plug. attrs: type: object additionalProperties: true description: 'A static map of the plug''s attributes. These are attributes that belong to the plug' apps: type: array items: type: string description: A list of apps associated with this plug. label: type: string description: The display label for the plug. connections: type: array items: $ref: '#/components/schemas/SlotRef' description: A list of slots this plug is connected to. MalformedRequestError: type: object properties: message: type: string example: cannot decode request body into an alias action ConfdbError: type: object description: An error occured while interacting with confdb. properties: kind: type: string description: machine-readable definition of the error. enum: - option-not-available - option-not-found - assertion-not-found message: type: string description: Human-readable string describing the error. example: 'cannot get ''ssid'' through canonical/network/wifi-setup: no data' SlotRef: type: object description: A reference to a specific slot. properties: snap: type: string description: The name of the snap providing the slot. slot: type: string description: The name of the slot. Slot: type: object description: Detailed information about a slot. properties: snap: type: string description: The name of the snap providing the slot. slot: type: string description: The name of the slot itself. interface: type: string description: The interface name for the slot. attrs: type: object additionalProperties: true description: 'A static map of the slot''s attributes. These are attributes that belong to the slot' apps: type: array items: type: string description: A list of apps associated with this slot. label: type: string description: The display label for the slot. connections: type: array items: $ref: '#/components/schemas/PlugRef' description: A list of plugs connected to this slot. UserNotFoundError: type: object properties: message: type: string example: 'cannot create user user@canonical.com: cannot find user user@canonical.com' PlugRef: type: object description: A reference to a specific plug. properties: snap: type: string description: The name of the snap providing the plug. plug: type: string description: The name of the plug. responses: AccessDenied: description: "Access Denied. The daemon/store cannot or will not process the request because \nthe user does not have the correct authorization from the system." content: application/json: schema: type: object properties: status-code: type: integer description: The HTTP status code. enum: - 401 status: type: string description: The textual representation of the status code. enum: - Unauthorized type: type: string description: The type of response. enum: - error result: type: object properties: kind: type: string description: A machine-readable string identifying the error type. enum: - login-required message: type: string description: A human-readable error message. enum: - access denied Accepted: description: The asynchronous request was accepted and is being processed. content: application/json: schema: type: object description: The response for an accepted asynchronous operation. properties: type: type: string enum: - async status-code: type: integer enum: - 202 status: type: string enum: - Accepted change: type: string description: The ID of the background change that was initiated. This is a string because JSON only uses floats. example: '61' result: type: - object - 'null' description: For an accepted async operation, this is always null as the result is not yet available. example: null BadRequest: description: 'Bad Request. The request could not be processed due to a client-side error. This can be due to malformed syntax or providing an entity that does not exist.' content: application/json: schema: type: object properties: status-code: type: integer enum: - 400 status: type: string enum: - Bad Request type: type: string enum: - error result: oneOf: - $ref: '#/components/schemas/ConfdbError' - $ref: '#/components/schemas/MalformedRequestError' - $ref: '#/components/schemas/NoSSHKeysError' - $ref: '#/components/schemas/UserNotFoundError' - $ref: '#/components/schemas/SnapNotInstalledError' NotFound: description: 'Not Found. The requested resource could not be found. Can refer to either a local or remote resource' content: application/json: schema: type: object properties: status-code: type: integer enum: - 404 status: type: string enum: - Not Found type: type: string enum: - error result: oneOf: - $ref: '#/components/schemas/NoModelAssertionError' - $ref: '#/components/schemas/NoSerialAssertionError' - $ref: '#/components/schemas/NotFoundError' - $ref: '#/components/schemas/UserNotFoundError' - $ref: '#/components/schemas/SnapNotInstalledError' Forbidden: description: 'Forbidden. The server understood the request but refuses to authorize it because the authenticated user lacks the necessary permissions for the target resource.' content: application/json: schema: type: object properties: status-code: type: integer enum: - 403 status: type: string enum: - Forbidden type: type: string enum: - error result: type: object properties: kind: type: string enum: - auth-cancelled message: type: string enum: - cancelled securitySchemes: PeerAuth: type: apiKey in: header name: X-PEER-CREDENTIALS description: '**Unix Socket Peer Authentication** Authentication is not handled via traditional HTTP headers or tokens. Instead, it is managed at the operating system level using Unix domain socket peer credentials (e.g., `SO_PEERCRED` on Linux). **How It Works:** 1. The API server listens on a local Unix domain socket. 2. When a client connects to this socket, the server can ask the operating system kernel for the client process''s credentials. 3. The kernel securely provides the client''s User ID (UID), Group ID (GID), and Process ID (PID). Authorization decisions are then based on this trusted, kernel-provided UID. For example, access may be restricted to only the `root` user (UID 0).' externalDocs: url: https://snapcraft.io/docs description: Snap and Snapcraft documentation