"Fossies" - the Fresh Open Source Software Archive

Member "ampache-5.0.0/docs/API-JSON-methods.md" (31 Aug 2021, 78374 Bytes) of package /linux/www/ampache-5.0.0.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the latest Fossies "Diffs" side-by-side code changes report for "API-JSON-methods.md": 4.4.3_vs_5.0.0.

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:

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.

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
"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
"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

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
"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
"server": "",
"version": "",
"compatible": ""

Example

goodbye

Destroy a session using the auth parameter.

Input Type Description Optional
'auth' string (Session ID) destroys the session if it exists NO
"success": ""
"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)

"success": ""
"error": ""

Example

system_preferences

Get your server preferences

ACCESS REQUIRED: 100 (Admin)

"preference": []
"error": ""

Example

users

Get ids and usernames for your site

"user": []
"error": ""

Example

user_preferences

Get your user preferences

"preference": []
"error": ""

Example

bookmarks

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

"bookmark": []
"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

Input Type Description Optional
'type' string 'song', 'album', 'artist', 'album_artist', 'playlist', NO
'podcast', 'podcast_episode', 'live_stream'
'filter' string Value is Alpha Match for returned results, may be more than one letter/number YES
'add' set_filter ISO 8601 Date Format (2020-09-16) YES
Find objects with an 'add' date newer than the specified date
'update' set_filter ISO 8601 Date Format (2020-09-16) YES
Find objects with an 'update' time newer than the specified date
'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
'hide_search' integer 0,1, if true do not include searches/smartlists in the result YES
"song": []|"album": []|"artist": []|"playlist": []|"podcast": []
"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.

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', 'playlist', NO
'label', '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
"song": []|"album": []|"artist": []|"playlist": []|"label": []|"user": []|"video": []
"error": ""

SONG Example

ARTIST Example

ALBUM 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) YES
Find objects with an 'add' date newer than the specified date
'update' set_filter ISO 8601 Date Format (2020-09-16) YES
Find objects with an 'update' time newer than the specified date
'include' string 'albums', 'songs' and will include the corresponding JSON 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
"artist": []
"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' and will include the corresponding JSON nested in the artist JSON YES
"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": ""
"error": ""

Example

artist_albums

This returns the albums of an artist

Input Type Description Optional
'filter' string UID of Artist, returns Album JSON NO
'offset' integer Return results starting from this index position YES
'limit' integer Maximum number of results to return YES
album": []
"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
"song": []
"error": ""

Example

albums

This returns albums based on the provided search filters

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) YES
Find objects with an 'add' date newer than the specified date
'update' set_filter ISO 8601 Date Format (2020-09-16) YES
Find objects with an 'update' time newer than the specified date
'offset' integer Return results starting from this index position YES
'limit' integer Maximum number of results to return YES
'include' string 'albums', 'songs' will include nested in the album JSON YES
"album": []
"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' will include the corresponding JSON nested in the album JSON YES
"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": ""
"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
'exact' boolean 0,1 if true don't group songs from different disks YES
'offset' integer Return results starting from this index position YES
'limit' integer Maximum number of results to return YES
"song": []
"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
"genre": []
"error": ""

Example

genre

This returns a single genre based on UID

Input Type Description Optional
'filter' string UID of genre, returns genre JSON NO
"id": "",
"name": "",
"albums": 0,
"artists": 0,
"songs": 0,
"videos": 0,
"playlists": 0,
"live_streams": 0
"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
"artist": []
"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
"album": []
"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
"song": []
"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) YES
Find objects with an 'add' date newer than the specified date
'update' set_filter ISO 8601 Date Format (2020-09-16) YES
Find objects with an 'update' time newer than the specified date
'offset' integer Return results starting from this index position YES
'limit' integer Maximum number of results to return YES
"song": []
"error": ""

Example

song

returns a single song

Input Type Description Optional
'filter' string UID of Song, returns song JSON NO
"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
"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
"success": ""
"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
"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
"error": ""

Example

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) YES
Find objects with an 'add' date newer than the specified date
'update' set_filter ISO 8601 Date Format (2020-09-16) YES
Find objects with an 'update' time newer than the specified date
'offset' integer Return results starting from this index position YES
'limit' integer Maximum number of results to return YES
'hide_search' integer 0,1, if true do not include searches/smartlists in the result YES
"playlist": []
"error": ""

Example

playlist

This returns a single playlist

Input Type Description Optional
'filter' string UID of playlist, returns playlist JSON NO
"playlist": []
"error": ""

Example

playlist_songs

This returns the songs for a playlist

