JSON Methods

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

With the exception of Binary methods, all responses will return a HTTP 200 response.

Also remember that 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

return object

"auth": "",
"api": "",
"session_expire": "",
"update": "",
"add": "",
"clean": "",
"songs": 0,
"albums": 0,
"artists": 0,
"genres": 0,
"playlists": 0,
"users": 0,
"catalogs": 0,
"videos": 0,
"podcasts": 0,
"podcast_episodes": 0,
"shares": 0,
"licenses": 0,
"live_streams": 0,
"labels": 0

throws object

"error": ""

Example

goodbye

Destroy a session using the auth parameter.

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

return object

"success": ""

throws object

"error": ""

Example

lost_password

Email a new password to the user (if allowed) using a reset token.

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

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

return

"success": ""

throws object

"error": ""

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 object

"session_expire": "",
"server": "",
"version": "",
"compatible": "",
"auth": "",
"api": "",
"update": "",
"add": "",
"clean": "",
"songs": 0,
"albums": 0,
"artists": 0,
"genres": 0,
"playlists": 0,
"users": 0,
"catalogs": 0,
"videos": 0,
"podcasts": 0,
"podcast_episodes": 0,
"shares": 0,
"licenses": 0,
"live_streams": 0,
"labels": 0

throws array

"server": "",
"version": "",
"compatible": ""

Example

register

Input	Type	Description	Optional
'username'	string	$username	NO
'password'	string	hash('sha256', $password)	NO
'email'	string	e.g. `user@gmail.com`	NO
'fullname'	string		YES

return object

"success": ""

throws object

"error": ""

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 object

"success": ""

throws object

"error": ""

Example

system_preferences

Get your server preferences

ACCESS REQUIRED: 100 (Admin)

return array

"preference": []

throws object

"error": ""

Example

users

Get ids and usernames for your site

return array

"user": []

throws object

"error": ""

Example

user_preferences

Get your user preferences

return array

"preference": []

throws object

"error": ""

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 array

"song": []|"album": []|"artist": []|"playlist": []|"label": []|"user": []|"video": []

throws object

"error": ""

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 array

"album": []

throws object

"error": ""

Example

album

This returns a single album based on the UID provided

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

return object

"id": "",
"name": "",
"artist": {},
"time": 0,
"year": 0,
"tracks": [],
"songcount": 0,
"diskcount": 0,
"type": "",
"genre": [],
"art": "",
"flag": 0,
"preciserating": 0.0,
"rating": 0.0,
"averagerating": 0.0,
"mbid": ""

throws object

"error": ""

Example

album_songs

This returns the songs of a specified album

Input	Type	Description	Optional
'filter'	string	UID of Album, 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 array

"song": []

throws object

"error": ""

Example

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 array

"artist": []

throws object

"error": ""

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 JSON	NO
'include'	string	`albums`, `songs` (include child objects in the response)	YES

return object

"id": "",
"name": "",
"albums": [],
"albumcount": 0,
"songs": [],
"songcount": 0,
"genre": [],
"art": "",
"flag": 0,
"preciserating": 0,
"rating": 0,
"averagerating": 0,
"mbid": "",
"summary": "",
"time": 0,
"yearformed": 0,
"placeformed": ""

throws object

"error": ""

Example

artist_albums

This returns the albums of an artist

Input	Type	Description	Optional
'filter'	string	UID of Artist, returns Album JSON	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 array

"album": []

throws object

"error": ""

Example

artist_songs

This returns the songs of the specified artist

Input	Type	Description	Optional
'filter'	string	UID of Artist, returns Song JSON	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 array

"song": []

throws object

"error": ""

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 array

"bookmark": []

throws object

"error": ""

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

"id": "",
"owner": "",
"object_type": "",
"object_id": "",
"position": 0,
"client": "",
"creation_date": 0,
"update_date": 0

throws

"error": ""

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 array

"id": "",
"owner": "",
"object_type": "",
"object_id": "",
"position": 0,
"client": "",
"creation_date": 0,
"update_date": 0

throws object

"error": ""

Example

bookmark_delete

Delete an existing bookmark. (if it exists)

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

return object

"success": ""

throws object

"error": ""

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 array

"bookmark": []

throws object

"error": ""

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 Catalog ID is required on 'artist', 'album', 'podcast' so you can filter the browse correctly

