JSON Methods

Lets go through come calls and examples that you can do for each JSON method.

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

Non-Data Methods

handshake

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

@param array $input @return boolean

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

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 @param array $input

InputTypeDescriptionOptional
'auth'string(Session ID) returns version information and extends the session if passedYES

Example

goodbye

Destroy a session using the auth parameter.

@param array $input

InputTypeDescriptionOptional
'auth'string(Session ID) destroys the session if it existsNO

Example

url_to_song

This takes a url and returns the song object in question @param array $input

InputTypeDescriptionOptional
'url'stringFull Ampache URL from server, translates back into a song JSONNO

Example

Data Methods

get_indexes

This takes a collection of inputs and returns ID + name for the object type @param array $input @return boolean

InputTypeDescriptionOptional
'type'string'song', 'album', 'artist', 'playlist'NO
'filter'stringYES
'add'set_filterISO 8601 Date Format (2020-09-16) add date is newer then specified dateYES
'update'set_filterISO 8601 Date Format (2020-09-16) update itme is newer then specified dateYES
'offset'integerYES
'limit'integerYES

SONGS

Example

ARTIST

Example

ALBUM

Example

PLAYLIST

Example

Changes to text searches

  • 'is not' has been added shifting values down the list. 0=contains, 1=does not contain, 2=starts with, 3=ends with 4=is, 5=is not, 6=sounds like, 7=does not sound like
  • rule_1['name'] is depreciated. Instead of rule_1['name'] use rule_1['title'] (I have put a temp workaround into the search rules to alleviate this change for any existing apps)
  • Metadata Search is combined with text and numeric. Meaning that changes to text lists push the numeric fields down.

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.

@param array $input

InputTypeDescriptionOptional
operatorstring'and','or' (whether to match one rule or all)NO
rulesarray[[rule_1,rule_1_operator,rule_1_input], [rule_2,rule_2_operator,rule_2_input], [etc]]NO
typestring'song', 'album', 'artist', 'playlist', 'label', 'user', 'video'NO
randomboolean0, 1 (random order of results; default to 0)YES
offsetintegerYES
limit'integerYES

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

SONG

Example

ARTIST

Example

ALBUM

Example

artists

This takes a collection of inputs and returns artist objects.

@param array $input

InputTypeDescriptionOptional
'filter'stringValue is Alpha Match for returned results, may be more than one letter/numberYES
'exact'boolean(0, 1) if true filter is exact rather then fuzzyYES
'add'set_filterISO 8601 Date Format (2020-09-16) add date is newer then specified dateYES
'update'set_filterISO 8601 Date Format (2020-09-16) update itme is newer then specified dateYES
'offset'integerYES
'limit'integerYES
'include'string'albums', 'songs' and will include JSON nested in the artist JSONYES

Example

artist

This returns a single artist based on the UID of said artist @param array $input

InputTypeDescriptionOptional
'filter'stringUID of Artist, returns artist JSONNO
'include'string'albums', 'songs' and will include the corresponding JSON nested in the artist JSONYES

Example

artist_albums

This returns the albums of an artist @param array $input

InputTypeDescriptionOptional
'filter'stringUID of Artist, returns Album JSONNO
'offset'integerYES
'limit'integerYES

Example

artist_songs

This returns the songs of the specified artist @param array $input

InputTypeDescriptionOptional
'filter'stringUID of Artist, returns Song JSONNO
'offset'integerYES
'limit'integerYES

Example

albums

This returns albums based on the provided search filters @param array $input

InputTypeDescriptionOptional
'filter'stringValue is Alpha Match for returned results, may be more than one letter/numberYES
'exact'boolean(0, 1) if true filter is exact rather then fuzzyNO
'add'set_filterISO 8601 Date Format (2020-09-16) add date is newer then specified dateYES
'update'set_filterISO 8601 Date Format (2020-09-16) update itme is newer then specified dateYES
'offset'integerYES
'limit'integerYES
'include'string'albums', 'songs' will include nested in the album JSONYES

Example

album

This returns a single album based on the UID provided @param array $input

InputTypeDescriptionOptional
'filter'stringUID of Album, returns album JSONNO
'include'string'songs' will include the corresponding JSON nested in the album JSONYES

Example

album_songs

This returns the songs of a specified album @param array $input

InputTypeDescriptionOptional
'filter'stringUID of Album, returns song JSONNO
'offset'integerYES
'limit'integerYES

Example

genres

This returns the genres (Tags) based on the specified filter @param array $input

InputTypeDescriptionOptional
'filter'stringValue is Alpha Match for returned results, may be more than one letter/numberYES
'exact'booleanif true filter is exact rather then fuzzyYES
'offset'integerYES
'limit'integerYES

Example

genre

This returns a single genre based on UID @param array $input

