Shelves

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.

Combined Hero Shelves

This convenience endpoint serves a single, randomly selected, primary hero shelf, and a single, randomly selected secondary hero shelf.

GET /api/v5/hero/

Query Parameters:

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

Response JSON Object:

• primary (object) – A primary hero shelf.

• secondary (object) – A secondary hero shelf.

Primary Hero Shelves

This endpoint returns all enabled primary hero shelves. As there will only ever be a small number of shelves this endpoint is not paginated.

GET /api/v5/hero/primary/

Query Parameters:

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

• all (boolean) – return all shelves - both enabled and disabled. To be used internally to generate .po files containing the strings defined by the content team.

• raw (string) – If this parameter is present, don’t localise description or fall-back to addon metadata. To be used internally to generate .po files containing the strings defined by the content team.

Response JSON Object:

• results (array) – The array containing the results for this query.

• results[].gradient (object) – The background colors used for the gradient.

• results[].gradient.start (string) – The starting color name for gradient - typically top or left. The name is from the photon color variables.

• results[].gradient.end (string) –

  The ending color name for gradient - typically bottom or right. The name is from the photon color variables.

• results[].featured_image (string|null) – The image used to illustrate the item, if set.

• results[].description (object|null) – The description for this item, if any. (See translated fields. Note: when lang is not specified, not all locales will be returned, unlike other translated fields).

• results[].addon (object) – The add-on for this item if the addon is hosted on AMO. Either this field or external will be present. Only a subset of fields are present: id, authors, average_daily_users, current_version (with only the id, compatibility, is_strict_compatibility_enabled and file fields present), guid, icon_url, name, ratings, previews, promoted, slug, theme_data, type, and url.

• results[].external (object) – The add-on for this item if the addon is externally hosted. Either this field or addon will be present. Only a subset of fields are present: id, guid, homepage, name and type.

Secondary Hero Shelves

This endpoint returns all enabled secondary hero shelves. As there will only ever be a small number of shelves - and likely only one - this endpoint is not paginated.

GET /api/v5/hero/secondary/

Query Parameters:

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

• all (boolean) – return all shelves - both enabled and disabled. To be used internally to generate .po files containing the strings defined by the content team.

Response JSON Object:

• results (array) – The array containing the results for this query.

• results[].headline (object|null) – The headline for this item. (See translated fields. Note: when lang is not specified, not all locales will be returned, unlike other translated fields).

• results[].description (object|null) – The description for this item. (See translated fields. Note: when lang is not specified, not all locales will be returned, unlike other translated fields).

• results[].cta (object|null) – The optional call to action link and text to be displayed with the item.

• results[].cta.url (string) – The url the call to action would link to.

• results[].cta.outgoing (string) – (v5+ only) url wrapped with outgoing (See Outgoing Links)

• results[].cta.text (object|null) – The call to action text. (See translated fields. Note: when lang is not specified, not all locales will be returned, unlike other translated fields).

• results[].modules (array) – The modules for this shelf. Should always be 3.

• results[].modules[].icon (string) – The icon used to illustrate the item.

• results[].modules[].description (object|null) – The description for this item. (See translated fields. Note: when lang is not specified, not all locales will be returned, unlike other translated fields).

• results[].modules[].cta (object|null) – The optional call to action link and text to be displayed with the item.

• results[].modules[].cta.url (string) – The url the call to action would link to.

• results[].modules[].cta.outgoing (string) – (v5+ only) url wrapped with outgoing (See Outgoing Links)

• results[].modules[].cta.text (object|null) – The call to action text. (See translated fields. Note: when lang is not specified, not all locales will be returned, unlike other translated fields).

Homepage Shelves

This endpoint returns the shelves to display on the AMO Homepage. A single, randomly selected, primary hero shelf and a single, randomly selected secondary hero shelf is returned, along with the enabled shelves. As there will only ever be a small number of shelves this endpoint is not paginated.

GET /api/v5/shelves/

Query Parameters:

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

Response JSON Object:

• results (array) – The array of shelves displayed on the AMO Homepage.

• results[].title (object|null) – The title of the shelf. (See translated fields. Note: when lang is not specified, not all locales will be returned, unlike other translated fields).

• results[].url (string) – The configured URL using the shelf’s endpoint and criteria; links to the shelf’s returned add-ons.

• results[].endpoint (string) – The endpoint type selected for the shelf.

• results[].addon_type (string) – The add-on type selected for the shelf.

• results[].footer (object) – The footer to be displayed with the shelf.

• results[].footer.url (string) – The url for the footer text.

• results[].footer.outgoing (string) – url wrapped with outgoing (See Outgoing Links)

• results[].footer.text (object|null) – The optional text in the footer of the shelf. (See translated fields. Note: when lang is not specified, not all locales will be returned, unlike other translated fields).

• results[].addons (array) – An array of add-ons.

• primary (object|null) – A primary hero shelf.

• secondary (object|null) – A secondary hero shelf.

Possible values for the endpoint field:

Value	Description
search	an addon search.
collections	a mozilla collection.
random-tag	a search for addons matching a randomly chosen tag each time.

Homepage Shelves Editorial Content

This endpoint allows you to fetch all editorial content for Homepage Shelves. This is used internally to generate .po files containing the strings defined by the content team.

GET /api/v5/shelves/editorial

Response JSON Object:

• results (array) – The array of shelves displayed on the AMO Homepage.

• results[].title (string|null) – The title of the shelf.

• results[].footer_text (string|null) – The optional text in the footer of the shelf.