Add-ons

Warning

These v3 APIs are now deprecated and you should switch to a newer version before it is removed. See the API versions available for details of the different API versions available and the deprection timeline.

Note

The only authentication method available at the moment is the internal one.

Autocomplete

Similar to add-ons search endpoint above, this endpoint allows you to search through public add-ons. Because it’s meant as a backend for autocomplete though, there are a couple key differences:

  • No pagination is supported. There are no next, prev or count fields, and passing page_size or page has no effect, a maximum of 10 results will be returned at all times.

  • Only a subset of fields are returned.

GET /api/v3/addons/autocomplete/
Query Parameters:

  • q (string) – The search query.

  • app (string) – Filter by add-on application availability.

  • appversion (string) – Filter by application version compatibility. Pass the full version as a string, e.g. 46.0. Only valid when the app parameter is also present.

  • author (string) – Filter by exact author username.

  • category (string) – Filter by category slug. app and type parameters need to be set, otherwise this parameter is ignored.

  • lang (string) – Activate translations in the specific language for that query. (See translated fields)

  • platform (string) – Filter by add-on platform availability.

  • tag (string) – Filter by exact tag name. Multiple tag names can be specified, separated by comma(s).

  • type (string) – Filter by add-on type.

  • sort (string) – The sort parameter. The available parameters are documented in the table below.

Response JSON Object:

  • results (array) – An array of add-ons. Only the id, icon_url, name and url fields are supported though.

Detail

This endpoint allows you to fetch a specific add-on by id, slug or guid.

Note

Non-public add-ons and add-ons with only unlisted versions require both authentication and reviewer permissions or an account listed as a developer of the add-on.

A 401 or 403 error response will be returned when clients don’t meet those requirements. Those responses will contain the following properties:

  • detail: string containing a message about the error.

  • is_disabled_by_developer: boolean set to true when the add-on has been voluntarily disabled by its developer.

  • is_disabled_by_mozilla: boolean set to true when the add-on has been disabled by Mozilla.

GET /api/v3/addons/addon/(int:id|string:slug|string:guid)/
Query Parameters:

  • lang (string) – Activate translations in the specific language for that query. (See Translated Fields)

  • wrap_outgoing_links (string) – If this parameter is present, wrap outgoing links through outgoing.prod.mozaws.net (See Outgoing Links)

Response JSON Object:

  • id (int) – The add-on id on AMO.

  • authors (array) – Array holding information about the authors for the add-on.

  • authors[].id (int) – The id for an author.

  • authors[].name (string) – The name for an author.

  • authors[].url (string) – The link to the profile page for an author.

  • authors[].username (string) – The username for an author.

  • authors[].picture_url (string) – URL to a photo of the user, or /static/img/anon_user.png if not set. For performance reasons this field is omitted from the search endpoint.

  • average_daily_users (int) – The average number of users for the add-on (updated daily).

  • categories (object) – Object holding the categories the add-on belongs to.

  • categories[app_name] (array) – Array holding the category slugs the add-on belongs to for a given add-on application. (Combine with the add-on type to determine the name of the category).

  • contributions_url (string|null) – URL to the (external) webpage where the addon’s authors collect monetary contributions, if set.

  • current_version (object) – Object holding the current version of the add-on. For performance reasons the license field omits the text property from the detail endpoint. In addition, license and release_notes are omitted entirely from the search endpoint.

  • default_locale (string) – The add-on default locale for translations.

  • description (string|object|null) – The add-on description (See translated fields).

  • developer_comments (string|object|null) – Additional information about the add-on provided by the developer. (See translated fields).

  • edit_url (string) – The URL to the developer edit page for the add-on.

  • guid (string) – The add-on extension identifier.

  • has_eula (boolean) – The add-on has an End-User License Agreement that the user needs to agree with before installing (See add-on EULA and privacy policy).

  • has_privacy_policy (boolean) – The add-on has a Privacy Policy (See add-on EULA and privacy policy).

  • homepage (string|object|null) – The add-on homepage (See translated fields).

  • icon_url (string) – The URL to icon for the add-on (including a cachebusting query string).

  • icons (object) – An object holding the URLs to an add-ons icon including a cachebusting query string as values and their size as properties. Currently exposes 32 and 64 pixels wide icons.

  • is_disabled (boolean) – Whether the add-on is disabled or not.

  • is_experimental (boolean) – Whether the add-on has been marked by the developer as experimental or not.

  • is_featured (boolean) – The add-on appears in a featured collection.

  • is_source_public (boolean) – Whether the add-on source is publicly viewable or not.

  • name (string|object|null) – The add-on name (See translated fields).

  • last_updated (string) – The date of the last time the add-on was updated by its developer(s).

  • latest_unlisted_version (object|null) – Object holding the latest unlisted version of the add-on. This field is only present if the user has unlisted reviewer permissions, or is listed as a developer of the add-on.

  • previews (array) – Array holding information about the previews for the add-on.

  • previews[].id (int) – The id for a preview.

  • previews[].caption (string|object|null) – The caption describing a preview (See translated fields).

  • previews[].image_size[] (int) – width, height dimensions of of the preview image.

  • previews[].image_url (string) – The URL (including a cachebusting query string) to the preview image.

  • previews[].thumbnail_size[] (int) – width, height dimensions of of the preview image thumbnail.

  • previews[].thumbnail_url (string) – The URL (including a cachebusting query string) to the preview image thumbnail.

  • ratings (object) – Object holding ratings summary information about the add-on.

  • ratings.count (int) – The total number of user ratings for the add-on.

  • ratings.text_count (int) – The number of user ratings with review text for the add-on.

  • ratings_url (string) – The URL to the user ratings list page for the add-on.

  • ratings.average (float) – The average user rating for the add-on.

  • ratings.bayesian_average (float) – The bayesian average user rating for the add-on.

  • requires_payment (boolean) – Does the add-on require payment, non-free services or software, or additional hardware.

  • review_url (string) – The URL to the reviewer review page for the add-on.

  • slug (string) – The add-on slug.

  • status (string) – The add-on status.

  • summary (string|object|null) – The add-on summary (See translated fields).

  • support_email (string|object|null) – The add-on support email (See translated fields).

  • support_url (string|object|null) – The add-on support URL (See translated fields).

  • tags (array) – List containing the text of the tags set on the add-on.

  • theme_data (object) – Object holding lightweight theme (Persona) data. Only present for themes (Persona).

  • type (string) – The add-on type.

  • url (string) – The (absolute) add-on detail URL.

  • versions_url (string) – The URL to the version history page for the add-on.

  • weekly_downloads (int) – The number of downloads for the add-on in the last week. Not present for lightweight themes.

