Skip to main content

API5.0 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

Auth Methods

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

handshake

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

InputTypeDescriptionOptional
'auth'string$passphrase (Timestamp . Password SHA hash) OR (API Key)NO
'user'string$username (Required if login/password authentication)YES
'timestamp'integerUNIXTIME() The timestamp used in seed of password hash (Required if login/password authentication)YES
'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

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

InputTypeDescriptionOptional
'auth'string(Session ID) returns version information and extends the session if passedYES
'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

goodbye

Destroy a session using the auth parameter.

InputTypeDescriptionOptional
'auth'string(Session ID) destroys the session if it existsNO
  • return object
"success": ""
  • throws object
"error": ""

Example

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

bookmarks

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

  • return array
"bookmark": []
  • throws object
"error": ""

Example

Data Methods

Data methods require additional information and parameters to return information

get_indexes

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

InputTypeDescriptionOptional
'type'stringsong, album, artist, album_artist, playlist, podcast, podcast_episode, live_streamNO
'filter'stringValue is Alpha Match for returned results, may be more than one letter/numberYES
'add'set_filterISO 8601 Date Format (2020-09-16) Find objects with an 'add' date newer than the specified dateYES
'update'set_filterISO 8601 Date Format (2020-09-16) Find objects with an 'update' time newer than the specified dateYES
'include'boolean0, 1 (include songs in a playlist or episodes in a podcast)YES
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
'hide_search'integer0, 1 (if true do not include searches/smartlists in the result)YES
  • return array
"song": []|"album": []|"artist": []|"playlist": []|"podcast": []

  • throws object
"error": ""

SONGS Example

ARTIST Example

ALBUM Example

PLAYLIST Example

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
InputTypeDescriptionOptional
operatorstringand, 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
typestringsong, album, artist, playlist, label, user, videoNO
randomboolean0, 1 (random order of results; default to 0)YES
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
  • return array
"song": []|"album": []|"artist": []|"playlist": []|"label": []|"user": []|"video": []
  • throws object
"error": ""

SONG Example

ARTIST Example

ALBUM Example

artists

This takes a collection of inputs and returns artist objects.

InputTypeDescriptionOptional
'filter'stringFilter results to match this stringYES
'exact'boolean0, 1 (if true filter is exact = rather than fuzzy LIKE)YES
'add'set_filterISO 8601 Date Format (2020-09-16) Find objects with an 'add' date newer than the specified dateYES
'update'set_filterISO 8601 Date Format (2020-09-16) Find objects with an 'update' time newer than the specified dateYES
'include'stringalbums, songs (include child objects in the response)YES
'album_artist'boolean0, 1 (if true filter for album artists only)YES
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
  • return array
"artist": []
  • throws object
"error": ""

Example

artist

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

InputTypeDescriptionOptional
'filter'stringUID of Artist, returns artist JSONNO
'include'stringalbums, 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

InputTypeDescriptionOptional
'filter'stringUID of Artist, returns Album JSONNO
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
  • return array
album": []
  • throws object
"error": ""

Example

artist_songs

This returns the songs of the specified artist

InputTypeDescriptionOptional
'filter'stringUID of Artist, returns Song JSONNO
'top50'boolean0, 1 (if true filter to the artist top 50)YES
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
  • return array
"song": []
  • throws object
"error": ""

Example

albums

This returns albums based on the provided search filters

InputTypeDescriptionOptional
'filter'stringFilter results to match this stringYES
'exact'boolean0, 1 (if true filter is exact = rather than fuzzy LIKE)YES
'add'set_filterISO 8601 Date Format (2020-09-16) Find objects with an 'add' date newer than the specified dateYES
'update'set_filterISO 8601 Date Format (2020-09-16) Find objects with an 'update' time newer than the specified dateYES
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
'include'stringalbums, songs (include child objects in the response)YES
  • return array
"album": []
  • throws object
"error": ""

Example

album

This returns a single album based on the UID provided