Input Type Description Optional
'filter' string UID of Playlist, returns song JSON NO
'offset' integer Return results starting from this index position YES
'limit' integer Maximum number of results to return YES
"song": []
"error": ""

Example

playlist_create

This create a new playlist and return it

Input Type Description Optional
'name' string Playlist name NO
'type' string Playlist type 'public', 'private' YES
"playlist": []
"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.

Input Type Description Optional
'filter' string UID of Playlist NO
'name' string Playlist name YES
'type' string Playlist type 'public', 'private' 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
"success": ""
"error": ""

Example

playlist_delete

This deletes a playlist

Input Type Description Optional
'filter' string UID of Playlist NO
"success": ""
"error": ""

Example

playlist_add_song

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
'song' string UID of song to add to playlist NO
'check' boolean 0, 1 Whether to check and ignore duplicates (default = 0) YES
"success": ""
"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
"success": ""
"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 get flagged songs only 0, 1 (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
"song": []|"index": []|"id": []
"error": ""

SONG Example

INDEX Example

ID Example

shares

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
"share": []
"error": ""

Example

share

Return shares by UID

Input Type Description Optional
'filter' string UID of Share, returns song JSON NO
"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": ""
"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
"share": []
"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
"success": ""
"error": ""

Example

share_delete

Delete an existing share.

Input Type Description Optional
'filter' string UID of Share to delete NO
"success": ""
"error": ""

Example

get_similar

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

Input Type Description Optional
'type' string 'song' or '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
"song": []|"artist": []
"error": ""

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
"song": []
"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
"video": []
"error": ""

Example

video

This returns a single video

Input Type Description Optional
'filter' string UID of video, returns video JSON NO
"id": "",
"title": "",
"mime": "",
"resolution": "",
"size": 0,
"genre": [],
"url": ""
"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
'offset' integer Return results starting from this index position YES
'limit' integer Maximum number of results to return YES
'include' string 'episodes' (include episodes in the response) YES
"podcast": []
"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 episodes in the response) YES
"id": "",
"name": "",
"description": "",
"language": "",
"copyright": "",
"feed_url": "",
"generator": "",
"website": "",
"build_date": "",
"sync_date": "",
"public_url": "",
"podcast_episode": []
"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
"podcast": []
"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
"success": ""
"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
"success": ""
"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
"podcast_episode": []
"error": ""

Example

podcast_episode

Get the podcast_episode from it's id.

Input Type Description Optional
'filter' string podcast_episode ID number NO
"podcast_episode": []
"error": ""

Example

podcast_episode_delete

Delete an existing podcast_episode.

Input Type Description Optional
'filter' string UID of podcast_episode to delete NO
"success": ""
"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' NO
'filter' string 'newest', 'highest', 'frequent', 'recent', YES
'forgotten', 'flagged', 'random'
'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
"song": []|"album": []|"artist": []
"error": ""

SONG Example

ARTIST Example

ALBUM Example

user

This get an user public information

Input Type Description Optional
'username' string Username of the user to get details NO
"user": []
"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 'user@gmail.com' NO
'fullname' string YES
'disable' boolean 0, 1 YES
"success": ""
"error": ""

Example

user_update

Update an existing user.

ACCESS REQUIRED: 100 (Admin)

Input Type Description Optional
'username' string $username NO
'password' string hash('sha256', $password)) YES
'email' string 'user@gmail.com' YES
'fullname' string YES
'website' string YES
'state' string YES
'city' string YES
'disable' boolean 0, 1 YES
'maxbitrate' string YES
"success": ""
"error": ""

Example

user_delete

Delete an existing user.

ACCESS REQUIRED: 100 (Admin)

Input Type Description Optional
'username' string NO
"success": ""
"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) YES
Find objects with an 'add' date newer than the specified date
'update' set_filter ISO 8601 Date Format (2020-09-16) YES
Find objects with an 'update' time newer than the specified date
'offset' integer YES
'limit' integer YES
"license": []
"error": ""

Example

license

This returns a single license

Input Type Description Optional
'filter' string UID of license, returns license JSON NO
"id": "",
"name": "",
"description": "",
"external_link": ""
"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
"song": []
"error": ""

Example

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) YES
Find objects with an 'add' date newer than the specified date
'update' set_filter ISO 8601 Date Format (2020-09-16) YES
Find objects with an 'update' time newer than the specified date
'offset' integer Return results starting from this index position YES
'limit' integer Maximum number of results to return YES
"label": []
"error": ""

Example

label

This returns a single label

Input Type Description Optional
'filter' string UID of label, returns label JSON NO
"id": "",
"name": "",
"artists": 0,
"summary": "",
"external_link": "'",
"address": "",
"category": "",
"email": "",
"website": "",
"user": 0
"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
"artist": []
"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
"user": []
"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
"user": []
"error": ""

