Search

V2 APIs

All the documentation for V2 Search is with its definition snaps_find.

V1 APIs

All the V1 endpoints under the "search" group share the same output schema:

{
  "_embedded": {
    "clickindex:package": [
      {<snap representation>},
      ...
    ]
  }
}

The <snap representation>, as the name suggests, is a JSON object representing a snap revision released to a specific channel, with the following default fields:

aliases
anon_download_url: (deprecated) user download_url
apps
architecture
base
binary_filesize
channel
common_ids
confinement
contact
content: (deprecated) obsolete information
date_published
description
developer_id
developer_name
developer_validation
download_sha3_384
download_sha512: (deprecated) use download_sha3_384
download_url
epoch
gated_snap_ids
icon_url: (deprecated) use media
last_updated
license
name: (deprecated) use package_name
origin:
package_name
prices
private
publisher: (deprecated) use developer_name
ratings_average (deprecated) obsolete information
release
revision
screenshot_urls: (deprecated) use media
snap_id
summary
support_url
title
version
website

Additional fields have to be explicitly requested:

channel_maps_list
media
sections
snap_yaml_raw

We strongly recommend clients to specify the required fields explicitly to avoid unexpected compatibility breakages by changes in the default set, e.g.:

GET /api/v1/search?q=magic&fields=package_name,revision,architecture,channel

snap_search

Introduced in version 1

Summary: GET /api/v1/snaps/search

Search public snaps in the Store.

The endpoint supports the following optional query string parameters:

q: the search term to be matched (fulltext search) across snaps on name, title, keywords, summary and description
scope: if specified as 'wide' snaps released on any risk of the 'latest' track will be returned, otherwise only the ones released to 'stable'
arch: if specified as 'wide' matching snaps released on any architecture will be returned, otherwise only the ones matching the X-Ubuntu-Architecture header (defaults to 'amd64')
confinement: comma-separated list of confinements restricting the results (defaults to 'strict,classic')
promoted: if specified as 'true', restricts the results to snaps that are assigned to at least one section
section: if specified as the name of an existing section (see section_listing endpoint for the list of sections) without a search_term it lists the featured snaps within the given section, with search_term it returns the matching snaps within the given section.
exclude_non_free: if specified as 'true' it will restrict the results to snaps with free licences (see SPDX 2.0 definition)
private: if specified as 'true' it will restrict the results to private snaps to which the principal (requires Authorization header) has access
common_id: if specified it will match only snaps including the given application ID (exact-matching).
page_size: number of results per page, defaults to 100 and is limited to 250 entries
page: results page, the results _links field contains HAL-navigation links to first, previous, self, next and last pages

snap_search changelog

Version 3: Added 'arch' query string parameter.
Version 2: Added 'scope' query string parameter.

section_listing

Introduced in version 1

Summary: GET /api/v1/snaps/sections

No documentation yet.

store_snaps

Introduced in version 1

Summary: GET /api/v1/snaps

List snaps from a store.

This endpoint lists all snaps currently released to the stable channel in the context store. The output schema is the same used by snap_searches:

This endpoint requires the following headers:

X-Ubuntu-Series: currently "16"
X-Ubuntu-Store: the context store ID, subjected to further authentication