InputTypeDescriptionOptional
'filter'stringUID of Album, returns album JSONNO
'include'stringsongs (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

InputTypeDescriptionOptional
'filter'stringUID of Album, returns song JSONNO
'exact'boolean0, 1 (if true don't group songs from different disks)YES
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
  • return array
"song": []
  • throws object
"error": ""

Example

genres

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

InputTypeDescriptionOptional
'filter'stringFilter results to match this stringYES
'exact'boolean0, 1 (if true filter is exact = rather than fuzzy LIKE)YES
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
  • return array
"genre": []
  • throws object
"error": ""

Example

genre

This returns a single genre based on UID

InputTypeDescriptionOptional
'filter'stringUID of genre, returns genre JSONNO
  • return object
"id": "",
"name": "",
"albums": 0,
"artists": 0,
"songs": 0,
"videos": 0,
"playlists": 0,
"live_streams": 0
  • throws object
"error": ""

Example

genre_artists

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

InputTypeDescriptionOptional
'filter'stringUID of genre, returns artist JSONYES
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
  • return array
"artist": []
  • throws object
"error": ""

Example

genre_albums

This returns the albums associated with the genre in question

InputTypeDescriptionOptional
'filter'stringUID of genre, returns album JSONYES
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
  • return array
"album": []
  • throws object
"error": ""

Example

genre_songs

returns the songs for this genre

InputTypeDescriptionOptional
'filter'stringUID of genre, returns song JSONYES
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
  • return array
"song": []
  • throws object
"error": ""

Example

songs

Returns songs based on the specified filter

InputTypeDescriptionOptional
'filter'stringFilter results to match this stringYES
'exact'boolean0, 1 (if true filter is exact = rather than fuzzy LIKE)YES
'add'set_filterISO 8601 Date Format (2020-09-16) Find objects with an 'add' date newer than the specified dateYES
'update'set_filterISO 8601 Date Format (2020-09-16) Find objects with an 'update' time newer than the specified dateYES
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
  • return array
"song": []
  • throws object
"error": ""

Example

song

returns a single song

InputTypeDescriptionOptional
'filter'stringUID of Song, returns song JSONNO
  • 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)

InputTypeDescriptionOptional
'filter'stringUID of song to deleteNO
  • return object
"success": ""
  • throws object
"error": ""

Example

url_to_song

This takes a url and returns the song object in question

InputTypeDescriptionOptional
'url'stringFull Ampache URL from server, translates back into a song JSONNO
  • 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

playlists

This returns playlists based on the specified filter

InputTypeDescriptionOptional
'filter'stringFilter results to match this stringYES
'exact'boolean0, 1 (if true filter is exact = rather than fuzzy LIKE)YES
'add'set_filterISO 8601 Date Format (2020-09-16) Find objects with an 'add' date newer than the specified dateYES
'update'set_filterISO 8601 Date Format (2020-09-16) Find objects with an 'update' time newer than the specified dateYES
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
'hide_search'integer0, 1 (if true do not include searches/smartlists in the result)YES
  • return array
"playlist": []
  • throws object
"error": ""

Example

playlist

This returns a single playlist

InputTypeDescriptionOptional
'filter'stringUID of playlist, returns playlist JSONNO
  • return array
"playlist": []
  • throws object
"error": ""

Example

playlist_songs

This returns the songs for a playlist

InputTypeDescriptionOptional
'filter'stringUID of Playlist, returns song JSONNO
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
  • return array
"song": []
  • throws object
"error": ""

Example

playlist_create

This create a new playlist and return it

InputTypeDescriptionOptional
'name'stringPlaylist nameNO
'type'stringpublic, private (Playlist type)YES
  • return array
"playlist": []
  • 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

InputTypeDescriptionOptional
'filter'stringUID of PlaylistNO
'name'stringPlaylist nameYES
'type'stringpublic, private (Playlist type)YES
'owner'stringChange playlist owner to the user id (-1 = System playlist)YES
'items'stringcomma-separated song_id's (replaces existing items with a new id)YES
'tracks'stringcomma-separated playlisttrack numbers matched to 'items' in orderYES
  • return object
"success": ""
  • throws object
"error": ""

Example

playlist_delete

This deletes a playlist

InputTypeDescriptionOptional
'filter'stringUID of PlaylistNO
  • 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

InputTypeDescriptionOptional
'filter'stringUID of PlaylistNO
'song'stringUID of song to add to playlistNO
'check'boolean0, 1 Whether to check and ignore duplicates (default = 0)YES
  • return object
"success": ""
  • throws object
"error": ""

Example

playlist_remove_song

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

InputTypeDescriptionOptional
'filter'stringUID of PlaylistNO
'song'stringUID of song to remove from playlistYES
'track'integerTrack number to remove from playlistYES
  • 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

InputTypeDescriptionOptional
'mode'stringrecent, forgotten, unplayed, random (default = 'random')YES
'filter'stringstring LIKE matched to song titleYES
'album'integer$album_idYES
'artist'integer$artist_idYES
'flag'boolean0, 1 (get flagged songs only. default = 0)YES
'format'stringsong, index, id (default = 'song')YES
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
  • return array
"song": []|"index": []|"id": []
  • throws object
"error": ""

SONG Example

INDEX Example

ID Example

shares

This searches the shares and returns... shares

InputTypeDescriptionOptional
'filter'stringFilter results to match this stringYES
'exact'boolean0, 1 boolean to match the exact filter stringYES
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
  • return array
"share": []
  • throws object
"error": ""

Example

share

Return shares by UID

InputTypeDescriptionOptional
'filter'stringUID of Share, returns song JSONNO
  • 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.

InputTypeDescriptionOptional
'filter'stringUID of object you are sharingNO
'type'stringobject_typeNO
'description'stringdescription (will be filled for you if empty)YES
'expires'integerdays to keep activeYES
  • return array
"share": []
  • 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.

InputTypeDescriptionOptional
'filter'stringAlpha-numeric search termNO
'stream'boolean0, 1YES
'download'boolean0, 1YES
'expires'integernumber of days before expiryYES
'description'stringupdate descriptionYES
  • return object
"success": ""
  • throws object
"error": ""

Example

share_delete

Delete an existing share.

InputTypeDescriptionOptional
'filter'stringUID of Share to deleteNO
  • return object
"success": ""
  • throws object
"error": ""

Example

get_similar

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

InputTypeDescriptionOptional
'type'stringsong, artistNO
'filter'integerartist id or song idNO
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
  • return array
"song": []|"artist": []

  • throws object
"error": ""

Example

search_songs

This searches the songs and returns... songs

InputTypeDescriptionOptional
'filter'stringFilter results to match this stringNO
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
  • return array
"song": []
  • throws object
"error": ""

Example

videos

This returns video objects!

InputTypeDescriptionOptional
'filter'stringFilter results to match this stringYES
'exact'boolean0, 1 (if true filter is exact = rather than fuzzy LIKE)YES
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
  • return array
"video": []
  • throws object
"error": ""

Example

video

This returns a single video

InputTypeDescriptionOptional
'filter'stringUID of video, returns video JSONNO
  • return object
"id": "",
"title": "",
"mime": "",
"resolution": "",
"size": 0,
"genre": [],
"url": ""
  • throws object
"error": ""

Example

podcasts

Get information about podcasts

InputTypeDescriptionOptional
'filter'stringValue is Alpha Match for returned results, may be more than one letter/numberYES
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
'include'stringepisodes (include podcast_episodes in the response)YES
  • return array
"podcast": []
  • throws object
"error": ""

Example

podcast

Get the podcast from it's id.

InputTypeDescriptionOptional
'filter'stringUID of podcast, returns podcast JSONNO
'include'stringepisodes (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)

InputTypeDescriptionOptional
'url'stringrss url for podcastNO
'catalog'stringpodcast catalogNO
  • return array
"podcast": []
  • 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)

