Queues API Documentation

The QueuesController handles queue-related operations, such as creating, updating, shuffling, and deleting playback queues, as well as managing tracks within queues.

Controller Route: `/api/queues`

All routes within the QueuesController are prefixed by /api/queues.

Summary of Endpoints

Endpoint	Method	Description	Authorization
`/api/queues/create`	POST	Create a new queue with a list of track IDs.	Admin, User
`/api/queues/create-from-albums`	POST	Create a queue from albums.	Admin, User
`/api/queues/create-from-artists`	POST	Create a queue from artists.	Admin, User
`/api/queues/create-from-playlists`	POST	Create a queue from playlists.	Admin, User
`/api/queues/create-from-collections`	POST	Create a queue from collections.	Admin, User
`/api/queues/get`	GET	Get details of a specific queue by ID.	Admin, User
`/api/queues/search`	GET	Search for queues by name.	Admin, User
`/api/queues/get-tracks`	GET	Get tracks of a specific queue.	Admin, User
`/api/queues/get-track`	GET	Get a specific track from a queue by index.	Admin, User
`/api/queues/add-tracks`	POST	Add tracks to a specific queue.	Admin, User
`/api/queues/remove-tracks`	POST	Remove tracks from a specific queue.	Admin, User
`/api/queues/delete`	POST	Delete a specific queue.	Admin, User
`/api/queues/move-track`	POST	Move a track within a queue.	Admin, User
`/api/queues/update-position`	POST	Update the playback position within a queue.	Admin, User
`/api/queues/update`	POST	Update the metadata (name, editors, viewers) of a queue.	Admin, User
`/api/queues/shuffle`	POST	Shuffle the tracks within a queue.	Admin, User
`/api/queues/favorite`	POST	Mark or unmark a queue as a favorite.	Admin, User

Endpoint Details

Create Queue from Track IDs

Create a new queue with a list of track IDs and optional shuffle settings.

Details:

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

Parameters:

name (string, required): The name of the queue.
ids (List<string>, required): A list of track IDs to add to the queue.
shuffle (string, optional): Shuffle mode (none, TrackRandom, Album, etc.).
enableTrackLinks (boolean, optional): Whether to enable track links (default: true).

Responses:

200 OK: Queue created successfully with the new ID.
404 Not Found: No tracks found with the provided IDs.

Example Request (using curl):

curl -X POST "https://your-api-url.com/api/queues/create?name=MyQueue&ids=track1&ids=track2" \
             -H "Authorization: Bearer <JWT-token>"

Create Queue from Albums

Create a queue from a list of album IDs.

Details:

Endpoint: /api/queues/create-from-albums
Method: POST
Authorization: JWT (Roles: Admin, User)

Parameters:

name (string, required): The name of the queue.
ids (List<string>, required): A list of album IDs.
shuffle (string, optional): Shuffle mode (none, TrackRandom, etc.).
enableTrackLinks (boolean, optional): Whether to enable track links (default: true).

Responses:

200 OK: Queue created successfully with the new ID.
404 Not Found: One or more albums not found.

Example Request (using curl):

curl -X POST "https://your-api-url.com/api/queues/create-from-albums?name=AlbumQueue&ids=album1&ids=album2" \
             -H "Authorization: Bearer <JWT-token>"

Create Queue from Artists

Create a queue from a list of artist IDs.

Details:

Endpoint: /api/queues/create-from-artists
Method: POST
Authorization: JWT (Roles: Admin, User)

Parameters:

name (string, required): The name of the queue.
ids (List<string>, required): A list of artist IDs.
shuffle (string, optional): Shuffle mode (none, TrackRandom, etc.).
enableTrackLinks (boolean, optional): Whether to enable track links (default: true).

Responses:

200 OK: Queue created successfully with the new ID.
404 Not Found: One or more artists not found.

Example Request (using curl):

curl -X POST "https://your-api-url.com/api/queues/create-from-artists?name=ArtistQueue&ids=artist1&ids=artist2" \
             -H "Authorization: Bearer <JWT-token>"