Input	Type	Description	Optional
'filter'	string	object_id	YES
'type'	string	'root', 'catalog', 'artist', 'album', 'podcast'	YES
'filter'	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 array

"browse": []

throws object

"error": ""

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 array

"catalog": []

throws object

"error": ""

Example

catalog

Return catalog by UID

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

return object

"id": "",
"name": "",
"type": "",
"gather_types": "",
"enabled": 0,
"last_add": "",
"last_clean": "",
"last_update": "",
"path": "",
"rename_pattern": "",
"sort_pattern": ""

throws object

"error": ""

Example

catalog_action

Kick off a catalog update or clean for the selected catalog

ACCESS REQUIRED: 75 (Catalog Manager)

Input	Type	Description	Optional
'task'	string	`add_to_catalog`, `clean_catalog`	NO
'catalog'	integer	$catalog_id	NO

return object

"success": ""

throws object

"error": ""

Example: clean_catalog

Example: add_to_catalog

catalog_add

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

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

return array

"id": "",
"name": "",
"type": "",
"gather_types": "",
"enabled": 0,
"last_add": "",
"last_clean": "",
"last_update": "",
"path": "",
"rename_pattern": "",
"sort_pattern": ""

throws object

"error": ""

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 object

"success": ""

throws object

"error": ""

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)

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

return object

"success": ""

throws object

"error": ""

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)

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

return object

"success": ""

throws object

"error": ""

Example

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 array

"deleted_podcast_episode": []

throws object

"error": ""

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 array

"deleted_song": []

throws object

"error": ""

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 array

"deleted_video": []

throws object

"error": ""

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

Input	Type	Description	Optional
'type'	string	`song`, `album`, `artist`, `playlist`, `podcast`	NO
		`podcast_episode`, `video`, `tvshow`, `tvshow_season`
'id'	integer	$object_id	NO
'flag'	boolean	`0`, `1`	NO

return object

"success": ""

throws object

"error": ""

Example

followers

This gets the followers for the requested username

Input	Type	Description	Optional
'username'	string	Username of the user 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 array

"user": []

throws object

"error": ""

Example

following

Get a list of people that this user follows

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

return array

"user": []

throws object

"error": ""

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 array

"activity": []

throws object

"error": ""

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 array

"genre": []

throws object

"error": ""

Example

genre

This returns a single genre based on UID

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

return object

"id": "",
"name": "",
"albums": 0,
"artists": 0,
"songs": 0,
"videos": 0,
"playlists": 0,
"live_streams": 0

throws object

"error": ""

Example

genre_albums

This returns the albums associated with the genre in question

Input	Type	Description	Optional
'filter'	string	UID of genre, returns album JSON	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 array

"album": []

throws object

"error": ""

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 JSON	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 array

"artist": []

throws object

"error": ""

Example

genre_songs

returns the songs for this genre

Input	Type	Description	Optional
'filter'	string	UID of genre, returns song JSON	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 array

"song": []

throws object

"error": ""

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 in a bookmark array.

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

DEFAULT return object (all=False)

"id": "",
"owner": "",
"object_type": "",
"object_id": "",
"position": 0,
"client": "client",
"creation_date": 0,
"update_date": 0

return array (all=True)

"bookmark": []

throws object

"error": ""

Example Example (with include)

get_indexes

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

NOTE This method is depreciated and will be removed in API7 (Use list OR index)

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
'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 array

"song": []|"album": []|"artist": []|"playlist": []|"podcast": []

throws object

"error": ""

SONG Example

ARTIST Example

ALBUM Example

PLAYLIST 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'	integer	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 array

"song": []|"artist": []

throws object

"error": ""

Example

index

This takes a collection of inputs and return ID's for the object type. Add 'include' to include child objects

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 array

"catalog": []|"song": []|"album": []|"artist": []|"album_artist": []|"song_artist": []|"playlist": []|"podcast": []|"podcast_episode": []|"share": []|"video": []|"live_stream": []

throws object

"error": ""

SONG Example

ARTIST Example

ALBUM Example

PLAYLIST 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
'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 array

"label": []

throws object

"error": ""

Example

label

This returns a single label

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

return object

"id": "",
"name": "",
"artists": 0,
"summary": "",
"external_link": "'",
"address": "",
"category": "",
"email": "",
"website": "",
"user": 0

throws object

"error": ""

Example

label_artists

This returns the artists for a label

Input	Type	Description	Optional
'filter'	string	UID of label, returns artist 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 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 array