InputTypeDescriptionOptional
'filter'stringAlpha-numeric search termNO
'feed'stringfeed rss xml urlYES
'title'stringtitle stringYES
'website'stringsource website urlYES
'description'stringYES
'generator'stringYES
'copyright'stringYES
  • return object
"success": ""
  • throws object
"error": ""

Example

podcast_delete

Delete an existing podcast.

ACCESS REQUIRED: 75 (Catalog Manager)

InputTypeDescriptionOptional
'filter'stringUID of podcast to deleteNO
  • return object
"success": ""
  • throws object
"error": ""

Example

podcast_episodes

This returns the episodes for a podcast

InputTypeDescriptionOptional
'filter'stringUID of podcastNO
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
  • return array
"podcast_episode": []
  • throws object
"error": ""

Example

podcast_episode

Get the podcast_episode from it's id.

InputTypeDescriptionOptional
'filter'stringpodcast_episode ID numberNO
  • return array
"podcast_episode": []
  • throws object
"error": ""

Example

podcast_episode_delete

Delete an existing podcast_episode.

InputTypeDescriptionOptional
'filter'stringUID of podcast_episode to deleteNO
  • 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

InputTypeDescriptionOptional
'type'stringsong, album, artistNO
'filter'stringnewest, highest, frequent, recent, forgotten, flagged, randomYES
'user_id'integerYES
'username'stringYES
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
  • return array
