Collections Controller Documentation

The CollectionsController provides APIs for managing collections of tracks, including creating, updating, deleting, and retrieving collections. Collections allow users to create auto-generated playlists using filters based on metadata. It also supports setting permissions for who can view and edit a collection. For more info on Collections see the Playlist Guide.

For more details on managing collections, refer to the Melon Collections Guide.

Controller Route: `/api/collections`

All routes within the CollectionsController are prefixed by /api/collections.

Summary of Endpoints

Endpoint	Method	Description	Authorization
`/api/collections/create`	POST	Creates a new collection.	Admin, User
`/api/collections/add-filters`	POST	Adds filters to an existing collection.	Admin, User
`/api/collections/remove-filters`	POST	Removes filters from an existing collection.	Admin, User
`/api/collections/delete`	POST	Deletes a collection.	Admin, User
`/api/collections/update`	POST	Updates collection metadata and permissions.	Admin, User
`/api/collections/get`	GET	Retrieves metadata about a specific collection.	Admin, User, Pass
`/api/collections/search`	GET	Searches for collections based on filters and pagination.	Admin, User, Pass
`/api/collections/get-tracks`	GET	Retrieves tracks from a specific collection.	Admin, User, Pass
`/api/collections/get-albums`	GET	Retrieves albums from a specific collection.	Admin, User, Pass
`/api/collections/get-artists`	GET	Retrieves artists from a specific collection.	Admin, User, Pass

Filters

Collections take filters, which they use to find the tracks to add. They use the same filters as Search uses to find tracks. Filters look like this: property;comparison;value.

Property is any property from a Track model. For example, Genre, Artist, Ratings, Name.
Comparison is the type of comparing you want to match the property to the value. This can be Contains, Eq, NotEq, Lt, or Gt.
Value is the value to compare, for example a string or a number. Examples:
Artist;Eq;Madeon
Ratings;Gt;4
Year;Lt;2010

Create Collection

Creates a new collection based on provided filters.

Details:

Endpoint: /api/collections/create
Method: POST
Authorization: JWT with Admin or User role

Parameters:

name (string, required): The name of the collection.
description (string, optional): The description of the collection.
andFilters (List<string>, optional): Filters where each must match for a track to be included.
orFilters (List<string>, optional): Filters where at least one must match for a track to be included.

Responses:

200 OK: Collection created successfully, returns the collection's ID.
400 Bad Request: Invalid parameters or filters.
401 Unauthorized: User lacks necessary permissions.

Example Request (using curl):

curl -X POST "https://your-melon-server.com/api/collections/create" \
             -H "Authorization: Bearer <Admin-or-User-JWT>" \
             -d "name=My Collection" \
             -d "description=My favorite tracks" \
             -d "andFilters=Artist:Eq:Madeon" \
             -d "orFilters=Genre;Eq;French House"

Add Filters to Collection

Adds filters to an existing collection.

Details:

Endpoint: /api/collections/add-filters
Method: POST
Authorization: JWT with Admin or User role

Parameters:

id (string, required): The unique identifier of the collection.
andFilters (List<string>, optional): Filters where each must match for a track to be included.
orFilters (List<string>, optional): Filters where at least one must match for a track to be included.

Responses:

200 OK: Filters added successfully.
400 Bad Request: Invalid parameters or filters.
401 Unauthorized: User lacks necessary permissions.
404 Not Found: Collection not found.

Example Request (using curl):

curl -X POST "https://your-melon-server.com/api/collections/add-filters" \
             -H "Authorization: Bearer <Admin-or-User-JWT>" \
             -d "id=66bc9aadab7ba419497e6a97" \
             -d "andFilters=Genre;Eq;Pop"

Remove Filters from Collection

Removes filters from an existing collection.

Details:

Endpoint: /api/collections/remove-filters
Method: POST
Authorization: JWT with Admin or User role

Parameters:

id (string, required): The unique identifier of the collection.
andFilters (List<string>, optional): Filters to remove from the andFilters list.
orFilters (List<string>, optional): Filters to remove from the orFilters list.

Responses:

200 OK: Filters removed successfully.
400 Bad Request: Invalid parameters or filters.
401 Unauthorized: User lacks necessary permissions.
404 Not Found: Collection not found.

Example Request (using curl):

curl -X POST "https://your-melon-server.com/api/collections/remove-filters" \
             -H "Authorization: Bearer <Admin-or-User-JWT>" \
             -d "id=66bc9aadab7ba419497e6a97" \
             -d "andFilters=Artist;Contains;John"

Delete Collection

Deletes a collection.

Details:

Endpoint: /api/collections/delete
Method: POST
Authorization: JWT with Admin or User role

Parameters:

id (string, required): The unique identifier of the collection.

Responses:

200 OK: Collection deleted successfully.
401 Unauthorized: User lacks necessary permissions.
404 Not Found: Collection not found.

Example Request (using curl):

curl -X POST "https://your-melon-server.com/api/collections/delete" \
             -H "Authorization: Bearer <Admin-or-User-JWT>" \
             -d "id=66bc9aadab7ba419497e6a97"