"artist": []

throws object

"error": ""

Example

last_shouts

This gets the latest posted shouts

Input	Type	Description	Optional
'username'	string	Get latest shouts for this username	YES
'limit'	integer	Maximum number of results to return	YES

return array

"shout": []

throws object

"error": ""

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
'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		YES
'limit'	integer		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 array

"license": []

throws object

"error": ""

Example

license

This returns a single license

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

return object

"id": "",
"name": "",
"description": "",
"external_link": ""

throws object

"error": ""

Example

license_songs

This returns the songs for a license

Input	Type	Description	Optional
'filter'	string	UID of license, 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 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 array

"song": []

throws object

"error": ""

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
'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 array

"list": []

throws object

"error": ""

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
'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 array

"live_stream": []

throws object

"error": ""

Example

live_stream

This returns a single live_stream

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

return object

"id": "",
"name": "",
"artists": 0,
"summary": "",
"external_link": "'",
"address": "",
"category": "",
"email": "",
"website": "",
"user": 0

throws object

"error": ""

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 array

"id": "",
"name": "",
"artists": 0,
"summary": "",
"external_link": "'",
"address": "",
"category": "",
"email": "",
"website": "",
"user": 0

throws object

"error": ""

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 object

"success": ""

throws object

"error": ""

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 array

"id": "",
"name": "",
"artists": 0,
"summary": "",
"external_link": "'",
"address": "",
"category": "",
"email": "",
"website": "",
"user": 0

throws object

"error": ""

Example

now_playing

Get what is currently being played by all users.

return array

"now_playing": []

throws object

"error": ""

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 array

"now_playing": []

throws object

"error": ""

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 array

"playlist": []

throws object

"error": ""

Example

playlist

This returns a single playlist

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

return array

"playlist": []

throws object

"error": ""

Example

playlist_add

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

Input	Type	Description	Optional
'filter'	string	UID of Playlist	NO
'id'	string	UID of the object to add to playlist	NO
'type'	string	'song', 'album', 'artist', 'playlist'	NO

return object

"success": ""

throws object

"error": ""

Example

playlist_add_song

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