Possible values for the status field / parameter:

Value

Description

lite

Preliminarily Reviewed

public

Fully Reviewed

deleted

Deleted

pending

Pending approval (Valid for themes only)

disabled

Disabled by Mozilla

rejected

Rejected (Valid for themes only)

nominated

Awaiting Full Review

incomplete

Incomplete

unreviewed

Awaiting Preliminary Review

lite-nominated

Preliminarily Reviewed and Awaiting Full Review

review-pending

Flagged for further review (Valid for themes only)

Possible values for the keys in the compatibility field, as well as the app parameter in the search API:

Value

Description

android

Firefox for Android

firefox

Firefox

seamonkey

SeaMonkey

thunderbird

Thunderbird

Note

For possible version values per application, see valid application versions.

Possible values for the current_version.files[].platform field:

Value

Description

all

All

mac

Mac

linux

Linux

android

Android

windows

Windows

Possible values for the type field / parameter:

Note

For backwards-compatibility reasons, the value for Theme is persona. theme refers to a Complete Theme.

Value

Description

theme

Complete Theme

search

Search Engine

persona

Theme

language

Language Pack (Application)

extension

Extension

dictionary

Dictionary

Add-on and Version Submission

See Uploading a version.

Versions List

This endpoint allows you to list all versions belonging to a specific add-on.

GET /api/v3/addons/addon/(int:addon_id|string:addon_slug|string:addon_guid)/versions/

Note

Non-public add-ons and add-ons with only unlisted versions require both:

  • authentication

  • reviewer permissions or an account listed as a developer of the add-on

Query Parameters:

  • filter (string) – The filter to apply.

  • lang (string) – Activate translations in the specific language for that query. (See translated fields)

  • page (int) – 1-based page number. Defaults to 1.

  • page_size (int) – Maximum number of results to return for the requested page. Defaults to 25.

Response JSON Object:

  • count (int) – The number of versions for this add-on.

  • next (string) – The URL of the next page of results.

  • previous (string) – The URL of the previous page of results.

  • results (array) – An array of versions.

By default, the version list API will only return public versions (excluding versions that have incomplete, disabled, deleted, rejected or flagged for further review files) - you can change that with the filter query parameter, which may require authentication and specific permissions depending on the value:

Value

Description

all_without_unlisted

Show all listed versions attached to this add-on. Requires either reviewer permissions or a user account listed as a developer of the add-on.

all_with_unlisted

