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: 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: 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, nor name. private - search private snaps (by default, find only searches public snaps). Cannot be used with name, only q (for now at least). schema: type: string enum: - refresh - private - name: common-id in: query description: |- Search for packages using the common-id attribute. This is often the application name used by other packaging formats. schema: type: string example: org.videolan.vlc responses: '200': description: A list of snaps from the store that match the search criteria. content: application/json: schema: type: array items: $ref: '#/components/schemas/Snap' '400': $ref: '#/components/responses/BadRequest' /v2/icons/{name}/icon: parameters: - name: name in: path required: true description: The name of the snap to get the icon for. schema: type: string get: tags: - OpenAccess - Synchronous - Snaps summary: Get a snap's icon description: |- 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. operationId: getSnapIcon security: [] responses: '200': description: The raw icon file. The Content-Type will be set appropriately. headers: Accept-Ranges: schema: type: string example: bytes Content-Type: description: The media type of the icon file, for example 'image/svg+xml' or 'image/png'. schema: type: string enum: - image/jpeg - image/png - image/svg+xml Content-Disposition: description: Indicates that the content is expected to be downloaded as a file; specifies the filename. schema: type: string example: attachment; filename="icon.svg" Content-Length: description: The size of the icon file in bytes. schema: type: integer example: 1623 content: image/svg+xml: schema: type: string format: binary image/png: schema: type: string format: binary image/jpeg: schema: type: string format: binary '404': $ref: '#/components/responses/NotFound' /v2/interfaces: get: tags: - Interfaces - OpenAccess - Synchronous summary: Get available interfaces description: Retrieves the available interfaces and their associated metadata. operationId: getInterfaces security: [] parameters: - name: select in: query description: |- 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). schema: type: string enum: - all - connected - name: slots in: query description: If set to true, slot information will be returned. schema: type: boolean - name: plugs in: query description: If set to true, plug information will be returned. schema: type: boolean - name: doc in: query description: If set to true, interface documentation will be returned. schema: type: boolean - name: names in: query description: |- 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. schema: type: string example: content responses: '200': description: |- For non-legacy calls, returns an array of interface information. For legacy calls, returns an array of interface objects. content: application/json: schema: type: object properties: status-code: type: integer example: 200 status: type: string example: OK type: type: string example: sync result: oneOf: - $ref: '#/components/schemas/LegacyInterfaceObject' - $ref: '#/components/schemas/ModernInterfaceObject' '400': $ref: '#/components/responses/BadRequest' post: tags: - Asynchronous - AuthenticationRequired - Interfaces 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/interfaces/requests/prompts: get: tags: - Experimental - Interfaces - OpenAccess - Prompting - Sync summary: Retrieve all outstanding prompts description: Retrieves a list of all outstanding access request prompts. operationId: getPrompts security: [] parameters: - $ref: '#/components/parameters/UserId' responses: '200': description: An array of prompt objects. content: application/json: schema: type: array items: $ref: '#/components/schemas/PromptingPrompt' '404': $ref: '#/components/responses/NotFound' /v2/interfaces/requests/prompts/{id}: get: tags: - Experimental - Interfaces - OpenAccess - Prompting - Synchronous summary: Retrieve a prompt by ID description: Retrieves the details of a single prompt specified by its unique ID. operationId: getPromptById security: [] parameters: - name: id in: path required: true description: The unique identifier of the prompt to retrieve. schema: type: string - $ref: '#/components/parameters/UserId' responses: '200': description: The details of the requested prompt. content: application/json: schema: $ref: '#/components/schemas/PromptingPrompt' '404': $ref: '#/components/responses/NotFound' post: tags: - Experimental - Interfaces - OpenAccess - Prompting - Synchronous summary: Reply to a prompt description: |- Submit a reply (allow or deny) to an outstanding prompt, potentially creating a new rule. operationId: replyToPrompt security: [] parameters: - name: id in: path required: true description: The unique identifier of the prompt to which to reply. schema: type: string - $ref: '#/components/parameters/UserId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PromptingReply' responses: '200': description: An array of prompt IDs that were also satisfied by this reply. content: application/json: schema: type: array items: type: string '404': $ref: '#/components/responses/NotFound' /v2/interfaces/requests/rules: get: tags: - Experimental - Interfaces - OpenAccess - Prompting - Synchronous summary: Retrieve all rules description: Retrieves a list of all prompting rules, with optional filtering. operationId: getRules security: [] parameters: - name: snap in: query required: false description: Only retrieve rules which apply to the given snap. schema: type: string - name: interface in: query required: false description: Only retrieve rules which apply to the given interface. schema: type: string - $ref: '#/components/parameters/UserId' responses: '200': description: An array of rule objects. content: application/json: schema: type: array items: $ref: '#/components/schemas/PromptingRule' '404': $ref: '#/components/responses/NotFound' post: tags: - Experimental - Interfaces - OpenAccess - Prompting - Synchronous summary: Create or remove rules description: Create a new access rule or remove a set of existing rules based on a selector. operationId: manageRules security: [] parameters: - $ref: '#/components/parameters/UserId' requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/PromptingRuleActionAdd' - $ref: '#/components/schemas/PromptingRuleActionRemove' responses: '200': description: The created rule (for 'add' action) or an array of removed rules (for 'remove' action). content: application/json: schema: oneOf: - $ref: '#/components/schemas/PromptingRule' - type: array items: $ref: '#/components/schemas/PromptingRule' '404': $ref: '#/components/responses/NotFound' /v2/interfaces/requests/rules/{id}: get: tags: - Experimental - Interfaces - OpenAccess - Prompting - Synchronous summary: Retrieve a rule by ID description: Retrieves the details of a single rule specified by its unique ID. operationId: getRuleById security: [] parameters: - name: id in: path required: true description: The unique identifier of the rule to retrieve. schema: type: string - $ref: '#/components/parameters/UserId' responses: '200': description: The details of the requested rule. content: application/json: schema: $ref: '#/components/schemas/PromptingRule' '404': $ref: '#/components/responses/NotFound' post: tags: - Experimental - Interfaces - OpenAccess - Prompting - Synchronous summary: Patch or remove a rule by ID description: Update or remove an existing rule specified by its unique ID. operationId: updateRuleById security: [] parameters: - name: id in: path required: true description: The unique identifier of the rule to patch or remove. schema: type: string - $ref: '#/components/parameters/UserId' requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/PromptingRuleActionPatch' - $ref: '#/components/schemas/PromptingRuleActionRemoveById' responses: '200': description: The updated state of the rule, or its last state before deletion. content: application/json: schema: $ref: '#/components/schemas/PromptingRule' '404': $ref: '#/components/responses/NotFound' /v2/login: post: tags: - AuthenticationRequired - Store - Synchronous summary: Authenticate user with snapd and store description: |- 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. operationId: loginUser security: - PeerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - email - password properties: email: type: string format: email description: The email associated with the desired account. pattern: .@.*\.. example: random.user@emailaddr.com password: type: string format: password description: The password associated with the email address. example: password1234! otp: type: string description: A one-time password for two-factor authentication. example: '123456' responses: '200': description: A synchronous response containing the result of the login information. 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 required: - id - email - macaroon properties: id: type: integer email: type: string format: email description: The email used to authenticate with the store. macaroon: type: string description: The macaroon returned by the store after successful authentication. discharges: type: array items: type: string example: - discharge-for-macaroon-authentication username: type: string description: Local username associated with the account. example: user-name '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessDenied' /v2/logout: post: tags: - AuthenticationRequired - Store - Synchronous summary: Log user out of snapd and the store description: Logs the currently authenticated user out of snapd and the store. operationId: logoutUser security: - PeerAuth: [] parameters: - in: header name: Authorization schema: type: string format: 'Authorization: Macaroon ' description: The authorization to remove from the system. responses: '200': description: Successfully logged out. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessDenied' /v2/logs: get: tags: - AuthenticationRequired - Synchronous summary: Get log contents description: Retrieves log contents from the snapd daemon. The response is a stream of newline-delimited JSON objects. operationId: getLogs security: - PeerAuth: [] parameters: - name: follow in: query description: If set, returns log entries as they occur, streaming the response. schema: type: boolean default: false - name: 'n' in: query description: Number of log entries to return. schema: type: integer default: 10 - name: names in: query description: Comma-separated list of snap names to filter by. schema: type: string example: multipass,lxd responses: '200': description: A stream of log messages. Each line is a self-contained JSON object. content: application/x-ndjson: schema: $ref: '#/components/schemas/Log' '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' /v2/model: get: tags: - Assertions - OpenAccess - Synchronous summary: Get the active model assertion description: |- Retrieves the active model assertion for the system. The model assertion describes a snap-based device. externalDocs: description: Read more about model assertions on the Ubuntu Core documentation. url: https://documentation.ubuntu.com/core/reference/assertions/model/ operationId: getModelAssertion security: [] responses: '200': description: The raw model assertion text. content: text/plain: schema: type: string example: | type: model authority-id: generic series:16 brand-id: generic model: generic-classic classic: true timestamp: 2017-07-27T00:00:00.0Z sign-key-sha3-384: d-JcZF9nD9eBw7bwMnH61x-bklnQOhQud1Is6o_cn2wTj8EYDi9musrIT9z2MdAa AcLBXAQAAQ[...] '404': $ref: '#/components/responses/NotFound' post: tags: - Assertions - Asynchronous - AuthenticationRequired summary: Replace the model assertion description: |- 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. externalDocs: description: Read more about offline remodeling on the Ubuntu Core documentation. url: https://documentation.ubuntu.com/core/explanation/remodelling/index.html#heading--offline operationId: setModelAssertion security: - PeerAuth: [] requestBody: description: |- The new model assertion and, for offline remodels, any required files (snaps, etc.). required: true content: application/json: schema: description: |- Used for online remodeling. The request body is a JSON object containing the new model assertion. type: object required: - assertion properties: assertion: type: string description: A string containing the full, signed model assertion. example: | type: model authority-id: generic series: 16 brand-id: generic model: generic-classic classic: true timestamp: 2025-10-03T10:40:00.0Z sign-key-sha3-384: d-JcZF9nD9eBw7bwMnH61x-bklnQOhQud1Is6o_cn2wTj8EYDi9musrIT9z2MdAa AcLBXAQAAQ[...] examples: remodelRequest: summary: A typical JSON request to set a new model. value: assertion: |- type: model authority-id: generic series: 16 brand-id: generic model: generic-classic classic: true timestamp: 2025-10-03T10:40:00.0Z sign-key-sha3-384: d-JcZF9nD9eBw7bwMnH61x-bklnQOhQud1Is6o_cn2wTj8EYDi9musrIT9z2MdAa AcLBXAQAAQ[...] multipart/form-data: schema: description: |- Used for offline remodeling to sideload the assertion and all required files (e.g., snaps) in a single request, avoiding the need to download them from the store. type: object properties: assertion: type: string description: The new model assertion text. additionalProperties: type: string format: binary description: Snap files or other assets required by the new model. encoding: assertion: contentType: text/plain '*': contentType: application/octet-stream responses: '202': $ref: '#/components/responses/Accepted' '400': $ref: '#/components/responses/BadRequest' /v2/model/serial: get: tags: - Assertions - OpenAccess - Synchronous summary: Get the current serial assertion description: |- 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. externalDocs: description: Read more about serial assertions on the Ubuntu Core documentation. url: https://documentation.ubuntu.com/core/reference/assertions/serial/ operationId: getSerialAssertion security: [] responses: '200': description: The raw serial assertion text. content: text/plain: schema: type: string example: | type: serial authority-id: generic brand-id: generic model: generic-classic serial: 46923e6d-5d45-420d-905a-99a9e92493b4 device-key: AcbBTQRWhcGAARAA... ...AEQEAAQ== device-key-sha3-384: PznqOqWAx4_f8tFafGI2... timestamp: 2025-07-17T03:11:33.518427Z sign-key-sha3-384: wrfougkz3Huq2T_Kklfnu... ...bX5JkJG5cunW0h/ '404': $ref: '#/components/responses/NotFound' post: tags: - Assertions - Asynchronous - AuthenticationRequired summary: Perform an action on the serial assertion description: |- 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. externalDocs: description: Read more about offline remodeling on the Ubuntu Core documentation. url: https://documentation.ubuntu.com/core/explanation/remodelling/index.html#heading--offline operationId: setSerialAssertion security: - PeerAuth: [] requestBody: description: A JSON object specifying the action to perform on the serial. required: true content: application/json: schema: type: object properties: action: type: string description: The action to perform on the serial assertion. enum: - forget no-registration-until-reboot: type: boolean description: If true, delays device registration until the next reboot. default: false required: - action example: action: forget no-registration-until-reboot: true responses: '202': $ref: '#/components/responses/Accepted' '400': $ref: '#/components/responses/BadRequest' /v2/notices: get: tags: - Notices - OpenAccess - Synchronous summary: Retrieve system notices description: |- Retrieves notices for the current user and any public notices, with optional filtering. operationId: getNotices security: [] parameters: - name: types in: query description: |- 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. schema: type: array items: $ref: '#/components/schemas/NoticeType' - name: keys in: query description: If specified, only return notices with one of the given keys. schema: type: array items: type: string example: '-' - name: after in: query description: |- If specified, only return notices with a 'last-repeated' field greater than the specified time, in RFC3339 UTC format. schema: type: string format: date-time example: '2025-09-08T17:29:40.829324752Z' - name: timeout in: query description: |- 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. schema: type: string example: 7m30s - name: user-id in: query description: |- 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. schema: type: integer example: 1000 - name: users in: query description: |- 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. schema: type: string enum: - all responses: '200': description: |- A synchronous response containing a list of notices matching the filter criteria. 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/Notice' 4XX: $ref: '#/components/responses/InternalError' post: tags: - Notices - OpenAccess - Synchronous summary: Create a notice description: |- 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. operationId: postNotices security: [] requestBody: required: true content: application/json: schema: type: object required: - action - key - type properties: action: type: string description: The action to perform. enum: - add key: type: string description: The key of the notice to add. type: type: string description: The type of the notice to add. enum: - snap-run-inhibit responses: '200': description: A synchronous response indicating success. 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 description: |- The result object contains information about the response to the request. properties: id: type: string description: The ID of the newly-created notice. example: '74' '400': $ref: '#/components/responses/BadRequest' /v2/notices/{id}: get: tags: - Notices - OpenAccess - Synchronous summary: Retrieve a specific system notice description: Retrieves a single notice by its unique ID. operationId: getNoticeByID security: [] parameters: - name: id in: path required: true description: The unique ID of the notice to retrieve. schema: type: string example: '74' responses: '200': description: A synchronous response containing the details of the requested notice. 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/Notice' '404': $ref: '#/components/responses/NotFound' /v2/quotas: get: tags: - OpenAccess - Quotas - Synchronous summary: Get all quota groups description: Retrieves a list of all quota groups and their constraints. operationId: getQuotaGroups security: [] responses: '200': description: A list of quota groups. content: application/json: schema: type: array items: $ref: '#/components/schemas/QuotaGroup' '400': $ref: '#/components/responses/BadRequest' post: tags: - Asynchronous - AuthenticationRequired - Quotas 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/quotas/{group-name}: parameters: - name: group-name in: path required: true description: The name of the quota group. schema: type: string get: tags: - OpenAccess - Quotas - Synchronous summary: Get a specific quota group description: Retrieves the details for a single quota group by its name, or returns an error. operationId: getQuotaGroupByName security: [] responses: '200': description: Details for the specified quota group. content: application/json: schema: $ref: '#/components/schemas/QuotaGroup' '404': $ref: '#/components/responses/NotFound' /v2/sections: get: tags: - OpenAccess - Store - Synchronous summary: Get store sections description: Retrieves the list of available sections in the Snap Store. operationId: getStoreSections security: [] responses: '200': description: A synchronous response containing the names of the store sections. 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 description: An array containing the names of the store sections. items: type: string example: - featured - development - social - utilities 4XX: $ref: '#/components/responses/InternalError' /v2/snapctl: post: tags: - AuthenticationRequired - Snaps - Synchronous summary: Run snapctl command description: |- 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. operationId: runSnapctl security: - PeerAuth: [] parameters: - in: header name: X-Snapctl-Features description: | A comma-separated list of feature flags supported by the connecting snapctl client. This is used for feature negotiation between the client and the daemon. Older clients may not send this header. required: false schema: type: string requestBody: description: The context and arguments for the snapctl command. required: true content: application/json: schema: type: object required: - context-id - args properties: context-id: type: string description: |- 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. example: ABCDEF args: type: array description: A list of arguments to pass to snapctl. items: type: string example: - get - username stdin: type: string description: If args is fde-setup-result, provides stdin to the context. responses: '200': description: The output from the snapctl command. content: application/json: schema: type: object properties: stdout: type: string description: Data written to stdout by the command. stderr: type: string description: Data written to stderr by the command. '400': $ref: '#/components/responses/BadRequest' /v2/snaps: get: tags: - OpenAccess - Snaps - Synchronous summary: List installed snaps description: Lists snaps installed on the system, including their components. operationId: listInstalledSnaps security: [] parameters: - name: select in: query description: Filter which revisions of snaps are returned. schema: type: string enum: - all - enabled - refresh-inhibited default: enabled - name: snaps in: query description: A comma-separated list of snap names to filter by. schema: type: string responses: '200': description: A list of installed snaps matching the query. content: application/json: schema: type: array items: $ref: '#/components/schemas/InstalledSnap' '400': $ref: '#/components/responses/BadRequest' post: tags: - Asynchronous - AuthenticationRequired - Snaps 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 get: tags: - OpenAccess - Snaps - Synchronous summary: Get details for an installed snap description: Retrieves details for a specific snap installed on the system. operationId: getInstalledSnapByName security: [] responses: '200': description: Details for the specified snap. content: application/json: schema: $ref: '#/components/schemas/InstalledSnap' '404': $ref: '#/components/responses/NotFound' post: tags: - Asynchronous - AuthenticationRequired - Snaps 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: get: tags: - AuthenticationRequired - Snaps - Synchronous summary: Get snap configuration description: Retrieve configuration details for an installed snap. Use 'system' as the name to get system options. operationId: getSnapConfig security: - PeerAuth: [] parameters: - name: name in: path required: true description: The name of the snap or the reserved name 'system'. schema: type: string - name: keys in: query required: false description: A comma-separated list of keys to retrieve. Dotted keys can be used for nested values. schema: type: string responses: '200': description: A JSON map of configuration keys and their values. content: application/json: schema: type: object additionalProperties: true '400': $ref: '#/components/responses/BadRequest' put: tags: - Asynchronous - AuthenticationRequired - Snaps 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: get: tags: - OpenAccess - Snapshots - Synchronous summary: Get a list of snapshots description: Retrieves a list containing metadata for all snapshot sets stored on the system. operationId: listSnapshots security: [] responses: '200': description: A synchronous response containing a list of snapshot sets. 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/SnapshotSet' 4XX: $ref: '#/components/responses/InternalError' post: tags: - Asynchronous - AuthenticationRequired - Snapshots 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' /v2/snapshots/{set-id}/export: get: tags: - AuthenticationRequired - Snapshots - Synchronous summary: Export a snapshot set description: |- Retrieves a snapshot set as a downloadable tar archive (`.tgz`). The response body is a binary stream. operationId: exportSnapshot security: - PeerAuth: [] parameters: - name: set-id in: path required: true description: The ID of the snapshot set to export. schema: type: integer example: 2 responses: '200': description: A gzipped tar archive (.tgz) of the exported snapshot set. content: application/gzip: schema: type: string format: binary '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessDenied' '404': $ref: '#/components/responses/NotFound' /v2/system/system-recovery-keys: get: tags: - AuthenticationRequired - Synchronous - System summary: Get system recovery key description: Retrieve LUKS encryption keys when using full disk encryption on Ubuntu Core. operationId: getSystemRecoveryKey security: - PeerAuth: [] responses: '200': description: The recovery key for the system. content: application/json: schema: type: object properties: result: type: object properties: recovery-key: type: string example: 14697-25590-04585-06938-46886-23115-29787-34072 '400': $ref: '#/components/responses/BadRequest' post: tags: - AuthenticationRequired - Synchronous - System summary: Manage system recovery keys description: Removes and resets LUKS encryption keys when using full disk encryption on Ubuntu Core devices. operationId: manageSystemRecoveryKeys security: - PeerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - action properties: action: type: string description: The only supported action is 'remove'. enum: - remove responses: '200': description: The action was successful. '400': $ref: '#/components/responses/BadRequest' /v2/systems: get: tags: - OpenAccess - Systems - Synchronous summary: Get the list of recovery systems description: Retrieves a list of all available recovery systems on the device. operationId: getSystems security: [] responses: '200': description: A list of recovery systems. content: application/json: schema: type: object properties: systems: type: array items: $ref: '#/components/schemas/System' '404': $ref: '#/components/responses/NotFound' post: tags: - AuthenticationRequired - Systems - Asynchronous - Synchronous summary: Perform an action on the current recovery system or create a new one description: |- Perform an action such as 'reboot', 'install' on the current active recovery system, or 'create' a new recovery system. operationId: performSystemAction security: - PeerAuth: [] requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/SystemActionCreate' - $ref: '#/components/schemas/SystemActionInstall' - $ref: '#/components/schemas/SystemActionReboot' responses: '200': description: The action was successfully initiated (for synchronous actions like reboot). '202': description: The asynchronous action (e.g., create, install) was accepted and is in progress. $ref: '#/components/responses/Accepted' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' /v2/systems/{label}: parameters: - name: label in: path required: true description: The label of the recovery system. schema: type: string get: tags: - AuthenticationRequired - Systems - Synchronous summary: Get details for a specific recovery system description: Retrieves detailed information for a single recovery system, including storage encryption status and available actions. operationId: getSystemDetails security: - PeerAuth: [] responses: '200': description: Detailed information about the recovery system. content: application/json: schema: $ref: '#/components/schemas/SystemDetails' '404': $ref: '#/components/responses/NotFound' post: tags: - AuthenticationRequired - Systems summary: Perform an action on a specific recovery system description: Perform an action on the recovery system identified by its label. The required parameters in the request body depend on the specified action. operationId: performLabeledSystemAction security: - PeerAuth: [] requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/SystemActionDo' - $ref: '#/components/schemas/SystemActionReboot' - $ref: '#/components/schemas/SystemActionInstall' - $ref: '#/components/schemas/SystemActionRemove' - $ref: '#/components/schemas/SystemActionCheckPassphrase' - $ref: '#/components/schemas/SystemActionCheckPin' - $ref: '#/components/schemas/SystemActionFixEncryptionSupport' responses: '200': description: The action was successfully initiated (for synchronous actions). '202': description: The asynchronous action (e.g., install, remove) was accepted and is in progress. $ref: '#/components/responses/Accepted' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' /v2/system-info: get: tags: - OpenAccess - Synchronous - Systems summary: Get system information description: Retrieves a dictionary of server configuration and environment information. operationId: getSystemInfo security: [] responses: '200': description: A synchronous response containing detailed system information. 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/SystemInfo' 4XX: $ref: '#/components/responses/InternalError' /v2/users: get: tags: - Root - Synchronous - Users summary: Get user accounts description: Get information on user accounts on the system. operationId: getUsers security: - PeerAuth: [] responses: '200': description: An array of user account information. content: application/json: schema: type: array items: $ref: '#/components/schemas/User' '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' post: tags: - Root - Synchronous - Users summary: Manage users description: Create or remove local users on the system. operationId: manageUsers security: - PeerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - action properties: action: type: string enum: - create - remove email: type: string format: email username: type: string sudoer: type: boolean default: false description: Whether the user can escalate to root privileges or not. known: type: boolean default: false responses: '200': description: A list of objects with the created user details. content: application/json: schema: type: array items: type: object properties: username: type: string ssh-keys: type: array items: type: string '400': $ref: '#/components/responses/BadRequest' '405': $ref: '#/components/responses/MethodNotAllowed' /v2/validation-sets: get: tags: - AuthenticationRequired - Synchronous - Validation Sets summary: Get all enabled validation sets description: Retrieves a list of all enabled validation sets on the system. externalDocs: description: Read more about validation sets on the Canonical Snapcraft documentation. url: https://snapcraft.io/docs/validation-sets operationId: listValidationSets security: - PeerAuth: [] responses: '200': description: A list of validation sets. content: application/json: schema: type: array items: $ref: '#/components/schemas/ValidationSet' '400': $ref: '#/components/responses/BadRequest' /v2/validation-sets/{account-id}/{name}: parameters: - name: account-id in: path required: true description: The developer account ID for the validation set. schema: type: string example: ABCDEF12345678900987654321FEDCBA - name: name in: path required: true description: The name of the validation set. schema: type: string example: myset1 get: tags: - AuthenticationRequired - Synchronous - Validation Sets summary: Get a specific validation set description: Retrieves a single validation set by its account ID and name. operationId: getValidationSet security: - PeerAuth: [] responses: '200': description: A single validation set object. content: application/json: schema: $ref: '#/components/schemas/ValidationSet' '404': $ref: '#/components/responses/NotFound' post: tags: - AuthenticationRequired - Synchronous - Validation Sets summary: Manage a specific validation set description: Apply or forget a specific validation set. operationId: applyValidationSet security: - PeerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - action properties: action: type: string description: The operation to perform on the validation set. enum: - apply - forget mode: type: string description: The mode to enable for the validation set. Required when action is 'apply'. enum: - monitor - enforce sequence: type: integer description: |- When using 'apply': an optional sequence number to pin. When using 'forget': an optional sequence number to match before forgetting. example: action: apply mode: monitor sequence: 1 responses: '200': description: The validation set was successfully updated. The updated resource is returned. content: application/json: schema: $ref: '#/components/schemas/ValidationSet' example: account-id: ABCDEF12345678900987654321FEDCBA mode: monitor name: myset1 pinned-at: 1 sequence: 1 valid: true '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' /v2/warnings: get: tags: - OpenAccess - Synchronous - Warnings summary: Get system warnings description: Retrieves the current warnings in snapd. operationId: getWarnings security: [] parameters: - name: select in: query description: |- Retrieve specific warnings. The default only shows pending warnings. All shows warnings that haven't expired or been cleaned. schema: type: string enum: - '' - all - pending default: pending responses: '200': description: A synchronous response containing a list of warnings. 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/Warning' '400': $ref: '#/components/responses/BadRequest' post: tags: - AuthenticationRequired - Synchronous - Warnings summary: Respond to warnings description: |- Warnings can only be acknowledged to clear them, but they may reoccur Acknowledging warnings does not fix the underlying cause. operationId: respondToWarnings security: - PeerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - action - timestamp properties: action: type: string enum: - okay timestamp: type: string format: date-time description: Time to clear warnings before (RFC3339 UTC format). example: '2025-09-08T17:29:40.829324752Z' responses: '200': description: A synchronous response indicating success. 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: integer description: The number of warnings cleared. example: 0 '400': $ref: '#/components/responses/BadRequest' components: 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). responses: 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 nullable: true description: For an accepted async operation, this is always null as the result is not yet available. example: null AccessDenied: description: |- Access Denied. The daemon/store cannot or will not process the request because the user does not have the correct authorization from the system. content: application/json: schema: type: object properties: status-code: type: integer description: The HTTP status code. enum: - 401 status: type: string description: The textual representation of the status code. enum: - Unauthorized type: type: string description: The type of response. enum: - error result: type: object properties: kind: type: string description: A machine-readable string identifying the error type. enum: - login-required message: type: string description: A human-readable error message. enum: - access denied BadRequest: description: |- Bad Request. The request could not be processed due to a client-side error. This can be due to malformed syntax or providing an entity that does not exist. content: application/json: schema: type: object properties: status-code: type: integer enum: - 400 status: type: string enum: - Bad Request type: type: string enum: - error result: oneOf: - $ref: '#/components/schemas/ConfdbError' - $ref: '#/components/schemas/MalformedRequestError' - $ref: '#/components/schemas/NoSSHKeysError' - $ref: '#/components/schemas/UserNotFoundError' - $ref: '#/components/schemas/SnapNotInstalledError' Conflict: description: Conflict. The request conflicts with the current state of the server. content: application/json: schema: type: object properties: status-code: type: integer description: The HTTP status code. enum: - 409 status: type: string description: The textual representation of the status code. enum: - Conflict type: type: string description: The type of response. enum: - error result: $ref: '#/components/schemas/ConflictError' 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 InternalError: description: An internal error occurred on the server. This is a generic response for server-side issues. content: application/json: schema: type: object properties: status-code: type: integer enum: - 500 status: type: string enum: - Internal Server Error type: type: string enum: - error result: $ref: '#/components/schemas/InternalServerError' MethodNotAllowed: description: The requested method is not allowed. content: application/json: schema: type: object properties: status-code: type: integer enum: - 405 status: type: string enum: - Method Not Allowed type: type: string enum: - error result: type: object properties: message: type: string example: system user administration via snapd is not allowed on this system 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' schemas: 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' ConflictError: type: object properties: message: type: string description: A human-readable error message explaining the conflict. example: snap 'alias-snap' has 'manip' change in progress kind: type: string description: A machine-readable string identifying the error type. enum: - snap-change-conflict value: type: object description: Additional structured data about the conflict. properties: change-kind: type: string description: The kind of change that is in progress. enum: - manip snap-name: type: string description: The name of the snap that has a conflicting change. example: alias-snap InternalServerError: type: object properties: message: type: string description: A human-readable error message. enum: - internal server error MalformedRequestError: type: object properties: message: type: string example: cannot decode request body into an alias action NoModelAssertionError: type: object description: The model assertion has not been created yet. properties: kind: type: string description: machine-readable definition of the error. enum: - assertion-not-found message: type: string description: Human-readable string describing the error. enum: - no model assertion yet value: type: string description: Value passed that triggered the error. enum: - model 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 NoSSHKeysError: type: object properties: message: type: string example: 'cannot create user user@canonical.com: no ssh keys found' 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 UserNotFoundError: type: object properties: message: type: string example: 'cannot create user user@canonical.com: cannot find user user@canonical.com' Activator: type: object description: |- Details about a single service activator. Note that uppercase field names exist to maintain backward compatibility with the non-conformant previous implementation, and are thus not documented here. required: - name - type - active - enabled properties: active: type: boolean description: Whether the activator is active or not. enabled: type: boolean description: Whether the activator is enabled or not. name: type: string description: The name of the activator. type: type: string description: The type of the activator. enum: - dbus - socket - timer App: type: object description: Represents a single application provided by a snap. required: - name properties: snap: type: string description: The snap providing the app. name: type: string description: The name of the app. desktop-file: type: string description: The desktop file for the app. daemon: type: string description: The daemon type, if the app is a service. enum: - forking - notify - oneshot - simple enabled: type: boolean description: True if the app is an enabled service. active: type: boolean description: True if the app is an active service. common-id: type: string description: Common ID associated with this app. activators: type: array items: $ref: '#/components/schemas/Activator' example: snap: lxd name: daemon daemon: simple enabled: true activators: - name: unix type: socket active: true enabled: true AppActionBase: type: object required: - action - names properties: action: type: string description: The action to perform. names: type: array description: A list of names of snaps (e.g. "lxd") or specific apps (e.g. "lxd.daemon") to operate on. items: type: string example: multipass scope: type: array items: type: string users: type: object properties: names: type: array items: type: string selector: type: string description: Internally converted to an integer by the servers marshalling/unmarshalling process enum: - userX - self - all AppActionRestart: type: object description: Restarts one or more services. allOf: - $ref: '#/components/schemas/AppActionBase' - type: object required: - action properties: action: type: string enum: - restart reload: type: boolean description: Tries to reload the service if it supports it; otherwise, it performs a full restart. default: false example: action: restart names: - lxd reload: true AppActionStart: type: object description: Starts one or more services. allOf: - $ref: '#/components/schemas/AppActionBase' - type: object required: - action properties: action: type: string enum: - start enable: type: boolean description: Arranges to have the service start at system boot. default: false example: action: start names: - lxd enable: true AppActionStop: type: object description: Stops one or more services. allOf: - $ref: '#/components/schemas/AppActionBase' - type: object required: - action properties: action: type: string enum: - stop disable: type: boolean description: Arranges to no longer start the service at system boot. default: false example: action: stop names: - lxd disable: true AssertionResult: type: object properties: result: type: array description: A list of assertion results. items: type: object properties: headers: type: object description: A key-value map of the assertion headers. additionalProperties: type: string status: type: string example: OK status-code: type: integer example: 200 type: type: string example: sync example: result: - headers: account-id: canonical authority-id: canonical display-name: Canonical sign-key-sha3-384: '-CvQKAwRQ5h3Ffn10FILJoEZUXOv6km9FwA80-Rcj-f-6jadQ89VRswHNiEB9Lxk' timestamp: '2016-04-01T00:00:00.0Z' type: account username: canonical validation: certified - headers: account-id: generic authority-id: canonical display-name: Generic sign-key-sha3-384: '-CvQKAwRQ5h3Ffn10FILJoEZUXOv6km9FwA80-Rcj-f-6jadQ89VRswHNiEB9Lxk' timestamp: '2017-07-27T00:00:00.0Z' type: account username: generic validation: certified status: OK status-code: 200 type: sync Change: type: object description: Represents the state and progress of a background operation. properties: id: type: string description: A unique ID for this change. example: '73' kind: type: string description: A code describing what type of change this is. example: auto-refresh summary: type: string description: Human-readable description of the change. example: Auto-refresh snaps "core22", "firefox" status: type: string description: Summary status of the current combined task statuses. enum: - Abort - Do - Doing - Done - Error - Hold - Undo - Undoing - Wait tasks: type: array description: An array of objects describing tasks in this change. items: $ref: '#/components/schemas/Task' ready: type: boolean description: True if this change has completed. spawn-time: type: string format: date-time description: The time this change started. ready-time: type: string format: date-time description: The time this change completed (omitted if not completed). err: type: string description: A human-readable error description if the transaction fails. data: type: object description: Result of the change, structure depends on the 'kind'. additionalProperties: true log: type: array items: type: string description: A log of events that occurred during the change. ConfdbControlAction: type: object description: Request to delegate or withdraw an operator's remote access to confdb views. required: - action - operator-id properties: action: type: string enum: - delegate - undelegate description: |- The action to perform. Use `delegate` to grant access, or `undelegate` to withdraw it. operator-id: type: string description: The account ID of the operator. example: alice authentications: type: array description: |- Determines how request messages are signed. With `operator-key`, the operator signs messages directly. With `store`, the Store signs on their behalf. Required for `delegate`. For `undelegate`, omit to withdraw all authentication methods. items: type: string enum: - operator-key - store example: - operator-key views: type: array description: |- The confdb views, specified in the format `//`. Required for `delegate`. For `undelegate`, omit to withdraw access from all views. items: type: string example: - bob/network/wifi-admin - bob/network/wifi-state Connection: type: object description: Represents a connection between a specific plug and slot. properties: slot: $ref: '#/components/schemas/SlotRef' plug: $ref: '#/components/schemas/PlugRef' interface: type: string description: The name of the interface governing the connection. manual: type: boolean description: True if the connection was established manually. gadget: type: boolean description: True if the connection is defined by the gadget snap. slot-attrs: type: object additionalProperties: true description: |- A map of the slot's attributes. These are negotiated by and belong to the connection. plug-attrs: type: object additionalProperties: true description: |- A map of the plug's attributes. These are negotiated by and belong to the connection. ConnectionStatus: type: object description: The overall connection status of plugs and slots on the system. properties: established: type: array description: A list of connections that are currently established. items: $ref: '#/components/schemas/Connection' undesired: type: array description: A list of connections that have been manually disconnected. items: $ref: '#/components/schemas/Connection' plugs: type: array description: A list of all available plugs. items: $ref: '#/components/schemas/Plug' slots: type: array description: A list of all available slots. items: $ref: '#/components/schemas/Slot' FindResult: type: object description: The complete response object for a successful find operation. properties: type: type: string enum: - sync status-code: type: integer enum: - 200 status: type: string enum: - OK result: type: array description: An array of snap details matching the query. items: $ref: '#/components/schemas/Snap' sources: type: array description: Indicates the source of the find results. items: type: string example: store suggested-currency: type: string description: The suggested currency for any pricing information. example: USD InstalledSnap: type: object description: Represents a snap package that is installed on the system. allOf: - $ref: '#/components/schemas/Snap' - type: object properties: apps: type: array description: A list of applications provided by the snap. items: $ref: '#/components/schemas/App' status: type: string description: The current status of the snap revision. enum: - active - installed install-date: type: string format: RFC3339 description: The date and time when this snap revision was installed. installed-size: type: integer format: int64 description: The disk space used by the snap in bytes. devmode: type: boolean description: True if the snap is currently installed in development mode. trymode: type: boolean description: True if the snap was installed in try mode. jailmode: type: boolean description: True if the snap is currently installed in jail mode. tracking-channel: type: string description: The channel that updates will be installed from. example: stable refresh-inhibit: type: object description: Indicates that the snap refresh is currently inhibited. properties: proceed-time: type: string format: RFC3339 description: The time after which a refresh will be forced. refresh-failures: type: object description: Information about failed auto-refresh attempts. properties: revision: type: integer failure-count: type: integer last-failure-time: type: string format: RFC3339 last-failure-severity: type: string enum: - after-reboot components: type: array description: A list of installed and available components for this snap. items: type: object properties: name: type: string type: type: string version: type: string summary: type: string description: type: string revision: type: string install-date: type: string format: RFC3339 installed-size: type: integer format: int64 LegacyInterfaceObject: type: object description: The legacy interface object. properties: plugs: type: array description: A list of plugs on the system matching the search criteria. items: $ref: '#/components/schemas/Plug' slots: type: array description: A list of slots on the system matching the search criteria. items: $ref: '#/components/schemas/Slot' Links: type: object description: A collection of relevant links for the snap. properties: contact: type: array items: type: string format: uri example: - mailto:user@canonical.com - https://discourse.example.com/c/support website: type: array items: type: string format: uri example: https://canonical.com additionalProperties: type: array description: Allows for other link collections like 'issues', 'docs', etc. items: type: string format: uri example: https://github.com/user/repo/issues Log: type: object properties: timestamp: type: string format: date-time description: The timestamp of the log entry in RFC3339 UTC format. example: '2025-09-11T15:10:22.264675Z' message: type: string description: The content of the log message. example: Failed to get https://cloud-images.ubuntu.com/releases/streams/v1/index.json sid: type: string description: The service identifier for the log entry. example: multipassd pid: type: string description: The process ID associated with the log entry. example: '2062' Media: type: object description: A media asset for the snap, such as an icon or screenshot. properties: height: type: integer description: The height of the asset in pixels. type: type: string enum: - icon - screenshot url: type: string format: uri description: The URL of the asset. width: type: integer description: The width of the asset in pixels. ModernInterfaceObject: type: array description: Modernized interface object. items: type: object properties: name: type: string description: The name of the interface. summary: type: string description: The summary providing information regarding the interface. doc-url: type: string format: url description: The url to the interfaces documentation. plugs: type: array description: A list of plugs on the system matching the search criteria. items: $ref: '#/components/schemas/Plug' slots: type: array description: A list of slots on the system matching the search criteria. items: $ref: '#/components/schemas/Slot' Notice: type: object description: A notice recorded by snapd, such as a warning or change update. properties: id: type: string description: The unique ID of the notice. example: '67' user-id: type: integer nullable: true description: The UID of the user who may view the notice, or null if public. example: 4293792034 type: $ref: '#/components/schemas/NoticeType' key: type: string description: |- An identifier which differentiates notices of this type. Notices recorded with the type and key of an existing notice count as an occurrence of that notice. Notice keys can take the form of the following: - 63 - '-' - 'libreoffice' - 'ABCDABCDABCDABCD' example: ABCDABCDABCDABCD first-occurred: type: string format: date-time description: The timestamp of the first time this notice occurred (RFC3339 UTC format). example: '2025-09-08T17:29:40.829324752Z' last-occurred: type: string format: date-time description: The timestamp of the last time this notice occurred (RFC3339 UTC format). example: '2025-09-10T14:30:23.055109521Z' last-repeated: type: string format: date-time description: |- The timestamp of the last time this notice was repeated (RFC3339 UTC format). example: '2025-09-10T14:30:23.055109521Z' occurrences: type: integer description: The number of times this notice has occurred. example: 4 last-data: type: object description: Additional data captured from the last occurrence. additionalProperties: true example: kind: alias repeat-after: type: string description: A duration string after which the notice may be repeated (optional). example: 1h30m expire-after: type: string description: A duration string after which the notice may be deleted. example: 168h0m0s NoticeType: type: string description: The type of the notice. enum: - change-update - warning - refresh-inhibit - snap-run-inhibit - interfaces-requests-prompt - interfaces-requests-rule-update 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. 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. Progress: type: object description: Represents the progress of a task. properties: done: type: integer description: The number of units completed. example: 1 label: type: string description: A descriptive label for the progress bar. example: core22 (delta) total: type: integer description: The total number of units for the task. example: 3 PromptingConstraintsCamera: type: object description: Details about the applicability of the new rule to requests. required: - permissions properties: permissions: type: object description: A map from permission name to the information about that permission. additionalProperties: $ref: '#/components/schemas/PromptingPermissionEntry' PromptingConstraintsHome: type: object description: Details about the applicability of the new rule to requests. required: - path-pattern - permissions properties: path-pattern: type: string description: Path glob matching filepaths for which the rule applies. permissions: type: object description: A map from permission name to the information about that permission. additionalProperties: $ref: '#/components/schemas/PromptingPermissionEntry' PromptingPatchConstraintsCamera: type: object description: |- Details about the applicability of the modified rule to requests. Any fields which are omitted are left unchanged from the existing rule. properties: permissions: type: object description: |- 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. additionalProperties: nullable: true $ref: '#/components/schemas/PromptingPermissionEntry' PromptingPatchConstraintsHome: type: object description: |- Details about the applicability of the modified rule to requests. Any fields which are omitted are left unchanged from the existing rule. properties: path-pattern: type: string description: Path glob matching filepaths for which the rule applies. permissions: type: object description: |- 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. additionalProperties: nullable: true $ref: '#/components/schemas/PromptingPermissionEntry' PromptingPermissionEntry: type: object required: - outcome - lifespan properties: outcome: type: string enum: - allow - deny lifespan: type: string description: |- The lifespan for which the permission applies. timespan: the permission applies for the given duration specified by the duration field or until it is deleted session: the permission applies until the user logs out (specifically, until the systemd user session ends) forever: the permission applies until it is deleted enum: - timespan - session - forever duration: type: string description: |- The duration for which the permission is valid. Required if lifespan is timespan, otherwise must be omitted. format: Go duration externalDocs: description: |- Read more about how Go handles time and durations in the official Go Time package documentation. url: https://pkg.go.dev/time example: 7h30m PromptingPermissionRuleEntry: type: object required: - outcome - lifespan properties: outcome: type: string enum: - allow - deny lifespan: type: string description: |- The lifespan for which the permission applies. timespan: the permission applies for the given duration specified by the duration field or until it is deleted session: the permission applies until the user logs out (specifically, until the systemd user session ends) forever: the permission applies until it is deleted enum: - timespan - session - forever expiration: type: string format: date-time description: |- The timestamp at which the permission will expire. Required if lifespan is timespan, otherwise must be omitted. session-id: type: string description: |- The opaque session ID used for session-based permissions. Required if lifespan is session, otherwise must be omitted. PromptingPrompt: type: object required: - id - timestamp - snap - interface - constraints properties: id: type: string description: Unique prompt identifier. timestamp: type: string format: date-time description: Timestamp at which the prompt was created or last modified (RFC3339Nano format). snap: type: string description: The name of the snap whose action triggered the prompt. interface: type: string description: The interface associated with the prompt. enum: - home - camera constraints: oneOf: - $ref: '#/components/schemas/PromptingPromptConstraintsCamera' - $ref: '#/components/schemas/PromptingPromptConstraintsHome' PromptingPromptConstraintsCamera: type: object description: Represents the constraints associated with a prompt for the camera interface. required: - requested-permissions - available-permissions properties: requested-permissions: type: array description: The permissions for which access is requested. items: type: string enum: - access available-permissions: type: array description: The complete list of permissions for the camera interface. items: type: string enum: - access PromptingPromptConstraintsHome: type: object description: Represents the constraints associated with a prompt for the home interface. required: - path - requested-permissions - available-permissions properties: path: type: string description: The path for which access is requested. example: /home/ubuntu/Downloads/image.png requested-permissions: type: array description: The permissions for which access is requested. items: type: string enum: - read - write - execute available-permissions: type: array description: The complete list of permissions for the home interface. items: type: string enum: - read - write - execute PromptingReply: type: object required: - action - lifespan - constraints properties: action: type: string enum: - allow - deny lifespan: type: string description: |- 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 enum: - single - timespan - session - forever duration: type: string description: |- The duration for which the decision applies. Required if lifespan is timespan, otherwise must be omitted. format: Go duration externalDocs: description: |- Read more about how Go handles time and durations in the official Go Time package documentation. url: https://pkg.go.dev/time example: 7h30m constraints: oneOf: - $ref: '#/components/schemas/PromptingReplyConstraintsCamera' - $ref: '#/components/schemas/PromptingReplyConstraintsHome' PromptingReplyConstraintsCamera: type: object description: Represents the constraints associated with a reply to a prompt for the camera interface. required: - permissions properties: permissions: type: array description: The permissions applied to requests to access cameras via the camera interface. items: type: string enum: - access PromptingReplyConstraintsHome: type: object description: Represents the constraints associated with a reply to a prompt for the home interface. required: - path-pattern - permissions properties: path-pattern: type: string description: |- Path glob matching filepaths for which the reply applies, which must match (in the globstar sense) the originally-requested path, must begin with /, and may include bash-like constructions such as *, /**/, and {a,b}, but must not include character classes of the form [abc] or [^abc]. example: /home/user0/Pictures/**/*.{png,jpg,jpeg,svg} permissions: type: array description: |- The permission applied to files matching the path glob in 'path-pattern'. items: type: string enum: - read - write - execute PromptingRule: type: object description: An object describing the structure of a rule. required: - id - timestamp - user - snap - interface - constraints properties: id: type: string description: Unique rule identifier. timestamp: type: string format: date-time description: Timestamp of rule creation/modification. user: type: integer description: The UID for which the rule applies. snap: type: string description: The name of the snap for which the rule applies. interface: type: string description: The interface for which the rule applies. enum: - camera - home constraints: oneOf: - $ref: '#/components/schemas/PromptingRuleConstraintsCamera' - $ref: '#/components/schemas/PromptingRuleConstraintsHome' PromptingRuleActionAdd: type: object description: The schema the API uses for the 'add' action of /v2/interfaces/rules. required: - action - rule properties: action: type: string description: The action to perform on the rules endpoint. enum: - add rule: type: object properties: snap: type: string description: The snap for which to add the rule. interface: type: string description: The interface for which to add the rule. constraints: oneOf: - $ref: '#/components/schemas/PromptingConstraintsCamera' - $ref: '#/components/schemas/PromptingConstraintsHome' PromptingRuleActionPatch: type: object description: The schema the API uses for the 'patch' action of /v2/interfaces/rules/{id}. required: - action - rule properties: action: type: string description: The action to perform on the rule with the given ID. enum: - patch rule: type: object properties: constraints: oneOf: - $ref: '#/components/schemas/PromptingPatchConstraintsCamera' - $ref: '#/components/schemas/PromptingPatchConstraintsHome' PromptingRuleActionRemove: type: object description: The schema the API uses for the 'remove' action of /v2/interfaces/rules. required: - action - selector properties: action: type: string description: The action to perform on the rules endpoint. enum: - remove selector: type: object description: Used to select rules for removal. properties: snap: type: string description: The snap for which to remove rules. interface: type: string description: The interface for which to remove rules. PromptingRuleActionRemoveByID: $ref: '#/components/schemas/PromptingRuleActionRemoveById' PromptingRuleConstraintsCamera: type: object description: Details about the applicability of the existing rule to requests. required: - permissions properties: permissions: type: object description: A map linking the permission name to it's respective information. additionalProperties: $ref: '#/components/schemas/PromptingPermissionRuleEntry' PromptingRuleConstraintsHome: type: object description: Details about the applicability of the existing rule to requests. required: - path-pattern - permissions properties: path-pattern: type: string description: Path glob matching filepaths for which the rule applies. permissions: type: object description: A map linking the permission name to it's respective information. additionalProperties: $ref: '#/components/schemas/PromptingPermissionRuleEntry' Publisher: type: object description: Information about the publisher of the snap. properties: display-name: type: string description: The user name associated with the account. id: type: string description: The developer ID associated with the account. username: type: string validation: type: string enum: - verified - starred - unproven 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 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. 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. Snap: type: object description: Detailed information about a single snap. properties: id: type: string description: The unique identifier for the snap. name: type: string description: The name of the snap. base: type: string description: The base snap this snap is built on. example: core20 channel: type: string description: The default channel for this snap. common-ids: type: array items: type: string example: code.desktop confinement: type: string enum: - classic - devmode - strict contact: type: string description: The primary contact URL or email for the developer. description: type: string description: A detailed description of the snap. developer: type: string description: The username of the snap developer. devmode: type: boolean description: |- If set to true, the snap needs to be installed with devmode confinement and doesn't, yet, work with strict confinement due to sandbox limitations or developer unfamiliarity. download-size: type: integer format: int64 description: The size of the snap package in bytes. icon: type: string format: uri description: A URL to the snap's icon image. license: type: string private: type: boolean description: Whether the snap is private. revision: type: string description: The latest revision number of the snap in this channel. status: type: string example: available store-url: type: string format: uri description: The URL to the snap's page in the Snap Store. summary: type: string description: A short, one-line summary of the snap. title: type: string type: type: string description: |- The type of the snap. 'os' is deprecated, and is left for compatibility with the 'core' and 'ubuntu-core' snaps. enum: - app - kernel - os - gadget - base version: type: string description: The version string of the latest revision. website: type: string format: uri description: The official website for the snap or application. categories: type: array items: $ref: '#/components/schemas/StoreCategory' links: $ref: '#/components/schemas/Links' media: type: array items: $ref: '#/components/schemas/Media' publisher: $ref: '#/components/schemas/Publisher' Snapshot: type: object description: Metadata for a single snap's snapshot. properties: id: type: integer description: The ID of the snapshot. example: 2 set: type: integer description: The ID of the set this snapshot belongs to. example: 1 time: type: string format: date-time description: The creation timestamp of the snapshot (RFC3339 UTC format). example: '2025-08-18T14:30:38.226662804-02:30' snap: type: string description: The name of the snap that was snapshotted. example: libreoffice snap-id: type: string description: The unique store ID of the snap. example: CpUkI0qPIIBVRsjy49adNq4D6Ra72y4v revision: type: string description: The revision of the snap at the time of the snapshot. example: '355' version: type: string description: The version of the snap at the time of the a snapshot. example: 25.2.5.2 size: type: integer format: int64 description: The size of the snapshot data in bytes. example: 1286593 auto: type: boolean description: True if the snapshot was created automatically. epoch: type: object externalDocs: description: To learn more about snap epochs, consult the Snapcraft documentation url: https://documentation.ubuntu.com/snapcraft/stable/how-to/crafting/manage-data-compatibility/ properties: read: type: array items: type: integer write: type: array items: type: integer sha3-384: type: object description: |- A map of archive components to their SHA3-384 checksums. There is a top level archive for system wide data, and a per-user archive as well. additionalProperties: type: string example: archive.tgz: fb8e887e47b1e8763d82ee5ddc8da8ad4601824d3154381a5d3b5bbe4125ded31fcc7b701a8318fbe3ea21213f333c8b user/$USER.tgz: 00cd2cf11d3c5731129dd11f8f82b0f13e807f6d839fd79afe052e301e43ee32ecdd217059cae0c400ff9c49e6dbaff6 summary: type: string description: A user-provided summary or description of the snapshot (often empty). SnapshotSet: type: object description: Represents a set of snapshots, typically created at the same time. properties: id: type: integer description: The unique identifier for this snapshot set. example: 1 snapshots: type: array description: A list of individual snapshots included in this set. items: $ref: '#/components/schemas/Snapshot' StoreCategory: type: object description: A store category associated with the snap. properties: featured: type: boolean description: Indicates if the snap is featured in this category. name: type: string description: The name of the category. SystemActionCheckPassphrase: type: object title: SystemActionCheckPassphrase description: Payload to check the quality of a given passphrase. required: - action - passphrase properties: action: type: string enum: - check-passphrase passphrase: type: string format: password description: The passphrase to validate. SystemActionCheckPin: type: object title: SystemActionCheckPin description: Payload to check the quality of a given PIN. required: - action - pin properties: action: type: string enum: - check-pin pin: type: string format: password description: The PIN to validate. SystemActionCreate: type: object title: SystemActionCreate required: - action - label properties: action: type: string enum: - create label: type: string description: A unique label for the new recovery system. validation-sets: type: array items: type: string description: A list of validation set strings to use for creating the system. test-system: type: boolean default: false description: If true, creates the system as a test system. mark-default: type: boolean default: false description: If true, marks the new system as the default recovery system. offline: type: boolean default: false description: If true, performs the creation in offline mode. SystemActionDo: type: object title: SystemActionDo description: Payload to perform a custom action defined by the system. required: - action - mode properties: action: type: string enum: - do mode: type: string description: The mode of the action to perform (e.g., 'recover', 'run'). title: type: string description: The title of the custom action to perform. SystemActionFixEncryptionSupport: type: object title: SystemActionFixEncryptionSupport description: Payload to apply a corrective action to fix storage encryption support. required: - action - fix-action properties: action: type: string enum: - fix-encryption-support fix-action: type: string description: The specific fix to apply. args: type: object additionalProperties: type: string description: A map of key-value arguments for the fix action. SystemActionInstall: type: object title: SystemActionInstall description: Payload to perform a step in the system installation process. required: - action - step properties: action: type: string enum: - install step: type: string description: The specific step of the installation process to execute. enum: - setup-storage-encryption - generate-recovery-key - finish oneOf: - type: object required: - step properties: step: type: string enum: - setup-storage-encryption on-volumes: type: array items: type: string description: A list of volume labels to operate on. volumes-auth: type: object additionalProperties: type: string description: A map of volume labels to their authentication credentials (e.g., passphrase or PIN). - type: object required: - step properties: step: type: string enum: - generate-recovery-key - type: object required: - step properties: step: type: string enum: - finish on-volumes: type: array items: type: string description: A list of volume labels to operate on. optional-install: type: object properties: all: type: boolean description: If true, install all optional snaps and components. Cannot be used if 'snaps' or 'components' are specified. snaps: type: array items: type: string description: A list of specific optional snaps to install. components: type: array items: type: string description: A list of specific optional components to install. SystemActionReboot: type: object title: SystemActionReboot description: Payload to reboot the device into a specific system mode. required: - action - mode properties: action: type: string enum: - reboot mode: type: string description: The mode to reboot into. enum: - factory-reset - install - recover - run SystemActionRemove: type: object title: SystemActionRemove description: Payload to remove a specified recovery system. required: - action properties: action: type: string enum: - remove System: type: object properties: actions: type: array items: type: object properties: mode: type: string enum: - install - recover - factory-reset - run title: type: string enum: - Reinstall - Recover - Factory Reset - Run normally brand: type: object properties: display-name: type: string example: Canonical id: type: string example: canonical username: type: string example: canonical validation: type: string enum: - starred - unproven - verified current: type: boolean default-recovery-system: type: boolean label: type: string example: '20240603' model: type: object properties: brand-id: type: string example: canonical display-name: type: string example: ubuntu-core-24-amd64 model: type: string example: ubuntu-core-24-amd64 SystemInfo: type: object description: Detailed information about the snapd server's configuration and environment. properties: architecture: type: string enum: - amd64 - arm64 - armhf - ppc64el - riscv64 - s390x build-id: type: string description: A unique identifier for the specific build of snapd. example: 3672763544646f6c... confinement: type: string description: The level of confinement the system supports. Partial indicates that Apparmor is disabled and Seccomp is enabled. enum: - partial - strict features: type: object description: A map of snapd feature names to their support and enabled status. additionalProperties: type: object properties: supported: type: boolean unsupported-reason: type: string description: If a feature is not supported, the property should contain an explanation as to why. enabled: type: boolean kernel-version: type: string description: The version string of the running Linux kernel. example: 6.14.0-29-generic locations: type: object properties: snap-bin-dir: type: string enum: - /snap/bin - /var/lib/snapd/snap/bin snap-mount-dir: type: string description: The prefix of 'snap-bin-dir'. enum: - /snap - /var/lib/snapd/snap managed: type: boolean description: True if the system is managed by an external authority. on-classic: type: boolean description: True if not running on a fully snap managed system (e.g., Ubuntu Core). os-release: type: object properties: id: type: string example: ubuntu variant-id: type: string enum: - desktop version-id: type: string example: '24.04' refresh: type: object properties: timer: $ref: '#/components/schemas/TimerString' last: type: string format: date-time description: The timestamp of the last refresh (RFC3339 format). example: '2025-09-11T13:18:00-02:30' next: type: string format: date-time description: The timestamp of the next scheduled refresh (RFC3339 format). example: '2025-09-11T22:37:00-02:30' sandbox-features: type: object description: Information about features supported by various components of the sandbox. additionalProperties: type: array items: type: string series: type: string description: |- The OS series the system is based on. This is always 16, and has not been used to-date. Introduced as a way to declare incompatible changes in the schema. enum: - '16' system-mode: type: string description: The current operational mode of the system. enum: - install - factory-reset - recover - run version: type: string description: The detailed version of snapd. example: '2.72' Task: type: object description: Represents a single task within a larger change. properties: id: type: string description: The unique ID for this task. example: '1502' kind: type: string description: A code describing what type of task this is. enum: - check-rerefresh - cleanup - clear-snap - copy-snap-data - discard-snap - download-snap - mount-snap - prerequisites - remove-aliases - run-hook - setup-profiles - start-snap-services - stop-snap-services - unlink-current-snap - validate-snap summary: type: string description: A human-readable description of the task. example: Download snap 'core22' (2133) from channel 'latest/stable' status: type: string description: |- The current status of the task. The usual state procedure is Do, Doing, Done. enum: - Abort - Default - Do - Doing - Done - Error - Hold - Undo - Undoing - Undone - Wait progress: $ref: '#/components/schemas/Progress' spawn-time: type: string format: date-time description: The time this task was started. example: '2024-03-28T13:00:35.505604296Z' ready-time: type: string format: date-time description: The time this task was completed. example: '2024-03-28T13:00:35.547274976Z' data: type: object properties: affected-snaps: type: array items: type: string example: - firefox - gnome-42-2204 - lxd additionalProperties: true description: Additional data related to the task, structure depends on the 'kind'. log: type: array description: A log of events that occurred during the task. items: type: string example: 2025-09-18T08:43:59-02:30 INFO No re-refreshes found. TimerString: type: string description: | A custom schedule format for defining recurring events, combining weekdays, times, spans, and frequencies. **Syntax Summary:** - A timer string is composed of one or more event sets, separated by ',,'. - Each event set can define weekdays ('mon', 'tue', 'wed2', 'fri5') and time windows ('10:00', '09:00-11:00'). - Weekday spans ('mon-fri') define an event for each day in the span. - Time spans ('14:00-16:00') define a single event within the span, which can be divided using a count ('/2'). externalDocs: description: For the complete specification, see the timer string documentation. url: https://snapcraft.io/docs/timer-string-format pattern: ^[a-zA-Z0-9,:~\/-]+$ example: mon-wed,fri,9:00-11:00/2 User: type: object description: Represents a user account on the system. required: - id - email properties: id: type: integer description: |- The unique numeric ID for this user account. This is not related to the user's linux UID. example: 1 username: type: string description: The local username associated with this account. example: local-username email: type: string format: email description: The email address associated with the launchpad account. example: first-name.last-name@example.com ValidationSet: type: object properties: account-id: type: string description: Identifier for the developer account. name: type: string description: Name of the validation set. mode: type: string description: Mode of validation the system will use. enum: - monitor - enforce pinned-at: type: integer description: The sequence number the set is pinned at (0 if not pinned). sequence: type: integer description: The current sequence of the validation set assertion. valid: type: boolean description: Reports whether the set is valid for currently installed snaps. Warning: type: object properties: message: type: string description: The warnings message content. first-added: type: string format: date-time description: The first time a warning with this message was created (RFC3339 UTC format). example: '2025-09-08T17:29:40.829324752Z' last-added: type: string format: date-time description: The last time a warning with this message was created (RFC3339 UTC format). example: '2025-09-08T17:34:40.829324752Z' last-shown: type: string format: date-time description: The last time this warning was displayed to the user (RFC3339 UTC format). example: '2025-09-08T17:34:40.829324752Z' delete-after: type: string description: A duration string indicating how much time since this warning was last added that it should be deleted. example: 1h30m repeat-after: type: string description: Duration string indicating how much time since this warning was last shown that it should be shown again. example: 30m PromptingRuleActionRemoveById: type: object description: The schema the API uses for the 'remove' action of /v2/interfaces/rules/{id}. required: - action properties: action: type: string description: The action to perform on the rule with the given ID. enum: - remove SystemDetails: type: object title: SystemDetails description: Detailed information about a specific recovery system. properties: current: type: boolean description: Whether this is the currently running system. label: type: string description: The unique label identifying the recovery system. brand: type: object title: StoreAccount properties: id: type: string username: type: string display-name: type: string validation: type: string model: type: object description: A map of the model assertion's headers. additionalProperties: true actions: type: array description: A list of actions that can be performed on this system. items: type: object title: SystemActionInfo properties: title: type: string mode: type: string available-optional: type: object properties: snaps: type: array items: type: string description: A list of optional snaps available for installation. components: type: array items: type: string description: A list of optional components available for installation. volumes: type: array description: A list of storage volumes defined by the system's gadget snap. items: type: object title: VolumeInfo properties: name: type: string description: The name of the volume. type: type: string description: The filesystem type. size: type: string description: The size of the volume. storage-encryption: type: object title: StorageEncryptionInfo description: Information about the system's storage encryption capabilities. properties: support: type: string enum: - disabled - available - defective - unavailable description: The current support status for storage encryption. storage-safety: type: string description: The required storage safety level (e.g., 'encrypted'). type: type: string description: The type of encryption (e.g., 'luks2'). unavailable-reason: type: string description: The reason why encryption is unavailable or defective. availability-check-errors: type: array items: type: string description: A list of errors encountered during the availability check. features: type: array items: type: string enum: - passphrase-auth description: A list of supported encryption features. parameters: UserId: name: user-id in: query required: false description: |- 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. schema: type: integer