Setting the `X-Ubuntu-Architecture' to a specific architecture name ('amd64', 'i386', 'armhf', etc) will filter out snaps not released in that architecture.

The results can be further filtered by the following query-string parameters:

channel: lists only results released to a specific channel ([<track>/]<risk>[/<branch>] notation)

snap_names

Introduced in version 1

Summary: GET /api/v1/snaps/names

List public and stable snap names for a given store, arch and series.

snaps_find

Introduced in version 19

Summary: GET /v2/snaps/find

Find snaps.

The current implementation of V2 Search is limited to the requirements of snapd but it is intended to eventually replace the older V1 Search APIs completely.

Results are limited to a maximum of 100 snaps.

Headers

Authorization: Publisher macaroon. Required to search private snaps.
Snap-Device-Authorization: Required for access to restricted stores.
Snap-Device-Series: Required. Must have the value "16".
Snap-Device-Store: Store to search. Defaults to "ubuntu".

Query Parameters

q=string: Full text query.
fields=comma separated list: See Supported Fields.
name-startswith=string: Filter name by starts with prefix.
architecture=string: Filter by architecture.
common-id=string: Filter for snaps containing this common_id.
category=string: Filter by category membership.
channel=string: Filter by channel.
confinement=comma separated list: Filter by confinement type. Defaults to strict,classic
featured=true/false: Filter by featured in category. Defaults is to return both featured and not featured snaps.
private=true/false: Filter only private snaps. Default is false, public snaps only.
publisher=string: Filter by publisher short name (exact match).

Supported Fields

Only the name and snap-id are returned unless fields are specified.

If the relevant fields are selected the revision in the response is picked using the "most stable" algorithm.

base
categories
channel
common-ids
confinement
contact
description
download
license
media
prices
private
publisher
revision
store-url
summary
title
type
version
website

snaps_find changelog

Version 21: Added links
Version 20: Added common-ids, store-url and website
Version 19: Add new V2 Search API

Response JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "error-list": {
            "items": {
                "additionalProperties": false,
                "properties": {
                    "code": {
                        "type": "string"
                    },
                    "message": {
                        "type": "string"
                    }
                },
                "required": [
                    "code",
                    "message"
                ],
                "type": "object"
            },
            "type": "array"
        },
        "results": {
            "items": {
                "additionalProperties": false,
                "properties": {
                    "name": {
                        "type": "string"
                    },
                    "revision": {
                        "additionalProperties": false,
                        "properties": {
                            "base": {
                                "type": [
                                    "string",
                                    "null"
                                ]
                            },
                            "channel": {
                                "type": "string"
                            },
                            "common-ids": {
                                "introduced_at": 20,
                                "items": {
                                    "type": "string"
                                },
                                "type": "array"
                            },
                            "confinement": {
                                "type": "string"
                            },
                            "download": {
                                "additionalProperties": false,
                                "properties": {
                                    "size": {
                                        "type": "number"
                                    }
                                },
                                "required": [
                                    "size"
                                ],
                                "type": "object"
                            },
                            "revision": {
                                "type": "number"
                            },
                            "type": {
                                "type": "string"
                            },
                            "version": {
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "snap": {
                        "additionalProperties": false,
                        "properties": {
                            "categories": {
                                "items": {
                                    "additionalProperties": false,
                                    "properties": {
                                        "featured": {
                                            "type": "boolean"
                                        },
                                        "name": {
                                            "type": "string"
                                        }
                                    },
                                    "required": [
                                        "name",
                                        "featured"
                                    ],
                                    "type": "object"
                                },
                                "type": "array"
                            },
                            "contact": {
                                "type": "string"
                            },
                            "description": {
                                "type": "string"
                            },
                            "license": {
                                "type": "string"
                            },
                            "links": {
                                "additionalProperties": {
                                    "items": {
                                        "type": "string"
                                    },
                                    "minItems": 1,
                                    "type": "array"
                                },
                                "introduced_at": 21,
                                "type": [
                                    "object",
                                    "null"
                                ]
                            },
                            "media": {
                                "items": {
                                    "additionalProperties": false,
                                    "properties": {
                                        "height": {
                                            "type": [
                                                "null",
                                                "integer"
                                            ]
                                        },
                                        "type": {
                                            "type": "string"
                                        },
                                        "url": {
                                            "type": "string"
                                        },
                                        "width": {
                                            "type": [
                                                "null",
                                                "integer"
                                            ]
                                        }
                                    },
                                    "required": [
                                        "type",
                                        "url",
                                        "width",
                                        "height"
                                    ],
                                    "type": "object"
                                },
                                "type": "array"
                            },
                            "prices": {
                                "type": "object"
                            },
                            "private": {
                                "type": "boolean"
                            },
                            "publisher": {
                                "additionalProperties": false,
                                "properties": {
                                    "display-name": {
                                        "type": "string"
                                    },
                                    "id": {
                                        "type": "string"
                                    },
                                    "username": {
                                        "type": "string"
                                    },
                                    "validation": {
                                        "type": "string"
                                    }
                                },
                                "required": [
                                    "id",
                                    "username",
                                    "display-name"
                                ],
                                "type": "object"
                            },
                            "store-url": {
                                "introduced_at": 20,
                                "type": "string"
                            },
                            "summary": {
                                "type": "string"
                            },
                            "title": {
                                "type": "string"
                            },
                            "website": {
                                "introduced_at": 20,
                                "type": [
                                    "null",
                                    "string"
                                ]
                            }
                        },
                        "type": "object"
                    },
                    "snap-id": {
                        "type": "string"
                    }
                },
                "required": [
                    "name",
                    "snap-id",
                    "snap"
                ],
                "type": "object"
            },
            "type": "array"
        }
    },
    "required": [
        "results"
    ],
    "type": "object"
}

legacy_search (DEPRECATED)

Deprecated: Deprecated from version 1

Summary: GET /api/v1/search

Legacy search implementation.

Ignore ':' in the query string for the sake of simplicity and match on exact snap name.

Response is wrapped into the usual CPI '_embedded["clickindex:package"]' structure.

TODO: field allowlist support.

Since the search could perform badly and is deprecated, we check that the useragent calling is actually a snapd process, based on the User-Agent.