InputTypeDescriptionOptional
'filter'stringUID of genre, returns genre JSONNO

Example

genre_artists

This returns the artists associated with the genre in question as defined by the UID @param array $input

InputTypeDescriptionOptional
'filter'stringUID of genre, returns artist JSONNO
'offset'integerYES
'limit'integerYES

Example

genre_albums

This returns the albums associated with the genre in question @param array $input

InputTypeDescriptionOptional
'filter'stringUID of genre, returns album JSONNO
'offset'integerYES
'limit'integerYES

Example

genre_songs

returns the songs for this genre @param array $input

InputTypeDescriptionOptional
'filter'stringUID of genre, returns song JSONNO
'offset'integerYES
'limit'integerYES

Example

songs

Returns songs based on the specified filter @param array $input

InputTypeDescriptionOptional
'filter'stringValue is Alpha Match for returned results, may be more than one letter/numberNO
'exact'boolean(0, 1) if true filter is exact rather then fuzzyNO
'add'set_filterISO 8601 Date Format (2020-09-16) add date is newer then specified dateYES
'update'set_filterISO 8601 Date Format (2020-09-16) update itme is newer then specified dateYES
'offset'integerYES
'limit'integerYES

Example

song

returns a single song @param array $input

InputTypeDescriptionOptional
'filter'stringUID of Song, returns song JSONNO

Example

playlists

This returns playlists based on the specified filter @param array $input

InputTypeDescriptionOptional
'filter'stringValue is Alpha Match for returned results, may be more than one letter/numberYES
'exact'boolean(0, 1) if true filter is exact rather then fuzzyYES
'add'set_filterISO 8601 Date Format (2020-09-16) add date is newer then specified dateYES
'update'set_filterISO 8601 Date Format (2020-09-16) update itme is newer then specified dateYES
'offset'integerYES
'limit'integerYES

Example

playlist

This returns a single playlist @param array $input

InputTypeDescriptionOptional
'filter'stringUID of playlist, returns playlist JSONNO

Example

playlist_songs

This returns the songs for a playlist @param array $input

InputTypeDescriptionOptional
'filter'stringUID of Playlist, returns song JSONNO
'offset'integerYES
'limit'integerYES

Example

playlist_create

This create a new playlist and return it @param array $input

InputTypeDescriptionOptional
'name'stringPlaylist nameNO
'type'stringPlaylist type 'public', 'private'YES

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. @param array $input

InputTypeDescriptionOptional
'filter'stringUID of PlaylistNO
'name'stringPlaylist nameYES
'type'stringPlaylist type 'public', 'private'YES
'items'stringcomma-separated song_id's (replace existing items with a new object_id)YES
'tracks'stringcomma-separated playlisttrack numbers matched to items in orderYES

Example

playlist_delete

This deletes a playlist @param array $input

InputTypeDescriptionOptional
'filter'stringUID of PlaylistNO

Example

playlist_add_song

This adds a song to a playlist. setting check=1 will not add duplicates to the playlist @param array $input

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

Example

playlist_remove_song

This remove a song from a playlist. Previous versions required 'track' instead of 'song'. @param array $input

InputTypeDescriptionOptional
'filter'stringUID of PlaylistNO
'song'stringUID of song to remove from playlistYES
'track'integerTrack number to remove from playlistYES

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

@param array $input

InputTypeDescriptionOptional
'mode'string'recent', 'forgotten', 'unplayed', 'random' (default = 'random')YES
'filter'stringstring LIKE matched to song titleYES
'album'integer$album_idYES
'artist'integer$artist_idYES
'flag'booleanget flagged songs only 0, 1 (default = 0)YES
'format'string'song', 'index','id' (default = 'song')YES
'offset'integerYES
'limit'integerYES

SONG

Example

INDEX

Example

ID

Example

shares

  • NEW in 4.2.0

This searches the shares and returns... shares @param array $input

InputTypeDescriptionOptional
'filter'stringValue is Alpha Match for Share TitleYES
'exact'boolean0, 1 boolean to match the exact filter stringYES
'offset'integerYES
'limit'integerYES

Example

share

  • (MINIMUM_API_VERSION=420000)

Return shares by UID @param array $input

InputTypeDescriptionOptional
'filter'stringUID of Share, returns song JSONNO

Example

