Playlists Controller Documentation

The PlaylistsController handles the creation, modification, and retrieval of playlists and their associated tracks, albums, and artists. This controller manages all playlist-related functionality within the API. For more info on playlists see the Playlist Guide.

Controller Route: `/api/playlists`

All routes within the PlaylistsController are prefixed by /api/playlists.

Summary of Endpoints

Endpoint	Method	Description	Authorization
`/api/playlists/create`	POST	Create a new playlist.	Admin, User
`/api/playlists/add-tracks`	POST	Add tracks to an existing playlist.	Admin, User
`/api/playlists/remove-tracks`	POST	Remove tracks from an existing playlist.	Admin, User
`/api/playlists/delete`	POST	Delete an existing playlist.	Admin, User
`/api/playlists/update`	POST	Update the details of an existing playlist.	Admin, User
`/api/playlists/move-track`	POST	Move a track from one position to another within a playlist.	Admin, User
`/api/playlists/get`	GET	Retrieve the details of a specific playlist by its ID.	Admin, User, Pass
`/api/playlists/search`	GET	Search for playlists by name with pagination support.	Admin, User, Pass
`/api/playlists/get-tracks`	GET	Retrieve a paginated list of tracks from a specific playlist.	Admin, User, Pass
`/api/playlists/get-albums`	GET	Retrieve albums associated with tracks in a playlist.	Admin, User, Pass
`/api/playlists/get-artists`	GET	Retrieve artists associated with tracks in a playlist.	Admin, User, Pass

Create a Playlist

Create a new playlist with an optional description and initial list of track IDs.

Details:

Endpoint: /api/playlists/create
Method: POST
Authorization: JWT (Roles: Admin, User)

Parameters:

name (string, required): The name of the playlist.
description (string, optional): A description for the playlist.
ids (List<string>, optional): A list of track IDs to add to the playlist.

Responses:

200 OK: Returns the ID of the newly created playlist.
404 Not Found: If any tracks provided in the list of track IDs are not found.

Example Request (using curl):

curl -X POST "https://your-api-url.com/api/playlists/create?name=My%20Playlist&description=This%20is%20a%20test%20playlist&ids=66bc9aafab7ba419497e7bcf&ids=66bc9aafab7ba419497e7fea" \
             -H "Authorization: Bearer <JWT-token>"

Add Tracks to Playlist

Add tracks to an existing playlist by providing a list of track IDs.

Details:

Endpoint: /api/playlists/add-tracks
Method: POST
Authorization: JWT (Roles: Admin, User)

Parameters:

id (string, required): The ID of the playlist.
trackIds (List<string>, required): A list of track IDs to add to the playlist.

Responses:

200 OK: Returns a success message if tracks were added successfully.
404 Not Found: If the playlist or any tracks in the provided list are not found.
401 Unauthorized: If the user does not have the required permissions to edit the playlist.

Example Request (using curl):

curl -X POST "https://your-api-url.com/api/playlists/add-tracks?id=66dd3bd79d629bfdda4c50be&trackIds=66bc9aafab7ba419497e7fea" \
             -H "Authorization: Bearer <JWT-token>"

Remove Tracks from Playlist

Remove tracks from a playlist by providing their positions in the playlist.

Details:

Endpoint: /api/playlists/remove-track
Method: POST
Authorization: JWT (Roles: Admin, User)

Parameters:

id (string, required): The ID of the playlist.
positions (List<int>, required): A list of track positions to remove (starting at 0).

Responses:

200 OK: Returns a success message if tracks were removed successfully.
404 Not Found: If the playlist or tracks at the specified positions are not found.
401 Unauthorized: If the user does not have the required permissions to edit the playlist.

Example Request (using curl):

curl -X POST "https://your-api-url.com/api/playlists/remove-tracks?id=66dd3bd79d629bfdda4c50be&positions=5" \
             -H "Authorization: Bearer <JWT-token>"

Delete a Playlist

Delete an existing playlist by its ID.

Details:

Endpoint: /api/playlists/delete
Method: POST
Authorization: JWT (Roles: Admin, User)

Parameters:

id (string, required): The ID of the playlist to delete.

Responses:

200 OK: Returns a success message if the playlist was deleted successfully.
404 Not Found: If the playlist is not found.
401 Unauthorized: If the user does not have the required permissions to delete the playlist.

Example Request (using curl):

curl -X POST "https://your-api-url.com/api/playlists/delete?id=66dd3bd79d629bfdda4c50be" \
             -H "Authorization: Bearer <JWT-token>"

Update Playlist

Update the details of an existing playlist, such as its name, description, editors, viewers, and public access settings.

Details:

Endpoint: /api/playlists/update
Method: POST
Authorization: JWT (Roles: Admin, User)

Parameters:

id (string, required): The ID of the playlist.
description (string, optional): New description for the playlist.
name (string, optional): New name for the playlist.
editors (List<string>, optional): List of users who can edit the playlist.
viewers (List<string>, optional): List of users who can view the playlist.
publicEditing (string, optional): Public editing flag (true/false).
publicViewing (string, optional): Public viewing flag (true/false).

