Collections

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.

The following API endpoints cover user created collections.

List

Note

This API requires authentication.

This endpoint allows you to list all collections authored by the specified user. The results are sorted by the most recently updated collection first.

GET /api/v4/accounts/account/(int:user_id|string:username)/collections/

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

Detail

This endpoint allows you to fetch a single collection by its slug. It returns any public collection by the specified user. You can access a non-public collection only if it was authored by you, the authenticated user. If you have Admin:Curation permission you can see any collection belonging to the mozilla user.

GET /api/v4/accounts/account/(int:user_id|string:username)/collections/(string: collection_slug)/

Response JSON Object:

id (int) – The id for the collection.
addon_count (int) – The number of add-ons in this collection.
author.id (int) – The id of the author (creator) of the collection.
author.name (string) – The name of the author.
author.url (string) – The link to the profile page for of the author.
author.username (string) – The username of the author.
default_locale (string) – The default locale of the description and name fields. (See translated fields).
description (string|object|null) – The description the author added to the collection. (See translated fields).
modified (string) – The date the collection was last updated.
name (string|object) – The name of the collection. (See translated fields).
public (boolean) – Whether the collection is listed - publicly viewable.
slug (string) – The name used in the URL.
url (string) – The (absolute) collection detail URL.
uuid (string) – A unique identifier for this collection; primarily used to count addon installations that come via this collection.

If the with_addons parameter is passed then addons in the collection are returned along with the detail. Add-ons returned are limited to the first 25 in the collection, in the default sort (popularity, descending). Filtering is as per collection addon list endpoint - i.e. defaults to only including public add-ons. Additional add-ons can be returned from the Collection Add-on list endpoint.

GET /api/v4/accounts/account/(int:user_id|string:username)/collections/(string: collection_slug)/?with_addons

Query Parameters:

filter (string) – The filter to apply.

Response JSON Object:

id (int) – The id for the collection.
addon_count (int) – The number of add-ons in this collection.
addons (array) – An array of addons with notes.

… rest as collection detail response

Create

Note

This API requires authentication.

This endpoint allows a collection to be created under your account. Any fields in the collection but not listed below are not settable and will be ignored in the request.

POST /api/v4/accounts/account/(int:user_id|string:username)/collections/

Request JSON Object:

default_locale (string|null) – The default locale of the description and name fields. Defaults to en-US. (See translated fields).
description (string|object|null) – The description the author added to the collection. (See translated fields).
name (string|object) – The name of the collection. (required) (See translated fields).
public (boolean) – Whether the collection is listed - publicly viewable. Defaults to True.
slug (string) – The name used in the URL (required).

Edit

Note

This API requires authentication. If you have Admin:Curation permission you can edit any collection belonging to the mozilla user.

This endpoint allows some of the details for a collection to be updated. Any fields in the collection but not listed below are not editable and will be ignored in the patch request.

PATCH /api/v4/accounts/account/(int:user_id|string:username)/collections/(string: collection_slug)/

Request JSON Object:

default_locale (string) – The default locale of the description and name fields. (See translated fields).
description (string|object|null) – The description the author added to the collection. (See translated fields).
name (string|object) – The name of the collection. (See translated fields).
public (boolean) – Whether the collection is listed - publicly viewable.
slug (string) – The name used in the URL.

Delete

Note

This API requires authentication.

This endpoint allows the collection to be deleted.

DELETE /api/v4/accounts/account/(int:user_id|string:username)/collections/(string: collection_slug)/

Collection Add-ons List

This endpoint lists the add-ons in a collection, together with collector’s notes.

GET /api/v4/accounts/account/(int:user_id|string:username)/collections/(string: collection_slug)/addons/

Query Parameters:

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

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 items in this collection.

Available sorting parameters:

Parameter

Description

added

Date the add-on was added to the collection, ascending.

popularity

Number of total weekly downloads of the add-on, ascending.

name

Add-on name, ascending.

All sort parameters can be reversed, e.g. ‘-added’ for descending dates. The default sorting is by popularity, descending (‘-popularity’). There can only be one sort parameter, multiple orderings are not supported.

By default, the collection addon list API will only return public add-ons (excluding add-ons that have no approved listed versions, are disabled or deleted) - you can change that with the filter query parameter:

Value

Description

all

Show all add-ons in the collection, including those that have non-public statuses. This still excludes deleted add-ons.

all_with_deleted

Show all add-ons in the collection, including deleted add-ons too.

Collection Add-ons Detail

This endpoint gets details of a single add-on in a collection, together with collector’s notes.

GET /api/v4/accounts/account/(int:user_id|string:username)/collections/(string: collection_slug)/addons/(int:addon_id|string:slug)/

Response JSON Object:

addon (object) – The add-on for this item.
notes (string|object|null) – The collectors notes for this item. (See translated fields).

Collection Add-ons Create

Note

This API requires authentication.

This endpoint allows a single add-on to be added to a collection, optionally with collector’s notes.

POST /api/v4/accounts/account/(int:user_id|string:username)/collections/(string: collection_slug)/addons/

Request JSON Object:

addon (string) – The add-on id or slug to be added (required).
notes (string|object|null) – The collectors notes for this item. (See translated fields).

Collection Add-ons Edit

Note

This API requires authentication. If you have Admin:Curation permission you can edit the add-ons of any collection belonging to the mozilla user. If you have Collections:Contribute permission you can edit the add-ons of mozilla’s Featured Themes collection.

This endpoint allows the collector’s notes for single add-on to be updated.

PATCH /api/v4/accounts/account/(int:user_id|string:username)/collections/(string: collection_slug)/addons/(int:addon_id|string:slug)/

Request JSON Object:

notes (string|object|null) – The collectors notes for this item. (See translated fields).

Collection Add-ons Delete

Note

This API requires authentication. If you have Admin:Curation permission you can remove add-ons from any collection belonging to the mozilla user. If you have Collections:Contribute permission you can remove add-ons from mozilla’s Featured Themes collection.

This endpoint allows a single add-on to be removed from a collection.

DELETE /api/v4/accounts/account/(int:user_id|string:username)/collections/(string: collection_slug)/addons/(int:addon_id|string:slug)/