Show all versions (including unlisted) attached to this add-on. Requires either reviewer permissions or a user account listed as a developer of the add-on.

all_with_deleted

Show all versions attached to this add-on, including deleted ones. Requires admin permissions.

Version Detail

This endpoint allows you to fetch a single version belonging to a specific add-on.

GET /api/v3/addons/addon/(int:addon_id|string:addon_slug|string:addon_guid)/versions/(int: id)/
Query Parameters:

  • lang (string) – Activate translations in the specific language for that query. (See translated fields)

Response JSON Object:

  • id (int) – The version id.

  • channel (string) – The version channel, which determines its visibility on the site. Can be either unlisted or listed.

  • compatibility (object) –

    Object detailing which applications the version is compatible with. The exact min/max version numbers in the object correspond to valid application versions. Example:

    {
  "compatibility": {
    "android": {
      "min": "38.0a1",
      "max": "43.0"
    },
    "firefox": {
      "min": "38.0a1",
      "max": "43.0"
    }
  }
}

  • compatibility[app_name].max (object) – Maximum version of the corresponding app the version is compatible with. Should only be enforced by clients if is_strict_compatibility_enabled is true.

  • compatibility[app_name].min (object) – Minimum version of the corresponding app the version is compatible with.

  • edit_url (string) – The URL to the developer edit page for the version.

  • files (array) – Array holding information about the files for the version.

  • files[].id (int) – The id for a file.

  • files[].created (string) – The creation date for a file.

  • files[].hash (string) – The hash for a file.

  • files[].platform (string) – The platform for a file.

  • files[].id – The size for a file, in bytes.

  • files[].is_mozilla_signed_extension (boolean) – Whether the file was signed with a Mozilla internal certificate or not.

  • files[].is_restart_required (boolean) – Whether the file requires a browser restart to work once installed or not.

  • files[].is_webextension (boolean) – Whether the file is a WebExtension or not.

  • files[].status (int) – The status for a file.

  • files[].url (string) – The (absolute) URL to download a file.

  • files[].permissions[] (array) – Array of the webextension permissions for this File, as strings. Empty for non-webextensions.

  • license (object) – Object holding information about the license for the version. For performance reasons this field is omitted from add-on search endpoint.

  • license.name (string|object|null) – The name of the license (See translated fields).

  • license.text (string|object|null) – The text of the license (See translated fields). For performance reasons this field is omitted from add-on detail endpoint.

  • license.url (string|null) – The URL of the full text of license.

  • release_notes (string|object|null) – The release notes for this version (See translated fields). For performance reasons this field is omitted from add-on search endpoint.

  • reviewed (string) – The date the version was reviewed at.

  • is_strict_compatibility_enabled (boolean) – Whether or not this version has strictCompatibility. set.

  • version (string) – The version number string for the version.

Add-on EULA and Privacy Policy

This endpoint allows you to fetch an add-on EULA and privacy policy.

GET /api/v3/addons/addon/(int:id|string:slug|string:guid)/eula_policy/

Note

Non-public add-ons and add-ons with only unlisted versions require both:

  • authentication

  • reviewer permissions or an account listed as a developer of the add-on

Response JSON Object:

  • eula (string|object|null) – The text of the EULA, if present (See translated fields).

  • privacy_policy (string|object|null) – The text of the Privacy Policy, if present (See translated fields).

Language Tools

This endpoint allows you to list all public language tools add-ons available on AMO.

GET /api/v3/addons/language-tools/

Note

Because this endpoint is intended to be used to feed a page that displays all available language tools in a single page, it is not paginated as normal, and instead will return all results without obeying regular pagination parameters. The ordering is left undefined, it’s up to the clients to re-order results as needed before displaying the add-ons to the end-users.

In addition, the results can be cached for up to 24 hours, based on the full URL used in the request.

Query Parameters:

  • app (string) – Mandatory. Filter by add-on application availability.

  • appversion (string) – Filter by application version compatibility. Pass the full version as a string, e.g. 46.0. Only valid when both the app and type parameters are also present, and only makes sense for Language Packs, since Dictionaries are always compatible with every application version.

  • lang (string) – Activate translations in the specific language for that query. (See translated fields)

  • type (string) – Mandatory when appversion is present. Filter by add-on type. The default is to return both Language Packs or Dictionaries.