Responses:

200 OK: Returns a success message if the playlist was updated successfully.
404 Not Found: If the playlist is not found.
400 Bad Request: If the parameters are invalid.
401 Unauthorized: If the user does not have the required permissions to edit the playlist.

Example Request (using curl):

curl -X POST "https://your-api-url.com/api/playlists/update?id=66dd3bd79d629bfdda4c50be&name=Updated%20Playlist&description=New%20description" \
             -H "Authorization: Bearer <JWT-token>"

Move Track in Playlist

Move a track from one position to another within a playlist.

Details:

Endpoint: /api/playlists/move-track
Method: POST
Authorization: JWT (Roles: Admin, User)

Parameters:

id (string, required): The ID of the playlist.
fromPos (int, required): The current position of the track.
toPos (int, required): The new position for the track.

Responses:

200 OK: Returns a success message if the track was moved successfully.
404 Not Found: If the playlist or track is not found.
401 Unauthorized: If the user does not have the required permissions to edit the playlist.

Example Request (using curl):

curl -X POST "https://your-api-url.com/api/playlists/move-track?id=playlistId&fromPos=2&toPos=4" \
             -H "Authorization: Bearer <JWT-token>"

Get Playlist by ID

Retrieve the details of a specific playlist by its ID.

Details:

Endpoint: /api/playlists/get
Method: GET
Authorization: JWT (Roles: Admin, User, Pass)

Parameters:

id (string, required): The ID of the playlist.

Responses:

200 OK: Returns the playlist details.
404 Not Found: If the playlist is not found.
401 Unauthorized: If the user does not have access to the playlist.

Example Request (using curl):

curl -X GET "https://your-api-url.com/api/playlists/get?id=playlistId" \
             -H "Authorization: Bearer <JWT-token>"

Search Playlists

Search for playlists by name, supporting pagination. Entering no search name will return all visible playlists.

Details:

Endpoint: /api/playlists/search
Method: GET
Authorization: JWT (Roles: Admin, User, Pass)

Parameters:

page (int, required): The page number for pagination.
count (int, required): The number of playlists per page.
name (string, optional): A keyword to search by playlist name.

Responses:

200 OK: Returns a paginated list of playlists matching the search criteria.
404 Not Found: If no playlists are found.

Example Request (using curl):

curl -X GET "https://your-api-url.com/api/playlists/search?page=0&count=10&name=My%20Playlist" \
             -H "Authorization: Bearer <JWT-token>"

Get Tracks from Playlist

Retrieve a paginated list of tracks from a specific playlist.

Details:

Endpoint: /api/playlists/get-tracks
Method: GET
Authorization: JWT (Roles: Admin, User, Pass)

Parameters:

id (string, required): The ID of the playlist.
page (int, optional): The page number (default is 0).
count (int, optional): The number of tracks per page (default is 100).

Responses:

200 OK: Returns a paginated list of tracks for the specified playlist.
404 Not Found: If the playlist is not found.
401 Unauthorized: If the user does not have access to the playlist.

Example Request (using curl):

curl -X GET "https://your-api-url.com/api/playlists/get-tracks?id=playlistId&page=0&count=10" \
             -H "Authorization: Bearer <JWT-token>"

Get Albums from Playlist

Retrieve albums associated with tracks in a playlist.

Details:

Endpoint: /api/playlists/get-albums
Method: GET
Authorization: JWT (Roles: Admin, User, Pass)

Parameters:

id (string, required): The ID of the playlist.
page (int, optional): The page number (default is 0).
count (int, optional): The number of albums per page (default is 100).

Responses:

200 OK: Returns a paginated list of albums associated with the playlist tracks.
404 Not Found: If the playlist is not found.
401 Unauthorized: If the user does not have access to the playlist.

Example Request (using curl):

curl -X GET "https://your-api-url.com/api/playlists/get-albums?id=playlistId&page=0&count=10" \
             -H "Authorization: Bearer <JWT-token>"

Get Artists from Playlist

Retrieve artists associated with tracks in a playlist.

Details:

Endpoint: /api/playlists/get-artists
Method: GET
Authorization: JWT (Roles: Admin, User, Pass)

Parameters:

id (string, required): The ID of the playlist.
page (int, optional): The page number (default is 0).
count (int, optional): The number of artists per page (default is 100).

Responses:

200 OK: Returns a paginated list of artists associated with the playlist tracks.
404 Not Found: If the playlist is not found.
401 Unauthorized: If the user does not have access to the playlist.

Example Request (using curl):

curl -X GET "https://your-api-url.com/api/playlists/get-artists?id=playlistId&page=0&count=10" \
             -H "Authorization: Bearer <JWT-token>"

Playlists Controller Documentation

Controller Route: /api/playlists

Summary of Endpoints

Create a Playlist

Add Tracks to Playlist

Remove Tracks from Playlist

Delete a Playlist

Update Playlist

Move Track in Playlist

Get Playlist by ID

Search Playlists

Get Tracks from Playlist

Get Albums from Playlist

Get Artists from Playlist

Controller Route: `/api/playlists`