NOTE This method is depreciated and will be removed in API7 (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 object

"success": ""

throws object

"error": ""

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 array

"playlist": []

throws object

"error": ""

Example

playlist_delete

This deletes a playlist

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

return object

"success": ""

throws object

"error": ""

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 object

"success": ""

throws object

"error": ""

Example

playlist_generate

Get a list of song JSON, 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

Input	Type	Description	Optional
'mode'	string	`recent`, `forgotten`, `unplayed`, `random` (default = 'random')	YES
'filter'	string	string LIKE matched to song title	YES
'album'	integer	$album_id	YES
'artist'	integer	$artist_id	YES
'flag'	boolean	`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 array

"song": []|"index": []|"id": []

throws object

"error": ""

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 object

"md5": ""

throws object

"error": ""

Example

playlist_remove_song

This remove a song from a playlist. Previous versions required 'track' instead of 'song'.

Input	Type	Description	Optional
'filter'	string	UID of Playlist	NO
'song'	string	UID of song to remove from playlist	YES
'track'	integer	Track number to remove from playlist	YES

return object

"success": ""

throws object

"error": ""

Example

playlist_songs

This returns the songs for a playlist

Input	Type	Description	Optional
'filter'	string	UID of Playlist, returns song JSON	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 array

"song": []

throws object

"error": ""

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 array

"podcast": []

throws object

"error": ""

Example

podcast

Get the podcast from it's id.

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

return object

"id": "",
"name": "",
"description": "",
"language": "",
"copyright": "",
"feed_url": "",
"generator": "",
"website": "",
"build_date": "",
"sync_date": "",
"public_url": "",
"podcast_episode": []

throws object

"error": ""

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 array

"podcast": []

throws object

"error": ""

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 object

"success": ""

throws object

"error": ""

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 object

"success": ""

throws object

"error": ""

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 array

"podcast_episode": []

throws object

"error": ""

Example

podcast_episode

Get the podcast_episode from it's id.

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

return array

"podcast_episode": []

throws object

"error": ""

Example

podcast_episode_delete

Delete an existing podcast_episode.

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

return object

"success": ""

throws object

"error": ""

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', 'ajax_load')	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 object

"success": ""

throws object

"error": ""

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', 'ajax_load')	NO

return object

"success": ""

throws object

"error": ""

Example

preference_edit

Edit a preference value and apply to all users if allowed

ACCESS REQUIRED: 100 (Admin)

Input	Type	Description	Optional
'filter'	string	Preference name e.g ('notify_email', 'ajax_load')	NO
'value'	mixed	(string/integer) Preference value	NO
'all'	boolean	`0`, `1` apply to all users	YES

return object

"success": ""

throws object

"error": ""

Example

rate

This rates a library item

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

return object

"success": ""

throws object

"error": ""

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

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

return object

"success": ""

throws object

"error": ""

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 object

"success": ""

throws object

"error": ""

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 array

"search": [
    "song: [],
    "album: [],
    "song_artist: [],
    "album_artist: [],
    "artist: [],
    "label: [],
    "playlist: [],
    "podcast: [],
    "podcast_episode: [],
    "genre: [],
    "user: []
]

throws object

"error": ""

ALL Example

MUSIC Example

PODCAST Example

search_songs

This searches the songs and returns... songs

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 array

"song": []

throws object

"error": ""

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 array

"share": []

throws object

"error": ""

Example

Return shares by UID

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

return object

"id": "",
"name": "",
"owner": "",
"allow_stream": 0,
"allow_download": 0,
"creation_date": "",
"lastvisit_date": "",
"object_type": "",
"object_id": "",
"expire_days": 0,
"max_counter": 0,
"counter": 0,
"secret": "",
"public_url": "",
"description": ""

throws object

"error": ""

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 array

"share": []

throws object

"error": ""

Example

share_delete

Delete an existing share.

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

return object

"success": ""

throws object

"error": ""

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`	YES
'download'	boolean	`0`, `1`	YES
'expires'	integer	number of days before expiry	YES
'description'	string	update description	YES

return object

"success": ""

throws object

"error": ""

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 array

"song": []

throws object

"error": ""

Example

song

returns a single song

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

return object

"id": "",
"title": "",
"name": "",
"artist": {},
"album": {},
"genre": [],
"albumartist": {},
"filename": "",
"track": 0,
"playlisttrack": 0,
"time": 0,
"year": 0,
"bitrate": 0,
"rate": 0,
"mode": "",
"mime": "",
"url": "",
"size": 0,
"mbid": "0",
"album_mbid": "",
"artist_mbid": "",
"albumartist_mbid": ",
"art": "",
"flag": 0,
"preciserating": 0.0,
"rating": 0.0,
"averagerating": 0.0,
"playcount": 0,
"catalog": 0,
"composer": "",
"channels": null,
"comment": "",
"publisher": "",
"language": "",
"replaygain_album_gain": 0.000000,
"replaygain_album_peak": 0.000000,
"replaygain_track_gain": 0.000000,
"replaygain_track_peak": 0.000000

throws object

"error": ""

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 object

"success": ""

throws object

"error": ""

Example

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

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 to return	YES

return array

"song": []|"album": []|"artist": []

throws object

"error": ""

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', 'ajax_load')	NO

return array

"preference": []

throws object

"error": ""

Example

timeline

This gets a user's timeline

Input	Type	Description	Optional
'username'	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 array

"activity": []

throws object

"error": ""

Example

toggle_follow

This follow/unfollow a user

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

return object

"success": ""

throws object

"error": ""

Example

update_art

Updates a single album, artist, song running the gather_art process Doesn't overwrite existing art by default.

ACCESS REQUIRED: 75 (Catalog Manager)

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

return object

"success": ""

throws object

"error": ""

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)

Input	Type	Description	Optional
'id'	integer	$artist_id	NO

return object

"success": ""

throws object

"error": ""

Example

update_from_tags

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

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

return object

"success": ""

throws object

"error": ""

Example

update_podcast

Sync and download new podcast episodes

ACCESS REQUIRED: 50 (Content Manager)

Input	Type	Description	Optional
'id'	integer	$object_id	NO

return object

"success": ""

throws object

"error": ""

Example

url_to_song

This takes a url and returns the song object in question

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

return object

