Collections

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.

The following API endpoints cover user created collections.

List

Note

This API requires authentication and Collections:Edit permission to list collections other than your own.

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/v3/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 your account has the Collections:Edit permission then you can access any collection.

GET /api/v3/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/v3/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/v3/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 and Collections:Edit permission to edit collections other than your own.

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/v3/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 and Collections:Edit permission to delete collections other than your own.

This endpoint allows the collection to be deleted.

DELETE /api/v3/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/v3/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’).

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/v3/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).

  • downloads (int) – The downloads that occured via this collection.

Collection Add-ons Create

Note

This API requires authentication and Collections:Edit permission to edit collections other than your own.

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

POST /api/v3/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 and Collections:Edit permission to edit collections other than your own.

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

PATCH /api/v3/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 and Collections:Edit permission to edit collections other than your own.

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

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