"song": []|"album": []|"artist": []
  • throws object
"error": ""

SONG Example

ARTIST Example

ALBUM Example

user

This gets a user's public information

InputTypeDescriptionOptional
'username'stringUsername of the user to get detailsNO
  • return array
"user": []
  • throws object
"error": ""

Example

user_create

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

ACCESS REQUIRED: 100 (Admin)

InputTypeDescriptionOptional
'username'string$usernameNO
'password'stringhash('sha256', $password)NO
'email'stringe.g. user@gmail.comNO
'fullname'stringYES
'disable'boolean0, 1YES
  • return object
"success": ""
  • throws object
"error": ""

Example

user_update

Update an existing user.

ACCESS REQUIRED: 100 (Admin)

InputTypeDescriptionOptional
'username'string$usernameNO
'password'stringhash('sha256', $password)YES
'email'stringe.g. user@gmail.comYES
'fullname'stringYES
'website'stringYES
'state'stringYES
'city'stringYES
'disable'boolean0, 1YES
'maxbitrate'stringYES
  • return object
"success": ""
  • throws object
"error": ""

Example

user_delete

Delete an existing user.

ACCESS REQUIRED: 100 (Admin)

InputTypeDescriptionOptional
'username'stringNO
  • return object
"success": ""
  • throws object
"error": ""

Example

licenses

This returns licenses based on the specified filter

InputTypeDescriptionOptional
'filter'stringFilter results to match this stringYES
'exact'boolean0, 1 (if true filter is exact = rather than fuzzy LIKE)YES
'add'set_filterISO 8601 Date Format (2020-09-16) Find objects with an 'add' date newer than the specified dateYES
'update'set_filterISO 8601 Date Format (2020-09-16) Find objects with an 'update' time newer than the specified dateYES
'offset'integerYES
'limit'integerYES
  • return array
"license": []
  • throws object
"error": ""

Example

license

This returns a single license

InputTypeDescriptionOptional
'filter'stringUID of license, returns license JSONNO
  • return object
"id": "",
"name": "",
"description": "",
"external_link": ""
  • throws object
"error": ""

Example

license_songs

This returns the songs for a license

InputTypeDescriptionOptional
'filter'stringUID of license, returns song JSONNO
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
  • return array
"song": []
  • throws object
"error": ""

Example

labels

This returns labels based on the specified filter

InputTypeDescriptionOptional
'filter'stringFilter results to match this stringYES
'exact'boolean0, 1 (if true filter is exact = rather than fuzzy LIKE)YES
'add'set_filterISO 8601 Date Format (2020-09-16) Find objects with an 'add' date newer than the specified dateYES
'update'set_filterISO 8601 Date Format (2020-09-16) Find objects with an 'update' time newer than the specified dateYES
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
  • return array
"label": []
  • throws object
"error": ""

Example

label

This returns a single label

InputTypeDescriptionOptional
'filter'stringUID of label, returns label JSONNO
  • 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

InputTypeDescriptionOptional
'filter'stringUID of label, returns artist JSONNO
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
  • return array
"artist": []
  • throws object
"error": ""

Example

followers

This gets the followers for the requested username

InputTypeDescriptionOptional
'username'stringUsername of the user to get followers listNO
  • return array
"user": []
  • throws object
"error": ""

Example

following

Get a list of people that this user follows

InputTypeDescriptionOptional
'username'stringUsername of the user to get following listNO
  • return array
"user": []
  • throws object
"error": ""

Example

toggle_follow

This follow/unfollow a user

InputTypeDescriptionOptional
'username'stringUsername of the user to follow/unfollowNO
  • return object
"success": ""
  • throws object
"error": ""

Example

last_shouts

This gets the latest posted shouts

InputTypeDescriptionOptional
'username'stringGet latest shouts for this usernameYES
'limit'integerMaximum number of results to returnYES
  • return array
"shout": []
  • throws object
"error": ""

Example

rate

This rates a library item