Update Collection Information

Updates collection metadata, permissions, and user access settings.

Details:

Endpoint: /api/collections/update
Method: POST
Authorization: JWT with Admin or User role

Parameters:

id (string, required): The unique identifier of the collection.
name (string, optional): The updated name of the collection.
description (string, optional): The updated description of the collection.
editors (List<string>, optional): A list of user IDs allowed to edit the collection.
viewers (List<string>, optional): A list of user IDs allowed to view the collection.
publicEditing (string, optional): Indicates if public editing is allowed.
publicViewing (string, optional): Indicates if public viewing is allowed.

Responses:

200 OK: Collection updated successfully.
400 Bad Request: Invalid parameters.
401 Unauthorized: User lacks necessary permissions.
404 Not Found: Collection not found.

Example Request (using curl):

curl -X POST "https://your-melon-server.com/api/collections/update" \
             -H "Authorization: Bearer <Admin-or-User-JWT>" \
             -d "id=66bc9aadab7ba419497e6a97" \
             -d "name=Updated Collection" \
             -d "publicViewing=true"

Get Collection Info

Retrieves metadata about a specific collection. Returns a ResponseCollection.

Details:

Endpoint: /api/collections/get
Method: GET
Authorization: JWT with Admin, User, or Pass role

Parameters:

id (string, required): The unique identifier of the collection.

Responses:

200 OK: Collection information retrieved successfully.
401 Unauthorized: User lacks necessary permissions.
404 Not Found: Collection not found.

Example Request (using curl):

curl -X GET "https://your-melon-server.com/api/collections/get?id=collection123" \
             -H "Authorization: Bearer <Admin-or-User-JWT>"

Search Collections

Searches for collections based on the name (or leave the name empty to list all collections).

Details:

Endpoint: /api/collections/search
Method: GET
Authorization: JWT with Admin, User, or Pass role

Parameters:

page (int, required): The page of results to retrieve.
count (int, required): The number of results per page.
name (string, optional): The name of the collection to search for.

Responses:

200 OK: Collections retrieved successfully.
401 Unauthorized: User lacks necessary permissions.
404 Not Found: Collections not found.

Example Request (using curl):

curl -X GET "https://your-melon-server.com/api/collections/search?page=0&count=10&name=rock" \
             -H "Authorization: Bearer <Admin-or-User-JWT>"

Get Collection Tracks

Retrieves tracks from a specific collection, by page.

Details:

Endpoint: /api/collections/get-tracks
Method: GET
Authorization: JWT with Admin, User, or Pass role

Parameters:

id (string, required): The unique identifier of the collection.
page (int, optional): The page of results to retrieve (default is 0).
count (int, optional): The number of results per page (default is 100).

Responses:

200 OK: Tracks retrieved successfully.
401 Unauthorized: User lacks necessary permissions.
404 Not Found: Collection or tracks not found.

Example Request (using curl):

curl -X GET "https://your-melon-server.com/api/collections/get-tracks?id=collection123&page=0&count=50" \
             -H "Authorization: Bearer <Admin-or-User-JWT>"

Get Collection Albums

Retrieves albums from a specific collection, by page. This returns the a list of albums, but does not return which tracks from each album are there.

Details:

Endpoint: /api/collections/get-albums
Method: GET
Authorization: JWT with Admin, User, or Pass role

Parameters:

id (string, required): The unique identifier of the collection.
page (int, optional): The page of results to retrieve (default is 0).
count (int, optional): The number of results per page (default is 100).

Responses:

200 OK: Albums retrieved successfully.
401 Unauthorized: User lacks necessary permissions.
404 Not Found: Collection or albums not found.

Example Request (using curl):

curl -X GET "https://your-melon-server.com/api/collections/get-albums?id=collection123&page=0&count=50" \
             -H "Authorization: Bearer <Admin-or-User-JWT>"

Get Collection Artists

Retrieves artists from a specific collection, by page. This returns the a list of artists, but does not return which tracks from each album are there.

Details:

Endpoint: /api/collections/get-artists
Method: GET
Authorization: JWT with Admin, User, or Pass role

Parameters:

id (string, required): The unique identifier of the collection.
page (int, optional): The page of results to retrieve (default is 0).
count (int, optional): The number of results per page (default is 100).

Responses:

200 OK: Artists retrieved successfully.
401 Unauthorized: User lacks necessary permissions.
404 Not Found: Collection or artists not found.

Example Request (using curl):

curl -X GET "https://your-melon-server.com/api/collections/get-artists?id=collection123&page=0&count=50" \
             -H "Authorization: Bearer <Admin-or-User-JWT>"

Collections Controller Documentation

Controller Route: /api/collections

Summary of Endpoints

Filters

Create Collection

Add Filters to Collection

Remove Filters from Collection

Delete Collection

Update Collection Information

Get Collection Info

Search Collections

Get Collection Tracks

Get Collection Albums

Get Collection Artists

Controller Route: `/api/collections`