owntone-server/README_JSON_API.md

OwnTone API Endpoint Reference

Available API endpoints:

• Player: control playback, volume, shuffle/repeat modes
• Outputs / Speakers: list available outputs and enable/disable outputs
• Queue: list, add or modify the current queue
• Library: list playlists, artists, albums and tracks from your library or trigger library rescan
• Search: search for playlists, artists, albums and tracks
• Server info: get server information
• Settings: list and change settings for the player web interface
• Push notifications: receive push notifications

JSON-Object model:

• Queue item
• Playlist
• Artist
• Album
• Track

Player

Method	Endpoint	Description
GET	/api/player	Get player status
PUT	/api/player/play, /api/player/pause, /api/player/stop, /api/player/toggle	Start, pause or stop playback
PUT	/api/player/next, /api/player/previous	Skip forward or backward
PUT	/api/player/shuffle	Set shuffle mode
PUT	/api/player/consume	Set consume mode
PUT	/api/player/repeat	Set repeat mode
PUT	/api/player/volume	Set master volume or volume for a specific output
PUT	/api/player/seek	Seek to a position in the currently playing track

Get player status

Endpoint

GET /api/player

Response

Key	Type	Value
state	string	play, pause or stop
repeat	string	off, all or single
consume	boolean	true if consume mode is enabled
shuffle	boolean	true if shuffle mode is enabled
volume	integer	Master volume in percent (0 - 100)
item_id	integer	The current playing queue item id
item_length_ms	integer	Total length in milliseconds of the current queue item
item_progress_ms	integer	Progress into the current queue item in milliseconds

Example

curl -X GET "http://localhost:3689/api/player"

{
  "state": "pause",
  "repeat": "off",
  "consume": false,
  "shuffle": false,
  "volume": 50,
  "item_id": 269,
  "item_length_ms": 278093,
  "item_progress_ms": 3674
}

Control playback

Start or resume, pause, stop playback.

Endpoint

PUT /api/player/play

PUT /api/player/pause

PUT /api/player/stop

PUT /api/player/toggle

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/player/play"

curl -X PUT "http://localhost:3689/api/player/pause"

curl -X PUT "http://localhost:3689/api/player/stop"

curl -X PUT "http://localhost:3689/api/player/toggle"

Skip tracks

Skip forward or backward

Endpoint

PUT /api/player/next

PUT /api/player/previous

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/player/next"

curl -X PUT "http://localhost:3689/api/player/previous"

Set shuffle mode

Enable or disable shuffle mode

Endpoint

PUT /api/player/shuffle

Query parameters

Parameter	Value
state	The new shuffle state, should be either true or false

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/player/shuffle?state=true"

Set consume mode

Enable or disable consume mode

Endpoint

PUT /api/player/consume

Query parameters

Parameter	Value
state	The new consume state, should be either true or false

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/player/consume?state=true"

Set repeat mode

Change repeat mode

Endpoint

PUT /api/player/repeat

Query parameters

Parameter	Value
state	The new repeat mode, should be either off, all or single

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/player/repeat?state=all"

Set volume

Change master volume or volume of a specific output.

Endpoint

PUT /api/player/volume

Query parameters

Parameter	Value
volume	The new volume (0 - 100)
step	The increase or decrease volume by the given amount (-100 - 100)
output_id	(Optional) If an output id is given, only the volume of this output will be changed. If parameter is omited, the master volume will be changed.

Either volume or step must be present as query parameter

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/player/volume?volume=50"

curl -X PUT "http://localhost:3689/api/player/volume?step=-5"

curl -X PUT "http://localhost:3689/api/player/volume?volume=50&output_id=0"

Seek

Seek to a position in the currently playing track.

Endpoint

PUT /api/player/seek

Query parameters

Parameter	Value
position_ms	The new position in milliseconds to seek to
seek_ms	A relative amount of milliseconds to seek to

Response

On success returns the HTTP 204 No Content success status response code.

Example

Seek to position:

curl -X PUT "http://localhost:3689/api/player/seek?position_ms=2000"

Relative seeking (skip 30 seconds backwards):

curl -X PUT "http://localhost:3689/api/player/seek?seek_ms=-30000"

Outputs / Speakers

Method	Endpoint	Description
GET	/api/outputs	Get a list of available outputs
PUT	/api/outputs/set	Set enabled outputs
GET	/api/outputs/{id}	Get an output
PUT	/api/outputs/{id}	Change an output setting
PUT	/api/outputs/{id}/toggle	Enable or disable an output, depending on the current state

Get a list of available outputs

Endpoint

GET /api/outputs

Response

Key	Type	Value
outputs	array	Array of output objects

output object

Key	Type	Value
id	string	Output id
name	string	Output name
type	string	Type of the output: AirPlay, Chromecast, ALSA, Pulseaudio, fifo
selected	boolean	true if output is enabled
has_password	boolean	true if output is password protected
requires_auth	boolean	true if output requires authentication
needs_auth_key	boolean	true if output requires an authorization key (device verification)
volume	integer	Volume in percent (0 - 100)

Example

curl -X GET "http://localhost:3689/api/outputs"

{
  "outputs": [
    {
      "id": "123456789012345",
      "name": "kitchen",
      "type": "AirPlay",
      "selected": true,
      "has_password": false,
      "requires_auth": false,
      "needs_auth_key": false,
      "volume": 0
    },
    {
      "id": "0",
      "name": "Computer",
      "type": "ALSA",
      "selected": true,
      "has_password": false,
      "requires_auth": false,
      "needs_auth_key": false,
      "volume": 19
    },
    {
      "id": "100",
      "name": "daapd-fifo",
      "type": "fifo",
      "selected": false,
      "has_password": false,
      "requires_auth": false,
      "needs_auth_key": false,
      "volume": 0
    }
  ]
}

Set enabled outputs

