Add-ons

Note

These APIs are not frozen and can change at any time without warning. See the API versions available for alternatives if you need stability.

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/v5/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), in which case add-ons containing all specified tags are returned. See available tags

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

Response JSON Object:

  • results (array) – An array of add-ons. Only the id, icon_url, icons, 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/v5/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)

  • show_grouped_ratings (boolean) – Whether or not to show ratings aggregates in the ratings object (Use “true”/”1” as truthy values, “0”/”false” as falsy ones).

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 user 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 (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 (object|null) – The add-on description (See translated fields). This field might contain some HTML tags.

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

  • position (int) – The position in the list of previews images.

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

  • ratings.grouped_counts (object) – Object with aggregate counts for ratings. Only included when show_grouped_ratings is present in the request.

  • ratings.grouped_counts.1 (int) – the count of ratings with a score of 1.

  • ratings.grouped_counts.2 (int) – the count of ratings with a score of 2.

  • ratings.grouped_counts.3 (int) – the count of ratings with a score of 3.

  • ratings.grouped_counts.4 (int) – the count of ratings with a score of 4.

  • ratings.grouped_counts.5 (int) – the count of ratings with a score of 5.

  • 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 (object|null) – The add-on summary (See translated fields). This field supports “linkification” and therefore might contain HTML hyperlinks.

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

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

  • tags (array) – List containing the tag names set on the add-on.

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

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

  • version (object) – For create or update requests that included a version only. Object holding the version that was submitted.

  • 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 add-on status field / parameter:

Value

Description

public

Approved

deleted

Deleted

disabled

Disabled by Mozilla

nominated

Awaiting Review

incomplete

Incomplete - no approved listed versions

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

notable

Notable category

recommended

Recommended category

sponsored

Sponsored category

spotlight

Spotlight category

strategic

Strategic category

verified

Verified 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&sponsored&verified.

Create

This endpoint allows a submission of an upload to create a new add-on and setting other AMO metadata.

To create an add-on with a listed version from an upload (an upload that has channel == listed) certain metadata must be defined - a version license, an add-on name, an add-on summary, and add-on categories for each app the version is compatible with.

Note

This API requires authentication.

POST /api/v5/addons/addon/
Request JSON Object:

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

  • contributions_url (string) – URL to the (external) webpage where the addon’s authors collect monetary contributions. Only a limited number of services are supported.

  • default_locale (string) – The fallback locale for translated fields for this add-on. Note this only applies to the fields here - the default locale for version release notes and custom license text is fixed to en-US.

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

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

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

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

  • is_experimental (boolean) – Whether the add-on should be marked as experimental or not.

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

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

  • slug (string) – The add-on slug. Valid slugs must only contain letters, numbers (categories L and N), -, _, ~, and can’t be all numeric.

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

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

  • tags (array) – List containing the tag names to set on the add-on - see available tags.

  • version (object) – Object containing the version to create this addon with.

Response: See add-on

Edit

This endpoint allows an add-on’s AMO metadata to be edited.

Note

This API requires authentication, and for the user to be an author of the add-on.

PATCH /api/v5/addons/addon/(int:id|string:slug|string:guid)/
Request JSON Object:

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

  • contributions_url (string) –

    URL to the (external) webpage where the addon’s authors collect monetary contributions. Only a limited number of services are supported.

  • default_locale (string) – The fallback locale for translated fields for this add-on. Note this only applies to the fields here - the default locale for version release notes and custom license text is fixed to en-US.

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

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

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

  • icon (null) – To clear the icon, i.e. revert to the default add-on icon, send null. See addon icon to upload a new icon.

  • is_disabled (boolean) – Whether the add-on is disabled or not. Note: if the add-on status is disabled the response will always be disabled=true regardless.

  • is_experimental (boolean) – Whether the add-on should be marked as experimental or not.

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

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

  • slug (string) –

    The add-on slug. Valid slugs must only contain letters, numbers (categories L and N), -, _, ~, and can’t be all numeric.

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

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

  • tags (array) – List containing the tag names to set on the add-on - see available tags.

Addon Icon

A single add-on icon used on AMO can be uploaded to icon, where it will be resized as 32, 64, and 128 pixels wide icons as icons. The resizing is carried out asynchronously so the urls in the response may not be available immediately. The image must be square, in either JPEG or PNG format, and we recommend 128x128.

The upload must be sent as multipart form-data rather than JSON. If desired, some other properties can be set/updated at the same time as icon, but fields that contain complex data structure (list or object) can not, so separate API calls are needed.

Note: as form-data can not include objects, and creating an add-on requires the version to be specified as an object, it’s not possible to set icons during an Add-on create.

PATCH /api/v5/addons/addon/(int:addon_id|string:addon_slug|string:addon_guid)/
Form Parameters:

  • icon – The icon file being uploaded, or an empty value to clear.

Request Headers:

Put - Create or Edit

This endpoint allows a submission of an upload, which will either update an existing add-on and create a new version if the guid already exists, or will create a new add-on if the guid does not exist. See the Add-on Create documentation for details of the request and restrictions.

Note

This API requires authentication, and for the user to be an author of the add-on if the add-on exists already.

Note

The guid in the url must match a guid specified in the manifest.

Note

A submission that results in a new add-on will have metadata defaults taken from the manifest (e.g. name), but a submission that updates an existing listing will not use data from the manifest.

PUT /api/v5/addons/addon/(string: guid)/

Delete

This endpoint allows an add-on to be deleted. Because add-on deletion is an irreversible and destructive action an additional token must be retrieved beforehand, and passed as a parameter to the delete endpoint. Deleting the add-on will permanently delete all versions and files submitted for this add-on, listed or not. The add-on ID (guid) cannot be restored and will forever be unusable for submission.

Note

This API requires authentication, and for the user to be an owner of the add-on..

DELETE /api/v5/addons/addon/(int:id|string:slug|string:guid)/
Query Parameters:

  • delete_confirm (string) – the confirmation token from the delete confirm endpoint.

Delete Confirm

This endpoint just supplies a special signed token that can be used to confirm deletion of an add-on. The token is valid for 60 seconds after it’s been created, and is only valid for this specific add-on.

Note

This API requires authentication, and for the user to be an owner of the add-on.

GET /api/v5/addons/addon/(int:id|string:slug|string:guid)/delete_confirm/
Response JSON Object:

  • delete_confirm (string) – The confirmation token to be used with add-on delete endpoint.

Versions List

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

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

Note

This API accepts both version ids and version numbers in the URL. If the version number passed does not contain any dot characters (.) it would be considered an id. To avoid this and force a lookup by version number, add a v prefix to it.

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

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

Response JSON Object:

  • id (int) – The version id.

  • approval_notes (string) – Information for Mozilla reviewers, for when the add-on is reviewed. These notes are only visible to Mozilla, and this field is only present if the user has reviewer permissions, or is listed as a developer of the add-on.

  • 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 (string) – 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 (string) – Minimum version of the corresponding app the version is compatible with.

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

  • file.id (int) – The id for the file.

  • file.created (string) – The creation date for the file.

  • file.hash (string) – The hash for the file.

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

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

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

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

  • file.size (int) – The size for the file, in bytes.

  • file.status (int) – The status for the file.

  • file.url (string) – The (absolute) URL to download the file.

  • is_disabled (boolean) – If this version has been disabled by the developer. This field is only present for authenticated users, for their own add-ons.

  • 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 (object|null) – The name of the license (See translated fields).

  • license.text (object|null) – The text of the license (See translated fields). For performance reasons this field is only present in version detail detail endpoint: all other endpoints omit it.

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

  • license.slug (string|null) – The license slug, for non-custom (predefined) licenses.

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

  • source (string|null) – The (absolute) URL to download the submitted source for this version. This field is only present for authenticated users, for their own add-ons.

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

Possible values for the version/file status field / parameter:

Value

Description

public

Approved

disabled

Rejected, disabled, or not reviewed

unreviewed

Awaiting Review

Version Create

This endpoint allows a submission of an upload to an existing add-on to create a new version, and setting other AMO metadata.

To create a listed version from an upload (an upload that has channel == listed) certain metadata must be defined - a version license, an add-on name, an add-on summary, and add-on categories for each app the version is compatible with. Add-on properties cannot be set with version create so an add-on update must be made beforehand if the properties are not already defined.

Note

This API requires authentication, and for the user to be an author of the add-on.

POST /api/v5/addons/addon/(int:addon_id|string:addon_slug|string:addon_guid)/versions/
Request JSON Object:

  • approval_notes (string) – Information for Mozilla reviewers, for when the add-on is reviewed. These notes are only visible to Mozilla.

  • compatibility (object|array) – Either an object detailing which applications and versions the version is compatible with; or an array of applications, where min/max versions from the manifest, or defaults, will be used. See examples.

  • compatibility[app_name].max (string) – 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 (string) – Minimum version of the corresponding app the version is compatible with.

  • license (string) – The slug of a non-custom license. The license must match the add-on type. Either provide license or custom_license, not both. If neither are provided, and there was a license defined for the previous version, it will inherit the previous version’s license.

  • custom_license.name (object|null) – The name of the license (See translated fields). Custom licenses are not supported for themes.

  • custom_license.text (object|null) – The text of the license (See translated fields). Custom licenses are not supported for themes.

  • release_notes (object|null) – The release notes for this version (See translated fields).

  • source (string|null) – The submitted source for this version. As JSON this field can only be set to null, to clear it - see uploading source to set/update the source file.

  • upload (string) – The uuid for the xpi upload to create this version with.

Version compatibility examples

Note

The compatibility for Dictionary type add-ons cannot be created or updated.

Full example:

{
    "compatibility": {
        "android": {
            "min": "58.0a1",
            "max": "73.0"
        },
        "firefox": {
            "min": "58.0a1",
            "max": "73.0"
        }
    }
}

With some versions omitted:

{
    "compatibility": {
        "android": {
            "min": "58.0a1"
            // "max" is undefined, so the manifest max or default will be used.
        },
        "firefox": {
            // the object is empty - both "min" and "max" are undefined so the manifest min/max
            // or defaults will be used.
        }
    }
}

Shorthand, for when you only want to define compatible apps, but use the min/max versions from the manifest, or use all defaults:

{
    "compatibility": [
        "android",
        "firefox"
    ]
}

Version Sources

Version source files cannot be uploaded as JSON - the request must be sent as multipart form-data instead. If desired, license can be set set/updated at the same time as source, but fields that contain complex data structure (list or object) such as compatibility, release_notes, or custom_license can not, so separate API calls are needed.

Note: as form-data can not be nested as objects it’s not possible to set source as part of the version object defined during an Add-on create.

POST /api/v5/addons/addon/(int:addon_id|string:addon_slug|string:addon_guid)/versions/
Form Parameters:

  • source – The add-on file being uploaded, or an empty value to clear.

  • upload – The uuid for the xpi upload to create this version with.

  • license – The slug of a non-custom license (optional).

Request Headers:
PATCH /api/v5/addons/addon/(int:addon_id|string:addon_slug|string:addon_guid)/versions/(int:id|string:version_number)/
Form Parameters:
Request Headers:

Version Edit

This endpoint allows the metadata for an existing version to be edited.

Note

This API requires authentication, and for the user to be an author of the add-on.

Note

This API accepts both version ids and version numbers in the URL. If the version number passed does not contain any dot characters (.) it would be considered an id. To avoid this and force a lookup by version number, add a v prefix to it.

PATCH /api/v5/addons/addon/(int:addon_id|string:addon_slug|string:addon_guid)/versions/(int:id|string:version_number)/
Request JSON Object:

  • approval_notes (string) – Information for Mozilla reviewers, for when the add-on is reviewed. These notes are only visible to Mozilla.

  • compatibility (object|array) – Either an object detailing which applications and versions the version is compatible with; or an array of applications, where default min/max versions will be used if not already defined. See examples.

  • compatibility[app_name].max (string) – 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 (string) – Minimum version of the corresponding app the version is compatible with.

  • is_disabled (boolean) – If this version has been disabled by the developer. Note: a version with an already disabled file (file.status is disabled) cannot be changed to true.

  • license (string) – The slug of a non-custom license. The license must match the add-on type. Either provide license or custom_license, not both.

  • custom_license.name (object|null) – The name of the license (See translated fields). Custom licenses are not supported for themes.

  • custom_license.text (object|null) – The text of the license (See translated fields). Custom licenses are not supported for themes.

  • release_notes (object|null) – The release notes for this version (See translated fields).

  • source (string|null) – The submitted source for this version. As JSON this field can only be set to null, to clear it - see uploading source to set/update the source file.

Version Delete

This endpoint allows a version to be deleted.

Note

This API requires authentication, and for the user to be an author of the add-on.

Note

This API accepts both version ids and version numbers in the URL. If the version number passed does not contain any dot characters (.) it would be considered an id. To avoid this and force a lookup by version number, add a v prefix to it.

DELETE /api/v5/addons/addon/(int:addon_id|string:addon_slug|string:addon_guid)/versions/(int:id|string:version_number)/

Preview Create

This endpoint allows a submission of a preview image to an existing non-theme add-on to create a new preview image. Themes can only have generated previews and new previews can not be created. Image files cannot be uploaded as JSON - the request must be sent as multipart form-data instead. If desired, position can be set set at the same time as image, but caption can not, so a separate API call is needed.

Note

This API requires authentication, and for the user to be an author of the add-on.

POST /api/v5/addons/addon/(int:addon_id|string:addon_slug|string:addon_guid)/previews/
Form Parameters:

  • image – The image being uploaded.

  • postion – Integer value for the position the image should be returned in the addon detail (optional). Order is ascending so lower positions are placed earlier.

Request Headers:

Preview Edit

This endpoint allows the metadata for an existing preview for a non-theme add-on to be edited. Themes can only have generated previews and previews can not be edited.

Note

This API requires authentication, and for the user to be an author of the add-on.

PATCH /api/v5/addons/addon/(int:addon_id|string:addon_slug|string:addon_guid)/previews/(int: id)/
Request JSON Object:

  • caption (object) – The caption describing a preview (See translated fields).

  • position (int) – The position the image should be returned in the addon detail. Order is ascending so lower positions are placed earlier.

Preview Delete

This endpoint allows the metadata for an existing preview for a non-theme add-on to be deleted. Themes can only have generated previews and previews can not be deleted.

Note

This API requires authentication, and for the user to be an author of the add-on.

DELETE /api/v5/addons/addon/(int:addon_id|string:addon_slug|string:addon_guid)/previews/(int: id)/

Upload Create

This endpoint is for uploading an addon file, to then be submitted to create a new addon or version.

Note

This API requires authentication.

POST /api/v5/addons/upload/
Form Parameters:

  • upload – The add-on file being uploaded.

  • channel – The channel this version should be uploaded to, which determines its visibility on the site. It can be either unlisted or listed.

Request Headers:

After the file has uploaded the upload response will be returned immediately, and the addon submitted for validation. The upload detail endpoint should be queried for validation status to determine when/if the upload can be used to create an add-on/version.

Upload List

This endpoint is for listing your previous uploads.

Note

This API requires authentication.

GET /api/v5/addons/upload/
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 number of uploads this user has submitted.

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

Upload Detail

This endpoint is for fetching a single previous upload by uuid.

Note

This API requires authentication.

GET /api/v5/addons/upload/<string:uuid>/
Response JSON Object:

  • uuid (string) – The upload id.

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

  • processed (boolean) – If the version has been processed by the validator.

  • submitted (boolean) – If this upload has been submitted as a new add-on or version already. An upload can only be submitted once.

  • url (string) – URL to check the status of this upload.

  • valid (boolean) – If the version passed validation.

  • validation (object) – the validation results JSON blob.

  • version (string) – The version number parsed from the manifest.

EULA and Privacy Policy

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

GET /api/v5/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 (object|null) – The text of the EULA, if present (See translated fields).

  • privacy_policy (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/v5/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 when appversion is present, ignored otherwise. 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, file, reviewed, and version.

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

  • results[].name (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/v5/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/v5/addons/recommendations/
Query Parameters:

  • app (string) – Set the add-on application for that query. This won’t filter the results. Defaults to firefox.

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

Browser Mappings

This endpoint provides browser mappings of non-Firefox and Firefox extensions. Added to support the extensions import feature in Firefox.

GET /api/v5/addons/browser-mappings/

Note

This endpoint uses a larger page_size than most other API endpoints.

Query Parameters:

  • browser (string) – The browser identifier for this query (required). Must be one of these: chrome.

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

Response JSON Object:

  • results (array) – An array containing a mapping of non-Firefox and Firefox extension IDs for a given browser.

  • results[].extension_id (string) – A non-Firefox extension ID.

  • results[].addon_guid (string) – The corresponding Firefox add-on guid.