InputTypeDescriptionOptional
'type'stringsong, album, artist, playlist, podcast, podcast_episode, video, tvshow, tvshow_seasonNO
'id'integerlibrary item idNO
'rating'integerrating between 0-5NO
  • return object
"success": ""
  • 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
InputTypeDescriptionOptional
'type'stringsong, album, artist, playlist, podcast, podcast_episode, video, tvshow, tvshow_seasonNO
'id'integer$object_idNO
'flag'boolean0, 1NO
  • 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

InputTypeDescriptionOptional
'id'integer$object_idNO
'user'integer$user_idYES
'client'string$agentYES
'date'integerUNIXTIME()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

InputTypeDescriptionOptional
'song'string$song_nameNO
'artist'string$artist_nameNO
'album'string$album_nameNO
'songmbid'string$song_mbidYES
'artistmbid'string$artist_mbidYES
'albummbid'string$album_mbidYES
'date'integerUNIXTIME()YES
'client'string$agentYES
  • return object
"success": ""
  • throws object
"error": ""

Example

catalogs

This searches the catalogs and returns... catalogs

InputTypeDescriptionOptional
'filter'stringmusic, clip, tvshow, movie, personal_video, podcast (Catalog type)YES
  • return array
"catalog": []
  • throws object
"error": ""

Example

catalog

Return catalog by UID

InputTypeDescriptionOptional
'filter'stringUID of CatalogNO
  • return object
"id": "",
"name": "",
"type": "",
"gather_types": "",
"enabled": 0,
"last_add": 0,
"last_clean": 0,
"last_update": 0,
"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)

InputTypeDescriptionOptional
'task'stringadd_to_catalog, clean_catalogNO
'catalog'integer$catalog_idNO
  • 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)

InputTypeDescriptionOptional
'file'stringFULL path to local fileNO
'task'stringadd, clean, verify, remove (can include comma-separated values)NO
'catalog'integer$catalog_idNO
  • return object
"success": ""
  • throws object
"error": ""

Example

timeline

This gets a user's timeline

InputTypeDescriptionOptional
'username'stringUsername of the user for whom to get the timelineNO
'limit'integerMaximum number of results to returnYES
'since'integerUNIXTIME()YES
  • return array
"activity": []
  • throws object
"error": ""

Example

friends_timeline

This get current user friends timeline

InputTypeDescriptionOptional
'limit'integerMaximum number of results to returnYES
'since'integerUNIXTIME()NO
  • return array
"activity": []
  • throws object
"error": ""

Example

update_from_tags

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

InputTypeDescriptionOptional
'type'stringsong, artist, albumNO
'id'integer$artist_id, $album_id, $song_idNO
  • 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)

InputTypeDescriptionOptional
'id'integer$artist_idNO
  • 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)

InputTypeDescriptionOptional
'id'integer$object_idNO
'type'stringsong, podcastNO
'overwrite'boolean0, 1YES
  • return object
"success": ""
  • throws object
"error": ""

Example

update_podcast

Sync and download new podcast episodes

ACCESS REQUIRED: 50 (Content Manager)

InputTypeDescriptionOptional
'id'integer$object_idNO
  • return object
"success": ""
  • throws object
"error": ""

Example

user_preference

Get your user preference by name

InputTypeDescriptionOptional
'filter'stringPreference name e.g ('notify_email', 'ajax_load')NO
  • return array
"preference": []
  • throws object
"error": ""

Example

system_preference

Get your server preference by name

ACCESS REQUIRED: 100 (Admin)

InputTypeDescriptionOptional
'filter'stringPreference name e.g ('notify_email', 'ajax_load')NO
  • return array
"preference": []
  • throws object
"error": ""

Example

preference_create

Add a new preference to your server

ACCESS REQUIRED: 100 (Admin)

InputTypeDescriptionOptional
'filter'stringPreference name e.g ('notify_email', 'ajax_load')NO
'type'stringboolean, integer, string, specialNO
'default'mixedstring or integer default valueNO
'category'stringinterface, internal, options, playlist, plugins, streaming, systemNO
'description'stringYES
'subcategory'stringYES
'level'integeraccess level required to change the value (default 100)YES
  • return object
"success": ""
  • throws object
"error": ""

Example

preference_edit

Edit a preference value and apply to all users if allowed

ACCESS REQUIRED: 100 (Admin)