Example

toggle_follow

This follow/unfollow an user

Input Type Description Optional
'username' string Username of the user to follow/unfollow NO
"success": ""
"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
"shout": []
"error": ""

Example

rate

This rates a library item

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

Example

flag

This flags a library item as a favorite

Input Type Description Optional
'type' string 'song', 'album', 'artist', 'playlist', NO
'podcast', 'podcast_episode', 'video'
'tvshow', 'tvshow_season'
'id' integer $object_id NO
'flag' boolean 0, 1 NO
"success": ""
"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
"success": ""
"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 $song_name NO
'artist' string $artist_name NO
'album' string $album_name NO
'songmbid' string $song_mbid YES
'artistmbid' string $artist_mbid YES
'albummbid' string $album_mbid YES
'date' integer UNIXTIME() YES
'client' string $agent YES
"success": ""
"error": ""

Example

catalogs

This searches the catalogs and returns... catalogs

Input Type Description Optional
'filter' string Catalog type: music, clip, tvshow, YES
movie, personal_video, podcast
"catalog": []
"error": ""

Example

catalog

Return catalog by UID

Input Type Description Optional
'filter' string UID of Catalog NO
"id": "",
"name": "",
"type": "",
"gather_types": "",
"enabled": 0,
"last_add": "",
"last_clean": "",
"last_update": "",
"path": "",
"rename_pattern": "",
"sort_pattern": ""
"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
"success": ""
"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' NO
(can include comma-separated values) NO
'catalog' integer $catalog_id NO
"success": ""
"error": ""

Example

timeline

This get an user 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
"activity": []
"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
"activity": []
"error": ""

Example

update_from_tags

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

Input Type Description Optional
'type' string 'artist', 'album', 'song' NO
'id' integer $artist_id, $album_id, $song_id NO
"success": ""
"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
"success": ""
"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
"success": ""
"error": ""

Example

update_podcast

Sync and download new podcast episodes

ACCESS REQUIRED: 50 (Content Manager)

Input Type Description Optional
'id' integer $object_id NO
"success": ""
"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
"preference": []
"error": ""

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
"preference": []
"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', NO
'plugins', 'streaming', 'system'
'description' string YES
'subcategory' string YES
'level' integer access level required to change the value (default 100) YES
"success": ""
"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
"success": ""
"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
"success": ""
"error": ""

Example

get_bookmark

Get the bookmark from it's object_id and object_type.

Input Type Description Optional
'filter' string object_id to find NO
'type' string object_type ('song', 'video', 'podcast_episode') NO
"bookmark": []
"error": ""

Example

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 object_type ('song', 'video', 'podcast_episode') NO
'position' integer current track time in seconds NO
'client' string Agent string. (Default: 'AmpacheAPI') YES
'date' integer update time (Default: UNIXTIME()) YES
"bookmark": []
"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 object_type ('song', 'video', 'podcast_episode') NO
'position' integer current track time in seconds NO
'client' string Agent string. (Default: 'AmpacheAPI') YES
'date' integer update time (Default: UNIXTIME()) YES
"bookmark": []
"error": ""

Example

bookmark_delete

Delete an existing bookmark. (if it exists)

Input Type Description Optional
'filter' string object_id to delete NO
'type' string object_type ('song', 'video', 'podcast_episode') NO
'client' string Agent string. (Default: 'AmpacheAPI') YES
"success": ""
"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
"deleted_song": []
"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
"deleted_podcast_episode": []
"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
"deleted_video": []
"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.

Input Type Description Optional
'id' integer $object_id NO
'type' string 'song', 'podcast' NO
'bitrate' integer max bitrate for transcoding YES
'format' string 'mp3', 'ogg', 'raw', etc YES
'offset' integer Return results starting from this index position YES
'length' boolean 0, 1 YES

download

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

Input Type Description Optional
'id' integer $object_id NO
'type' string 'song', 'podcast_episode' NO
'format' string 'mp3', 'ogg', 'raw', etc YES

get_art

Get an art image.

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

Control Methods

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', YES
'Broadcast', 'Democratic', 'Live_Stream'
'clear' boolean 0,1 Clear the current playlist before adding YES
"localplay": { "command": {} }
"error": ""

Example

Example (status)

democratic

This is for controlling democratic play (Songs only)

Input Type Description Optional
'oid' integer UID of Song object NO
'method' string vote, devote, playlist, play NO
"url": ""|"method": "","result": false|"song": []
"error": ""

Example

Example

Example