API XML Methods

Let's go through come calls and examples that you can do for each XML method.

Parameters may be sent as a query string, or (for POST/PUT/PATCH/DELETE) as a form-encoded or application/json request body. See API for details.

Valid responses will always return a HTTP 200 response.

Error responses return codes based on the error type:

HTTP 400
- Error '4710': BAD_REQUEST
- Error '4705': MISSING
HTTP 401
- Error '4701': INVALID_HANDSHAKE
HTTP 403
- Error '4700': ACCESS_CONTROL_NOT_ENABLED
- Error '4703': ACCESS_DENIED
- Error '4742': FAILED_ACCESS_CHECK
HTTP 404
- Error '4704': NOT_FOUND
HTTP 410
- Error '4706': DEPRECATED
HTTP 500
- Error '4702': GENERIC_ERROR

Binary data methods will not return JSON; just the file/data you have requested.

Binary methods will also return:

HTTP 400 responses for a bad or incomplete request
HTTP 404 responses where the requests data was not found
HTTP 416 responses where the stream is unable to return the requested content-range

For information about about how playback works and what a client can expect from Ampache check out API Media Methods

Auth Methods

Auth methods are used for authenticating or checking the status of your session in an Ampache server.

Remember that the auth parameter does not need to be sent as a parameter in the URL.

HTTP header authentication is supported for the auth parameter where present.

handshake

This is the function that handles verifying a new handshake Takes a timestamp, auth key, and username.

Input	Type	Description	Optional
'auth'	string	$passphrase (Timestamp . Password SHA hash) OR (API Key)	NO
'user'	string	$username (Required if login/password authentication)	YES
'timestamp'	integer	UNIXTIME() The timestamp used in seed of password hash	YES
		(Required if login/password authentication)
'version'	string	$version (API Version that the application understands)	YES

NOTE For privacy, send auth in a request body or the Authorization: Bearer header rather than the query string. Query-string support for auth is deprecated but still accepted for backward compatibility.

return

Returns a single object.

Field	Type	Nullable	Optional
auth	string	YES	NO
streamtoken	string	YES	NO
api	string	NO	NO
session_expire	integer \| string	NO	NO
update	string	NO	NO
add	string	NO	NO
clean	string	NO	NO
max_song	integer	NO	NO
max_album	integer	NO	NO
max_artist	integer	NO	NO
max_video	integer	NO	NO
max_podcast	integer	NO	NO
max_podcast_episode	integer	NO	NO
songs	integer	NO	NO
albums	integer	NO	NO
artists	integer	NO	NO
genres	integer	NO	NO
playlists	integer	NO	NO
searches	integer	NO	NO
playlists_searches	integer	NO	NO
users	integer	NO	NO
catalogs	integer	NO	NO
videos	integer	NO	NO
podcasts	integer	NO	NO
podcast_episodes	integer	NO	NO
shares	integer	NO	NO
licenses	integer	NO	NO
live_streams	integer	NO	NO
labels	integer	NO	NO
username	string	NO	NO

throws

<root><error></root>

Example

quickconnect_initiate

No authentication. Starts a QuickConnect pairing request: a device with no session yet asks for a short code, shows it to the person signing in, then polls quickconnect_status with the returned secret until it comes back authorized. Off unless the quickconnect_enable preference is on.

Input	Type	Description	Optional
'device_id'	string	An id the caller makes up and keeps, so its own initiate rate limit applies	YES
'device_name'	string	Shown to the approving user alongside the code	YES
'client'	string	The app name, shown to the approving user	YES
'version'	string	The app version, shown to the approving user	YES

return

Returns a single object.

Field	Type	Nullable	Optional
secret	string	NO	NO
code	string	NO	NO
device_id	string	NO	NO
device_name	string	NO	NO
app_name	string	NO	NO
app_version	string	NO	NO
date_added	integer	NO	NO
authorized	boolean	NO	NO

throws

<root><error></root>

quickconnect_status

No authentication. Polls a QuickConnect pairing request started by quickconnect_initiate. The caller has no session until this comes back authorized: true, at which point the response also carries a minted session, the same shape handshake returns.

Input	Type	Description	Optional
'secret'	string	The value `quickconnect_initiate` returned	NO

NOTE For privacy, send secret in a request body rather than the query string — it is a bearer credential for the pairing, the same as auth.

return

authorized is always returned. Once the code is approved it is true and every handshake field (auth, session_expire, server counts, ...) is added alongside it.

Field	Type	Nullable	Optional
authorized	boolean	NO	NO
auth	string	YES	YES
streamtoken	string	YES	YES
api	string	NO	YES
session_expire	integer \| string	NO	YES
update	string	NO	YES
add	string	NO	YES
clean	string	NO	YES
max_song	integer	NO	YES
max_album	integer	NO	YES
max_artist	integer	NO	YES
max_video	integer	NO	YES
max_podcast	integer	NO	YES
max_podcast_episode	integer	NO	YES
songs	integer	NO	YES
albums	integer	NO	YES
artists	integer	NO	YES
genres	integer	NO	YES
playlists	integer	NO	YES
searches	integer	NO	YES
playlists_searches	integer	NO	YES
users	integer	NO	YES
catalogs	integer	NO	YES
videos	integer	NO	YES
podcasts	integer	NO	YES
podcast_episodes	integer	NO	YES
shares	integer	NO	YES
licenses	integer	NO	YES
live_streams	integer	NO	YES
labels	integer	NO	YES
username	string	NO	YES

throws

<root><error></root>

goodbye

Destroy a session using the auth parameter.

Input	Type	Description	Optional
'auth'	string	(Session ID) destroys the session if it exists	NO

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

lost_password

Email a new password to the user (if allowed) using a reset token. Requires allow_lost_password to be enabled and a working mail configuration; not available to Content Manager, Manager or Admin accounts.

   $username;
   $key = hash('sha256', 'email');
   auth = hash('sha256', $username . $key);

Input	Type	Description	Optional
'auth'	string	password reset token	NO

return

Returns a single object.

Field	Type	Nullable	Optional	Notes
success	string	NO	YES

throws

<root><error></root>

ping

This can be called without being authenticated, it is useful for determining if what the status of the server is, and what version it is running/compatible with

Input	Type	Description	Optional
'auth'	string	(Session ID) returns version information and extends the session if passed	YES
'version'	string	$version (API Version that the application understands)	YES

return

server, version and compatible are always returned. Sending a valid auth extends the session and adds the handshake fields (session_expire, server counts, ...).

Field	Type	Nullable	Optional
server	string	NO	NO
version	string	NO	NO
compatible	string	NO	NO
auth	string	YES	YES
streamtoken	string	YES	YES
api	string	NO	YES
session_expire	integer \| string	NO	YES
update	string	NO	YES
add	string	NO	YES
clean	string	NO	YES
max_song	integer	NO	YES
max_album	integer	NO	YES
max_artist	integer	NO	YES
max_video	integer	NO	YES
max_podcast	integer	NO	YES
max_podcast_episode	integer	NO	YES
songs	integer	NO	YES
albums	integer	NO	YES
artists	integer	NO	YES
genres	integer	NO	YES
playlists	integer	NO	YES
searches	integer	NO	YES
playlists_searches	integer	NO	YES
users	integer	NO	YES
catalogs	integer	NO	YES
videos	integer	NO	YES
podcasts	integer	NO	YES
podcast_episodes	integer	NO	YES
shares	integer	NO	YES
licenses	integer	NO	YES
live_streams	integer	NO	YES
labels	integer	NO	YES
username	string	NO	YES

throws

<root>
    <server>
    <version>
    <compatible>
</root>

Example

register

Input	Type	Description	Optional
'username'	string	$username	NO
'password'	string	hash('sha256', $password)	NO
'email'	string	e.g. `[email protected]`	NO
'fullname'	string		YES

NOTE For privacy, send password in a form or JSON request body rather than the query string. Query-string support for password is deprecated but still accepted for backward compatibility.

return

<root>
    <success>
</root>

throws

<root><error></root>

Non-Data Methods

These methods take no parameters beyond your auth key to return information

system_update

Check Ampache for updates and run the update if there is one.

ACCESS REQUIRED: 100 (Admin)

return

Returns a single object.

Field	Type	Nullable	Optional	Notes
success	string	NO	YES

throws

<root><error></root>

Example

system_preferences

Get your server preferences

ACCESS REQUIRED: 100 (Admin)

You can modify and update your preferences using the following methods
return

Returns a preference list.

Field	Type	Nullable	Optional	Notes
preference	array<PreferenceObject>	NO	NO	see PreferenceObject fields

Each preference entry (PreferenceObject):

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	NO	NO
value	string	NO	NO
description	string	NO	NO
level	integer	NO	NO
type	string	NO	NO
category	string	NO	NO
subcategory	string	YES	NO
has_access	boolean	NO	YES
values	array<string> \| array<integer>	NO	YES

throws

<root><error></root>

Example

users

Get ids and usernames for your site

return

Returns a user list.

Field	Type	Nullable	Optional	Notes
user	array<UserSummaryObject>	NO	NO	see UserSummaryObject fields