Create Queue from Playlists

Create a queue using a list of playlists.

Details:

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

Parameters:

name (string, required): The name of the new queue.
ids (List<string>, required): A list of playlist IDs to include in the queue.
shuffle (string, optional): Shuffle mode for the queue. Options include none, TrackRandom, Album, ArtistRandom, etc. (default: none).
enableTrackLinks (boolean, optional): Whether to enable track links within the queue (default: true).

Responses:

200 OK: Queue created successfully, returns the ID of the new queue.
404 Not Found: One or more playlists not found.

Example Request (using curl):

curl -X POST "https://your-api-url.com/api/queues/create-from-playlists?name=MyQueue&ids=playlist1&ids=playlist2" \
             -H "Authorization: Bearer <JWT-token>"

Create Queue from Collections

Create a queue using a list of collections.

Details:

Endpoint: /api/queues/create-from-collections
Method: POST
Authorization: JWT (Roles: Admin, User)

Parameters:

name (string, required): The name of the new queue.
ids (List<string>, required): A list of collection IDs to include in the queue.
shuffle (string, optional): Shuffle mode for the queue. Options include none, TrackRandom, Album, ArtistRandom, etc. (default: none).
enableTrackLinks (boolean, optional): Whether to enable track links within the queue (default: true).

Responses:

200 OK: Queue created successfully, returns the ID of the new queue.
404 Not Found: One or more collections not found.

Example Request (using curl):

curl -X POST "https://your-api-url.com/api/queues/create-from-collections?name=MyQueue&ids=collection1&ids=collection2" \
             -H "Authorization: Bearer <JWT-token>"

Get Queue by ID

Retrieve the details of a specific queue by its ID.

Details:

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

Parameters:

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

Responses:

200 OK: Returns the details of the queue.
404 Not Found: If the queue does not exist.

Example Request (using curl):

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

Add Tracks to Queue

Add tracks to an existing queue.

Details:

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

Parameters:

id (string, required): The ID of the queue.
trackIds (List<string>, required): A list of track IDs to add.
position (string, optional): Position to add tracks (end, front, random, at).
place (int, optional): Specific index for position at.

Responses:

200 OK: Tracks added to the queue.
404 Not Found: Queue not found.

Example Request (using curl):

curl -X POST "https://your-api-url.com/api/queues/add-tracks?id=queue1&trackIds=track1&trackIds=track2" \
             -H "Authorization: Bearer <JWT-token>"

Search Queues

Search for queues based on a name filter, with pagination and sorting options.

Details:

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

Parameters:

page (int, optional): Page number for pagination (default: 0).
count (int, optional): Number of queues to return per page (default: 100).
name (string, optional): Name filter for searching queues (case-insensitive).
sortByLastListen (boolean, optional): Whether to sort results by the last listen time (default: true).

Responses:

200 OK: Returns a paginated list of queues.
404 Not Found: No queues found matching the search criteria.

Example Request (using curl):

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

Get Tracks in Queue

Retrieve a paginated list of tracks in a specific queue.

Details:

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

Parameters:

id (string, required): The ID of the queue.
page (int, optional): Page number for pagination (default: 0).
count (int, optional): Number of tracks to return per page (default: 100).

Responses:

200 OK: Returns a paginated list of tracks in the queue.
404 Not Found: Queue not found.

Example Request (using curl):

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

Get Track by Index

Retrieve a specific track from a queue by its index.

Details:

Endpoint: /api/queues/get-track
Method: GET
Authorization: JWT (Roles: Admin, User)

Parameters:

id (string, required): The ID of the queue.
index (uint, required): The index of the track within the queue.

Responses:

200 OK: Returns the details of the track at the specified index.
404 Not Found: Queue or track not found.

Example Request (using curl):

curl -X GET "https://your-api-url.com/api/queues/get-track?id=queue1&index=2" \
             -H "Authorization: Bearer <JWT-token>"

Remove Tracks from Queue

Remove one or more tracks from a queue based on their positions.

Details:

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

Parameters:

id (string, required): The ID of the queue.
positions (List<int>, required): List of track positions to remove from the queue.

Responses:

200 OK: Tracks removed from the queue.
404 Not Found: Queue not found.

Example Request (using curl):

curl -X POST "https://your-api-url.com/api/queues/remove-tracks?id=queue1&positions=1&positions=3" \
             -H "Authorization: Bearer <JWT-token>"

Delete Queue

Delete a specific queue.

Details:

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

Parameters:

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

Responses:

200 OK: Queue deleted successfully.
404 Not Found: Queue not found.

Example Request (using curl):

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

Move Track within Queue

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

Details:

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

Parameters:

id (string, required): The ID of the queue.
fromPos (int, required): The current position of the track.
toPos (int, required): The new position to move the track to.

Responses:

200 OK: Track moved successfully.
404 Not Found: Queue not found.

Example Request (using curl):

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

Update Queue Position

Update the playback position within a queue.

Details:

Endpoint: /api/queues/update-position
Method: POST
Authorization: JWT (Roles: Admin, User)

Parameters:

id (string, required): The ID of the queue.
pos (int, required): The new playback position.
device (string, optional): Device information to skip updates for specific devices.

Responses:

200 OK: Queue playback position updated.
404 Not Found: Queue not found.

Example Request (using curl):

curl -X POST "https://your-api-url.com/api/queues/update-position?id=queue1&pos=4" \
             -H "Authorization: Bearer <JWT-token>"

Update Queue Metadata

Update the metadata of a queue, including name, editors, viewers, and public access settings.

Details:

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

Parameters:

id (string, required): The ID of the queue.
name (string, optional): New name for the queue.
editors (List<string>, optional): List of editor IDs.
viewers (List<string>, optional): List of viewer IDs.
publicEditing (string, optional): Whether the queue allows public editing (true or false).
publicViewing (string, optional): Whether the queue allows public viewing (true or false).

Responses:

200 OK: Queue updated successfully.
404 Not Found: Queue not found.

Example Request (using curl):

curl -X POST "https://your-api-url.com/api/queues/update?id=queue1&name=UpdatedQueue" \
             -H "Authorization: Bearer <JWT-token>"

Shuffle Queue

Shuffle the tracks within a queue using various shuffle modes. For more info see the Shuffling Guide.

Details:

Endpoint: /api/queues/shuffle
Method: POST
Authorization: JWT (Roles: Admin, User)

Parameters:

id (string, required): The ID of the queue.
shuffle (string, optional): Shuffle mode (none, TrackRandom, Album, etc.).
enableTrackLinks (boolean, optional): Whether to enable track links (default: true).

Responses:

200 OK: Queue shuffled successfully.
404 Not Found: Queue not found.

Example Request (using curl):

curl -X POST "https://your-api-url.com/api/queues/shuffle?id=queue1&shuffle=TrackRandom" \
             -H "Authorization: Bearer <JWT-token>"

Toggle Favorite

Mark or unmark a queue as a favorite.

Details:

Endpoint: /api/queues/favorite
Method: POST
Authorization: JWT (Roles: Admin, User)

Parameters:

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

Responses:

200 OK: Queue favorited or unfavorited.
404 Not Found: Queue not found.

Example Request (using curl):

curl -X POST "https://your-api-url.com/api/queues/favorite?id=queue1" \
             -H "Authorization: Bearer <JWT-token>"

This concludes the detailed documentation for the QueuesController. The API provides robust functionality for managing queues, including operations for creating, shuffling, and modifying queues and their tracks.

Queues API Documentation

Controller Route: /api/queues

Summary of Endpoints

Endpoint Details

Create Queue from Track IDs

Create Queue from Albums

Create Queue from Artists

Create Queue from Playlists

Create Queue from Collections

Get Queue by ID

Add Tracks to Queue

Search Queues

Get Tracks in Queue

Get Track by Index

Remove Tracks from Queue

Delete Queue

Move Track within Queue

Update Queue Position

Update Queue Metadata

Shuffle Queue

Toggle Favorite

Controller Route: `/api/queues`