share_create

  • (MINIMUM_API_VERSION=420000

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

@param array $input

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

Example

share_edit

  • (MINIMUM_API_VERSION=420000

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

@param array $input

InputTypeDescriptionOptional
'filter'stringAlpha-numeric search termNO
'stream'boolean0, 1YES
'download'boolean0, 1YES
'expires'integernumber of days before expiryYES
'description'stringupdate descriptionYES

Example

share_delete

  • (MINIMUM_API_VERSION=420000

Delete an existing share.

@param array $input

InputTypeDescriptionOptional
'filter'stringUID of Share to deleteNO

Example

get_similar

  • NEW in 4.2.0

Return similar artist id's or similar song ids compared to the input filter @param array $input

InputTypeDescriptionOptional
'type'string'song' or 'artist'NO
'filter'integerartist id or song idNO
'offset'integerYES
'limit'integerYES

Example

search_songs

This searches the songs and returns... songs @param array $input

InputTypeDescriptionOptional
'filter'stringValue is Alpha Match for Song Title, Artist Name, Album Name, Genre Name returns song JSONNO
'offset'integerYES
'limit'integerYES

Example

videos

This returns video objects! @param array $input

InputTypeDescriptionOptional
'filter'stringValue is Alpha Match for returned results, may be more than one letter/numberNO
'exact'booleanif true filter is exact rather then fuzzyYES
'offset'integerYES
'limit'integerYES

Example

video

This returns a single video @param array $input

InputTypeDescriptionOptional
'filter'stringUID of video, returns video JSONNO

Example

podcasts

  • NEW in 4.2.0

Get information about podcasts @param array $input

InputTypeDescriptionOptional
'filter'stringNO
'offset'integerYES
'limit'integerYES
'include'string'episodes' (include episodes in the response)YES

Example

podcast

  • NEW in 4.2.0

Get the podcast from it's id. @param array $input

InputTypeDescriptionOptional
'filter'stringNO
'include'string'episodes' (include episodes in the response)YES

Example

podcast_create

  • NEW in 4.2.0

Create a podcast that can be used by anyone to stream media. Takes the url and catalog parameters. @param array $input

InputTypeDescriptionOptional
'url'stringrss url for podcastNO
'catalog'stringpodcast catalogNO

Example

podcast_edit

  • NEW in 4.2.0

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

InputTypeDescriptionOptional
'filter'stringAlpha-numeric search termNO
'feed'stringfeed rss xml urlYES
'title'stringtitle stringYES
'website'stringsource website urlYES
'description'stringYES
'generator'stringYES
'copyright'stringYES

Example

podcast_delete

  • NEW in 4.2.0

Delete an existing podcast. @param array $input

InputTypeDescriptionOptional
'filter'stringUID of podcast to deleteNO

Example

podcast_episodes

  • NEW in 4.2.0

This returns the episodes for a podcast @param array $input

InputTypeDescriptionOptional
'filter'stringUID of podcastNO
'offset'integerYES
'limit'integerYES

Example

podcast_episode

  • NEW in 4.2.0

Get the podcast_episode from it's id. @param array $input

InputTypeDescriptionOptional
'filter'stringpodcast_episode ID numberNO

Example

podcast_episode_delete

  • NEW in 4.2.0

Delete an existing podcast_episode. @param array $input

InputTypeDescriptionOptional
'filter'stringUID of podcast_episode to deleteNO

Example

stats

Get some items based on some simple search types and filters. This method has partial backwards compatibility with older api versions but should be updated to follow the current input values. (Changed in 400001 'filter' added) @param array $input

InputTypeDescriptionOptional
'type'string'song', 'album', 'artist'NO
'filter'string'newest', 'highest', 'frequent', 'recent', 'forgotten', 'flagged', 'random'NO
'user_id'integerYES
'username'stringYES
'offset'integerYES
'limit'integerYES

SONG

Example

ARTIST

Example

ALBUM

Example

users

  • NEW in develop

Get ids and usernames for your site @param array $input

Example

user

This get an user public information @param array $input

InputTypeDescriptionOptional
'username'stringUsername of the user to get detailsNO

Example

user_create

Create a new user. (Requires the username, password and email.) @param array $input

InputTypeDescriptionOptional
'username'string$usernameNO
'password'stringhash('sha256', $password))NO
'email'string'user@gmail.com'NO
'fullname'stringYES
'disable'boolean0, 1YES

Example

user_update

Update an existing user. @param array $input

InputTypeDescriptionOptional
'username'string$usernameNO
'password'stringhash('sha256', $password))YES
'email'string'user@gmail.com'YES
'fullname'stringYES
'website'stringYES
'state'stringYES
'city'stringYES
'disable'boolean0, 1YES
'maxbitrate'stringYES

Example

user_delete

Delete an existing user. @param array $input

InputTypeDescriptionOptional
'username'stringNO

Example

licenses

  • NEW in 4.2.0

This returns licenses based on the specified filter @param array $input

InputTypeDescriptionOptional
'filter'stringValue is Alpha Match for returned results, may be more than one letter/numberYES
'exact'boolean(0, 1) if true filter is exact rather then fuzzyYES
'add'set_filterISO 8601 Date Format (2020-09-16) add date is newer then specified dateYES
'update'set_filterISO 8601 Date Format (2020-09-16) update itme is newer then specified dateYES
'offset'integerYES
'limit'integerYES

Example

license

  • NEW in 4.2.0

This returns a single license @param array $input

InputTypeDescriptionOptional
'filter'stringUID of license, returns license JSONNO

Example

license_songs

  • NEW in 4.2.0

This returns the songs for a license @param array $input

InputTypeDescriptionOptional
'filter'stringUID of license, returns song JSONNO
'offset'integerYES
'limit'integerYES

Example

followers

This get an user followers @param array $input

InputTypeDescriptionOptional
'username'stringUsername of the user to get followers listNO

Example

following

This get the user list followed by an user @param array $input

InputTypeDescriptionOptional
'username'stringUsername of the user to get following listNO

Example

toggle_follow

This follow/unfollow an user @param array $input

InputTypeDescriptionOptional
'username'stringUsername of the user to follow/unfollowNO

Example

last_shouts

This get the latest posted shouts @param array $input

InputTypeDescriptionOptional
'username'stringUsername of the userYES
'limit'integerYES

Example

rate

This rates a library item @param array $input

InputTypeDescriptionOptional
'type'stringlibrary item type, album, artist, song, videoNO
'id'integerlibrary item idNO
'rating'stringrating between 0-5NO

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 @param array $input
InputTypeDescriptionOptional
'type'string'song', 'album', 'artist', 'video'NO
'id'integer$object_idNO
'flag'boolean0, 1NO

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 @param array $input

InputTypeDescriptionOptional
'id'integer$object_idNO
'user'integer$user_idNO
'client'string$agentYES

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 @param array $input

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

Example

catalogs

  • NEW in 4.2.0

This searches the catalogs and returns... catalogs @param array $input

InputTypeDescriptionOptional
'filter'stringCatalog type music, clip, tvshow, movie, personal_video, podcastYES

Example

catalog

  • NEW in 4.2.0

Return catalog by UID @param array $input

InputTypeDescriptionOptional
'filter'stringUID of CatalogNO

Example

catalog_action

Kick off a catalog update or clean for the selected catalog @param array $input

InputTypeDescriptionOptional
'task'string'add_to_catalog', 'clean_catalog'NO
'catalog'integer$catalog_idNO

Example

catalog_file

  • NEW in 4.2.0

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!

@param array $input

InputTypeDescriptionOptional
'file'stringFULL path to local fileNO
'task'string'add','clean','verify','remove'NO
'catalog'integer$catalog_idNO

Example

timeline

This get an user timeline @param array $input

InputTypeDescriptionOptional
'username'stringUsername of the user for whom to get the timelineNO
'limit'integerYES
'since'integerUNIXTIME()YES

Example

friends_timeline

This get current user friends timeline @param array $input

InputTypeDescriptionOptional
'limit'integerYES
'since'integerUNIXTIME()NO

Example

update_from_tags

Update a single album, artist, song from the tag data @param array $input

InputTypeDescriptionOptional
'type'string'artist', 'album', 'song'NO
'id'integer$artist_id, $album_id, $song_idNO

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 @param array $input

InputTypeDescriptionOptional
'id'integer$artist_idNO

Example

update_art

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

InputTypeDescriptionOptional
'id'integer$object_idNO
'type'string'song', 'podcast'NO
'overwrite'boolean0, 1YES

Example

update_podcast

Sync and download new podcast episodes @param array $input

InputTypeDescriptionOptional
'id'integer$object_idNO

Example

Binary Data Methods

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. @param array $input

InputTypeDescriptionOptional
'id'integer$object_idNO
'type'string'song', 'podcast'NO
'bitrate'integermax bitrate for transcodingYES
'format'string'mp3', 'ogg', 'raw', etcYES
'offset'integertime offset in secondsYES
'length'boolean0, 1YES

download

Downloads a given media file. set format=raw to download the full file @param array $input

InputTypeDescriptionOptional
'id'integer$object_idNO
'type'string'song', 'podcast'NO
'format'string'mp3', 'ogg', 'raw', etcYES

get_art

Get an art image. @param array $input

Control Methods

localplay

This is for controlling localplay @param array $input

Example

Example (status)

democratic

This is for controlling democratic play (Songs only) @param array $input

  • ACTION
    • method
      • vote
        • oid (Unique ID of the element you want to vote on)
      • devote
        • oid (Unique ID of the element you want to vote on)
      • playlist (Returns an array of song items with an additional \[VOTE COUNT]\ element)
      • play (Returns the URL for playing democratic play)
InputTypeDescriptionOptional
'oid'integerUID of Song objectNO
'method'stringvote, devote, playlist, playNO

Example