"id": "",
"title": "",
"name": "",
"artist": {},
"album": {},
"genre": [],
"albumartist": {},
"filename": "",
"track": 0,
"playlisttrack": 0,
"time": 0,
"year": 0,
"bitrate": 0,
"rate": 0,
"mode": "",
"mime": "",
"url": "",
"size": 0,
"mbid": "",
"album_mbid": "",
"artist_mbid": "",
"albumartist_mbid": "",
"art": "",
"flag": 0,
"preciserating": 0.0,
"rating": 0.0,
"averagerating": 0.0,
"playcount": 0,
"catalog": 0,
"composer": "",
"channels": null,
"comment": "",
"publisher": "",
"language": "",
"replaygain_album_gain": 0.000000,
"replaygain_album_peak": 0.000000,
"replaygain_track_gain": 0.000000,
"replaygain_track_peak": 0.000000

throws object

"error": ""

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 array

"user": []

throws object

"error": ""

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. `user@gmail.com`	NO
'fullname'	string		YES
'disable'	boolean	`0`, `1`	YES
'group'	integer	Catalog filter group, default = 0	YES

return object

"success": ""

throws object

"error": ""

Example

user_delete

Delete an existing user.

ACCESS REQUIRED: 100 (Admin)

Input	Type	Description	Optional
'username'	string		NO

return object

"success": ""

throws object

"error": ""

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

Input	Type	Description	Optional
'username'	string	$username	NO
'password'	string	hash('sha256', $password)	YES
'email'	string	e.g. `user@gmail.com`	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		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

return object

"success": ""

throws object

"error": ""

Example

user_playlists

This returns playlists 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 array

"playlist": []

throws object

"error": ""

Example

user_preference

Get your user preference by name

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

return array

"preference": []

throws object

"error": ""

Example

user_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 array

"playlist": []

throws object

"error": ""

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 array

"video": []

throws object

"error": ""

Example

video

This returns a single video

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

return object

"id": "",
"title": "",
"mime": "",
"resolution": "",
"size": 0,
"genre": [],
"url": ""

throws object

"error": ""

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

Input	Type	Description	Optional
'id'	integer	$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.

Input	Type	Description	Optional
'id'	integer	$object_id	NO
'type'	string	`song`, `artist`, `album`, `playlist`, `search`, `podcast`	NO

return image (HTTP 200 OK)
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

Input	Type	Description	Optional
'id'	integer	$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`	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

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'	integer	UID of Song object	NO
'method'	string	`vote`, `devote`, `playlist`, `play`	NO

return object|array

"url": ""|"method": "","result": false|"song": []

throws object

"error": ""

Example

localplay

This is for controlling localplay

Input	Type	Description	Optional
'command'	string	`next`, `prev`, `stop`, `play`, `pause`, `add`, `volume_up`	NO
		`volume_down`, `volume_mute`, `delete_all`, `skip`, `status`
'oid'	integer	$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 object

"localplay": { "command": {} }

throws object

"error": ""

Example

Example (status)

Auth Methods​

handshake​

goodbye​

lost_password​

ping​

register​

Non-Data Methods​

system_update​

system_preferences​

users​

user_preferences​

Data Methods​

advanced_search​

albums​

album​

album_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​

deleted_podcast_episodes​

deleted_songs​

deleted_videos​

flag​

followers​

following​

friends_timeline​

genres​

genre​

genre_albums​

genre_artists​

genre_songs​

get_bookmark​

get_indexes​

get_similar​

index​

labels​

label​

label_artists​

last_shouts​

licenses​

license​

license_songs​

list​

live_streams​

live_stream​

live_stream_create​

live_stream_delete​

live_stream_edit​

now_playing​

player​

playlists​

playlist​

playlist_add​

playlist_add_song​

playlist_create​

playlist_delete​

playlist_edit​

playlist_generate​

playlist_hash​

playlist_remove_song​

playlist_songs​

podcasts​

podcast​

podcast_create​

podcast_delete​

podcast_edit​

Auth Methods

handshake

goodbye

lost_password

ping

register

Non-Data Methods

system_update

system_preferences

users

user_preferences

Data Methods

advanced_search

albums

album

album_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

deleted_podcast_episodes

deleted_songs

deleted_videos

flag

followers

following

friends_timeline

genres

genre

genre_albums

genre_artists

genre_songs

get_bookmark

get_indexes

get_similar

index

labels

label

label_artists

last_shouts

licenses

license

license_songs

list

live_streams

live_stream

live_stream_create

live_stream_delete

live_stream_edit

now_playing

player

playlists

playlist

playlist_add

playlist_add_song

playlist_create

playlist_delete

playlist_edit

playlist_generate

playlist_hash

playlist_remove_song

playlist_songs

podcasts

podcast

podcast_create

podcast_delete

podcast_edit