Response JSON Object:

  • results (array) – An array of language tools.

  • results[].id (int) – The add-on id on AMO.

  • results[].current_compatible_version (object) – Object holding the latest publicly available version of the add-on compatible with the appversion parameter used. Only present when appversion is passed and valid. For performance reasons, only the following version properties are returned on the object: id, files, reviewed, and version.

  • results[].default_locale (string) – The add-on default locale for translations.

  • results[].name (string|object|null) – The add-on name (See translated fields).

  • results[].guid (string) –

    The add-on extension identifier.

  • results[].locale_disambiguation (string|null) – Free text field allowing clients to distinguish between multiple dictionaries in the same locale but different spellings. Only present when using the Language Tools endpoint.

  • results[].slug (string) – The add-on slug.

  • results[].target_locale (string) – For dictionaries and language packs, the locale the add-on is meant for. Only present when using the Language Tools endpoint.

  • results[].type (string) – The add-on type.

  • results[].url (string) – The (absolute) add-on detail URL.

Replacement Add-ons

This endpoint returns a list of suggested replacements for legacy add-ons that are unsupported in Firefox 57. Added to support the TAAR recommendation service.

GET /api/v3/addons/replacement-addon/
Query Parameters:

  • page (int) – 1-based page number. Defaults to 1.

  • page_size (int) – Maximum number of results to return for the requested page. Defaults to 25.

Response JSON Object:

  • count (int) – The total number of replacements.

  • next (string) – The URL of the next page of results.

  • previous (string) – The URL of the previous page of results.

  • results (array) – An array of replacements matches.

  • results[].guid (string) – The extension identifier of the legacy add-on.

  • results[].replacement[] (string) – An array of guids for the replacements add-ons. If there is a direct replacement this will be a list of one add-on guid. The list can be empty if all the replacement add-ons are invalid (e.g. not publicly available on AMO). The list will also be empty if the replacement is to a url that is not an addon or collection.

Compat Override

This endpoint allows compatibility overrides specified by AMO admins to be searched. Compatibilty overrides are used within Firefox i(and other toolkit applications e.g. Thunderbird) to change compatibility of installed add-ons where they have stopped working correctly in new release of Firefox, etc.

GET /api/v3/addons/compat-override/
Query Parameters:

  • guid (string) – Filter by exact add-on guid. Multiple guids can be specified, separated by comma(s), in which case any add-ons matching any of the guids will be returned. As guids are unique there should be at most one add-on result per guid specified.

  • page (int) – 1-based page number. Defaults to 1.

  • page_size (int) – Maximum number of results to return for the requested page. Defaults to 25.

Response JSON Object:

  • count (int) – The number of results for this query.

  • next (string) – The URL of the next page of results.

  • previous (string) – The URL of the previous page of results.

  • results (array) – An array of compat overrides.

  • results[].addon_id (int|null) – The add-on identifier on AMO, if specified.

  • results[].addon_guid (string) – The add-on extension identifier.

  • results[].name (string) – A description entered by AMO admins to describe the override.

  • results[].version_ranges (array) – An array of affected versions of the add-on.

  • results[].version_ranges[].addon_min_version (string) – minimum version of the add-on to be disabled.

  • results[].version_ranges[].addon_max_version (string) – maximum version of the add-on to be disabled.

  • results[].version_ranges[].applications (array) – An array of affected applications for this range of versions.

  • results[].version_ranges[].applications[].name (string) – Application name (e.g. Firefox).

  • results[].version_ranges[].applications[].id (int) – Application id on AMO.

  • results[].version_ranges[].applications[].min_version (string) – minimum version of the application to be disabled in.

  • results[].version_ranges[].applications[].max_version (string) – maximum version of the application to be disabled in.

  • results[].version_ranges[].applications[].guid (string) – Application guid.

Recommendations

This endpoint provides recommendations of other addons to install, fetched from the recommendation service. Four recommendations are fetched, but only valid, publicly available addons are shown (so max 4 will be returned, and possibly less).

GET /api/v3/addons/recommendations/
Query Parameters:

  • guid (string) – Fetch recommendations for this add-on guid.

  • lang (string) – Activate translations in the specific language for that query. (See translated fields)

  • recommended (boolean) – Fetch recommendations from the recommendation service, or return a curated fallback list instead.

Response JSON Object:

  • outcome (string) – Outcome of the response returned. Will be either: recommended - responses from recommendation service; recommended_fallback - service timed out or returned empty results so we returned fallback; curated - recommended=False was requested so fallback returned.

  • fallback_reason (string|null) – if outcome was recommended_fallback then the reason why. Will be either: timeout or no_results.

  • count (int) – The number of results for this query.

  • next (string) – The URL of the next page of results.

  • previous (string) – The URL of the previous page of results.

  • results (array) – An array of add-ons. The following fields are omitted for performance reasons: release_notes and license fields on current_version and current_beta_version, as well as picture_url from authors.