Each user entry (UserSummaryObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
username	string	YES	NO

throws

<root><error></root>

Example

user_preferences

Get your user preferences

You can modify and update your preferences using the following methods
return

<root>
    <preference>
</root>

Example

Data Methods

Data methods require additional information and parameters to return information

advanced_search

Perform an advanced search given passed rules. This works in a similar way to the web/UI search pages. You can pass multiple rules as well as joins to create in depth search results.

Rules must be sent in groups of 3 using an int (starting from 1) to designate which rules are combined. Use operator ('and', 'or') to choose whether to join or separate each rule when searching.

Refer to the Advanced Search page for details about creating searches.

NOTE the rules part can be confusing but essentially you can include as many 'arrays' of rules as you want. Just add 1 to the rule value to create a new group of rules.

Mandatory Rule Values
- rule_1
- rule_1_operator
- rule_1_input
Optional (Metadata searches only)
- rule_1_subtype

Input	Type	Description	Optional
operator	string	and, or (whether to match one rule or all)	NO
rule_*	array	[`rule_1`, `rule_1_operator`, `rule_1_input`]	NO
rule_*	array	[`rule_2`, `rule_2_operator`, `rule_2_input`], [etc]	YES
type	string	`song`, `album`, `artist`, `label`, `playlist`	NO
		`podcast`, `podcast_episode`, `genre`, `user`, `video`
random	boolean	`0`, `1` (random order of results; default to 0)	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES

return

<root>
    <total_count>
    <song>|<album>|<artist>|<playlist>|<label>|<user>|<video>
</root>

throws

<root><error></root>

SONG Example

ARTIST Example

ALBUM Example

albums

This returns albums based on the provided search filters

Input	Type	Description	Optional
'filter'	string	Filter results to match this string	YES
'include'	string	`albums`, `songs` (include child objects in the response)	YES
'exact'	boolean	`0`, `1` (if true filter is exact `=` rather than fuzzy `LIKE`)	YES
'add'	set_filter	ISO 8601 Date Format (2020-09-16) Find objects with an 'add' date newer than the specified date	YES
'update'	set_filter	ISO 8601 Date Format (2020-09-16) Find objects with an 'update' time newer than the specified date	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a album list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
album	array<AlbumObject>	NO	NO	see AlbumObject fields

Each album entry (AlbumObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
name	string	YES	NO
prefix	string	YES	NO
basename	string	YES	NO
artist	object	YES	YES	`{id, name, prefix, basename}`
artists	array<NamedReference>	NO	YES	see NamedReference fields
songartists	array<NamedReference>	NO	YES	see NamedReference fields
time	integer	NO	NO
year	integer	NO	NO
tracks	array<SongObject>	NO	NO	see SongObject fields
songcount	integer	NO	NO
diskcount	integer	NO	NO
type	string	YES	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
mbid	string	YES	NO
mbid_group	string	YES	NO
catalog	string	NO	NO

throws

<root><error></root>

Example

album

This returns a single album based on the UID provided

Input	Type	Description	Optional
'filter'	string	UID of Album, returns album XML	NO
'include'	string	`songs` (include child objects in the response)	YES

return

Returns a single object.

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
name	string	YES	NO
prefix	string	YES	NO
basename	string	YES	NO
artist	object	YES	YES	`{id, name, prefix, basename}`
artists	array<NamedReference>	NO	YES	see NamedReference fields
songartists	array<NamedReference>	NO	YES	see NamedReference fields
time	integer	NO	NO
year	integer	NO	NO
tracks	array<SongObject>	NO	NO	see SongObject fields
songcount	integer	NO	NO
diskcount	integer	NO	NO
type	string	YES	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
mbid	string	YES	NO
mbid_group	string	YES	NO
catalog	string	NO	NO

throws

<root><error></root>

Example

album_songs

This returns the songs of a specified album

Input	Type	Description	Optional
'filter'	string	UID of Album, returns song XML	NO
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated	YES
		comma string pairs (e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a song list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
song	array<SongObject>	NO	NO	see SongObject fields

Each song entry (SongObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
title	string	YES	NO
name	string	YES	NO
artist	NamedReference	NO	NO	see NamedReference fields
artists	array<NamedReference>	NO	NO	see NamedReference fields
album	NamedReference	NO	NO	see NamedReference fields
albumartist	NamedReference	NO	YES	see NamedReference fields
disk	integer	NO	NO
disksubtitle	string	YES	NO
bpm	number	YES	NO
track	integer	NO	NO
filename	string	YES	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
mood	array<object>	NO	NO	`{id, name}`
playlisttrack	integer	NO	NO
time	integer	NO	NO
year	integer	NO	NO
format	string	YES	NO
stream_format	string	YES	NO
bitrate	integer	YES	NO
stream_bitrate	integer	YES	NO
rate	integer	NO	NO
mode	string	YES	NO
mime	string	YES	NO
stream_mime	string	YES	NO
url	string	NO	NO
size	integer	NO	NO
mbid	string	YES	NO
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
playcount	integer	NO	NO
last_played	string	YES	NO
catalog	string	NO	NO
composer	string	YES	NO
channels	integer	YES	NO
comment	string	YES	NO
license	string	YES	NO
publisher	string	YES	NO
language	string	YES	NO
lyrics	string	YES	NO
replaygain_album_gain	number	YES	NO
replaygain_album_peak	number	YES	NO
replaygain_track_gain	number	YES	NO
replaygain_track_peak	number	YES	NO
r128_album_gain	number	YES	NO
r128_track_gain	number	YES	NO
metadata	object<string, string>	NO	YES

throws

<root><error></root>

Example

album_disks

This returns the disks of a specified album

Album disks are the browsing unit whenever the album_group preference is disabled. This method is API 8 only; albums and album never change shape based on that preference.

Input	Type	Description	Optional
'filter'	string	UID of Album, returns album_disk JSON	NO
'include'	string	`songs` (include child objects in the response)	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated	YES
		comma string pairs (e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a album_disk list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
album_disk	array<AlbumDiskObject>	NO	NO	see AlbumDiskObject fields

Each album_disk entry (AlbumDiskObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
name	string	NO	NO
prefix	string	YES	NO
basename	string	YES	NO
album	object	NO	NO	`{id, name, prefix, basename}`
artist	object	NO	YES	`{id, name, prefix, basename}`
artists	array<object>	NO	YES	`{id, name, prefix, basename}`
songartists	array<object>	NO	YES	`{id, name, prefix, basename}`
disk	integer	NO	NO
disksubtitle	string	YES	NO
time	integer	NO	NO
year	integer	NO	NO
tracks	array<SongObject>	NO	NO	see SongObject fields
songcount	integer	NO	NO
type	string	YES	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
mbid	string	YES	NO
mbid_group	string	YES	NO
catalog	string	NO	NO

throws object

"error": ""

album_disk

This returns a single album disk based on the UID provided

Input	Type	Description	Optional
'filter'	string	UID of AlbumDisk, returns album_disk JSON	NO
'include'	string	`songs` (include child objects in the response)	YES

return

Returns a single object.

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
name	string	NO	NO
prefix	string	YES	NO
basename	string	YES	NO
album	object	NO	NO	`{id, name, prefix, basename}`
artist	object	NO	YES	`{id, name, prefix, basename}`
artists	array<object>	NO	YES	`{id, name, prefix, basename}`
songartists	array<object>	NO	YES	`{id, name, prefix, basename}`
disk	integer	NO	NO
disksubtitle	string	YES	NO
time	integer	NO	NO
year	integer	NO	NO
tracks	array<SongObject>	NO	NO	see SongObject fields
songcount	integer	NO	NO
type	string	YES	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
mbid	string	YES	NO
mbid_group	string	YES	NO
catalog	string	NO	NO

throws object

"error": ""

album_disk_songs

This returns the songs of a specified album disk

Input	Type	Description	Optional
'filter'	string	UID of AlbumDisk, returns song JSON	NO
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated	YES
		comma string pairs (e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a song list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
song	array<SongObject>	NO	NO	see SongObject fields

Each song entry (SongObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
title	string	YES	NO
name	string	YES	NO
artist	NamedReference	NO	NO	see NamedReference fields
artists	array<NamedReference>	NO	NO	see NamedReference fields
album	NamedReference	NO	NO	see NamedReference fields
albumartist	NamedReference	NO	YES	see NamedReference fields
disk	integer	NO	NO
disksubtitle	string	YES	NO
bpm	number	YES	NO
track	integer	NO	NO
filename	string	YES	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
mood	array<object>	NO	NO	`{id, name}`
playlisttrack	integer	NO	NO
time	integer	NO	NO
year	integer	NO	NO
format	string	YES	NO
stream_format	string	YES	NO
bitrate	integer	YES	NO
stream_bitrate	integer	YES	NO
rate	integer	NO	NO
mode	string	YES	NO
mime	string	YES	NO
stream_mime	string	YES	NO
url	string	NO	NO
size	integer	NO	NO
mbid	string	YES	NO
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
playcount	integer	NO	NO
last_played	string	YES	NO
catalog	string	NO	NO
composer	string	YES	NO
channels	integer	YES	NO
comment	string	YES	NO
license	string	YES	NO
publisher	string	YES	NO
language	string	YES	NO
lyrics	string	YES	NO
replaygain_album_gain	number	YES	NO
replaygain_album_peak	number	YES	NO
replaygain_track_gain	number	YES	NO
replaygain_track_peak	number	YES	NO
r128_album_gain	number	YES	NO
r128_track_gain	number	YES	NO
metadata	object<string, string>	NO	YES

throws object

"error": ""

artists

This takes a collection of inputs and returns artist objects.

Input	Type	Description	Optional
'filter'	string	Filter results to match this string	YES
'exact'	boolean	`0`, `1` (if true filter is exact `=` rather than fuzzy `LIKE`)	YES
'add'	set_filter	ISO 8601 Date Format (2020-09-16) Find objects with an 'add' date newer than the specified date	YES
'update'	set_filter	ISO 8601 Date Format (2020-09-16) Find objects with an 'update' time newer than the specified date	YES
'include'	string	`albums`, `songs` (include child objects in the response)	YES
'album_artist'	boolean	`0`, `1` (if true filter for album artists only)	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a artist list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
artist	array<ArtistObject>	NO	NO	see ArtistObject fields

Each artist entry (ArtistObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
name	string	YES	NO
prefix	string	YES	NO
basename	string	YES	NO
albums	array<AlbumObject>	NO	NO	see AlbumObject fields
albumcount	integer	NO	NO
songs	array<SongObject>	NO	NO	see SongObject fields
songcount	integer	NO	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
mbid	string	YES	NO
summary	string	YES	NO
time	integer	NO	NO
yearformed	integer	NO	NO
placeformed	string	YES	NO

throws

<root><error></root>

Example

artist

This returns a single artist based on the UID of said artist

Input	Type	Description	Optional
'filter'	string	UID of Artist, returns artist XML	NO
'include'	string	`albums`, `songs` (include child objects in the response)	YES

return

Returns a single object.

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
name	string	YES	NO
prefix	string	YES	NO
basename	string	YES	NO
albums	array<AlbumObject>	NO	NO	see AlbumObject fields
albumcount	integer	NO	NO
songs	array<SongObject>	NO	NO	see SongObject fields
songcount	integer	NO	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
mbid	string	YES	NO
summary	string	YES	NO
time	integer	NO	NO
yearformed	integer	NO	NO
placeformed	string	YES	NO

throws

<root><error></root>

Example

artist_albums

This returns the albums of an artist

Input	Type	Description	Optional
'filter'	string	UID of Artist, returns Album XML	NO
'album_artist'	boolean	`0`, `1` (if true filter for album artists only)	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a album list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
album	array<AlbumObject>	NO	NO	see AlbumObject fields

Each album entry (AlbumObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
name	string	YES	NO
prefix	string	YES	NO
basename	string	YES	NO
artist	object	YES	YES	`{id, name, prefix, basename}`
artists	array<NamedReference>	NO	YES	see NamedReference fields
songartists	array<NamedReference>	NO	YES	see NamedReference fields
time	integer	NO	NO
year	integer	NO	NO
tracks	array<SongObject>	NO	NO	see SongObject fields
songcount	integer	NO	NO
diskcount	integer	NO	NO
type	string	YES	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
mbid	string	YES	NO
mbid_group	string	YES	NO
catalog	string	NO	NO

throws

<root><error></root>

Example

artist_songs

This returns the songs of the specified artist

Input	Type	Description	Optional
'filter'	string	UID of Artist, returns Song XML	NO
'top50'	boolean	`0`, `1` (if true filter to the artist top 50)	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a song list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
song	array<SongObject>	NO	NO	see SongObject fields

Each song entry (SongObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
title	string	YES	NO
name	string	YES	NO
artist	NamedReference	NO	NO	see NamedReference fields
artists	array<NamedReference>	NO	NO	see NamedReference fields
album	NamedReference	NO	NO	see NamedReference fields
albumartist	NamedReference	NO	YES	see NamedReference fields
disk	integer	NO	NO
disksubtitle	string	YES	NO
bpm	number	YES	NO
track	integer	NO	NO
filename	string	YES	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
mood	array<object>	NO	NO	`{id, name}`
playlisttrack	integer	NO	NO
time	integer	NO	NO
year	integer	NO	NO
format	string	YES	NO
stream_format	string	YES	NO
bitrate	integer	YES	NO
stream_bitrate	integer	YES	NO
rate	integer	NO	NO
mode	string	YES	NO
mime	string	YES	NO
stream_mime	string	YES	NO
url	string	NO	NO
size	integer	NO	NO
mbid	string	YES	NO
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
playcount	integer	NO	NO
last_played	string	YES	NO
catalog	string	NO	NO
composer	string	YES	NO
channels	integer	YES	NO
comment	string	YES	NO
license	string	YES	NO
publisher	string	YES	NO
language	string	YES	NO
lyrics	string	YES	NO
replaygain_album_gain	number	YES	NO
replaygain_album_peak	number	YES	NO
replaygain_track_gain	number	YES	NO
replaygain_track_peak	number	YES	NO
r128_album_gain	number	YES	NO
r128_track_gain	number	YES	NO
metadata	object<string, string>	NO	YES

throws

<root><error></root>

Example

bookmarks

Get information about bookmarked media this user is allowed to manage.

Input	Type	Description	Optional
'client'	string	filter by the agent/client name	YES
'include'	integer	0,1, if true include the object in the bookmark	YES

return

Returns a bookmark list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
bookmark	array<BookmarkObject>	NO	NO	see BookmarkObject fields

Each bookmark entry (BookmarkObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
owner	string	NO	NO
object_type	string	YES	NO
object_id	string	NO	NO
position	integer	NO	NO
client	string	YES	NO
creation_date	integer	NO	NO
update_date	integer	NO	NO
song	array<SongObject>	NO	YES	see SongObject fields
podcast_episode	array<PodcastEpisodeObject>	NO	YES	see PodcastEpisodeObject fields
video	array<VideoObject>	NO	YES	see VideoObject fields

throws

<root><error></root>

Example Example (with include)

bookmark

Get a single bookmark by bookmark_id

Input	Type	Description	Optional
'filter'	string	bookmark_id	YES
'include'	integer	0,1, if true include the object in the bookmark	YES

return

Returns a single object.

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
owner	string	NO	NO
object_type	string	YES	NO
object_id	string	NO	NO
position	integer	NO	NO
client	string	YES	NO
creation_date	integer	NO	NO
update_date	integer	NO	NO
song	array<SongObject>	NO	YES	see SongObject fields
podcast_episode	array<PodcastEpisodeObject>	NO	YES	see PodcastEpisodeObject fields
video	array<VideoObject>	NO	YES	see VideoObject fields

throws

<root><error></root>

Example Example (with include)

bookmark_create

Create a placeholder for the current media that you can return to later.

Input	Type	Description	Optional
'filter'	string	$object_id to find	NO
'type'	string	`song`, `video`, `podcast_episode` (object_type)	NO
'position'	integer	current track time in seconds	NO
'client'	string	Agent string.	YES
'date'	integer	update time (Default: UNIXTIME())	YES
'include'	integer	0,1, if true include the object in the bookmark	YES

return

Returns a single object.

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
owner	string	NO	NO
object_type	string	YES	NO
object_id	string	NO	NO
position	integer	NO	NO
client	string	YES	NO
creation_date	integer	NO	NO
update_date	integer	NO	NO
song	array<SongObject>	NO	YES	see SongObject fields
podcast_episode	array<PodcastEpisodeObject>	NO	YES	see PodcastEpisodeObject fields
video	array<VideoObject>	NO	YES	see VideoObject fields

throws

<root><error></root>

Example

bookmark_delete

Delete an existing bookmark. (if it exists)

Input	Type	Description	Optional
'filter'	string	$object_id to delete	NO
'type'	string	`bookmark`, `song`, `video`, `podcast_episode`, default: bookmark	NO
'client'	string	Agent string.	YES

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

bookmark_edit

Edit a placeholder for the current media that you can return to later.

Input	Type	Description	Optional
'filter'	string	$object_id to find	NO
'type'	string	`bookmark`, `song`, `video`, `podcast_episode` (object_type)	NO
'position'	integer	current track time in seconds	NO
'client'	string	Agent string.	YES
'date'	integer	update time (Default: UNIXTIME())	YES
'include'	integer	0,1, if true include the object in the bookmark	YES

return

Returns a single object.

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
owner	string	NO	NO
object_type	string	YES	NO
object_id	string	NO	NO
position	integer	NO	NO
client	string	YES	NO
creation_date	integer	NO	NO
update_date	integer	NO	NO
song	array<SongObject>	NO	YES	see SongObject fields
podcast_episode	array<PodcastEpisodeObject>	NO	YES	see PodcastEpisodeObject fields
video	array<VideoObject>	NO	YES	see VideoObject fields

throws

<root><error></root>

Example

browse

Return children of a parent object in a folder traversal/browse style. If you don't send any parameters you'll get a catalog list (the 'root' path)

NOTE From API version 8 the catalog ID is optional on 'album_artist', 'artist', 'album', 'album_disk' and 'podcast'. Send it to restrict the children to a single catalog; omit it to get the children from every catalog you can see. API version 6 still requires it on those types.

Input	Type	Description	Optional
'filter'	string	object_id	YES
'type'	string	'root', 'catalog', 'album_artist', 'artist', 'album', 'album_disk', 'podcast'	YES
'catalog'	string	catalog ID you are browsing	YES
'add'	set_filter	ISO 8601 Date Format (2020-09-16) Find objects with an 'add' date newer than the specified date	YES
'update'	set_filter	ISO 8601 Date Format (2020-09-16) Find objects with an 'update' time newer than the specified date	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a browse list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
catalog_id	string	NO	NO
parent_id	string	NO	NO
parent_type	string	NO	NO
child_type	string	NO	NO
browse	array<BrowseObject>	NO	NO	see BrowseObject fields

Each browse entry (BrowseObject):

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	NO	NO
prefix	string	YES	NO
basename	string	NO	NO

throws

<root><error></root>

Example

Example: music catalog

Example: podcast catalog

Example: video catalog

Example: artist

Example: album

Example: podcast

catalogs

This searches the catalogs and returns... catalogs

Input	Type	Description	Optional
'filter'	string	`music`, `clip`, `tvshow`, `movie`, `personal_video`, `podcast` (Catalog type)	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a catalog list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
catalog	array<CatalogObject>	NO	NO	see CatalogObject fields

Each catalog entry (CatalogObject):

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	YES	NO
type	string	YES	NO
gather_types	string	YES	NO
enabled	boolean	NO	NO
last_add	integer	NO	NO
last_clean	integer	YES	NO
last_update	integer	NO	NO
path	string	NO	NO
rename_pattern	string	YES	NO
sort_pattern	string	YES	NO

throws

<root><error></root>

Example

catalog

Return catalog by UID

Input	Type	Description	Optional
'filter'	string	UID of Catalog	NO

return

Returns a single object.

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	YES	NO
type	string	YES	NO
gather_types	string	YES	NO
enabled	boolean	NO	NO
last_add	integer	NO	NO
last_clean	integer	YES	NO
last_update	integer	NO	NO
path	string	NO	NO
rename_pattern	string	YES	NO
sort_pattern	string	YES	NO

throws

<root><error></root>

Example

catalog_action

Kick off a catalog update or clean for the selected catalog

ACCESS REQUIRED: 75 (Catalog Manager)

NOTE filter is available in Ampache 7.9.0 and higher. catalog is deprecated and will be removed in API9.

Input	Type	Description	Optional
'task'	string	`add_to_catalog`, `clean_catalog`, `verify_catalog`, `update_catalog`, `gather_art`, `garbage_collect`, `scan_catalog_folders`	NO
'filter'	string	$catalog_id	NO

return

<root>
    <success>
</root>

throws

<root><error></root>

Example: clean_catalog

Example: add_to_catalog

catalog_add

Create a new catalog.

ACCESS REQUIRED: 75 (Catalog Manager)

Input	Type	Description	Optional
'name'	string	Name for the catalog	NO
'path'	string	URL or folder path for your catalog	NO
'type'	string	'local', 'beets', 'remote', 'subsonic', 'seafile', 'beetsremote' Default: local	YES
'media_type'	string	'music', 'podcast', 'clip', 'tvshow', 'movie', 'personal_video' Default: 'music'	YES
'file_pattern'	string	Pattern used identify tags from the file name. Default: '%T - %t'	YES
'folder_pattern'	string	Pattern used identify tags from the folder name. Default: '%a/%A'	YES
'username'	string	login to remote catalog ('remote', 'subsonic', 'seafile', 'beetsremote')	YES
'password'	string	password to remote catalog ('remote', 'subsonic', 'seafile', 'beetsremote')	YES

NOTE For privacy, send password in a form or JSON request body rather than the query string. Query-string support for password is deprecated but still accepted for backward compatibility.

return

<root>
    <total_count>
    <catalog>
</root>

throws

<root><error></root>

Example

catalog_delete

Delete an existing catalog.

ACCESS REQUIRED: 75 (Catalog Manager)

Input	Type	Description	Optional
'filter'	string	UID of catalog to delete	NO

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

catalog_file

Perform actions on local catalog files. Single file versions of catalog add, clean, verify and remove (delete) Make sure you remember to urlencode those file names!

ACCESS REQUIRED: 50 (Content Manager)

NOTE filter is available in Ampache 7.9.0 and higher. catalog is deprecated and will be removed in API9.

Input	Type	Description	Optional
'file'	string	FULL path to local file	NO
'task'	string	`add`, `clean`, `verify`, `remove` (can include comma-separated values)	NO
'filter'	string	$catalog_id	NO

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

catalog_folder

Perform actions on local catalog folders. Single folder versions of catalog add, clean, verify and remove (delete) Make sure you remember to urlencode those folder names!

ACCESS REQUIRED: 50 (Content Manager)

NOTE filter is available in Ampache 7.9.0 and higher. catalog is deprecated and will be removed in API9.

Input	Type	Description	Optional
'folder'	string	FULL path to local folder	NO
'task'	string	`add`, `clean`, `verify`, `remove` (can include comma-separated values)	NO
'filter'	string	$catalog_id	NO

return

Returns a single object.

Field	Type	Nullable	Optional	Notes
success	string	NO	YES

throws

<root><error></root>

Example

collections

A collection is a hand-curated list of objects of any type: the static counterpart to a search, and the non-media counterpart to a playlist. Playing one expands its members, so an album contributes its songs and anything that cannot be streamed is skipped.

This returns every collection you own, plus every public collection on the server.

Input	Type	Description	Optional
'type'	string	Only return collections pinned to this object_type	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES

return

Returns a collection list.

Field	Type	Nullable	Optional	Notes
collection	array<CollectionObject>	NO	NO	see CollectionObject fields

Each collection entry (CollectionObject):

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	NO	NO
owner	string	YES	NO
type	string	YES	NO
object_type	string	YES	NO
items	integer	NO	NO
has_art	boolean	NO	NO
playlist_folder_id	string	NO	YES
playlist_folder_sort_order	integer	NO	YES

throws

<root><error></root>

collection

Return a collection by UID, without its contents.

Input	Type	Description	Optional
'filter'	string	UID of Collection	NO

return

Returns a collection list.

Field	Type	Nullable	Optional	Notes
collection	array<CollectionObject>	NO	NO	see CollectionObject fields

Each collection entry (CollectionObject):

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	NO	NO
owner	string	YES	NO
type	string	YES	NO
object_type	string	YES	NO
items	integer	NO	NO
has_art	boolean	NO	NO
playlist_folder_id	string	NO	YES
playlist_folder_sort_order	integer	NO	YES

throws

<root><error></root>

collection_items

A collection's members, in curated order.

The order is the data. A collection records the order its members were curated into, so <contents> holds one <item> per member in that order and a client should render them exactly as they arrive. Each <item> carries track (the 1-based position), track_id (the membership row, which is what identifies one member when the same object appears more than once) and object_type as attributes, and nests that type's own element inside:

<contents>
    <item track="1" track_id="7" object_type="album">
        <album id="21">...</album>
    </item>
    <item track="2" track_id="8" object_type="song">
        <song id="60">...</song>
    </item>
</contents>

Positions are dense and 1-based. They are renumbered whenever a member is added, removed or moved, so a position is only meaningful against the collection as it was when you read it.

offset and limit page the list without disturbing the order. The scalar items on the collection stays the total member count, so it is not reduced by paging.

Input	Type	Description	Optional
'filter'	string	UID of Collection	NO
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES

return

Returns a single object.

Field	Type	Nullable	Optional	Notes
collection	object	NO	NO	`{id, name, owner, type, object_type, items, has_art, playlist_folder_id, playlist_folder_sort_order, contents}`

throws

<root><error></root>

collection_create

Create a new, empty collection.

Leave object_type out for a mixed collection, or set it to pin the collection to a single type so anything else is refused when it is added.

Input	Type	Description	Optional
'name'	string	Collection name	NO
'type'	string	`public`, `private` (Default: `private`)	YES
'object_type'	string	Pin the collection to a single object_type	YES

return

Returns a collection list.

Field	Type	Nullable	Optional	Notes
collection	array<CollectionObject>	NO	NO	see CollectionObject fields

Each collection entry (CollectionObject):

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	NO	NO
owner	string	YES	NO
type	string	YES	NO
object_type	string	YES	NO
items	integer	NO	NO
has_art	boolean	NO	NO
playlist_folder_id	string	NO	YES
playlist_folder_sort_order	integer	NO	YES

throws

<root><error></root>

collection_edit

Change a collection's name, visibility, pinned type, collaborators or member order.

Only the values you send are changed. Send an empty object_type to un-pin a collection back to mixed; pinning is refused while the collection still holds a different type.

Reordering

items and tracks reorder the members the same way playlist_edit does: the two lists are paired in order, and each pair puts one member at one position, replacing whatever held that position before. Send only the pairs you want to change for a partial reorder, or every pair for a whole one.

Because a collection is heterogeneous, each entry in items carries its type as object_type:object_id:

items=album:21,song:60,album:44
tracks=1,2,3

The two lists must name the same number of entries or the call is refused. Pairs naming an unknown type, a non-positive id or a non-positive position are skipped rather than failing the whole request. Positions are renumbered afterwards so the order stays dense.

Input	Type	Description	Optional
'filter'	string	UID of Collection	NO
'name'	string	Collection name	YES
'type'	string	`public`, `private`	YES
'object_type'	string	Pinned object_type, or an empty string to un-pin	YES
'collaborate'	string	Comma separated list of user ids allowed to curate the contents	YES
'items'	string	Comma separated `object_type:object_id` pairs	YES
'tracks'	string	Comma separated positions matched to `items` in order	YES

return

Returns a collection list.

Field	Type	Nullable	Optional	Notes
collection	array<CollectionObject>	NO	NO	see CollectionObject fields

Each collection entry (CollectionObject):

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	NO	NO
owner	string	YES	NO
type	string	YES	NO
object_type	string	YES	NO
items	integer	NO	NO
has_art	boolean	NO	NO
playlist_folder_id	string	NO	YES
playlist_folder_sort_order	integer	NO	YES

throws

<root><error></root>

collection_delete

Delete a collection and its membership rows. The objects it referenced are untouched.

ACCESS REQUIRED: collection owner or admin. A collaborator may curate the contents but not destroy the list.

Input	Type	Description	Optional
'filter'	string	UID of Collection	NO

return object

<root><success></root>

throws

<root><error></root>

collection_add

Add one object to the end of a collection.

The new member takes the next free position, so an add never disturbs the order of what is already there.

Whether a collection may hold the same object twice is the user's unique_playlist preference, the same one that governs duplicates in their playlists. It is off by default, so duplicates are allowed by default; with it on, adding an object that is already a member is refused with an error rather than silently doing nothing.

A pinned collection refuses anything but its own type, and an object that does not exist is refused rather than stored as a dangling id.

Input	Type	Description	Optional
'filter'	string	UID of Collection	NO
'id'	string	UID of the object to add	NO
'object_type'	string	type of the object to add	NO

return object

<root><success></root>

throws

<root><error></root>

collection_remove

Remove members from a collection. The objects themselves are untouched, and removing something that was never a member is not an error.

Name either a position or an object:

track removes exactly the one member holding that position.
id with object_type removes every member pointing at that object. With duplicates allowed that can be more than one, which is what naming an object rather than a position means.

Either way the remaining positions close up, so the order stays dense and 1-based. Positions you read before the call are stale afterwards.

Input	Type	Description	Optional
'filter'	string	UID of Collection	NO
'track'	integer	position of the member to remove	YES
'id'	string	UID of the object to remove	YES
'object_type'	string	type of the object to remove	YES

track takes precedence. Without it, both id and object_type are required.

return object

<root><success></root>

throws

<root><error></root>

deleted_podcast_episodes

This returns the episodes for a podcast that have been deleted

Input	Type	Description	Optional
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES

return

Returns a deleted_podcast_episode list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
deleted_podcast_episode	array<DeletedPodcastEpisodeObject>	NO	NO	see DeletedPodcastEpisodeObject fields

Each deleted_podcast_episode entry (DeletedPodcastEpisodeObject):

Field	Type	Nullable	Optional
id	string	NO	NO
addition_time	integer	NO	NO
delete_time	integer	NO	NO
title	string	YES	NO
file	string	NO	NO
catalog	string	NO	NO
total_count	integer	NO	NO
total_skip	integer	NO	NO
podcast	string	NO	NO

throws

<root><error></root>

Example

deleted_songs

Returns songs that have been deleted from the server

Input	Type	Description	Optional
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES

return

Returns a deleted_song list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
deleted_song	array<DeletedSongObject>	NO	NO	see DeletedSongObject fields

Each deleted_song entry (DeletedSongObject):

Field	Type	Nullable	Optional
id	string	NO	NO
addition_time	integer	NO	NO
delete_time	integer	NO	NO
title	string	YES	NO
file	string	NO	NO
catalog	string	NO	NO
total_count	integer	NO	NO
total_skip	integer	NO	NO
update_time	integer	NO	NO
album	string	NO	NO
artist	string	NO	NO

throws

<root><error></root>

Example

deleted_videos

This returns video objects that have been deleted

Input	Type	Description	Optional
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES

return

Returns a deleted_video list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
deleted_video	array<DeletedVideoObject>	NO	NO	see DeletedVideoObject fields

Each deleted_video entry (DeletedVideoObject):

Field	Type	Nullable	Optional
id	string	NO	NO
addition_time	integer	NO	NO
delete_time	integer	NO	NO
title	string	YES	NO
file	string	NO	NO
catalog	string	NO	NO
total_count	integer	NO	NO
total_skip	integer	NO	NO

throws

<root><error></root>

Example

flag

This flags a library item as a favorite

Setting flag to true (1) will set the flag
Setting flag to false (0) will remove the flag

NOTE filter is available in Ampache 7.9.0 and higher. id is deprecated and will be removed in API9.

Input	Type	Description	Optional
'type'	string	`song`, `album`, `artist`, `playlist`, `podcast`	NO
		`podcast_episode`, `video`, `tvshow`, `tvshow_season`
'filter'	string	$object_id	NO
'filter'	string	Alias of `id` (Ampache 7.9.0+)	YES
'flag'	boolean	`0`, `1`	NO

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

folders

Return children of a parent object in a folder traversal style Ampache 8.0.0+

Input	Type	Description	Optional
'filter'	string	Path name or folder UID filter (Default: '/', the root folder; -1 is also the root)	YES
'exact'	boolean	`0`, `1` (if true filter is exact rather than fuzzy; default: 1)	YES
'add'	set_filter	ISO 8601 Date Format (2020-09-16) Find objects with an 'add' date newer than the specified date	YES
'update'	set_filter	ISO 8601 Date Format (2020-09-16) Find objects with an 'update' time newer than the specified date	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a single object.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
folder	FolderBrowseNode	NO	NO	see FolderBrowseNode fields

throws

<root><error></root>

followers

This gets the followers for the requested username

Input	Type	Description	Optional
'username'	string	Username of the user for who to get followers list	NO
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a user list.

Field	Type	Nullable	Optional	Notes
user	array<UserSummaryObject>	NO	NO	see UserSummaryObject fields

Each user entry (UserSummaryObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
username	string	YES	NO

throws

<root><error></root>

Example

following

Get a list of people that this user follows

Input	Type	Description	Optional
'username'	string	(Username of the user for who to get following list	NO

return

Returns a user list.

Field	Type	Nullable	Optional	Notes
user	array<UserSummaryObject>	NO	NO	see UserSummaryObject fields

Each user entry (UserSummaryObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
username	string	YES	NO

throws

<root><error></root>

Example

friends_timeline

This get current user friends timeline

Input	Type	Description	Optional
'limit'	integer	Maximum number of results to return	YES
'since'	integer	UNIXTIME()	NO

return

Returns a activity list.

Field	Type	Nullable	Optional	Notes
activity	array<ActivityObject>	NO	NO	see ActivityObject fields

Each activity entry (ActivityObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
date	integer	NO	NO
object_type	string	YES	NO
object_id	string	NO	NO
action	string	NO	NO
user	UserSummaryObject	NO	NO	see UserSummaryObject fields

throws

<root><error></root>

Example

genres

This returns the genres (Tags) based on the specified filter

Input	Type	Description	Optional
'filter'	string	Filter results to match this string	YES
'exact'	boolean	`0`, `1` (if true filter is exact `=` rather than fuzzy `LIKE`)	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a genre list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
genre	array<GenreObject>	NO	NO	see GenreObject fields

Each genre entry (GenreObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
name	string	YES	NO
albums	integer	NO	NO
artists	integer	NO	NO
songs	integer	NO	NO
videos	integer	NO	NO
playlists	integer	NO	NO
live_streams	integer	NO	NO
is_hidden	boolean	NO	NO
merge	array<GenreReference>	NO	NO	see GenreReference fields

throws

<root><error></root>

Example

genre

This returns a single genre based on UID. All XML Documents that have a <genre></genre> element may have 0 or more genre elements associated with them. Each genre element has an attribute "count" that indicates the number of people who have specified this genre.

Input	Type	Description	Optional
'filter'	string	UID of genre, returns genre XML	NO

return

Returns a single object.

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
name	string	YES	NO
albums	integer	NO	NO
artists	integer	NO	NO
songs	integer	NO	NO
videos	integer	NO	NO
playlists	integer	NO	NO
live_streams	integer	NO	NO
is_hidden	boolean	NO	NO
merge	array<GenreReference>	NO	NO	see GenreReference fields

throws

<root><error></root>

Example

genre_albums

This returns the albums associated with the genre in question

Input	Type	Description	Optional
'filter'	string	UID of genre, returns album XML	NO
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a album list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
album	array<AlbumObject>	NO	NO	see AlbumObject fields

Each album entry (AlbumObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
name	string	YES	NO
prefix	string	YES	NO
basename	string	YES	NO
artist	object	YES	YES	`{id, name, prefix, basename}`
artists	array<NamedReference>	NO	YES	see NamedReference fields
songartists	array<NamedReference>	NO	YES	see NamedReference fields
time	integer	NO	NO
year	integer	NO	NO
tracks	array<SongObject>	NO	NO	see SongObject fields
songcount	integer	NO	NO
diskcount	integer	NO	NO
type	string	YES	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
mbid	string	YES	NO
mbid_group	string	YES	NO
catalog	string	NO	NO

throws

<root><error></root>

Example

genre_artists

This returns the artists associated with the genre in question as defined by the UID

Input	Type	Description	Optional
'filter'	string	UID of genre, returns artist XML	NO
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a artist list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
artist	array<ArtistObject>	NO	NO	see ArtistObject fields

Each artist entry (ArtistObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
name	string	YES	NO
prefix	string	YES	NO
basename	string	YES	NO
albums	array<AlbumObject>	NO	NO	see AlbumObject fields
albumcount	integer	NO	NO
songs	array<SongObject>	NO	NO	see SongObject fields
songcount	integer	NO	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
mbid	string	YES	NO
summary	string	YES	NO
time	integer	NO	NO
yearformed	integer	NO	NO
placeformed	string	YES	NO

throws

<root><error></root>

Example

genre_songs

returns the songs for this genre

Input	Type	Description	Optional
'filter'	string	UID of genre, returns song XML	NO
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a song list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
song	array<SongObject>	NO	NO	see SongObject fields

Each song entry (SongObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
title	string	YES	NO
name	string	YES	NO
artist	NamedReference	NO	NO	see NamedReference fields
artists	array<NamedReference>	NO	NO	see NamedReference fields
album	NamedReference	NO	NO	see NamedReference fields
albumartist	NamedReference	NO	YES	see NamedReference fields
disk	integer	NO	NO
disksubtitle	string	YES	NO
bpm	number	YES	NO
track	integer	NO	NO
filename	string	YES	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
mood	array<object>	NO	NO	`{id, name}`
playlisttrack	integer	NO	NO
time	integer	NO	NO
year	integer	NO	NO
format	string	YES	NO
stream_format	string	YES	NO
bitrate	integer	YES	NO
stream_bitrate	integer	YES	NO
rate	integer	NO	NO
mode	string	YES	NO
mime	string	YES	NO
stream_mime	string	YES	NO
url	string	NO	NO
size	integer	NO	NO
mbid	string	YES	NO
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
playcount	integer	NO	NO
last_played	string	YES	NO
catalog	string	NO	NO
composer	string	YES	NO
channels	integer	YES	NO
comment	string	YES	NO
license	string	YES	NO
publisher	string	YES	NO
language	string	YES	NO
lyrics	string	YES	NO
replaygain_album_gain	number	YES	NO
replaygain_album_peak	number	YES	NO
replaygain_track_gain	number	YES	NO
replaygain_track_peak	number	YES	NO
r128_album_gain	number	YES	NO
r128_track_gain	number	YES	NO
metadata	object<string, string>	NO	YES

throws

<root><error></root>

Example

get_bookmark

Get the bookmark from it's object_id and object_type. By default; get only the most recent bookmark. Use all to retrieve all media bookmarks for the object.

Input	Type	Description	Optional
'filter'	string	$object_id to find	NO
'type'	string	`song`, `video`, `podcast_episode` (object_type)	NO
'include'	integer	0,1, if true include the object in the bookmark	YES
'all'	integer	0,1, if true include every bookmark for the object	YES

return

<root>
    <bookmark>
</root>

throws

<root><error></root>

Example Example (with include)

get_external_metadata

Return External plugin metadata searching by object id and type

Input	Type	Description	Optional
'filter'	string	$object_id to find	NO
'type'	string	`song`, `album`, `artist`, `label` (object_type)	NO

return

Returns the plugin payloads when at least one metadata plugin answered, and the empty list envelope for the requested type when none did.

ExternalMetadataObject

plugin is keyed by metadata-retriever plugin name; each value is that plugin's payload.

Field	Type	Nullable	Optional	Notes
object_id	string	NO	NO
object_type	string	NO	NO
plugin	`_PluginMap`	NO	NO	see `_PluginMap` fields

EmptyListResponse

The standard empty envelope, with an empty list keyed by the requested type.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO

throws

<root><error></root>

Example

get_indexes

This takes a collection of inputs and returns ID + name for the object type

NOTE This method was removed in API8 (Use list)

Input	Type	Description	Optional
'type'	string	`song`, `album`, `artist`, `album_artist`, `song_artist`, `playlist`, `podcast`	NO
		`podcast_episode`, `live_stream`, `catalog`
'filter'	string	Value is Alpha Match for returned results, may be more than one letter/number	YES
'hide_search'	integer	`0`, `1` (if true do not include searches/smartlists in the result)	YES
'update'	set_filter	ISO 8601 Date Format (2020-09-16) Find objects with an 'update' time newer than the specified date	YES
'include'	boolean	`0`, `1` (include songs in a playlist or episodes in a podcast)	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

<root>
    <total_count>
    <song>|<album>|<artist>|<playlist>|<podcast>
</root>

throws

<root><error></root>

SONGS Example

ARTIST Example

ALBUM Example

PLAYLIST Example

PODCAST Example

get_lyrics

Return Database lyrics or search with plugins by Song id

Input	Type	Description	Optional
'filter'	string	$song_id to find	NO
'plugins'	string	`0`, `1`, if false disable plugin lookup (default: 1)	NO

return

plugin is keyed by lyric source (database plus any lyric-retriever plugin that answered). When nothing answered it is serialised as an empty array, not an empty object.

Field	Type	Nullable	Optional	Notes
object_id	string	NO	NO
object_type	string	NO	NO
plugin	`_PluginMap`	NO	NO	see `_PluginMap` fields

throws

<root><error></root>

Example

get_similar

Return similar artist id's or similar song ids compared to the input filter

Input	Type	Description	Optional
'type'	string	`song`, `artist`	NO
'filter'	string	artist id or song id	NO
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES

return

Returns a song list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
song	array<SongObject>	NO	NO	see SongObject fields

Each song entry (SongObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
title	string	YES	NO
name	string	YES	NO
artist	NamedReference	NO	NO	see NamedReference fields
artists	array<NamedReference>	NO	NO	see NamedReference fields
album	NamedReference	NO	NO	see NamedReference fields
albumartist	NamedReference	NO	YES	see NamedReference fields
disk	integer	NO	NO
disksubtitle	string	YES	NO
bpm	number	YES	NO
track	integer	NO	NO
filename	string	YES	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
mood	array<object>	NO	NO	`{id, name}`
playlisttrack	integer	NO	NO
time	integer	NO	NO
year	integer	NO	NO
format	string	YES	NO
stream_format	string	YES	NO
bitrate	integer	YES	NO
stream_bitrate	integer	YES	NO
rate	integer	NO	NO
mode	string	YES	NO
mime	string	YES	NO
stream_mime	string	YES	NO
url	string	NO	NO
size	integer	NO	NO
mbid	string	YES	NO
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
playcount	integer	NO	NO
last_played	string	YES	NO
catalog	string	NO	NO
composer	string	YES	NO
channels	integer	YES	NO
comment	string	YES	NO
license	string	YES	NO
publisher	string	YES	NO
language	string	YES	NO
lyrics	string	YES	NO
replaygain_album_gain	number	YES	NO
replaygain_album_peak	number	YES	NO
replaygain_track_gain	number	YES	NO
replaygain_track_peak	number	YES	NO
r128_album_gain	number	YES	NO
r128_track_gain	number	YES	NO
metadata	object<string, string>	NO	YES

throws

<root><error></root>

Example

index

This takes a collection of inputs and returns ID + name for the object type

Input	Type	Description	Optional
'type'	string	`catalog`, `song`, `album`, `artist`, `album_artist`, `song_artist`	NO
		`playlist`, `podcast`, `podcast_episode`, `share`, `video`, `live_stream`
'filter'	string	Value is Alpha Match for returned results, may be more than one letter/number	YES
'hide_search'	integer	`0`, `1` (if true do not include searches/smartlists in the result)	YES
'exact'	boolean	`0`, `1` (if true filter is exact `=` rather than fuzzy `LIKE`)	YES
'add'	set_filter	ISO 8601 Date Format (2020-09-16) Find objects with an 'add' date newer than the specified date	YES
'update'	set_filter	ISO 8601 Date Format (2020-09-16) Find objects with an 'update' time newer than the specified date	YES
'include'	boolean	`0`, `1` (include songs in a playlist or episodes in a podcast)	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Keyed by the requested type (e.g. album, artist, song). Without include the value is an array of object ids; with include it is an array of {id, type} references, or a map of parent id -> reference array for parent types such as playlists.

Open map — each value is: array<string> | array<IndexReferenceObject> | object<string, array<IndexReferenceObject>>.

throws

<root><error></root>

SONGS Example

ARTIST Example

ALBUM Example

PLAYLIST Example

PODCAST Example

SONG Example (with include)

ARTIST Example (with include)

ALBUM Example (with include)

PLAYLIST Example (with include)

labels

This returns labels based on the specified filter

Input	Type	Description	Optional
'filter'	string	Filter results to match this string	YES
'exact'	boolean	`0`, `1` (if true filter is exact `=` rather than fuzzy `LIKE`)	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a label list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
label	array<LabelObject>	NO	NO	see LabelObject fields

Each label entry (LabelObject):

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	YES	NO
artists	integer	NO	NO
summary	string	YES	NO
external_link	string	NO	NO
address	string	YES	NO
category	string	YES	NO
email	string	YES	NO
website	string	YES	NO
user	string	NO	NO

throws

<root><error></root>

Example

label

This returns a single label

Input	Type	Description	Optional
'filter'	string	UID of label, returns label XML	NO

return

Returns a single object.

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	YES	NO
artists	integer	NO	NO
summary	string	YES	NO
external_link	string	NO	NO
address	string	YES	NO
category	string	YES	NO
email	string	YES	NO
website	string	YES	NO
user	string	NO	NO

throws

<root><error></root>

Example

label_artists

This returns the artists for a label

Input	Type	Description	Optional
'filter'	string	UID of label, returns artist XML	NO
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a artist list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
artist	array<ArtistObject>	NO	NO	see ArtistObject fields

Each artist entry (ArtistObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
name	string	YES	NO
prefix	string	YES	NO
basename	string	YES	NO
albums	array<AlbumObject>	NO	NO	see AlbumObject fields
albumcount	integer	NO	NO
songs	array<SongObject>	NO	NO	see SongObject fields
songcount	integer	NO	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
mbid	string	YES	NO
summary	string	YES	NO
time	integer	NO	NO
yearformed	integer	NO	NO
placeformed	string	YES	NO

throws

<root><error></root>

Example

last_shouts

This gets the latest posted shouts

NOTE filter is available in Ampache 7.9.0 and higher. catalog is deprecated and will be removed in API9

Input	Type	Description	Optional
'filter'	string	Get latest shouts for this username	YES
'limit'	integer	Maximum number of results (Use `popular_threshold` when missing; default 10)	YES

return

Returns a shout list.

Field	Type	Nullable	Optional	Notes
shout	array<ShoutObject>	NO	NO	see ShoutObject fields

Each shout entry (ShoutObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
date	integer	NO	NO
text	string	NO	NO
object_type	string	NO	NO
object_id	string	NO	NO
user	object	NO	NO	`{id, username}`

throws

<root><error></root>

Example

license

This returns a single license

Input	Type	Description	Optional
'filter'	string	UID of license, returns license XML	NO

return

Returns a single object.

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	NO	NO
description	string	NO	NO
external_link	string	NO	NO

throws

<root><error></root>

Example

license_songs

This returns the songs for a license

Input	Type	Description	Optional
'filter'	string	UID of license, returns song XML	NO
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a song list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
song	array<SongObject>	NO	NO	see SongObject fields

Each song entry (SongObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
title	string	YES	NO
name	string	YES	NO
artist	NamedReference	NO	NO	see NamedReference fields
artists	array<NamedReference>	NO	NO	see NamedReference fields
album	NamedReference	NO	NO	see NamedReference fields
albumartist	NamedReference	NO	YES	see NamedReference fields
disk	integer	NO	NO
disksubtitle	string	YES	NO
bpm	number	YES	NO
track	integer	NO	NO
filename	string	YES	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
mood	array<object>	NO	NO	`{id, name}`
playlisttrack	integer	NO	NO
time	integer	NO	NO
year	integer	NO	NO
format	string	YES	NO
stream_format	string	YES	NO
bitrate	integer	YES	NO
stream_bitrate	integer	YES	NO
rate	integer	NO	NO
mode	string	YES	NO
mime	string	YES	NO
stream_mime	string	YES	NO
url	string	NO	NO
size	integer	NO	NO
mbid	string	YES	NO
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
playcount	integer	NO	NO
last_played	string	YES	NO
catalog	string	NO	NO
composer	string	YES	NO
channels	integer	YES	NO
comment	string	YES	NO
license	string	YES	NO
publisher	string	YES	NO
language	string	YES	NO
lyrics	string	YES	NO
replaygain_album_gain	number	YES	NO
replaygain_album_peak	number	YES	NO
replaygain_track_gain	number	YES	NO
replaygain_track_peak	number	YES	NO
r128_album_gain	number	YES	NO
r128_track_gain	number	YES	NO
metadata	object<string, string>	NO	YES

throws

<root><error></root>

Example

licenses

This returns licenses based on the specified filter

Input	Type	Description	Optional
'filter'	string	Filter results to match this string	YES
'exact'	boolean	`0`, `1` (if true filter is exact `=` rather than fuzzy `LIKE`)	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a license list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
license	array<LicenseObject>	NO	NO	see LicenseObject fields

Each license entry (LicenseObject):

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	NO	NO
description	string	NO	NO
external_link	string	NO	NO

throws

<root><error></root>

Example

list

This takes a named array of objects and returning id, name, prefix and basename

NOTE This method replaces get_indexes and does not have the include parameter and does not include children in the response.

Input	Type	Description	Optional
'type'	string	`song`, `album`, `artist`, `album_artist`, `song_artist`, `playlist`, `podcast`	NO
		`podcast_episode`, `live_stream`, `catalog`
'filter'	string	Value is Alpha Match for returned results, may be more than one letter/number	YES
'hide_search'	integer	`0`, `1` (if true do not include searches/smartlists in the result)	YES
'update'	set_filter	ISO 8601 Date Format (2020-09-16) Find objects with an 'update' time newer than the specified date	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a list list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
list	array<ListObject>	NO	NO	see ListObject fields

Each list entry (ListObject):

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	NO	NO
prefix	string	YES	NO
basename	string	NO	NO

throws

<root><error></root>

Example

live_streams

This returns live_streams based on the specified filter

Input	Type	Description	Optional
'filter'	string	Filter results to match this string	YES
'exact'	boolean	`0`, `1` (if true filter is exact `=` rather than fuzzy `LIKE`)	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a live_stream list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
live_stream	array<LiveStreamObject>	NO	NO	see LiveStreamObject fields

Each live_stream entry (LiveStreamObject):

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	YES	NO
url	string	YES	NO
codec	string	YES	NO
catalog	string	NO	NO
site_url	string	YES	NO

throws

<root><error></root>

Example

live_stream

This returns a single live_stream

Input	Type	Description	Optional
'filter'	string	UID of live_stream, returns live_stream XML	NO

return

Returns a single object.

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	YES	NO
url	string	YES	NO
codec	string	YES	NO
catalog	string	NO	NO
site_url	string	YES	NO

throws

<root><error></root>

Example

live_stream_create

Create a live_stream (radio station) object.

ACCESS REQUIRED: 50 (Content Manager) permission to create and edit live_streams

Input	Type	Description	Optional
'filter'	string	$object_id to find	NO
'type'	string	`song`, `video`, `podcast_episode` (object_type)	NO
'position'	integer	current track time in seconds	NO
'client'	string	Agent string. (Default: 'AmpacheAPI')	YES
'date'	integer	update time (Default: UNIXTIME())	YES

return

Returns a single object.

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	YES	NO
url	string	YES	NO
codec	string	YES	NO
catalog	string	NO	NO
site_url	string	YES	NO

throws

<root><error></root>

Example

live_stream_delete

Delete an existing live_stream (radio station). (if it exists)

ACCESS REQUIRED: 50 (Content Manager) permission to create and edit live_streams

Input	Type	Description	Optional
'filter'	string	$object_id to delete	NO
'type'	string	`song`, `video`, `podcast_episode` (object_type)	NO
'client'	string	Agent string. (Default: 'AmpacheAPI')	YES

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

live_stream_edit

Edit a live_stream (radio station) object.

ACCESS REQUIRED: 50 (Content Manager) permission to create and edit live_streams

Input	Type	Description	Optional
'filter'	string	$object_id to find	NO
'type'	string	`song`, `video`, `podcast_episode` (object_type)	NO
'position'	integer	current track time in seconds	NO
'client'	string	Agent string. (Default: 'AmpacheAPI')	YES
'date'	integer	update time (Default: UNIXTIME())	YES

return

<root>
    <live_stream>
</root>

throws

<root><error></root>

Example

now_playing

Get what is currently being played by all users.

return

Returns a now_playing list.

Field	Type	Nullable	Optional	Notes
now_playing	array<NowPlayingObject>	NO	NO	see NowPlayingObject fields

Each now_playing entry (NowPlayingObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
type	string	NO	NO
client	string	NO	NO
expire	integer	NO	NO
user	object	NO	NO	`{id, username}`

throws

<root><error></root>

Example

player

Inform the server about the state of your client. (Song you are playing, Play/Pause state, etc.)

Return the now_playing state when completed

Input	Type	Description	Optional
'filter'	string	$object_id currently playing/stopping	NO
'type'	string	`song`, `video`, `podcast_episode` (Default: `song`)	YES
'state'	string	`play`, `stop` (Default: `play`)	YES
'time'	integer	current play time in whole seconds (Default: 0)	YES
'client'	string	agent/client name	YES

return

Returns a now_playing list.

Field	Type	Nullable	Optional	Notes
now_playing	array<NowPlayingObject>	NO	NO	see NowPlayingObject fields

Each now_playing entry (NowPlayingObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
type	string	NO	NO
client	string	NO	NO
expire	integer	NO	NO
user	object	NO	NO	`{id, username}`

throws

<root><error></root>

Example

playlists

This returns playlists based on the specified filter

Input	Type	Description	Optional
'filter'	string	Filter results to match this string	YES
'hide_search'	integer	`0`, `1` (if true do not include searches/smartlists in the result)	YES
'show_dupes'	integer	`0`, `1` (if true if true ignore 'api_hide_dupe_searches' setting)	YES
'exact'	boolean	`0`, `1` (if true filter is exact `=` rather than fuzzy `LIKE`)	YES
'add'	set_filter	ISO 8601 Date Format (2020-09-16) Find objects with an 'add' date newer than the specified date	YES
'update'	set_filter	ISO 8601 Date Format (2020-09-16) Find objects with an 'update' time newer than the specified date	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a playlist list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
playlist	array<PlaylistObject>	NO	NO	see PlaylistObject fields

Each playlist entry (PlaylistObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
name	string	YES	NO
owner	string	YES	NO
user	UserSummaryObject	NO	NO	see UserSummaryObject fields
items	array<object> \| integer	NO	NO
type	string	YES	NO
art	string	YES	NO
has_access	boolean	NO	NO
has_collaborate	boolean	NO	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
md5	string	YES	NO
last_update	integer	YES	NO
time	integer	NO	NO
playlist_folder_id	string	NO	YES
playlist_folder_sort_order	integer	NO	YES

throws

<root><error></root>

Example

playlist

This returns a single playlist

Input	Type	Description	Optional
'filter'	string	UID of playlist, returns playlist XML	NO

return

Returns a single object.

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
name	string	YES	NO
owner	string	YES	NO
user	UserSummaryObject	NO	NO	see UserSummaryObject fields
items	array<object> \| integer	NO	NO
type	string	YES	NO
art	string	YES	NO
has_access	boolean	NO	NO
has_collaborate	boolean	NO	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
md5	string	YES	NO
last_update	integer	YES	NO
time	integer	NO	NO
playlist_folder_id	string	NO	YES
playlist_folder_sort_order	integer	NO	YES

throws

<root><error></root>

Example

playlist_add

This adds a song to a playlist. setting check=1 will not add duplicates to the playlist

NOTE object_type is optional from Ampache8+

NOTE type is DEPRECATED, use object_type instead. Will be removed in API9. REST callers should always use object_type: the path playlists/{playlist_id}/add already binds type to the resource name (playlist), so type sent in the request body only works via an explicit body-over-path precedence rule in the REST dispatcher

Input	Type	Description	Optional
'filter'	string	UID of Playlist	NO
'id'	string	UID of the object to add to playlist	NO
'object_type'	string	'song', 'album', 'artist', 'playlist' (Default: song)	YES
'type'	string	DEPRECATED alias of `object_type`	YES

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

playlist_add_song

This adds a song to a playlist. setting check=1 will not add duplicates to the playlist

NOTE This method was removed in API8 (Use playlist_add)

Input	Type	Description	Optional
'filter'	string	UID of Playlist	NO
'song'	string	UID of song to add to playlist	NO
'check'	boolean	`0`, `1` Whether to check and ignore duplicates (default = 0)	YES

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

playlist_create

This create a new playlist and return it

Input	Type	Description	Optional
'name'	string	Playlist name	NO
'type'	string	`public`, `private` (Playlist type)	YES

return

Returns a single object.

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
name	string	YES	NO
owner	string	YES	NO
user	UserSummaryObject	NO	NO	see UserSummaryObject fields
items	array<object> \| integer	NO	NO
type	string	YES	NO
art	string	YES	NO
has_access	boolean	NO	NO
has_collaborate	boolean	NO	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
md5	string	YES	NO
last_update	integer	YES	NO
time	integer	NO	NO
playlist_folder_id	string	NO	YES
playlist_folder_sort_order	integer	NO	YES

throws

<root><error></root>

Example

playlist_delete

This deletes a playlist

Input	Type	Description	Optional
'filter'	string	UID of Playlist	NO

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

playlist_edit

This modifies name and type of a playlist Previously name and type were mandatory while filter wasn't. this has been reversed.

NOTE items and tracks must be sent together and be of equal length

Input	Type	Description	Optional
'filter'	string	UID of Playlist	NO
'name'	string	Playlist name	YES
'type'	string	`public`, `private` (Playlist type)	YES
'owner'	string	Change playlist owner to the user id (-1 = System playlist)	YES
'items'	string	comma-separated song_id's (replaces existing items with a new id)	YES
'tracks'	string	comma-separated playlisttrack numbers matched to 'items' in order	YES

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

playlist_generate

Get a list of song XML, indexes or id's based on some simple search criteria 'recent' will search for tracks played after 'Popular Threshold' days 'forgotten' will search for tracks played before 'Popular Threshold' days 'unplayed' added in 400002 for searching unplayed tracks

Note when using the 'id' format total_count is not returned.

Input	Type	Description	Optional
'mode'	string	`recent`, `forgotten`, `unplayed`, `random` (default = 'random')	YES
'filter'	string	string LIKE matched to song title	YES
'album'	string	$album_id	YES
'artist'	string	$artist_id	YES
'flag'	integer	`0`, `1` (get flagged songs only. default = 0)	YES
'format'	string	`song`, `index`, `id` (default = 'song')	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES

return

Depends on the format parameter: song (default) and index return the song list envelope, id returns a bare array of song ids.

SongsResponse

Returns a song list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
song	array<SongObject>	NO	NO	see SongObject fields

Each song entry (SongObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
title	string	YES	NO
name	string	YES	NO
artist	NamedReference	NO	NO	see NamedReference fields
artists	array<NamedReference>	NO	NO	see NamedReference fields
album	NamedReference	NO	NO	see NamedReference fields
albumartist	NamedReference	NO	YES	see NamedReference fields
disk	integer	NO	NO
disksubtitle	string	YES	NO
bpm	number	YES	NO
track	integer	NO	NO
filename	string	YES	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
mood	array<object>	NO	NO	`{id, name}`
playlisttrack	integer	NO	NO
time	integer	NO	NO
year	integer	NO	NO
format	string	YES	NO
stream_format	string	YES	NO
bitrate	integer	YES	NO
stream_bitrate	integer	YES	NO
rate	integer	NO	NO
mode	string	YES	NO
mime	string	YES	NO
stream_mime	string	YES	NO
url	string	NO	NO
size	integer	NO	NO
mbid	string	YES	NO
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
playcount	integer	NO	NO
last_played	string	YES	NO
catalog	string	NO	NO
composer	string	YES	NO
channels	integer	YES	NO
comment	string	YES	NO
license	string	YES	NO
publisher	string	YES	NO
language	string	YES	NO
lyrics	string	YES	NO
replaygain_album_gain	number	YES	NO
replaygain_album_peak	number	YES	NO
replaygain_track_gain	number	YES	NO
replaygain_track_peak	number	YES	NO
r128_album_gain	number	YES	NO
r128_track_gain	number	YES	NO
metadata	object<string, string>	NO	YES

array<string>

Returned by format=id: song ids only, with no envelope.

throws

<root><error></root>

SONG Example

INDEX Example

ID Example

playlist_hash

This returns the md5 hash for the songs in a playlist

Input	Type	Description	Optional
'filter'	string	UID of Playlist	NO

return

Returns a single object.

Field	Type	Nullable	Optional	Notes
md5	string	YES	NO

throws

<root><error></root>

Example

playlist_remove

Remove objects from a playlist using track number in the list or object id and type. Using clear will empty the entire list.

NOTE this replaces playlist_remove_song in API8

NOTE type is DEPRECATED, use object_type instead. Will be removed in API9. REST callers should always use object_type: the path playlists/{playlist_id}/remove already binds type to the resource name (playlist), so type sent in the request body only works via an explicit body-over-path precedence rule in the REST dispatcher

Input	Type	Description	Optional
'filter'	string	UID of Playlist	NO
'id'	string	UID of object to remove from playlist	YES
'object_type'	string	'song', 'album', 'artist', 'playlist', default = song	YES
'type'	string	DEPRECATED alias of `object_type`	YES
'track'	integer	Track number to remove from playlist	YES
'clear'	integer	0,1 Clear the whole playlist	YES

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

playlist_songs

This returns the songs for a playlist

Input	Type	Description	Optional
'filter'	string	UID of Playlist, returns song XML	NO
'random'	integer	`0`, `1` (if true get random songs using limit)	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES

return

Returns a song list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
song	array<SongObject>	NO	NO	see SongObject fields

Each song entry (SongObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
title	string	YES	NO
name	string	YES	NO
artist	NamedReference	NO	NO	see NamedReference fields
artists	array<NamedReference>	NO	NO	see NamedReference fields
album	NamedReference	NO	NO	see NamedReference fields
albumartist	NamedReference	NO	YES	see NamedReference fields
disk	integer	NO	NO
disksubtitle	string	YES	NO
bpm	number	YES	NO
track	integer	NO	NO
filename	string	YES	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
mood	array<object>	NO	NO	`{id, name}`
playlisttrack	integer	NO	NO
time	integer	NO	NO
year	integer	NO	NO
format	string	YES	NO
stream_format	string	YES	NO
bitrate	integer	YES	NO
stream_bitrate	integer	YES	NO
rate	integer	NO	NO
mode	string	YES	NO
mime	string	YES	NO
stream_mime	string	YES	NO
url	string	NO	NO
size	integer	NO	NO
mbid	string	YES	NO
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
playcount	integer	NO	NO
last_played	string	YES	NO
catalog	string	NO	NO
composer	string	YES	NO
channels	integer	YES	NO
comment	string	YES	NO
license	string	YES	NO
publisher	string	YES	NO
language	string	YES	NO
lyrics	string	YES	NO
replaygain_album_gain	number	YES	NO
replaygain_album_peak	number	YES	NO
replaygain_track_gain	number	YES	NO
replaygain_track_peak	number	YES	NO
r128_album_gain	number	YES	NO
r128_track_gain	number	YES	NO
metadata	object<string, string>	NO	YES

throws

<root><error></root>

Example

playlist_folders

A playlist folder organises playlists, smartlists and collections into a private tree. The tree belongs to the calling user alone and is never visible to another user, so filing someone else's public playlist changes nothing for them.

This returns the whole tree as a flat list; rebuild the hierarchy from each folder's parent, where 0 is the root.

Input	Type	Description	Optional
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES

return

Returns a playlist_folder list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
playlist_folder	array<PlaylistFolderObject>	NO	NO	see PlaylistFolderObject fields

Each playlist_folder entry (PlaylistFolderObject):

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	NO	NO
parent	string	NO	NO
sort_order	integer	NO	NO
items	integer	NO	NO

throws

<root><error></root>

playlist_folder

One folder's own details, without its contents. A folder belonging to another user reports as not found rather than forbidden, so a tree cannot be probed from outside.

Input	Type	Description	Optional
'filter'	string	The folder, as an id or a name path such as `/Rock/Live`; the root when omitted	YES

return

Returns a playlist_folder list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
playlist_folder	array<PlaylistFolderObject>	NO	NO	see PlaylistFolderObject fields

Each playlist_folder entry (PlaylistFolderObject):

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	NO	NO
parent	string	NO	NO
sort_order	integer	NO	NO
items	integer	NO	NO

throws

<root><error></root>

playlist_folder_create

Create a folder in the calling user's tree. The name may not contain a /, because that is the path separator, and must be unique among its siblings; the comparison is case-insensitive, so Rock and rock collide.

Input	Type	Description	Optional
'name'	string	Folder name	NO
'parent'	string	Parent folder as an id or a name path	YES
'sort_order'	integer	Position among its siblings	YES

parent defaults to the root when omitted; sort_order defaults to appended (last among its siblings) when omitted.

return

Returns a playlist_folder list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
playlist_folder	array<PlaylistFolderObject>	NO	NO	see PlaylistFolderObject fields

Each playlist_folder entry (PlaylistFolderObject):

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	NO	NO
parent	string	NO	NO
sort_order	integer	NO	NO
items	integer	NO	NO

throws

<root><error></root>

playlist_folder_edit

Change a folder's name, parent or position. Anything not sent is left as it is; at least one of name, parent or sort_order must be sent. Moving a folder into its own subtree is refused, because it would detach the branch from the tree.

Input	Type	Description	Optional
'filter'	string	The folder, as an id or a name path	NO
'name'	string	New name	YES
'parent'	string	New parent as an id or a name path, or `0` for the root	YES
'sort_order'	integer	New position among its siblings	YES

return

Returns a playlist_folder list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
playlist_folder	array<PlaylistFolderObject>	NO	NO	see PlaylistFolderObject fields

Each playlist_folder entry (PlaylistFolderObject):

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	NO	NO
parent	string	NO	NO
sort_order	integer	NO	NO
items	integer	NO	NO

throws

<root><error></root>

playlist_folder_delete

Delete a folder. It must hold neither a child folder nor a filed list; the lists themselves are never touched, so emptying a folder means moving its contents out first.

Input	Type	Description	Optional
'filter'	string	The folder, as an id or a name path	NO

return object

<root><success></root>

throws

<root><error></root>

playlist_folder_items

The playlists, smartlists and collections filed in one folder. The root is not a stored folder: it holds every list the calling user can see that has not been filed elsewhere, so a newly created playlist appears there without anything having been written for it.

Input	Type	Description	Optional
'filter'	string	The folder, as an id or a name path; `0` or `/` for the root; the root when omitted	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES

return

Returns a single object.

Field	Type	Nullable	Optional	Notes
playlist_folder	object	NO	NO	`{id, name, parent, sort_order, items, contents}`

throws

<root><error></root>

playlist_folder_add

File a playlist, smartlist or collection into a folder. A list already filed is moved rather than duplicated: it sits in exactly one of the calling user's folders at a time.

Input	Type	Description	Optional
'filter'	string	The folder, as an id or a name path; `0` or `/` returns the list to the root; the root when omitted	YES
'id'	integer	UID of the list to file	NO
'type'	string	`playlist`, `smartlist`, `collection`	NO
'sort_order'	integer	Position among its siblings	YES

sort_order defaults to appended (last among its siblings) when omitted.

return object

<root><success></root>

throws

<root><error></root>

playlist_folder_remove

Take a list out of its folder. The list itself is untouched and reappears at the root, because an unfiled list has no placement row at all.

Input	Type	Description	Optional
'id'	integer	UID of the list	NO
'type'	string	`playlist`, `smartlist`, `collection`	NO

return object

<root><success></root>

throws

<root><error></root>

podcast

Get the podcast from it's id.

Input	Type	Description	Optional
'filter'	string	UID of podcast, returns podcast XML	NO
'include'	string	`episodes` (include podcast_episodes in the response)	YES

return

Returns a single object.

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
name	string	YES	NO
description	string	NO	NO
language	string	NO	NO
copyright	string	NO	NO
feed_url	string	NO	NO
generator	string	NO	NO
website	string	NO	NO
build_date	string	NO	NO
sync_date	string	NO	NO
public_url	string	NO	NO
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
catalog	string	NO	NO
podcast_episode	array<PodcastEpisodeObject>	NO	NO	see PodcastEpisodeObject fields

throws

<root><error></root>

Example

podcasts

Get information about podcasts

Input	Type	Description	Optional
'filter'	string	Value is Alpha Match for returned results, may be more than one letter/number	YES
'include'	string	`episodes` (include podcast_episodes in the response)	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a podcast list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
podcast	array<PodcastObject>	NO	NO	see PodcastObject fields

Each podcast entry (PodcastObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
name	string	YES	NO
description	string	NO	NO
language	string	NO	NO
copyright	string	NO	NO
feed_url	string	NO	NO
generator	string	NO	NO
website	string	NO	NO
build_date	string	NO	NO
sync_date	string	NO	NO
public_url	string	NO	NO
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
catalog	string	NO	NO
podcast_episode	array<PodcastEpisodeObject>	NO	NO	see PodcastEpisodeObject fields

throws

<root><error></root>

Example

podcast_create

Create a podcast that can be used by anyone to stream media. Takes the url and catalog parameters.

ACCESS REQUIRED: 75 (Catalog Manager)

Input	Type	Description	Optional
'url'	string	rss url for podcast	NO
'catalog'	string	podcast catalog	NO

return

Returns a single object.

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
name	string	YES	NO
description	string	NO	NO
language	string	NO	NO
copyright	string	NO	NO
feed_url	string	NO	NO
generator	string	NO	NO
website	string	NO	NO
build_date	string	NO	NO
sync_date	string	NO	NO
public_url	string	NO	NO
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
catalog	string	NO	NO
podcast_episode	array<PodcastEpisodeObject>	NO	NO	see PodcastEpisodeObject fields

throws

<root><error></root>

Example

podcast_delete

Delete an existing podcast.

ACCESS REQUIRED: 75 (Catalog Manager)

Input	Type	Description	Optional
'filter'	string	UID of podcast to delete	NO

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

podcast_edit

Update the description and/or expiration date for an existing podcast. Takes the podcast id to update with optional description and expires parameters.

ACCESS REQUIRED: 50 (Content Manager)

Input	Type	Description	Optional
'filter'	string	Alpha-numeric search term	NO
'feed'	string	feed rss xml url	YES
'title'	string	title string	YES
'website'	string	source website url	YES
'description'	string		YES
'generator'	string		YES
'copyright'	string		YES

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

podcast_episodes

This returns the episodes for a podcast

Input	Type	Description	Optional
'filter'	string	UID of podcast	NO
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a podcast_episode list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
podcast_episode	array<PodcastEpisodeObject>	NO	NO	see PodcastEpisodeObject fields

Each podcast_episode entry (PodcastEpisodeObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
title	string	YES	NO
name	string	YES	NO
podcast	object	NO	NO	`{id, name}`
description	string	NO	NO
category	string	YES	NO
author	string	YES	NO
author_full	string	YES	NO
website	string	NO	NO
pubdate	string	YES	NO
state	string	NO	NO
filelength	string	NO	NO
filesize	string	NO	NO
filename	string	NO	NO
mime	string	YES	NO
time	integer	NO	NO
size	integer	NO	NO
bitrate	integer	NO	NO
stream_bitrate	integer	NO	NO
rate	integer	NO	NO
mode	string	YES	NO
channels	integer	YES	NO
public_url	string	NO	NO
url	string	NO	NO
catalog	string	NO	NO
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
playcount	integer	NO	NO
last_played	string	YES	NO
played	string	NO	NO

throws

<root><error></root>

Example

podcast_episode

Get the podcast_episode from it's id.

Input	Type	Description	Optional
'filter'	string	podcast_episode ID number	NO

return

Returns a single object.

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
title	string	YES	NO
name	string	YES	NO
podcast	object	NO	NO	`{id, name}`
description	string	NO	NO
category	string	YES	NO
author	string	YES	NO
author_full	string	YES	NO
website	string	NO	NO
pubdate	string	YES	NO
state	string	NO	NO
filelength	string	NO	NO
filesize	string	NO	NO
filename	string	NO	NO
mime	string	YES	NO
time	integer	NO	NO
size	integer	NO	NO
bitrate	integer	NO	NO
stream_bitrate	integer	NO	NO
rate	integer	NO	NO
mode	string	YES	NO
channels	integer	YES	NO
public_url	string	NO	NO
url	string	NO	NO
catalog	string	NO	NO
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
playcount	integer	NO	NO
last_played	string	YES	NO
played	string	NO	NO

throws

<root><error></root>

Example

podcast_episode_delete

Delete an existing podcast_episode.

Input	Type	Description	Optional
'filter'	string	UID of podcast_episode to delete	NO

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

preference_create

Add a new preference to your server

ACCESS REQUIRED: 100 (Admin)

Input	Type	Description	Optional
'filter'	string	Preference name e.g ('notify_email', 'popular_threshold')	NO
'type'	string	`boolean`, `integer`, `string`, `special`	NO
'default'	mixed	string or integer default value	NO
'category'	string	`interface`, `internal`, `options`, `playlist`, `plugins`, `streaming`	NO
'description'	string		YES
'subcategory'	string		YES
'level'	integer	access level required to change the value (default 100)	YES

return

<root>
    <preference>
</root>

throws

<root><error></root>

Example

preference_delete

Delete a non-system preference by name

ACCESS REQUIRED: 100 (Admin)

Input	Type	Description	Optional
'filter'	string	Preference name e.g ('notify_email', 'popular_threshold')	NO

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

preference_edit

Edit a preference value and apply to all users if allowed

Input	Type	Description	Optional
'filter'	string	Preference name e.g ('notify_email', 'popular_threshold')	NO
'value'	mixed	(string/integer) Preference value	NO
'all'	boolean	`0`, `1` apply to all users ACCESS REQUIRED: 100 (Admin)	YES
'default'	boolean	`0`, `1` set as system default (New and public users) ACCESS REQUIRED: 100 (Admin)	YES

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

rate

This rates a library item

NOTE filter is available in Ampache 7.9.0 and higher. id is deprecated and will be removed in API9.

Input	Type	Description	Optional
'filter'	string	library item id	NO
'type'	string	`song`, `album`, `artist`, `playlist`, `podcast`	NO
		`podcast_episode`, `video`, `tvshow`, `tvshow_season`
'rating'	integer	rating between 0-5	NO

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

record_play

Take a song_id and update the object_count and user_activity table with a play. This allows other sources to record play history to Ampache.

If you don't supply a user id (optional) then just fall back to you.

ACCESS REQUIRED: 100 (Admin) permission to change another user's play history

NOTE filter is available in Ampache 7.9.0 and higher. id is deprecated and will be removed in API9.

Input	Type	Description	Optional
'filter'	string	$object_id	NO
'user'	string	$user_id	YES
'client'	string	$agent	YES
'date'	integer	UNIXTIME()	YES

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

scrobble

Search for a song using text info and then record a play if found. This allows other sources to record play history to ampache

Input	Type	Description	Optional
'song'	string	HTML encoded string	NO
'artist'	string	HTML encoded string	NO
'album'	string	HTML encoded string	NO
'songmbid'	string	`song_mbid` also supported	YES
'artistmbid'	string	`artist_mbid` also supported	YES
'albummbid'	string	`album_mbid` also supported	YES
'date'	integer	UNIXTIME()	YES
'client'	string	$agent	YES

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

search

Perform an advanced search given passed rules. This works in a similar way to the web/UI search pages. Ampache 6.3.0+

This is the current name for the advanced_search method; parameters and results are identical.

Refer to the Advanced Search page for details about creating searches.

Input	Type	Description	Optional
operator	string	and, or (whether to match one rule or all)	NO
rule_*	array	[`rule_1`, `rule_1_operator`, `rule_1_input`]	NO
rule_*	array	[`rule_2`, `rule_2_operator`, `rule_2_input`], [etc]	YES
type	string	`song`, `album`, `artist`, `label`, `playlist`	NO
		`podcast`, `podcast_episode`, `genre`, `user`, `video`
random	boolean	`0`, `1` (random order of results; default to 0)	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES

return

Returns a video list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
video	array<VideoObject>	NO	NO	see VideoObject fields

Each video entry (VideoObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
title	string	YES	NO
mime	string	YES	NO
resolution	string	YES	NO
size	integer	NO	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
time	integer	NO	NO
url	string	NO	NO
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
playcount	integer	NO	NO
last_played	string	YES	NO
catalog	string	NO	NO

throws

<root><error></root>

SONG Example

ARTIST Example

ALBUM Example

search_group

Perform a group search given passed rules. This function will return multiple object types if the rule names match the object type. You can pass multiple rules as well as joins to create in depth search results.

Limit and offset are applied per object type. Meaning with a limit of 10 you will return 10 objects of each type not 10 results total.

Rules must be sent in groups of 3 using an int (starting from 1) to designate which rules are combined. Use operator ('and', 'or') to choose whether to join or separate each rule when searching.

Refer to the Advanced Search page for details about creating searches.

NOTE the rules part can be confusing but essentially you can include as many 'arrays' of rules as you want. Just add 1 to the rule value to create a new group of rules.

Mandatory Rule Values
- rule_1
- rule_1_operator
- rule_1_input
Optional (Metadata searches only)
- rule_1_subtype

NOTE the type parameter is different from the regular advanced_search method. Each type is a grouping of object types so allow single search calls to be made

all
- song
- album
- song_artist
- album_artist
- artist
- label
- playlist
- podcast
- podcast_episode
- genre
- user
music
- song
- album
- artist
song_artist
- song
- album
- song_artist
album_artist
- song
- album
- album_artist
podcast
- podcast
- podcast_episode
video
- video

Input	Type	Description	Optional
operator	string	and, or (whether to match one rule or all)	NO
rule_*	array	[`rule_1`, `rule_1_operator`, `rule_1_input`]	NO
rule_*	array	[`rule_2`, `rule_2_operator`, `rule_2_input`], [etc]	YES
type	string	`all`, `music`, `song_artist`, `album_artist`, `podcast`, `video` (`all` by default)	YES
random	boolean	`0`, `1` (random order of results; default to 0)	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES

return

search is keyed by object type (album, artist, album_artist, song_artist, song, playlist, podcast, podcast_episode, genre, label, user, video); each value is that type's usual object list. Types with no matches are omitted.

Field	Type	Nullable	Optional	Notes
search	object<string, array<object>>	NO	NO

throws

<root><error></root>

ALL Example

MUSIC Example

PODCAST Example

search_rules

Print a list of valid search rules for your search type

Input	Type	Description	Optional
'filter'	string	'song', 'album', 'song_artist', 'album_artist',	NO
		'artist', 'label', 'playlist', 'podcast',
		'podcast_episode', 'genre', 'user', 'video'

return

Returns a rule list.

Field	Type	Nullable	Optional	Notes
rule	array<SearchRuleObject>	NO	NO	see SearchRuleObject fields

Each rule entry (SearchRuleObject):

Field	Type	Nullable	Optional
name	string	NO	NO
label	string	NO	NO
type	string	NO	NO
widget	array<string \| object<string, string>>	NO	NO
title	string	NO	NO

throws

<root><error></root>

Artist Example

Album Example

Song Example

search_songs

This searches the songs and returns... songs

NOTE filter has an alias rule_1_input to match other search methods

Input	Type	Description	Optional
'filter'	string	Filter results to match this string	NO
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES

return

<root>
    <total_count>
    <song>
</root>

throws

<root><error></root>

Example

This searches the shares and returns... shares

Input	Type	Description	Optional
'filter'	string	Filter results to match this string	YES
'exact'	boolean	`0`, `1` boolean to match the exact filter string	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a share list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
share	array<ShareObject>	NO	NO	see ShareObject fields

Each share entry (ShareObject):

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	NO	NO
owner	string	NO	NO
allow_stream	boolean	NO	NO
allow_download	boolean	NO	NO
creation_date	integer	NO	NO
lastvisit_date	integer	NO	NO
object_type	string	YES	NO
object_id	string	NO	NO
expire_days	integer	NO	NO
max_counter	integer	NO	NO
counter	integer	NO	NO
secret	string	YES	NO
public_url	string	YES	NO
description	string	YES	NO

throws

<root><error></root>

Example

Return shares by UID

Input	Type	Description	Optional
'filter'	string	UID of Share, returns song XML	NO

return

Returns a single object.

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	NO	NO
owner	string	NO	NO
allow_stream	boolean	NO	NO
allow_download	boolean	NO	NO
creation_date	integer	NO	NO
lastvisit_date	integer	NO	NO
object_type	string	YES	NO
object_id	string	NO	NO
expire_days	integer	NO	NO
max_counter	integer	NO	NO
counter	integer	NO	NO
secret	string	YES	NO
public_url	string	YES	NO
description	string	YES	NO

throws

<root><error></root>

Example

share_create

Create a public url that can be used by anyone to stream media. Takes the file id with optional description and expires parameters.

Input	Type	Description	Optional
'filter'	string	UID of object you are sharing	NO
'type'	string	object_type	NO
'description'	string	description (will be filled for you if empty)	YES
'expires'	integer	days to keep active	YES

return

Returns a single object.

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	NO	NO
owner	string	NO	NO
allow_stream	boolean	NO	NO
allow_download	boolean	NO	NO
creation_date	integer	NO	NO
lastvisit_date	integer	NO	NO
object_type	string	YES	NO
object_id	string	NO	NO
expire_days	integer	NO	NO
max_counter	integer	NO	NO
counter	integer	NO	NO
secret	string	YES	NO
public_url	string	YES	NO
description	string	YES	NO

throws

<root><error></root>

Example

share_delete

Delete an existing share.

Input	Type	Description	Optional
'filter'	string	UID of Share to delete	NO

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

share_edit

Update the description and/or expiration date for an existing share. Takes the share id to update with optional description and expires parameters.

Input	Type	Description	Optional
'filter'	string	Alpha-numeric search term	NO
'stream'	boolean	`0`, `1` Allow streaming	YES
'download'	boolean	`0`, `1` Allow Downloading	YES
'expires'	integer	number of whole days before expiry	YES
'description'	string	update description	YES

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

smartlists

This returns smartlists based on the specified filter

Input	Type	Description	Optional
'filter'	string	Filter results to match this string	YES
'exact'	boolean	`0`, `1` (if true filter is exact `=` rather than fuzzy `LIKE`)	YES
'add'	set_filter	ISO 8601 Date Format (2020-09-16) Find objects with an 'add' date newer than the specified date	YES
'update'	set_filter	ISO 8601 Date Format (2020-09-16) Find objects with an 'update' time newer than the specified date	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a playlist list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
playlist	array<PlaylistObject>	NO	NO	see PlaylistObject fields

Each playlist entry (PlaylistObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
name	string	YES	NO
owner	string	YES	NO
user	UserSummaryObject	NO	NO	see UserSummaryObject fields
items	array<object> \| integer	NO	NO
type	string	YES	NO
art	string	YES	NO
has_access	boolean	NO	NO
has_collaborate	boolean	NO	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
md5	string	YES	NO
last_update	integer	YES	NO
time	integer	NO	NO
playlist_folder_id	string	NO	YES
playlist_folder_sort_order	integer	NO	YES

throws

<root><error></root>

Example

smartlist

This returns a single smartlist

Input	Type	Description	Optional
'filter'	string	UID of smartlist, returns smartlist XML	NO

return

Returns a single object.

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
name	string	YES	NO
owner	string	YES	NO
user	UserSummaryObject	NO	NO	see UserSummaryObject fields
items	array<object> \| integer	NO	NO
type	string	YES	NO
art	string	YES	NO
has_access	boolean	NO	NO
has_collaborate	boolean	NO	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
md5	string	YES	NO
last_update	integer	YES	NO
time	integer	NO	NO
playlist_folder_id	string	NO	YES
playlist_folder_sort_order	integer	NO	YES

throws

<root><error></root>

Example

smartlist_songs

This returns the songs for a smartlist

Input	Type	Description	Optional
'filter'	string	UID of smartlist, returns song XML	NO
'random'	integer	`0`, `1` (if true get random songs using limit)	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES

return

Returns a song list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
song	array<SongObject>	NO	NO	see SongObject fields

Each song entry (SongObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
title	string	YES	NO
name	string	YES	NO
artist	NamedReference	NO	NO	see NamedReference fields
artists	array<NamedReference>	NO	NO	see NamedReference fields
album	NamedReference	NO	NO	see NamedReference fields
albumartist	NamedReference	NO	YES	see NamedReference fields
disk	integer	NO	NO
disksubtitle	string	YES	NO
bpm	number	YES	NO
track	integer	NO	NO
filename	string	YES	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
mood	array<object>	NO	NO	`{id, name}`
playlisttrack	integer	NO	NO
time	integer	NO	NO
year	integer	NO	NO
format	string	YES	NO
stream_format	string	YES	NO
bitrate	integer	YES	NO
stream_bitrate	integer	YES	NO
rate	integer	NO	NO
mode	string	YES	NO
mime	string	YES	NO
stream_mime	string	YES	NO
url	string	NO	NO
size	integer	NO	NO
mbid	string	YES	NO
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
playcount	integer	NO	NO
last_played	string	YES	NO
catalog	string	NO	NO
composer	string	YES	NO
channels	integer	YES	NO
comment	string	YES	NO
license	string	YES	NO
publisher	string	YES	NO
language	string	YES	NO
lyrics	string	YES	NO
replaygain_album_gain	number	YES	NO
replaygain_album_peak	number	YES	NO
replaygain_track_gain	number	YES	NO
replaygain_track_peak	number	YES	NO
r128_album_gain	number	YES	NO
r128_track_gain	number	YES	NO
metadata	object<string, string>	NO	YES

throws

<root><error></root>

Example

smartlist_delete

This deletes a smartlist

Input	Type	Description	Optional
'filter'	string	UID of smartlist	NO

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

songs

Returns songs based on the specified filter

Input	Type	Description	Optional
'filter'	string	Filter results to match this string	YES
'exact'	boolean	`0`, `1` (if true filter is exact `=` rather than fuzzy `LIKE`)	YES
'add'	set_filter	ISO 8601 Date Format (2020-09-16) Find objects with an 'add' date newer than the specified date	YES
'update'	set_filter	ISO 8601 Date Format (2020-09-16) Find objects with an 'update' time newer than the specified date	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a song list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
song	array<SongObject>	NO	NO	see SongObject fields

Each song entry (SongObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
title	string	YES	NO
name	string	YES	NO
artist	NamedReference	NO	NO	see NamedReference fields
artists	array<NamedReference>	NO	NO	see NamedReference fields
album	NamedReference	NO	NO	see NamedReference fields
albumartist	NamedReference	NO	YES	see NamedReference fields
disk	integer	NO	NO
disksubtitle	string	YES	NO
bpm	number	YES	NO
track	integer	NO	NO
filename	string	YES	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
mood	array<object>	NO	NO	`{id, name}`
playlisttrack	integer	NO	NO
time	integer	NO	NO
year	integer	NO	NO
format	string	YES	NO
stream_format	string	YES	NO
bitrate	integer	YES	NO
stream_bitrate	integer	YES	NO
rate	integer	NO	NO
mode	string	YES	NO
mime	string	YES	NO
stream_mime	string	YES	NO
url	string	NO	NO
size	integer	NO	NO
mbid	string	YES	NO
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
playcount	integer	NO	NO
last_played	string	YES	NO
catalog	string	NO	NO
composer	string	YES	NO
channels	integer	YES	NO
comment	string	YES	NO
license	string	YES	NO
publisher	string	YES	NO
language	string	YES	NO
lyrics	string	YES	NO
replaygain_album_gain	number	YES	NO
replaygain_album_peak	number	YES	NO
replaygain_track_gain	number	YES	NO
replaygain_track_peak	number	YES	NO
r128_album_gain	number	YES	NO
r128_track_gain	number	YES	NO
metadata	object<string, string>	NO	YES

throws

<root><error></root>

Example

song

returns a single song

Input	Type	Description	Optional
'filter'	string	UID of Song, returns song XML	NO

return

Returns a single object.

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
title	string	YES	NO
name	string	YES	NO
artist	NamedReference	NO	NO	see NamedReference fields
artists	array<NamedReference>	NO	NO	see NamedReference fields
album	NamedReference	NO	NO	see NamedReference fields
albumartist	NamedReference	NO	YES	see NamedReference fields
disk	integer	NO	NO
disksubtitle	string	YES	NO
bpm	number	YES	NO
track	integer	NO	NO
filename	string	YES	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
mood	array<object>	NO	NO	`{id, name}`
playlisttrack	integer	NO	NO
time	integer	NO	NO
year	integer	NO	NO
format	string	YES	NO
stream_format	string	YES	NO
bitrate	integer	YES	NO
stream_bitrate	integer	YES	NO
rate	integer	NO	NO
mode	string	YES	NO
mime	string	YES	NO
stream_mime	string	YES	NO
url	string	NO	NO
size	integer	NO	NO
mbid	string	YES	NO
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
playcount	integer	NO	NO
last_played	string	YES	NO
catalog	string	NO	NO
composer	string	YES	NO
channels	integer	YES	NO
comment	string	YES	NO
license	string	YES	NO
publisher	string	YES	NO
language	string	YES	NO
lyrics	string	YES	NO
replaygain_album_gain	number	YES	NO
replaygain_album_peak	number	YES	NO
replaygain_track_gain	number	YES	NO
replaygain_track_peak	number	YES	NO
r128_album_gain	number	YES	NO
r128_track_gain	number	YES	NO
metadata	object<string, string>	NO	YES

throws

<root><error></root>

Example

song_delete

Delete an existing song. (if you are allowed to)

Input	Type	Description	Optional
'filter'	string	UID of song to delete	NO

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

song_tags

Get the full song file tags using VaInfo

This is used to get tags for remote catalogs to allow maximum data to be returned

Input	Type	Description	Optional
'filter'	string	UID of song to fetch	NO

return

Returns a single object.

Field	Type	Nullable	Optional
id	string	NO	NO
albumartist	string	YES	NO
album	string	YES	NO
artist	string	YES	NO
artists	array<string>	YES	NO
art	string	YES	NO
audio_codec	string	YES	NO
barcode	string	YES	NO
bitrate	integer	YES	NO
bpm	number	YES	NO
catalog	integer	YES	NO
catalog_number	string	YES	NO
channels	integer	YES	NO
comment	string	YES	NO
composer	string	YES	NO
description	string	YES	NO
disk	integer	YES	NO
disksubtitle	string	YES	NO
display_x	integer	YES	NO
display_y	integer	YES	NO
encoding	string	YES	NO
file	string	YES	NO
frame_rate	number	YES	NO
genre	array<string>	YES	NO
isrc	string	YES	NO
language	string	YES	NO
lyrics	string	YES	NO
mb_albumartistid	string	YES	NO
mb_albumartistid_array	array<string>	YES	NO
mb_albumid_group	string	YES	NO
mb_albumid	string	YES	NO
mb_artistid	string	YES	NO
mb_artistid_array	array<string>	YES	NO
mb_trackid	string	YES	NO
mime	string	YES	NO
mode	string	YES	NO
original_name	string	YES	NO
original_year	string	YES	NO
publisher	string	YES	NO
r128_album_gain	integer	YES	NO
r128_track_gain	integer	YES	NO
rate	integer	YES	NO
rating	number	YES	NO
release_date	string	YES	NO
release_status	string	YES	NO
release_type	string	YES	NO
replaygain_album_gain	number	YES	NO
replaygain_album_peak	number	YES	NO
replaygain_track_gain	number	YES	NO
replaygain_track_peak	number	YES	NO
size	integer	YES	NO
version	string	YES	NO
summary	string	YES	NO
time	integer	YES	NO
title	string	YES	NO
totaldisks	integer	YES	NO
totaltracks	integer	YES	NO
track	integer	YES	NO
year	integer	YES	NO

throws

<root><error></root>

Example

sonic_match

Songs that sound like the given song, most similar first.

Similarity is derived from analysing the audio, which Ampache does not do itself, so this needs a sonic analysis plugin (e.g. AudioMuse) enabled for the user. With no plugin to ask, the method reports the feature as unavailable rather than returning an empty list.

Each entry carries the full song plus similarity, a 0.0-1.0 score where 1.0 is the same recording. A backend that gives no comparable score reports -1.

Input	Type	Description	Optional
'filter'	string	UID of Song	NO
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES

return

Returns a sonic_match list.

Field	Type	Nullable	Optional	Notes
sonic_match	array<SonicMatchObject>	NO	NO	see SonicMatchObject fields

Each sonic_match entry (SonicMatchObject):

Field	Type	Nullable	Optional	Notes

throws

<root><error></root>

stats

Get some items based on some simple search types and filters. (Random by default) This method HAD partial backwards compatibility with older api versions but it has now been removed Pass -1 limit to get all results. (0 will fall back to the popular_threshold value)

Input	Type	Description	Optional
'type'	string	`song`, `album`, `artist`, `video`, `playlist`, `podcast`, `podcast_episode`	NO
'filter'	string	`newest`, `highest`, `frequent`, `recent`, `forgotten`, `flagged`, `random`	YES
'user_id'	integer		YES
'username'	string		YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results (Use `popular_threshold` when missing; default 10)	YES

return

Returns a video list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
video	array<VideoObject>	NO	NO	see VideoObject fields

Each video entry (VideoObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
title	string	YES	NO
mime	string	YES	NO
resolution	string	YES	NO
size	integer	NO	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
time	integer	NO	NO
url	string	NO	NO
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
playcount	integer	NO	NO
last_played	string	YES	NO
catalog	string	NO	NO

throws

<root><error></root>

SONG Example

ARTIST Example

ALBUM Example

system_preference

Get your server preference by name

ACCESS REQUIRED: 100 (Admin)

Input	Type	Description	Optional
'filter'	string	Preference name e.g ('notify_email', 'popular_threshold')	NO

return

Returns a single object.

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	NO	NO
value	string	NO	NO
description	string	NO	NO
level	integer	NO	NO
type	string	NO	NO
category	string	NO	NO
subcategory	string	YES	NO
has_access	boolean	NO	YES
values	array<string> \| array<integer>	NO	YES

throws

<root><error></root>

Example

timeline

This gets a user's timeline

NOTE filter is available in Ampache 7.9.0 and higher. username is deprecated and will be removed in API9.

Input	Type	Description	Optional
'filter'	string	Username of the user for whom to get the timeline	NO
'limit'	integer	Maximum number of results to return	YES
'since'	integer	UNIXTIME()	YES

return

Returns a activity list.

Field	Type	Nullable	Optional	Notes
activity	array<ActivityObject>	NO	NO	see ActivityObject fields

Each activity entry (ActivityObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
date	integer	NO	NO
object_type	string	YES	NO
object_id	string	NO	NO
action	string	NO	NO
user	UserSummaryObject	NO	NO	see UserSummaryObject fields

throws

<root><error></root>

Example

toggle_follow

This follow/unfollow a user

NOTE filter is available in Ampache 7.9.0 and higher. username is deprecated and will be removed in API9.

Input	Type	Description	Optional
'filter'	string	Username of the user to follow/unfollow	NO

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

update_art

Updates a single album, artist, song running the gather_art process Existing art is replaced unless you send overwrite=0, which keeps whatever is already there.

ACCESS REQUIRED: 75 (Catalog Manager)

NOTE filter is available in Ampache 7.9.0 and higher. id is deprecated and will be removed in API9.

Input	Type	Description	Optional
'filter'	string	$object_id	NO
'type'	string	`song`, `podcast`	NO
'overwrite'	boolean	`0`, `1`	YES

return

<root>
    <success>
    <art>
</root>

throws

<root><error></root>

Example

update_artist_info

Update artist information and fetch similar artists from last.fm Make sure lastfm_API_key is set in your configuration file

ACCESS REQUIRED: 75 (Catalog Manager)

NOTE filter is available in Ampache 7.9.0 and higher. id is deprecated and will be removed in API9.

Input	Type	Description	Optional
'filter'	string	$artist_id	NO

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

update_from_tags

Update a single album, artist, song from the tag data

NOTE filter is available in Ampache 7.9.0 and higher. id is deprecated and will be removed in API9.

Input	Type	Description	Optional
'type'	string	`song`, `artist`, `album`	NO
'filter'	string	$artist_id, $album_id, $song_id	NO

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

update_podcast

Sync and download new podcast episodes

ACCESS REQUIRED: 50 (Content Manager)

NOTE There was an error in documentation listing id as a valid parameter. (id will work in Ampache 7.9.0 / API 6.9.1+)

Input	Type	Description	Optional
'filter'	string	$object_id	NO
'id'	string	Alias of `filter` (Ampache 7.9.0+)	YES

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

upload

Add a media file to the catalog named by the upload_catalog preference.

Send the file either as a multipart form field named upl, or as the raw request body, in which case filename names it.

ACCESS REQUIRED: the allow_upload preference, at the access level set by upload_access_level

NOTE send a real Content-Type (e.g. audio/mpeg) with a raw body. A form-encoded content type makes PHP parse the file as request variables, which can emit a max_input_vars warning ahead of the response.

NOTE an artist or album owned by another user is refused, and a file that fails to be added is removed from the catalog directory again. A name already present in the catalog is refused rather than renamed, only the file name is used (any path in it is ignored), and a request body larger than PHP's upload_max_filesize/post_max_size is rejected.

Input	Type	Description	Optional
'filename'	string	File name, required when the file is the request body	YES
'license'	integer	$license_id, required when `licensing` is enabled	YES
'artist_id'	integer	$artist_id	YES
'artist_name'	string	Create or reuse an artist you own	YES
'album_id'	integer	$album_id	YES
'album_name'	string	Create or reuse an album you own	YES

return

<root>
    <success>
</root>

throws

<root><error></root>

url_to_song

This takes a url and returns the song object in question

NOTE filter is available in Ampache 7.9.0 and higher. url is deprecated and will be removed in API9.

Input	Type	Description	Optional
'filter'	string	Full Ampache URL from server, translates back into a song XML	NO

return

Returns a song list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
song	array<SongObject>	NO	NO	see SongObject fields

Each song entry (SongObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
title	string	YES	NO
name	string	YES	NO
artist	NamedReference	NO	NO	see NamedReference fields
artists	array<NamedReference>	NO	NO	see NamedReference fields
album	NamedReference	NO	NO	see NamedReference fields
albumartist	NamedReference	NO	YES	see NamedReference fields
disk	integer	NO	NO
disksubtitle	string	YES	NO
bpm	number	YES	NO
track	integer	NO	NO
filename	string	YES	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
mood	array<object>	NO	NO	`{id, name}`
playlisttrack	integer	NO	NO
time	integer	NO	NO
year	integer	NO	NO
format	string	YES	NO
stream_format	string	YES	NO
bitrate	integer	YES	NO
stream_bitrate	integer	YES	NO
rate	integer	NO	NO
mode	string	YES	NO
mime	string	YES	NO
stream_mime	string	YES	NO
url	string	NO	NO
size	integer	NO	NO
mbid	string	YES	NO
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
playcount	integer	NO	NO
last_played	string	YES	NO
catalog	string	NO	NO
composer	string	YES	NO
channels	integer	YES	NO
comment	string	YES	NO
license	string	YES	NO
publisher	string	YES	NO
language	string	YES	NO
lyrics	string	YES	NO
replaygain_album_gain	number	YES	NO
replaygain_album_peak	number	YES	NO
replaygain_track_gain	number	YES	NO
replaygain_track_peak	number	YES	NO
r128_album_gain	number	YES	NO
r128_track_gain	number	YES	NO
metadata	object<string, string>	NO	YES

throws

<root><error></root>

Example

user

This gets a user's public information.

If the username is omitted, this will return the current api user's public information.

Input	Type	Description	Optional
'username'	string	Username of the user to get details for	YES

return

Returns a single object.

Field	Type	Nullable	Optional
id	string	NO	NO
username	string	YES	NO
create_date	integer	YES	NO
last_seen	integer	NO	NO
link	string	NO	NO
website	string	YES	NO
state	string	YES	NO
city	string	YES	NO
art	string	YES	NO
has_art	boolean	NO	NO
auth	string	YES	YES
email	string	YES	YES
access	integer	NO	YES
streamtoken	string	YES	YES
fullname_public	boolean	NO	YES
validation	string	YES	YES
disabled	boolean	NO	YES
fullname	string	YES	YES

throws

<root><error></root>

Example

user_create

Create a new user. (Requires the username, password and email.)

ACCESS REQUIRED: 100 (Admin)

Input	Type	Description	Optional
'username'	string	$username	NO
'password'	string	hash('sha256', $password)	NO
'email'	string	e.g. `[email protected]`	NO
'fullname'	string		YES
'disable'	boolean	`0`, `1`	YES
'group'	integer	Catalog filter group, default = 0	YES

NOTE For privacy, send password in a form or JSON request body rather than the query string. Query-string support for password is deprecated but still accepted for backward compatibility.

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

user_delete

Delete an existing user.

ACCESS REQUIRED: 100 (Admin)

NOTE filter is available in Ampache 7.9.0 and higher. username is deprecated and will be removed in API9.

Input	Type	Description	Optional
'filter'	string		NO

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

user_edit

Update an existing user.

ACCESS REQUIRED: 100 (Admin)

NOTE This function has been renamed from user_update to match other edit functions

NOTE filter is available in Ampache 7.9.0 and higher. username is deprecated and will be removed in API9.

Input	Type	Description	Optional
'filter'	string	$username	NO
'password'	string	hash('sha256', $password)	YES
'email'	string	e.g. `[email protected]`	YES
'fullname'	string		YES
'website'	string		YES
'state'	string		YES
'city'	string		YES
'disable'	boolean	`0`, `1`	YES
'group'	integer	Catalog filter group, default = 0	YES
'maxbitrate'	string	Transcode bitrate in bps, e.g. `320000`	YES
'fullname_public'	integer	`0`, `1` show fullname in public display	YES
'reset_apikey'	integer	`0`, `1` reset user Api Key	YES
'reset_streamtoken'	integer	`0`, `1` reset user Stream Token	YES
'clear_stats'	integer	`0`, `1` reset all stats for this user	YES

NOTE For privacy, send password in a form or JSON request body rather than the query string. Query-string support for password is deprecated but still accepted for backward compatibility.

return

<root>
    <success>
</root>

throws

<root><error></root>

Example

user_playlists

This returns playlists based on the specified filter for your user

NOTE This method does not include smartlists

Input	Type	Description	Optional
'filter'	string	Filter results to match this string	YES
'exact'	boolean	`0`, `1` (if true filter is exact `=` rather than fuzzy `LIKE`)	YES
'include'	string	`0`, `1` (include playlist items)	YES
'add'	set_filter	ISO 8601 Date Format (2020-09-16) Find objects with an 'add' date newer than the specified date	YES
'update'	set_filter	ISO 8601 Date Format (2020-09-16) Find objects with an 'update' time newer than the specified date	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a playlist list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
playlist	array<PlaylistObject>	NO	NO	see PlaylistObject fields

Each playlist entry (PlaylistObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
name	string	YES	NO
owner	string	YES	NO
user	UserSummaryObject	NO	NO	see UserSummaryObject fields
items	array<object> \| integer	NO	NO
type	string	YES	NO
art	string	YES	NO
has_access	boolean	NO	NO
has_collaborate	boolean	NO	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
md5	string	YES	NO
last_update	integer	YES	NO
time	integer	NO	NO
playlist_folder_id	string	NO	YES
playlist_folder_sort_order	integer	NO	YES

throws

<root><error></root>

Example

user_preference

Get your user preference by name

Input	Type	Description	Optional
'filter'	string	Preference name e.g ('notify_email', 'popular_threshold')	NO

return

Returns a single object.

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	NO	NO
value	string	NO	NO
description	string	NO	NO
level	integer	NO	NO
type	string	NO	NO
category	string	NO	NO
subcategory	string	YES	NO
has_access	boolean	NO	YES
values	array<string> \| array<integer>	NO	YES

throws

<root><error></root>

Example

user_smartlists

This returns smartlists based on the specified filter for your user

NOTE This method does not include playlists

Input	Type	Description	Optional
'filter'	string	Filter results to match this string	YES
'exact'	boolean	`0`, `1` (if true filter is exact `=` rather than fuzzy `LIKE`)	YES
'include'	string	`0`, `1` (include playlist items)	YES
'add'	set_filter	ISO 8601 Date Format (2020-09-16) Find objects with an 'add' date newer than the specified date	YES
'update'	set_filter	ISO 8601 Date Format (2020-09-16) Find objects with an 'update' time newer than the specified date	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES
'cond'	string	Apply additional filters to the browse using `;` separated comma string pairs	YES
		(e.g. 'filter1,value1;filter2,value2')
'sort'	string	Sort name or comma-separated key pair. (e.g. 'name,order')	YES
		Default order 'ASC' (e.g. 'name,ASC' == 'name')

return

Returns a playlist list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
playlist	array<PlaylistObject>	NO	NO	see PlaylistObject fields

Each playlist entry (PlaylistObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
name	string	YES	NO
owner	string	YES	NO
user	UserSummaryObject	NO	NO	see UserSummaryObject fields
items	array<object> \| integer	NO	NO
type	string	YES	NO
art	string	YES	NO
has_access	boolean	NO	NO
has_collaborate	boolean	NO	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
md5	string	YES	NO
last_update	integer	YES	NO
time	integer	NO	NO
playlist_folder_id	string	NO	YES
playlist_folder_sort_order	integer	NO	YES

throws

<root><error></root>

Example

videos

This returns video objects!

Input	Type	Description	Optional
'filter'	string	Filter results to match this string	YES
'exact'	boolean	`0`, `1` (if true filter is exact `=` rather than fuzzy `LIKE`)	YES
'offset'	integer	Return results starting from this index position	YES
'limit'	integer	Maximum number of results to return	YES

return

Returns a video list.

Field	Type	Nullable	Optional	Notes
total_count	integer	NO	NO
md5	string	NO	NO
video	array<VideoObject>	NO	NO	see VideoObject fields

Each video entry (VideoObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
title	string	YES	NO
mime	string	YES	NO
resolution	string	YES	NO
size	integer	NO	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
time	integer	NO	NO
url	string	NO	NO
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
playcount	integer	NO	NO
last_played	string	YES	NO
catalog	string	NO	NO

throws

<root><error></root>

Example

video

This returns a single video

Input	Type	Description	Optional
'filter'	string	UID of video, returns video XML	NO

return

Returns a single object.

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
title	string	YES	NO
mime	string	YES	NO
resolution	string	YES	NO
size	integer	NO	NO
genre	array<GenreReference>	NO	NO	see GenreReference fields
time	integer	NO	NO
url	string	NO	NO
art	string	YES	NO
has_art	boolean	NO	NO
flag	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
playcount	integer	NO	NO
last_played	string	YES	NO
catalog	string	NO	NO

throws

<root><error></root>

Example

Binary Data Methods

Binary data methods are used for returning raw data to the user such as a image or stream.

download

Downloads a given media file. set format=raw to download the full file

NOTE search and playlist will only download a random object from the list

NOTE filter is available in Ampache 7.9.0 and higher. id is deprecated and will be removed in API9.

Input	Type	Description	Optional
'filter'	string	$object_id	NO
'type'	string	`song`, `podcast_episode`, `search`, `playlist`	NO
'bitrate'	integer	max bitrate for transcoding in bytes (e.g 192000=192Kb)	YES
'format'	string	`mp3`, `ogg`, `raw`, etc (raw returns the original format)	YES
'stats'	boolean	`0`, `1`, if false disable stat recording when playing the object (default: 1)	YES

return file (HTTP 200 OK)
throws (HTTP 400 Bad Request)
throws (HTTP 404 Not Found)

get_art

Get an art image.

NOTE filter is available in Ampache 7.9.0 and higher. id is deprecated and will be removed in API9.

Input	Type	Description	Optional
'filter'	string	$object_id	NO
'type'	string	`song`, `artist`, `album`, `playlist`, `search`, `podcast`	NO
'size'	string	width x height ('640x480')	YES

return image (HTTP 200 OK)
throws (HTTP 400 Bad Request)
throws (HTTP 404 Not Found)

NOTE Art was called using thumb parameters which do not make size obvious.Here is a conversion table to convert any links you have created previously

Thumb	Width	Height
1	200	200
2	256	256
22	512	512
32	768	768
3	160	160
5	64	64
6	200	300
34	68	68
64	128	128
174	348	348
300	400	600
7	400	600
8	940	400
9	300	168
10	48	48
4	300	300
11	300	300
12	300	300
999	400	400

random

Picks a random object and redirects (302) to its stream url. Ampache 8.0.0+

Mirrors stream's transcode parameters. A container type resolves to a random song from within it, so filter names that container.

NOTE filter is read against the table named by type, and those id spaces overlap - album 7 and album_disk 7 are different objects. A client browsing disks (album_group off) holds album_disk ids and must send type=album_disk.

Input	Type	Description	Optional
'type'	string	`album`, `album_artist`, `album_disk`, `artist`, `catalog`, `favorite`, `genre`, `label`, `playlist`, `podcast_episode`, `rating`, `search`, `song`, `song_artist`, `video` (default: song)	YES
'filter'	string	$object_id of the container to pick from; a `smart_` prefixed id selects a smartlist. `favorite` reads it as `1`/omitted = flagged, `0` = not flagged; `rating` as `1`-`5` = that many stars or more, `0` = unrated, omitted = any rated song	YES
'bitrate'	integer	max bitrate for transcoding in bytes (e.g 192000=192Kb) song only	YES
'format'	string	`mp3`, `ogg`, `raw`, etc (raw returns the original format) song only	YES
'offset'	integer	time offset in seconds	YES
'stats'	boolean	`0`, `1`, if false disable stat recording when playing the object (default: 1)	YES

return file (HTTP 302 Found; redirects to the stream url)
throws (HTTP 400 Bad Request)
throws (HTTP 404 Not Found)

stream

Streams a given media file. Takes the file id in parameter with optional max bit rate, file format, time offset, size and estimate content length option.

NOTE search and playlist will only stream a random object from the list

NOTE filter is available in Ampache 7.9.0 and higher. id is deprecated and will be removed in API9.

NOTE length requests an estimated Content-Length. The estimate is duration x bitrate and was measured 13% short to 7% over depending on codec, so it is unreliable unless the transcode is cached; an over-declared body is truncated in transit.

Input	Type	Description	Optional
'filter'	string	$object_id	NO
'type'	string	`song`, `podcast_episode`, `search`, `playlist`	NO
'bitrate'	integer	max bitrate for transcoding in bytes (e.g 192000=192Kb)	YES
'format'	string	`mp3`, `ogg`, `raw`, etc (raw returns the original format)	YES
'offset'	integer	Return results starting from this index position	YES
'length'	boolean	`0`, `1` estimated Content-Length (unreliable unless cached)	YES
'stats'	boolean	`0`, `1`, if false disable stat recording when playing the object (default: 1)	YES

return file (HTTP 200 OK)
throws (HTTP 400 Bad Request)
throws (HTTP 404 Not Found)

Control Methods

localplay

This is for controlling localplay

NOTE filter is available in Ampache 7.9.0 and higher. oid is deprecated and will be removed in API9.

Input	Type	Description	Optional
'command'	string	`next`, `prev`, `stop`, `play`, `pause`, `add`, `volume_up`	NO
		`volume_down`, `volume_mute`, `delete_all`, `skip`, `status`
'filter'	string	$object_id	YES
'type'	string	`song`, `video`, `podcast_episode`, `channel`, `broadcast`, `democratic`, `live_stream`	YES
'clear'	boolean	`0`, `1` (Clear the current playlist before adding)	YES

return

The status command reports the player state instead of a boolean.

Field	Type	Nullable	Optional	Notes
localplay	object	NO	NO	`{command}`

throws

<root><error></root>

Example

Example (status)

localplay_songs

Get the list of songs in your localplay instance

This method takes no additional parameters.

return

Returns a localplay_songs list.

Field	Type	Nullable	Optional	Notes
localplay_songs	array<LocalplaySongObject>	NO	NO	see LocalplaySongObject fields

Each localplay_songs entry (LocalplaySongObject):

Field	Type	Nullable	Optional
id	integer	NO	NO
raw	string	NO	NO
vlid	integer	NO	YES
oid	integer	NO	YES
name	string	YES	YES
link	string	YES	YES
track	integer	NO	NO

throws

<root><error></root>

Example

democratic

This is for controlling democratic play (Songs only)

Method Descriptions
- vote: +1 vote for the oid
- devote: -1 vote for the oid
- playlist: Return an array of song items with an additional <vote>[VOTE COUNT]</vote> element
- play: Returns the URL for playing democratic play

Input	Type	Description	Optional
'oid'	string	UID of Song object	NO
'method'	string	`vote`, `devote`, `playlist`, `play`	NO

return

Depends on the method parameter: play returns the stream url, vote/devote return the applied method and its result, and playlist returns the current democratic song list.

DemocraticPlayResponse

Returned by method=play: the stream URL of the democratic playlist.

Field	Type	Nullable	Optional	Notes
url	string	NO	NO

DemocraticVoteResponse

Returned by method=vote and method=devote.

Field	Type	Nullable	Optional	Notes
method	string	NO	NO
result	boolean	NO	NO

DemocraticSongsResponse

Returns a song list.

Field	Type	Nullable	Optional	Notes
song	array<DemocraticSongObject>	NO	NO	see DemocraticSongObject fields

Each song entry (DemocraticSongObject):

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
title	string	YES	NO
artist	NamedReference	NO	NO	see NamedReference fields
album	NamedReference	NO	NO	see NamedReference fields
genre	array<GenreReference>	NO	NO	see GenreReference fields
track	integer	NO	NO
time	integer	NO	NO
format	string	YES	NO
bitrate	integer	YES	NO
mime	string	YES	NO
url	string	NO	NO
size	integer	NO	NO
art	string	YES	NO
has_art	boolean	NO	NO
rating	integer	YES	NO
averagerating	number	YES	NO
playcount	integer	NO	NO
vote	integer	NO	NO

throws

<root><error></root>

Example

Shared reference objects

Objects referenced by the field tables above (as see <name> fields) that no single method response documents on its own — the shared reference shapes and a few payloads carried inside another response.

CollectionItemObject

One member of a collection, at the position it was curated into. object_type names the type and the property of the same name carries that type's own object, e.g. {"track": 1, "track_id": 7, "object_type": "album", "album": {...}}. track_id is the id of the membership row rather than of the object, and is the only stable way to tell two members apart when the same object appears more than once.

Field	Type	Nullable	Optional
track	integer	NO	NO
track_id	integer	NO	NO
object_type	string	NO	NO

FolderBrowseItem

One child of the folder being browsed. parent is always the id of that folder, so an item lifted out of the list still knows where it came from; it is -1 when the folder being browsed is the virtual root.

Field	Type	Nullable	Optional
id	string	NO	NO
object_type	string	NO	NO
title	string	YES	NO
parent	string	NO	NO
path	string	YES	NO
time	integer	YES	NO
art	string	YES	NO
has_art	boolean	NO	NO
play_url	string	NO	NO
rating	integer	YES	NO
averagerating	integer	YES	NO

FolderBrowseNode

The folder that was browsed, and its children. parent is the id of the folder this one hangs off: a top level folder reports the virtual root (-1) rather than nothing, so a client can always walk up, and null means this is the virtual root itself.

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
title	string	YES	NO
parent	string	YES	NO
path	string	YES	NO
catalog	string	NO	NO
time	integer	NO	NO
items	array<FolderBrowseItem>	NO	NO	see FolderBrowseItem fields

GenreReference

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
name	string	NO	NO

IndexReferenceObject

Field	Type	Nullable	Optional	Notes
id	string	NO	NO
type	string	NO	NO

LocalplayStatusObject

Player state. The exact fields come from the configured Localplay controller (MPD, VLC, XBMC, UPnP, HTTPQ), so only repeat and random are guaranteed - the API coerces those two to booleans. The rest are what that controller reports.

Field	Type	Nullable	Optional
state	string	NO	YES
volume	string	NO	YES
repeat	boolean	NO	NO
random	boolean	NO	NO
track	integer	NO	YES
track_title	string	NO	YES
track_artist	string	NO	YES
track_album	string	NO	YES

NamedReference

Field	Type	Nullable	Optional
id	string	NO	NO
name	string	YES	NO
prefix	string	YES	NO
basename	string	YES	NO

PlaylistFolderItemObject

One list filed in a playlist folder. object_type is playlist, smartlist or collection and the property of the same name carries that type's own object, e.g. {"sort_order": 1, "object_type": "playlist", "playlist": {...}}. sort_order is client-assigned and shared with the sibling folders, so ties are broken by name.

Field	Type	Nullable	Optional	Notes
sort_order	integer	NO	NO
object_type	string	NO	NO

Thumb	Width	Height
1	200	200
2	256	256
22	512	512
32	768	768
3	160	160
5	64	64
6	200	300
34	68	68
64	128	128
174	348	348
300	400	600
7	400	600
8	940	400
9	300	168
10	48	48
4	300	300
11	300	300
12	300	300
999	400	400

Thumb	Width	Height
1	200	200
2	256	256
22	512	512
32	768	768
3	160	160
5	64	64
6	200	300
34	68	68
64	128	128
174	348	348
300	400	600
7	400	600
8	940	400
9	300	168
10	48	48
4	300	300
11	300	300
12	300	300
999	400	400

API XML Methods​

Auth Methods​

handshake​

quickconnect_initiate​

quickconnect_status​

goodbye​

lost_password​

ping​

register​

Non-Data Methods​

system_update​

system_preferences​

users​

user_preferences​

Data Methods​

advanced_search​

albums​

album​

album_songs​

album_disks​

album_disk​

album_disk_songs​

artists​

artist​

artist_albums​

artist_songs​

bookmarks​

bookmark​

bookmark_create​

bookmark_delete​

bookmark_edit​

browse​

catalogs​

catalog​

catalog_action​

catalog_add​

catalog_delete​

catalog_file​

catalog_folder​

collections​

collection​

collection_items​

collection_create​

collection_edit​

Reordering​

collection_delete​

collection_add​

collection_remove​

deleted_podcast_episodes​

deleted_songs​

deleted_videos​

flag​

folders​

followers​

following​

friends_timeline​

genres​

genre​

genre_albums​

genre_artists​

genre_songs​

get_bookmark​

get_external_metadata​

get_indexes​

get_lyrics​

get_similar​

index​

labels​

label​

label_artists​

last_shouts​

license​

license_songs​

licenses​

list​

live_streams​

live_stream​

live_stream_create​

live_stream_delete​

live_stream_edit​

API XML Methods

Auth Methods

handshake

quickconnect_initiate

quickconnect_status

goodbye

lost_password

ping

register

Non-Data Methods

system_update

system_preferences

users

user_preferences

Data Methods

advanced_search

albums

album

album_songs

album_disks

album_disk

album_disk_songs

artists

artist

artist_albums

artist_songs

bookmarks

bookmark

bookmark_create

bookmark_delete

bookmark_edit

browse

catalogs

catalog

catalog_action

catalog_add

catalog_delete

catalog_file

catalog_folder

collections

collection

collection_items

collection_create

collection_edit

Reordering

collection_delete

collection_add

collection_remove

deleted_podcast_episodes

deleted_songs

deleted_videos

flag

folders

followers

following

friends_timeline

genres

genre

genre_albums

genre_artists

genre_songs

get_bookmark

get_external_metadata

get_indexes

get_lyrics

get_similar

index

labels

label

label_artists

last_shouts

license

license_songs

licenses

list

live_streams

live_stream

live_stream_create

live_stream_delete

live_stream_edit

Thumb	Width	Height
1	200	200
2	256	256
22	512	512
32	768	768
3	160	160
5	64	64
6	200	300
34	68	68
64	128	128
174	348	348
300	400	600
7	400	600
8	940	400
9	300	168
10	48	48
4	300	300
11	300	300
12	300	300
999	400	400