Add-ons

Note

These v4 APIs are now frozen. See the API versions available for details of the different API versions available. 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.

  • sort is not supported. Sort order is always relevance if q is provided, or the search default otherwise.

GET /api/v4/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 (listed) author username. Multiple author names can be specified, separated by comma(s), in which case add-ons with at least one matching author are returned.

  • 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)

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

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

Response JSON Object:

  • results (array) – An array of add-ons. Only the id, icon_url, name, promoted, type 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/v4/addons/addon/(int:id|string:slug|string:guid)/
Query Parameters:

  • app (string) – Used in conjunction with appversion below to alter current_version behaviour. Need to be a valid add-on application.

  • appversion (string) – Make current_version return the latest public version of the add-on compatible with the given application version, if possible, otherwise fall back on the generic implementation. Pass the full version as a string, e.g. 46.0. Only valid when the app parameter is also present. Currently only compatible with language packs through the add-on detail API, ignored for other types of add-ons and APIs.

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

  • wrap_outgoing_links (string) – (v3/v4 only) 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|object|null) – URL to the (external) webpage where the addon’s authors collect monetary contributions, if set. Can be an empty value. (See Outgoing Links)

  • created (string) – The date the add-on was created.

  • current_version (object) – Object holding the current version of the add-on. For performance reasons the license field omits the text property from both the search and detail endpoints.

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

  • description (string|object|null) – The add-on description (See translated fields). This field might contain some HTML tags.

  • 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 and Outgoing Links).

  • 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, 64, 128 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.

  • 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.

  • promoted (object|null) – Object holding promotion information about the add-on. Null if the add-on is not currently promoted.

  • promoted.category (string) – The name of the promoted category for the add-on.

  • promoted.apps[] (array) – Array of the applications for which the add-on is promoted.

  • 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). This field supports “linkification” and therefore might contain HTML hyperlinks.

  • 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 and Outgoing Links).

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

  • 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

public

Fully Reviewed

deleted

Deleted

disabled

Disabled by Mozilla

nominated

Awaiting Full Review

incomplete

Incomplete

unreviewed

Awaiting Preliminary Review

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

Note

See the supported 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 type of theme refers to a deprecated XUL Complete Theme. persona are another type of depreated theme. New webextension packaged non-dynamic themes are statictheme.

Value

Description

theme

Depreated. Theme (Complete Theme, XUL-based)

search

Search Engine

persona

Deprecated. Theme (Lightweight Theme, persona)

language

Language Pack (Application)

extension

Extension

dictionary

Dictionary

statictheme

Theme (Static Theme)

Possible values for the promoted.category field:

Value

Description

line

“By Firefox” category

recommended

Recommended category

spotlight

Spotlight category

strategic

Strategic category

badged

A meta category that’s available for the promoted search filter that is all the categories we expect an API client to expose as “reviewed” by Mozilla. Currently equal to line&recommended.

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/v4/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/v4/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 the supported 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[].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[].optional_permissions[] (array) – Array of the optional webextension permissions for this File, as strings. Empty for non-webextensions.

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

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

  • files[].size (int) – The size for a file, in bytes.

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

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

  • license (object) – Object holding information about the license for the version.

  • license.is_custom (boolean) – Whether the license text has been provided by the developer, or not. (When false the license is one of the common, predefined, licenses).

  • 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).

  • 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/v4/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 v4-translated fields).

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

Language Tools

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

GET /api/v4/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.

  • author (string) – Filter by exact (listed) author username. Multiple author names can be specified, separated by comma(s), in which case add-ons with at least one matching author are returned.

  • 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[].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/v4/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.

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/v4/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 or invalid 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, no_results, or invalid_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.