plug.dj Playlist API

plugdj-playlist-api.md

Base URL: https://plug.dj/_

Response Object

Field	Type	Description
data	array	endpoint-specific return data
meta	object	unknown
status	string	unknown - success of the request?
time	float	unknown - time to process request?

{
    "data": [],
    "meta": {},
    "status": "ok",
    "time": 26.842117309570312
}

Playlist

Playlists represent a sorted collection of media.

Playlist Object

Field	Type	Description
active?	boolean	whether or not the playlist is active
count	integer	quantity of media in the playlist
id	integer	playlist's id
name?	string	playlist's name

Example

{
    "active": false,
    "count": 0,
    "id": 11545358,
    "name": "test"
}

Get Playlists

GET /playlists

Returns playlist objects for the currently authenticated user. The objects are sorted by the id field in descending order.

Create Playlist

POST /playlists

Creates a new playlist. Returns the created playlist object.

Parameters

Field	Type	Description
media?	array of media objects	media with which to populate the playlist
name	string	playlist's name

Delete Playlist

DELETE /playlists/{playlist.id}

Deletes a playlist.

Rename Playlist

PUT /playlists/{playlist.id}/rename

Renames a playlist.

Parameters

Field	Type	Description
name	string	new name for the playlist

Media

Media represents some audio or video hosted on an external site.

Media Object

Field	Type	Description
author	string	media's artist
cid	string	content id used by the media's host
duration	string	media's duration in seconds
format	string	media's format - where it is hosted
id	integer	media's id
image	string	thumbnail url
title	string	media's title

Example (YouTube)

{
    "author": "Weast",
    "cid": "lr-zXfbdXow",
    "duration": 326,
    "format": 1,
    "id": 384246963,
    "image": "https://i.ytimg.com/vi/lr-zXfbdXow/default.jpg",
    "title": "Cocola"
}

Media Format

Value	Description
1	YouTube
2	SoundCloud

Get Media

GET /playlists/{playlist.id}/media

Returns media objects for the given playlist.

Add Media

POST /playlists/{playlist.id}/insert

Adds new or existing media to the given playlist. Returns the updated partial playlist object.

Note: To add new media, create media objects with the id set to 0.

Parameters

Field	Type	Description
append	boolean	whether or not to add the media to the end of the playlist rather than the beginning
ids	array of media objects or ids	media to add

Delete Media

POST /playlists/{playlist.id}/delete

Deletes media from the given playlist. Returns the media objects in the playlist after the deletion.

Parameters

Field	Type	Description
ids	array of media object ids	media to delete

Rearrange Media

PUT /playlists/{playlist.id}/move

Changes the order of media in the given playlist. Returns the media objects in the playlist after the rearrangement.

Parameters

Field	Type	Description
beforeID	integer	id of the media above which to place the media to be moved
ids	array of media object ids	media to move

Rename Media

PUT /playlists/{playlist.id}/update

Changes the artist and title of media in the given playlist. Returns the updated partial media object with only the author and title present.

Note: This change does not apply to the same media if it is in other playlists. However, if deleted and re-added, plug.dj does seem to remember the new name given.

Parameters

Field	Type	Description
author	string	new artist for the media
id	integer	media's id
title	string	new title for the media