InputTypeDescriptionOptional
'filter'stringPreference name e.g ('notify_email', 'ajax_load')NO
'value'mixed(string/integer) Preference valueNO
'all'boolean0, 1 apply to all usersYES
  • return object
"success": ""
  • throws object
"error": ""

Example

preference_delete

Delete a non-system preference by name

ACCESS REQUIRED: 100 (Admin)

InputTypeDescriptionOptional
'filter'stringPreference name e.g ('notify_email', 'ajax_load')NO
  • return object
"success": ""
  • throws object
"error": ""

Example

get_bookmark

Get the bookmark from it's object_id and object_type.

InputTypeDescriptionOptional
'filter'string$object_id to findNO
'type'stringsong, video, podcast_episode (object_type)NO
  • return array
"bookmark": []
  • throws object
"error": ""

Example

bookmark_create

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

InputTypeDescriptionOptional
'filter'string$object_id to findNO
'type'stringsong, video, podcast_episode (object_type)NO
'position'integercurrent track time in secondsNO
'client'stringAgent string. (Default: 'AmpacheAPI')YES
'date'integerupdate time (Default: UNIXTIME())YES
  • return array
"bookmark": []
  • throws object
"error": ""

Example

bookmark_edit

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

InputTypeDescriptionOptional
'filter'string$object_id to findNO
'type'stringsong, video, podcast_episode (object_type)NO
'position'integercurrent track time in secondsNO
'client'stringAgent string. (Default: 'AmpacheAPI')YES
'date'integerupdate time (Default: UNIXTIME())YES
  • return array
"bookmark": []
  • throws object
"error": ""

Example

bookmark_delete

Delete an existing bookmark. (if it exists)

InputTypeDescriptionOptional
'filter'string$object_id to deleteNO
'type'stringsong, video, podcast_episode (object_type)NO
'client'stringAgent string. (Default: 'AmpacheAPI')YES
  • return object
"success": ""
  • throws object
"error": ""

Example

deleted_songs

Returns songs that have been deleted from the server

InputTypeDescriptionOptional
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
  • return array
"deleted_song": []
  • throws object
"error": ""

Example

deleted_podcast_episodes

This returns the episodes for a podcast that have been deleted

InputTypeDescriptionOptional
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
  • return array
"deleted_podcast_episode": []
  • throws object
"error": ""

Example

deleted_videos

This returns video objects that have been deleted

InputTypeDescriptionOptional
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
  • return array
"deleted_video": []
  • 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.

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.

InputTypeDescriptionOptional
'id'integer$object_idNO
'type'stringsong, podcast_episode, podcastNO
'bitrate'integermax bitrate for transcodingYES
'format'stringmp3, ogg, raw, etc (raw returns the original format)YES
'offset'integerReturn results starting from this index positionYES
'length'boolean0, 1YES
  • return file (HTTP 200 OK)
  • throws (HTTP 400 Bad Request)
  • throws (HTTP 404 Not Found)

download

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

InputTypeDescriptionOptional
'id'integer$object_idNO
'type'stringsong, podcast_episodeNO
'format'stringmp3, ogg, raw, etc (raw returns the original format)YES
  • return file (HTTP 200 OK)
  • throws (HTTP 400 Bad Request)
  • throws (HTTP 404 Not Found)

get_art

Get an art image.

InputTypeDescriptionOptional
'id'integer$object_idNO
'type'stringsong, artist, album, playlist, search, podcastNO
  • return image (HTTP 200 OK)
  • throws (HTTP 400 Bad Request)
  • throws (HTTP 404 Not Found)

Control Methods

localplay

This is for controlling localplay

InputTypeDescriptionOptional
'command'stringnext, prev, stop, play, pause, add, volume_up, volume_down, volume_mute, delete_all, skip, statusNO
'oid'integer$object_idYES
'type'stringsong, video, podcast_episode, channel, broadcast, democratic, live_streamYES
'clear'boolean0, 1 (Clear the current playlist before adding)YES
  • return object
"localplay": { "command": {} }
  • throws object
"error": ""

Example

Example (status)

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
InputTypeDescriptionOptional
'oid'integerUID of Song objectNO
'method'stringvote, devote, playlist, playNO
  • return object|array
"url": ""|"method": "","result": false|"song": []
  • throws object
"error": ""

Example

Example

Example