Set the enabled outputs by passing an array of output ids. The server enables all outputs with the given ids and disables the remaining outputs.

Endpoint

PUT /api/outputs/set

Body parameters

Parameter	Type	Value
outputs	array	Array of output ids

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/outputs/set" --data "{\"outputs\":[\"198018693182577\",\"0\"]}"

Get an output

Get an output

Endpoint

GET /api/outputs/{id}

Path parameters

Parameter	Value
id	Output id

Response

On success returns the HTTP 200 OK success status response code. With the response body holding the output object.

Example

curl -X GET "http://localhost:3689/api/outputs/0"

{
  "id": "0",
  "name": "Computer",
  "type": "ALSA",
  "selected": true,
  "has_password": false,
  "requires_auth": false,
  "needs_auth_key": false,
  "volume": 3
}

Change an output

Enable or disable an output and change its volume.

Endpoint

PUT /api/outputs/{id}

Path parameters

Parameter	Value
id	Output id

Body parameters

Parameter	Type	Value
selected	boolean	(Optional) true to enable and false to disable the output
volume	integer	(Optional) Volume in percent (0 - 100)
pin	string	(Optional) PIN for device verification

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/outputs/0" --data "{\"selected\":true, \"volume\": 50}"

Toggle an output

Enable or disable an output, depending on its current state

Endpoint

PUT /api/outputs/{id}/toggle

Path parameters

Parameter	Value
id	Output id

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/outputs/0/toggle"

Queue

Method	Endpoint	Description
GET	/api/queue	Get a list of queue items
PUT	/api/queue/clear	Remove all items from the queue
POST	/api/queue/items/add	Add items to the queue
PUT	/api/queue/items/{id}|now_playing	Updating a queue item in the queue
DELETE	/api/queue/items/{id}	Remove a queue item from the queue

List queue items

Lists the items in the current queue

Endpoint

GET /api/queue

Query parameters

Parameter	Value
id	(Optional) If a queue item id is given, only the item with the id will be returend. Use id=now_playing to get the currently playing item.
start	(Optional) If a startand an end position is given, only the items from start (included) to end (excluded) will be returned. If only a start position is given, only the item at this position will be returned.
end	(Optional) See start parameter

Response

Key	Type	Value
version	integer	Version number of the current queue
count	integer	Number of items in the current queue
items	array	Array of queue item objects

Example

curl -X GET "http://localhost:3689/api/queue"

{
  "version": 833,
  "count": 20,
  "items": [
    {
      "id": 12122,
      "position": 0,
      "track_id": 10749,
      "title": "Angels",
      "artist": "The xx",
      "artist_sort": "xx, The",
      "album": "Coexist",
      "album_sort": "Coexist",
      "albumartist": "The xx",
      "albumartist_sort": "xx, The",
      "genre": "Indie Rock",
      "year": 2012,
      "track_number": 1,
      "disc_number": 1,
      "length_ms": 171735,
      "media_kind": "music",
      "data_kind": "file",
      "path": "/music/srv/The xx/Coexist/01 Angels.mp3",
      "uri": "library:track:10749"
    },
    ...
  ]
}

Clearing the queue

Remove all items form the current queue

Endpoint

PUT /api/queue/clear

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/queue/clear"

Adding items to the queue

Add tracks, playlists artists or albums to the current queue

Endpoint

POST /api/queue/items/add

Query parameters

Parameter	Value
uris	Comma seperated list of resource identifiers (track, playlist, artist or album object uri)
expression	A smart playlist query expression identifying the tracks that will be added to the queue.
position	(Optional) If a position is given, new items are inserted starting from this position into the queue.
playback	(Optional) If the playback parameter is set to start, playback will be started after adding the new items.
playback_from_position	(Optional) If the playback parameter is set to start, playback will be started with the queue item at the position given in playback_from_position.
clear	(Optional) If the clear parameter is set to true, the queue will be cleared before adding the new items.
shuffle	(Optional) If the shuffle parameter is set to true, the shuffle mode is activated. If it is set to something else, the shuffle mode is deactivated. To leave the shuffle mode untouched the parameter should be ommited.
limit	(Optional) Maximum number of tracks to add

Either the uris or the expression parameter must be set. If both are set the uris parameter takes presedence and the expression parameter will be ignored.

Response

On success returns the HTTP 200 OK success status response code.

Key	Type	Value
count	integer	number of tracks added to the queue

Example

Add new items by uri:

curl -X POST "http://localhost:3689/api/queue/items/add?uris=library:playlist:68,library:artist:2932599850102967727"

{
  "count": 42
}

Add new items by query language:

curl -X POST "http://localhost:3689/api/queue/items/add?expression=media_kind+is+music"

{
  "count": 42
}

Clear current queue, add 10 new random tracks of genre Pop and start playback

curl -X POST "http://localhost:3689/api/queue/items/add?limit=10&clear=true&playback=start&expression=genre+is+%22Pop%22+order+by+random+desc"

{
  "count": 10
}

Updating a queue item

Update or move a queue item in the current queue

Endpoint

PUT /api/queue/items/{id}

or

PUT /api/queue/items/now_playing

Path parameters

Parameter	Value
id	Queue item id

(or use now_playing to update the currenly playing track)

Query parameters

Parameter	Value
new_position	The new position for the queue item in the current queue.
title	New track title
album	New album title
artist	New artist
album_artist	New album artist
composer	New composer
genre	New genre
artwork_url	New URL to track artwork

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/queue/items/3?new_position=0"

curl -X PUT "http://localhost:3689/api/queue/items/3?title=Awesome%20title&artwork_url=http%3A%2F%2Fgyfgafguf.dk%2Fimages%2Fpige3.jpg"

curl -X PUT "http://localhost:3689/api/queue/items/now_playing?title=Awesome%20title&artwork_url=http%3A%2F%2Fgyfgafguf.dk%2Fimages%2Fpige3.jpg"

Removing a queue item

Remove a queue item from the current queue

Endpoint

DELETE /api/queue/items/{id}

Path parameters

Parameter	Value
id	Queue item id

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/queue/items/2"

Library

Method	Endpoint	Description
GET	/api/library	Get library information
GET	/api/library/playlists	Get a list of playlists
GET	/api/library/playlists/{id}	Get a playlist
PUT	/api/library/playlists/{id}	Update a playlist attribute
DELETE	/api/library/playlists/{id}	Delete a playlist
GET	/api/library/playlists/{id}/tracks	Get list of tracks for a playlist
PUT	/api/library/playlists/{id}/tracks	Update play count of tracks for a playlist
GET	/api/library/playlists/{id}/playlists	Get list of playlists for a playlist folder
GET	/api/library/artists	Get a list of artists
GET	/api/library/artists/{id}	Get an artist
GET	/api/library/artists/{id}/albums	Get list of albums for an artist
GET	/api/library/albums	Get a list of albums
GET	/api/library/albums/{id}	Get an album
GET	/api/library/albums/{id}/tracks	Get list of tracks for an album
GET	/api/library/tracks/{id}	Get a track
GET	/api/library/tracks/{id}/playlists	Get list of playlists for a track
PUT	/api/library/tracks/{id}	Update a tracks properties (rating, play_count)
GET	/api/library/genres	Get list of genres
GET	/api/library/count	Get count of tracks, artists and albums
GET	/api/library/files	Get list of directories in the local library
POST	/api/library/add	Add an item to the library
PUT	/api/update	Trigger a library rescan
PUT	/api/rescan	Trigger a library metadata rescan
PUT	/api/library/backup	Request library backup db

Library information

List some library stats

Endpoint

GET /api/library

Response

Key	Type	Value
songs	integer	Array of playlist objects
db_playtime	integer	Total playtime of all songs in the library
artists	integer	Number of album artists in the library
albums	integer	Number of albums in the library
started_at	string	Server startup time (timestamp in ISO 8601 format)
updated_at	string	Last library update (timestamp in ISO 8601 format)
updating	boolean	true if library rescan is in progress

Example

curl -X GET "http://localhost:3689/api/library"

{
  "songs": 217,
  "db_playtime": 66811,
  "artists": 9,
  "albums": 19,
  "started_at": "2018-11-19T19:06:08Z",
  "updated_at": "2018-11-19T19:06:16Z",
  "updating": false
}

List playlists

Lists all playlists in your library (does not return playlist folders)

Endpoint

GET /api/library/playlists

Query parameters

Parameter	Value
offset	(Optional) Offset of the first playlist to return
limit	(Optional) Maximum number of playlists to return

Response

Key	Type	Value
items	array	Array of playlist objects
total	integer	Total number of playlists in the library
offset	integer	Requested offset of the first playlist
limit	integer	Requested maximum number of playlists

Example

curl -X GET "http://localhost:3689/api/library/playlists"

{
  "items": [
    {
      "id": 1,
      "name": "radio",
      "path": "/music/srv/radio.m3u",
      "smart_playlist": false,
      "uri": "library:playlist:1"
    },
    ...
  ],
  "total": 20,
  "offset": 0,
  "limit": -1
}

Get a playlist

Get a specific playlists in your library

Endpoint

GET /api/library/playlists/{id}

Path parameters

Parameter	Value
id	Playlist id

Response

On success returns the HTTP 200 OK success status response code. With the response body holding the playlist object.

Example

curl -X GET "http://localhost:3689/api/library/playlists/1"

{
  "id": 1,
  "name": "radio",
  "path": "/music/srv/radio.m3u",
  "smart_playlist": false,
  "uri": "library:playlist:1"
}

Update a playlist

Update attributes of a specific playlists in your library

Endpoint

PUT /api/library/playlists/{id}

Path parameters

Parameter	Value
id	Playlist id

Query parameters

Parameter	Value
query_limit	For RSS feeds, this sets how many podcasts to retrieve

Example

curl -X PUT "http://localhost:3689/api/library/playlists/25?query_limit=20"

Delete a playlist

Delete a playlist, e.g. a RSS feed

Endpoint

DELETE /api/library/playlists/{id}

Path parameters

Parameter	Value
id	Playlist id

Example

curl -X DELETE "http://localhost:3689/api/library/playlists/25"

List playlist tracks

Lists the tracks in a playlists

Endpoint

GET /api/library/playlists/{id}/tracks

Path parameters

Parameter	Value
id	Playlist id

Query parameters

Parameter	Value
offset	(Optional) Offset of the first track to return
limit	(Optional) Maximum number of tracks to return

Response

Key	Type	Value
items	array	Array of track objects
total	integer	Total number of tracks in the playlist
offset	integer	Requested offset of the first track
limit	integer	Requested maximum number of tracks

Example

curl -X GET "http://localhost:3689/api/library/playlists/1/tracks"

{
  "items": [
    {
      "id": 10766,
      "title": "Solange wir tanzen",
      "artist": "Heinrich",
      "artist_sort": "Heinrich",
      "album": "Solange wir tanzen",
      "album_sort": "Solange wir tanzen",
      "albumartist": "Heinrich",
      "albumartist_sort": "Heinrich",
      "genre": "Electronica",
      "year": 2014,
      "track_number": 1,
      "disc_number": 1,
      "length_ms": 223085,
      "play_count": 2,
      "skip_count": 1,
      "time_played": "2018-02-23T10:31:20Z",
      "media_kind": "music",
      "data_kind": "file",
      "path": "/music/srv/Heinrich/Solange wir tanzen/01 Solange wir tanzen.mp3",
      "uri": "library:track:10766"
    },
    ...
  ],
  "total": 20,
  "offset": 0,
  "limit": -1
}

Update playlist tracks

Updates the play count for tracks in a playlists

Endpoint

PUT /api/library/playlists/{id}/tracks

Path parameters

Parameter	Value
id	Playlist id

Query parameters

Parameter	Value
play_count	Either increment, played or reset. increment will increment play_count and update time_played, played will be like increment but only where play_count is 0, reset will set play_count and skip_count to zero and delete time_played and time_skipped

Example

curl -X PUT "http://localhost:3689/api/library/playlists/1/tracks?play_count=played"

List playlists in a playlist folder

Lists the playlists in a playlist folder

Note: The root playlist folder has id 0.

Endpoint

GET /api/library/playlists/{id}/playlists

Path parameters

Parameter	Value
id	Playlist id

Query parameters

Parameter	Value
offset	(Optional) Offset of the first playlist to return
limit	(Optional) Maximum number of playlist to return

Response

Key	Type	Value
items	array	Array of playlist objects
total	integer	Total number of playlists in the playlist folder
offset	integer	Requested offset of the first playlist
limit	integer	Requested maximum number of playlist

Example

curl -X GET "http://localhost:3689/api/library/playlists/0/tracks"

{
  "items": [
    {
      "id": 11,
      "name": "Spotify",
      "path": "spotify:playlistfolder",
      "parent_id": "0",
      "smart_playlist": false,
      "folder": true,
      "uri": "library:playlist:11"
    },
    {
      "id": 8,
      "name": "bytefm",
      "path": "/srv/music/Playlists/bytefm.m3u",
      "parent_id": "0",
      "smart_playlist": false,
      "folder": false,
      "uri": "library:playlist:8"
    }
  ],
  "total": 2,
  "offset": 0,
  "limit": -1
}

List artists

Lists the artists in your library

Endpoint

GET /api/library/artists

Query parameters

Parameter	Value
offset	(Optional) Offset of the first artist to return
limit	(Optional) Maximum number of artists to return

Response

Key	Type	Value
items	array	Array of artist objects
total	integer	Total number of artists in the library
offset	integer	Requested offset of the first artist
limit	integer	Requested maximum number of artists

Example

curl -X GET "http://localhost:3689/api/library/artists"

{
  "items": [
    {
      "id": "3815427709949443149",
      "name": "ABAY",
      "name_sort": "ABAY",
      "album_count": 1,
      "track_count": 10,
      "length_ms": 2951554,
      "uri": "library:artist:3815427709949443149"
    },
    ...
  ],
  "total": 20,
  "offset": 0,
  "limit": -1
}

Get an artist

Get a specific artist in your library

Endpoint

GET /api/library/artists/{id}

Path parameters

Parameter	Value
id	Artist id

Response

On success returns the HTTP 200 OK success status response code. With the response body holding the artist object.

Example

curl -X GET "http://localhost:3689/api/library/artists/3815427709949443149"

{
  "id": "3815427709949443149",
  "name": "ABAY",
  "name_sort": "ABAY",
  "album_count": 1,
  "track_count": 10,
  "length_ms": 2951554,
  "uri": "library:artist:3815427709949443149"
}

List artist albums

Lists the albums of an artist

Endpoint

GET /api/library/artists/{id}/albums

Path parameters

Parameter	Value
id	Artist id

Query parameters

Parameter	Value
offset	(Optional) Offset of the first album to return
limit	(Optional) Maximum number of albums to return

Response

Key	Type	Value
items	array	Array of album objects
total	integer	Total number of albums of this artist
offset	integer	Requested offset of the first album
limit	integer	Requested maximum number of albums

Example

curl -X GET "http://localhost:3689/api/library/artists/32561671101664759/albums"

{
  "items": [
    {
      "id": "8009851123233197743",
      "name": "Add Violence",
      "name_sort": "Add Violence",
      "artist": "Nine Inch Nails",
      "artist_id": "32561671101664759",
      "track_count": 5,
      "length_ms": 1634961,
      "uri": "library:album:8009851123233197743"
    },
    ...
  ],
  "total": 20,
  "offset": 0,
  "limit": -1
}

List albums

Lists the albums in your library

Endpoint

GET /api/library/albums

Query parameters

Parameter	Value
offset	(Optional) Offset of the first album to return
limit	(Optional) Maximum number of albums to return

Response

Key	Type	Value
items	array	Array of album objects
total	integer	Total number of albums in the library
offset	integer	Requested offset of the first albums
limit	integer	Requested maximum number of albums

Example

curl -X GET "http://localhost:3689/api/library/albums"

{
  "items": [
    {
      "id": "8009851123233197743",
      "name": "Add Violence",
      "name_sort": "Add Violence",
      "artist": "Nine Inch Nails",
      "artist_id": "32561671101664759",
      "track_count": 5,
      "length_ms": 1634961,
      "uri": "library:album:8009851123233197743"
    },
    ...
  ],
  "total": 20,
  "offset": 0,
  "limit": -1
}

Get an album

Get a specific album in your library

Endpoint

GET /api/library/albums/{id}

Path parameters

Parameter	Value
id	Album id

Response

On success returns the HTTP 200 OK success status response code. With the response body holding the album object.

Example

curl -X GET "http://localhost:3689/api/library/albums/8009851123233197743"

{
  "id": "8009851123233197743",
  "name": "Add Violence",
  "name_sort": "Add Violence",
  "artist": "Nine Inch Nails",
  "artist_id": "32561671101664759",
  "track_count": 5,
  "length_ms": 1634961,
  "uri": "library:album:8009851123233197743"
}

List album tracks

Lists the tracks in an album

Endpoint

GET /api/library/albums/{id}/tracks

Path parameters

Parameter	Value
id	Album id

Query parameters

Parameter	Value
offset	(Optional) Offset of the first track to return
limit	(Optional) Maximum number of tracks to return

Response

Key	Type	Value
items	array	Array of track objects
total	integer	Total number of tracks
offset	integer	Requested offset of the first track
limit	integer	Requested maximum number of tracks

Example

curl -X GET "http://localhost:3689/api/library/albums/1/tracks"

{
  "items": [
    {
      "id": 10766,
      "title": "Solange wir tanzen",
      "artist": "Heinrich",
      "artist_sort": "Heinrich",
      "album": "Solange wir tanzen",
      "album_sort": "Solange wir tanzen",
      "albumartist": "Heinrich",
      "albumartist_sort": "Heinrich",
      "genre": "Electronica",
      "year": 2014,
      "track_number": 1,
      "disc_number": 1,
      "length_ms": 223085,
      "play_count": 2,
      "last_time_played": "2018-02-23T10:31:20Z",
      "media_kind": "music",
      "data_kind": "file",
      "path": "/music/srv/Heinrich/Solange wir tanzen/01 Solange wir tanzen.mp3",
      "uri": "library:track:10766"
    },
    ...
  ],
  "total": 20,
  "offset": 0,
  "limit": -1
}

Get a track

Get a specific track in your library

Endpoint

GET /api/library/tracks/{id}

Path parameters

Parameter	Value
id	Track id

Response

On success returns the HTTP 200 OK success status response code. With the response body holding the track object.

Example

curl -X GET "http://localhost:3689/api/library/track/1"

{
  "id": 1,
  "title": "Pardon Me",
  "title_sort": "Pardon Me",
  "artist": "Incubus",
  "artist_sort": "Incubus",
  "album": "Make Yourself",
  "album_sort": "Make Yourself",
  "album_id": "6683985628074308431",
  "album_artist": "Incubus",
  "album_artist_sort": "Incubus",
  "album_artist_id": "4833612337650426236",
  "composer": "Alex Katunich/Brandon Boyd/Chris Kilmore/Jose Antonio Pasillas II/Mike Einziger",
  "genre": "Alternative Rock",
  "year": 2001,
  "track_number": 12,
  "disc_number": 1,
  "length_ms": 223170,
  "rating": 0,
  "play_count": 0,
  "skip_count": 0,
  "time_added": "2019-01-20T11:58:29Z",
  "date_released": "2001-05-27",
  "seek_ms": 0,
  "media_kind": "music",
  "data_kind": "file",
  "path": "/music/srv/Incubus/Make Yourself/12 Pardon Me.mp3",
  "uri": "library:track:1",
  "artwork_url": "/artwork/item/1"
}

List playlists for a track

Get the list of playlists that contain a track (does not return smart playlists)

Endpoint

GET /api/library/tracks/{id}/playlists

Path parameters

Parameter	Value
id	Track id

Query parameters

Parameter	Value
offset	(Optional) Offset of the first playlist to return
limit	(Optional) Maximum number of playlist to return

Response

Key	Type	Value
items	array	Array of playlist objects
total	integer	Total number of playlists
offset	integer	Requested offset of the first playlist
limit	integer	Requested maximum number of playlists

Example

curl -X GET "http://localhost:3689/api/library/tracks/27/playlists"

{
  "items": [
    {
      "id": 1,
      "name": "playlist",
      "path": "/music/srv/playlist.m3u",
      "smart_playlist": false,
      "uri": "library:playlist:1"
    },
    ...
  ],
  "total": 2,
  "offset": 0,
  "limit": -1
}

Update track properties

Change properties of a specific track (supported properties are "rating" and "play_count")

Endpoint

PUT /api/library/tracks/{id}

Path parameters

Parameter	Value
id	Track id

Query parameters

Parameter	Value
rating	The new rating (0 - 100)
play_count	Either increment or reset. increment will increment play_count and update time_played, reset will set play_count and skip_count to zero and delete time_played and time_skipped

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/library/tracks/1?rating=100"

curl -X PUT "http://localhost:3689/api/library/tracks/1?play_count=increment"

List genres

Get list of genres

Endpoint

GET /api/library/genres

Response

Key	Type	Value
items	array	Array of genre objects
total	integer	Total number of genres in the library
offset	integer	Requested offset of the first genre
limit	integer	Requested maximum number of genres

Example

curl -X GET "http://localhost:3689/api/library/genres"

{
  "items": [
    {
      "name": "Classical"
    },
    {
      "name": "Drum & Bass"
    },
    {
      "name": "Pop"
    },
    {
      "name": "Rock/Pop"
    },
    {
      "name": "'90s Alternative"
    }
  ],
  "total": 5,
  "offset": 0,
  "limit": -1
}

List albums for genre

Lists the albums in a genre

Endpoint

GET api/search?type=albums&expression=genre+is+\"{genre name}\""

Query parameters

Parameter	Value
genre	genre name (uri encoded and html esc seq for chars: '/&)
offset	(Optional) Offset of the first album to return
limit	(Optional) Maximum number of albums to return

Response

Key	Type	Value
items	array	Array of album objects
total	integer	Total number of albums in the library
offset	integer	Requested offset of the first albums
limit	integer	Requested maximum number of albums

Example

curl -X GET "http://localhost:3689/api/search?type=albums&expression=genre+is+\"Pop\""
curl -X GET "http://localhost:3689/api/search?type=albums&expression=genre+is+\"Rock%2FPop\""            # Rock/Pop
curl -X GET "http://localhost:3689/api/search?type=albums&expression=genre+is+\"Drum%20%26%20Bass\""     # Drum & Bass
curl -X GET "http://localhost:3689/api/search?type=albums&expression=genre+is+\"%2790s%20Alternative\""  # '90 Alternative

{
  "albums": {
    "items": [
      {
        "id": "320189328729146437",
        "name": "Best Ever",
        "name_sort": "Best Ever",
        "artist": "ABC",
        "artist_id": "8760559201889050080",
        "track_count": 1,
        "length_ms": 3631,
        "uri": "library:album:320189328729146437"
      },
      {
        "id": "7964595866631625723",
        "name": "Greatest Hits",
        "name_sort": "Greatest Hits",
        "artist": "Marvin Gaye",
        "artist_id": "5261930703203735930",
        "track_count": 2,
        "length_ms": 7262,
        "uri": "library:album:7964595866631625723"
      },
      {
        "id": "3844610748145176456",
        "name": "The Very Best of Etta",
        "name_sort": "Very Best of Etta",
        "artist": "Etta James",
        "artist_id": "2627182178555864595",
        "track_count": 1,
        "length_ms": 177926,
        "uri": "library:album:3844610748145176456"
      }
    ],
    "total": 3,
    "offset": 0,
    "limit": -1
  }
}

Get count of tracks, artists and albums

Get information about the number of tracks, artists and albums and the total playtime

Endpoint

GET /api/library/count

Query parameters

Parameter	Value
expression	(Optional) The smart playlist query expression, if this parameter is omitted returns the information for the whole library

Response

Key	Type	Value
tracks	integer	Number of tracks matching the expression
artists	integer	Number of artists matching the expression
albums	integer	Number of albums matching the expression
db_playtime	integer	Total playtime in milliseconds of all tracks matching the expression

Example

curl -X GET "http://localhost:3689/api/library/count?expression=data_kind+is+file"

{
  "tracks": 6811,
  "artists": 355,
  "albums": 646,
  "db_playtime": 1590767
}

List local directories

List the local directories and the directory contents (tracks and playlists)

Endpoint

GET /api/library/files

Query parameters

Parameter	Value
directory	(Optional) A path to a directory in your local library.

Response

Key	Type	Value
directories	array	Array of directory objects containing the sub directories
tracks	object	paging object containing track objects that matches the directory
playlists	object	paging object containing playlist objects that matches the directory

Example

curl -X GET "http://localhost:3689/api/library/files?directory=/music/srv"

{
  "directories": [
    {
      "path": "/music/srv/Audiobooks"
    },
    {
      "path": "/music/srv/Music"
    },
    {
      "path": "/music/srv/Playlists"
    },
    {
      "path": "/music/srv/Podcasts"
    }
  ],
  "tracks": {
    "items": [
      {
        "id": 1,
        "title": "input.pipe",
        "artist": "Unknown artist",
        "artist_sort": "Unknown artist",
        "album": "Unknown album",
        "album_sort": "Unknown album",
        "album_id": "4201163758598356043",
        "album_artist": "Unknown artist",
        "album_artist_sort": "Unknown artist",
        "album_artist_id": "4187901437947843388",
        "genre": "Unknown genre",
        "year": 0,
        "track_number": 0,
        "disc_number": 0,
        "length_ms": 0,
        "play_count": 0,
        "skip_count": 0,
        "time_added": "2018-11-24T08:41:35Z",
        "seek_ms": 0,
        "media_kind": "music",
        "data_kind": "pipe",
        "path": "/music/srv/input.pipe",
        "uri": "library:track:1",
        "artwork_url": "/artwork/item/1"
      }
    ],
    "total": 1,
    "offset": 0,
    "limit": -1
  },
  "playlists": {
    "items": [
      {
        "id": 8,
        "name": "radio",
        "path": "/music/srv/radio.m3u",
        "smart_playlist": true,
        "uri": "library:playlist:8"
      }
    ],
    "total": 1,
    "offset": 0,
    "limit": -1
  }
}

Trigger rescan

Trigger a library rescan

Endpoint

PUT /api/update

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/update"

{
  "songs": 217,
  "db_playtime": 66811,
  "artists": 9,
  "albums": 19,
  "started_at": "2018-11-19T19:06:08Z",
  "updated_at": "2018-11-19T19:06:16Z",
  "updating": false
}

Trigger metadata rescan

Trigger a library metadata rescan even if files have not been updated. Maintenence method.

Endpoint

PUT /api/rescan

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/rescan"

Backup DB

Request a library backup - configuration must be enabled and point to a valid writable path. Maintenance method.

Endpoint

PUT /api/library/backup

Response

On success returns the HTTP 200 OK success status response code. If backups are not enabled returns HTTP 503 Service Unavailable response code. Otherwise a HTTP 500 Internal Server Error response is returned.

Example

curl -X PUT "http://localhost:3689/api/library/backup"

Search

Method	Endpoint	Description
GET	/api/search	Search for playlists, artists, albums, tracks,genres by a simple search term
GET	/api/search	Search by complex query expression

Search by search term

Search for playlists, artists, albums, tracks, genres that include the given query in their title (case insensitive matching).

Endpoint

GET /api/search

Query parameters

Parameter	Value
query	The search keyword
type	Comma separated list of the result types (playlist, artist, album, track, genre)
media_kind	(Optional) Filter results by media kind (music, movie, podcast, audiobook, musicvideo, tvshow). Filter only applies to artist, album and track result types.
offset	(Optional) Offset of the first item to return for each type
limit	(Optional) Maximum number of items to return for each type

Response

Key	Type	Value
tracks	object	paging object containing track objects that matches the query
artists	object	paging object containing artist objects that matches the query
albums	object	paging object containing album objects that matches the query
playlists	object	paging object containing playlist objects that matches the query

Example

Search for all tracks, artists, albums and playlists that contain "the" in their title and return the first two results for each type:

curl -X GET "http://localhost:3689/api/search?type=tracks,artists,albums,playlists&query=the&offset=0&limit=2"

{
  "tracks": {
    "items": [
      {
        "id": 35,
        "title": "Another Love",
        "artist": "Tom Odell",
        "artist_sort": "Tom Odell",
        "album": "Es is was es is",
        "album_sort": "Es is was es is",
        "album_id": "6494853621007413058",
        "album_artist": "Various artists",
        "album_artist_sort": "Various artists",
        "album_artist_id": "8395563705718003786",
        "genre": "Singer/Songwriter",
        "year": 2013,
        "track_number": 7,
        "disc_number": 1,
        "length_ms": 251030,
        "play_count": 0,
        "media_kind": "music",
        "data_kind": "file",
        "path": "/music/srv/Compilations/Es is was es is/07 Another Love.m4a",
        "uri": "library:track:35"
      },
      {
        "id": 215,
        "title": "Away From the Sun",
        "artist": "3 Doors Down",
        "artist_sort": "3 Doors Down",
        "album": "Away From the Sun",
        "album_sort": "Away From the Sun",
        "album_id": "8264078270267374619",
        "album_artist": "3 Doors Down",
        "album_artist_sort": "3 Doors Down",
        "album_artist_id": "5030128490104968038",
        "genre": "Rock",
        "year": 2002,
        "track_number": 2,
        "disc_number": 1,
        "length_ms": 233278,
        "play_count": 0,
        "media_kind": "music",
        "data_kind": "file",
        "path": "/music/srv/Away From the Sun/02 Away From the Sun.mp3",
        "uri": "library:track:215"
      }
    ],
    "total": 14,
    "offset": 0,
    "limit": 2
  },
  "artists": {
    "items": [
      {
        "id": "8737690491750445895",
        "name": "The xx",
        "name_sort": "xx, The",
        "album_count": 2,
        "track_count": 25,
        "length_ms": 5229196,
        "uri": "library:artist:8737690491750445895"
      }
    ],
    "total": 1,
    "offset": 0,
    "limit": 2
  },
  "albums": {
    "items": [
      {
        "id": "8264078270267374619",
        "name": "Away From the Sun",
        "name_sort": "Away From the Sun",
        "artist": "3 Doors Down",
        "artist_id": "5030128490104968038",
        "track_count": 12,
        "length_ms": 2818174,
        "uri": "library:album:8264078270267374619"
      },
      {
        "id": "6835720495312674468",
        "name": "The Better Life",
        "name_sort": "Better Life",
        "artist": "3 Doors Down",
        "artist_id": "5030128490104968038",
        "track_count": 11,
        "length_ms": 2393332,
        "uri": "library:album:6835720495312674468"
      }
    ],
    "total": 3,
    "offset": 0,
    "limit": 2
  },
  "playlists": {
    "items": [],
    "total": 0,
    "offset": 0,
    "limit": 2
  }
}

Search by query language

Search for artists, albums, tracks by a smart playlist query expression (see README_SMARTPL.md for the expression syntax).

Endpoint

GET /api/search

Query parameters

Parameter	Value
expression	The smart playlist query expression
type	Comma separated list of the result types (artist, album, track
offset	(Optional) Offset of the first item to return for each type
limit	(Optional) Maximum number of items to return for each type

Response

Key	Type	Value
tracks	object	paging object containing track objects that matches the query
artists	object	paging object containing artist objects that matches the query
albums	object	paging object containing album objects that matches the query

Example

Search for music tracks ordered descending by the time added to the library and limit result to 2 items:

curl -X GET "http://localhost:3689/api/search?type=tracks&expression=media_kind+is+music+order+by+time_added+desc&offset=0&limit=2"

Server info

Method	Endpoint	Description
GET	/api/config	Get configuration information

Config

Endpoint

GET /api/config

Response

Key	Type	Value
version	string	Server version
websocket_port	integer	Port number for the websocket (or 0 if websocket is disabled)
buildoptions	array	Array of strings indicating which features are supported by the server

Example

curl -X GET "http://localhost:3689/api/config"

{
  "websocket_port": 3688,
  "version": "25.0",
  "buildoptions": [
    "ffmpeg",
    "iTunes XML",
    "Spotify",
    "LastFM",
    "MPD",
    "Device verification",
    "Websockets",
    "ALSA"
  ]
}

Settings

Method	Endpoint	Description
GET	/api/settings	Get all available categories
GET	/api/settings/{category-name}	Get all available options for a category
GET	/api/settings/{category-name}/{option-name}	Get a single setting option
PUT	/api/settings/{category-name}/{option-name}	Change the value of a setting option
DELETE	/api/settings/{category-name}/{option-name}	Reset a setting option to its default

List categories

List all settings categories with their options

Endpoint

GET /api/settings

Response

Key	Type	Value
categories	array	Array of settings category objects

Example

curl -X GET "http://localhost:3689/api/settings"

{
  "categories": [
    {
      "name": "webinterface",
      "options": [
        {
          "name": "show_composer_now_playing",
          "type": 1,
          "value": true
        },
        {
          "name": "show_composer_for_genre",
          "type": 2,
          "value": "classical"
        }
      ]
    }
  ]
}

Get a category

Get a settings category with their options

Endpoint

GET /api/settings/{category-name}

Response

Returns a settings category object

Example

curl -X GET "http://localhost:3689/api/settings/webinterface"

{
  "name": "webinterface",
  "options": [
    {
      "name": "show_composer_now_playing",
      "type": 1,
      "value": true
    },
    {
      "name": "show_composer_for_genre",
      "type": 2,
      "value": "classical"
    }
  ]
}

Get an option

Get a single settings option

Endpoint

GET /api/settings/{category-name}/{option-name}

Response

Returns a settings option object

Example

curl -X GET "http://localhost:3689/api/settings/webinterface/show_composer_now_playing"

{
  "name": "show_composer_now_playing",
  "type": 1,
  "value": true
}

Change an option value

Get a single settings option

Endpoint

PUT /api/settings/{category-name}/{option-name}

Request

Key	Type	Value
name	string	Option name
value	(integer / boolean / string)	New option value

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/settings/webinterface/show_composer_now_playing" --data "{\"name\":\"show_composer_now_playing\",\"value\":true}"

Delete an option

Delete a single settings option (thus resetting it to default)

Endpoint

DELETE /api/settings/{category-name}/{option-name}

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X DELETE "http://localhost:3689/api/settings/webinterface/show_composer_now_playing"

Push notifications

If the server was built with websocket support it exposes a websocket at localhost:3688 to inform clients of changes (e. g. player state or library updates). The port depends on the server configuration and can be read using the /api/config endpoint.

After connecting to the websocket, the client should send a message containing the event types it is interested in. After that the server will send a message each time one of the events occurred.

Message

Key	Type	Value
notify	array	Array of event types

Event types

Type	Description
update	Library update started or finished
database	Library database changed (new/modified/deleted tracks)
outputs	An output was enabled or disabled
player	Player state changes
options	Playback option changes (shuffle, repeat, consume mode)
volume	Volume changes
queue	Queue changes

Example

curl --include \
     --no-buffer \
     --header "Connection: Upgrade" \
     --header "Upgrade: websocket" \
     --header "Host: localhost:3688" \
     --header "Origin: http://localhost:3688" \
     --header "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" \
     --header "Sec-WebSocket-Version: 13" \
     --header "Sec-WebSocket-Protocol: notify" \
     http://localhost:3688/ \
     --data "{ \"notify\": [ \"player\" ] }"

{ 
  "notify": [
    "player"
  ]
}

Object model

queue item object

Key	Type	Value
id	string	Item id
position	integer	Position in the queue (starting with zero)
track_id	string	Track id
title	string	Title
artist	string	Track artist name
artist_sort	string	Track artist sort name
album	string	Album name
album_sort	string	Album sort name
album_id	string	Album id
album_artist	string	Album artist name
album_artist_sort	string	Album artist sort name
album_artist_id	string	Album artist id
composer	string	Composer (optional)
genre	string	Genre
year	integer	Release year
track_number	integer	Track number
disc_number	integer	Disc number
length_ms	integer	Track length in milliseconds
media_kind	string	Media type of this track: music, movie, podcast, audiobook, musicvideo, tvshow
data_kind	string	Data type of this track: file, url, spotify, pipe
path	string	Path
uri	string	Resource identifier
artwork_url	string	(optional) Artwork url
type	string	file (codec) type (ie mp3/flac/...)
bitrate	string	file bitrate (ie 192/128/...)
samplerate	string	file sample rate (ie 44100/48000/...)
channel	string	file channel (ie mono/stereo/xx ch))

playlist object

Key	Type	Value
id	string	Playlist id
name	string	Playlist name
path	string	Path
parent_id	integer	Playlist id of the parent (folder) playlist
type	string	Type of this playlist: special, folder, smart, plain
smart_playlist	boolean	true if playlist is a smart playlist
folder	boolean	true if it is a playlist folder
uri	string	Resource identifier

artist object

Key	Type	Value
id	string	Artist id
name	string	Artist name
name_sort	string	Artist sort name
album_count	integer	Number of albums
track_count	integer	Number of tracks
length_ms	integer	Total length of tracks in milliseconds
uri	string	Resource identifier
artwork_url	string	(optional) Artwork url

album object

Key	Type	Value
id	string	Album id
name	string	Album name
name_sort	string	Album sort name
artist_id	string	Album artist id
artist	string	Album artist name
track_count	integer	Number of tracks
length_ms	integer	Total length of tracks in milliseconds
uri	string	Resource identifier
artwork_url	string	(optional) Artwork url

track object

Key	Type	Value
id	string	Track id
title	string	Title
title_sort	string	Sort title
artist	string	Track artist name
artist_sort	string	Track artist sort name
album	string	Album name
album_sort	string	Album sort name
album_id	string	Album id
album_artist	string	Album artist name
album_artist_sort	string	Album artist sort name
album_artist_id	string	Album artist id
composer	string	Track composer
genre	string	Genre
year	integer	Release year
track_number	integer	Track number
disc_number	integer	Disc number
length_ms	integer	Track length in milliseconds
rating	integer	Track rating (ranges from 0 to 100)
play_count	integer	How many times the track was played
skip_count	integer	How many times the track was skipped
time_played	string	Timestamp in ISO 8601 format
time_skipped	string	Timestamp in ISO 8601 format
time_added	string	Timestamp in ISO 8601 format
date_released	string	Date in the format yyyy-mm-dd
seek_ms	integer	Resume point in milliseconds (available only for podcasts and audiobooks)
media_kind	string	Media type of this track: music, movie, podcast, audiobook, musicvideo, tvshow
data_kind	string	Data type of this track: file, url, spotify, pipe
path	string	Path
uri	string	Resource identifier
artwork_url	string	(optional) Artwork url

paging object

Key	Type	Value
items	array	Array of result objects
total	integer	Total number of items
offset	integer	Requested offset of the first item
limit	integer	Requested maximum number of items

genre object

Key	Type	Value
name	string	Name of genre

directory object

Key	Type	Value
path	string	Directory path

category object

Key	Type	Value
name	string	Category name
options	array	Array of option in this category

option object

Key	Type	Value
name	string	Option name
type	integer	The type of the value for this option (0: integer, 1: boolean, 2: string)
value	(integer / boolean / string)	Current value for this option

Artwork urls

Artwork urls in queue item, artist, album and track objects can be either relative urls or absolute urls to the artwork image. Absolute artwork urls are pointing to external artwork images (e. g. for radio streams that provide artwork metadata), while relative artwork urls are served from the server.

It is possible to add the query parameters maxwidth and/or maxheight to relative artwork urls, in order to get a smaller image (the server only scales down never up).

Note that even if a relative artwork url attribute is present, it is not guaranteed to exist.