API 4

Compatible Versions:

  • 4.2.0-release
  • 4.2.1-release
  • 4.2.2-release
  • 4.2.3-release
  • 4.2.4-release
  • 4.2.5-release
  • 4.2.6-release
  • 4.3.0-release
  • 4.4.0-release

Ampache Provides an API for pulling out it's meta data in the form of simple XML documents. This was originally created for use by Amarok, but there is no reason it couldn't be used to create other front-ends to the Ampache data. Access to the API is controlled by the Internal Access Control Lists. The KEY defined in the ACL is the passphrase that must be used to establish an API session. Currently all requests are limited to a maximum of 5000 results for performance reasons. To get additional results pass offset as an additional parameter. If you have any questions or requests for this API please submit a Feature Request. All dates in the API calls should be passed as ISO 8601 dates.

Changelog

Added

  • NEW API functions
    • Api::users (ID and Username of the site users)
  • Api::localplay added new options to 'command' ('pause', 'add', 'volume_up', 'volume_down', 'volume_mute', 'delete_all', 'skip')
  • Api::localplay added parameters:
    • 'oid' (integer) object_id to add //optional
    • 'type' (string) Default: 'Song' ('Song', 'Video', 'Podcast_Episode', 'Channel', 'Broadcast', 'Democratic', 'Live_Stream') //optional
    • 'clear' (integer) 0|1 clear the current playlist on add //optional
  • Api::playlist_edit added new parameter 'sort': (0,1) sort the playlist by 'Artist, Album, Song' //optional
  • Api::get_indexes
    • New type options: 'album_artist', 'podcast', 'podcast_episode', 'share', 'video'
    • Added parameter 'include': (0,1) (add the extra songs details if a playlist or podcast_episodes if a podcast)
  • Api::rate - Added types 'playlist', 'podcast', 'podcast_episode', 'video', 'tvshow', 'tvshow_season'
  • Api::flag - Added types 'podcast', 'podcast_episode', 'video', 'tvshow', 'tvshow_season'
  • Add time to artist and album objects. (total time of all songs in seconds)
  • Add songcount, albumcount to artist objects. (time in seconds)
  • Add songcount to album objects. (time in seconds)
  • Add title, mime, catalog to podcast_episodes
  • Api::advanced_search Add 'playlist', 'user' and 'video' to search types
  • Api::handshake added extra total counts to the response
    • users, tags, podcasts, podcast_episodes, shares, licenses, live_streams, labels
  • Api::ping match the handshake response (excluding the auth token)
  • SubSonic - shift the current track start time when you pause/resume

Changed

  • get_indexes: 'playlist' now requires include=1 for xml calls if you want the tracks
  • Make filter optional in shares
  • Api::podcast_episodes
    • "url" is now a play url (instead of a link to the episode)
    • "public_url" is now the old episode link

Fixed

  • Api::podcast_edit wasn't able to edit a podcast...
  • Api::democratic was using action from localplay in the return responses
  • get_indexes for XML didn't include podcast indexes
  • Set OUTDATED_DATABASE_OK on image.php, play/index.php and share.php to stop blocking requests
  • SubSonic - Json clients need their playlist entry to always array (single item lists)

Deprecated

  • Dropped in API 5.0.0
    • Api::get_indexes; stop including playlist track and id in xml by default
    • Album objects: "tracks" will only include track details. Use "songcount"
    • Artist objects: "albums", "songs" will only include track details Use "albumcount" and "songcount"

Sending Handshake Request

Multiple authentication methods are available, described in the next sections.

User / Password

The handshake is a combination of the following three things

  • Encoded Passphrase
  • Timestamp
  • Username

The key that must be passed to Ampache is SHA256(TIME+KEY) where KEY is SHA256('PASSWORD'). Below is a PHP example

$time = time();
$key = hash('sha256','mypassword');
$passphrase = hash('sha256',$time . $key);

Once you've generated the encoded passphrase, you can call the following URL (localhost/ampache is the location of your Ampache installation)

http://localhost/ampache/server/xml.server.php?action=handshake&auth=PASSPHRASE&timestamp=TIME&version=350001&user=USER

Api Key

The key that must be passed to Ampache is the API Key generated for a specific user (none by default, only the administrator can generate one). Then call the following URL (localhost/ampache is the location of your Ampache installation):

http://localhost/ampache/server/xml.server.php?action=handshake&auth=API_KEY&version=350001

In API 400001 the key that must be passed to Ampache is SHA256(USER+KEY) where KEY is SHA256('APIKEY'). Below is a PHP example

$user = 'username';
$key = hash('sha256', 'myapikey');
$passphrase = hash('sha256', $user . $key);

Other handshake-related stuff

Ampache sheme

To standardize how to transfer Ampache connection information, the following Ampache scheme is defined.

ampache://authentication@hostname[:port]/subdirectory[#parameters]

for example:

  • ampache://myuser:mypwd@localhost/ampache
  • ampache://yourapikey@localhost:993/ampache#ssl=true

Application Name

By default Ampache uses USER_AGENT as application name but this could also be defined through http query string. Add &client=YourAppName to override the application name. This parameter also works on stream sessions.

Geolocation

  • Latitude
  • Longitude
  • Place name

Optionally, you can also provide geolocation information &geo_latitude=$latitude&geo_longitude=$longitude, with an optional place name if you already know coordinates match &geo_name=$placename.

Result

If your authenticated User and IP match a row in the Access List the following will be returned.

For XML

<?xml version="1.0" encoding="UTF-8" ?>
<root>
<auth><%AUTHENTICATION TOKEN%></auth>
<api><%APIVERSION%></api>
<session_expire><![CDATA[2019-12-03T09:36:46+10:00]]></session_expire>
<update><![CDATA[2019-11-26T16:35:05+10:00]]></update>
<add><![CDATA[2019-12-03T06:42:55+10:00]]></add>
<clean><![CDATA[2019-12-03T06:41:02+10:00]]></clean>
<songs><![CDATA[268302]]></songs>
<albums><![CDATA[25686]]></albums>
<artists><![CDATA[11055]]></artists>
<playlists><![CDATA[20]]></playlists>
<videos><![CDATA[0]]></videos>
<catalogs><![CDATA[4]]></catalogs>
</root>

For JSON

{
"auth": "%AUTHENTICATION TOKEN%",
"api": "%APIVERSION%",
"session_expire": "2020-01-28T13:59:24+10:00",
"update": "2020-01-24T19:29:35+10:00",
"add": "2020-01-28T04:49:18+10:00",
"clean": "2020-01-28T04:47:28+10:00",
"songs": "274209",
"albums": "26275",
"artists": "11275",
"playlists": 31,
"videos": "0",
"catalogs": "4"
}

All future interactions with the Ampache API must include the AUTHENTICATION_TOKEN as a GET variable named auth.

Methods

All methods must be passed as action=METHODNAME. All methods except the handshake can take an optional offset=XXX and limit=XXX. The limit determines the maximum number of results returned. The offset will tell Ampache where to start in the result set. For example if there are 100 total results and you set the offset to 50, and the limit to 50 Ampache will return results between 50 and 100. The default limit is 5000. The default offset is 0.

You can also pass it limit=none to overcome the limit limitation and return all the matching elements.

For more in depth information regarding the different api servers you can view the following documentation pages.

Non-Data Methods

  • handshake
  • ping
  • goodbye
  • url_to_song
  • check_parameter
  • message

Data Methods

  • get_indexes
  • artists
  • artist
  • artist_songs
  • artist_albums
  • albums
  • album
  • album_songs
  • tags
  • tag
  • tag_artists
  • tag_albums
  • tag_songs
  • songs
  • song
  • advanced_search
  • stats
  • playlists
  • playlist
  • playlist_songs
  • playlist_create
  • playlist_edit
  • playlist_delete
  • playlist_add_song
  • playlist_remove_song
  • playlist_generate
  • search_songs
  • videos
  • video
  • shares
  • share
  • share_create
  • share_edit
  • share_delete
  • get_similar
  • podcasts
  • podcast
  • podcast_create
  • podcast_edit
  • podcast_delete
  • podcast_episodes
  • podcast_episode
  • podcast_episode_delete
  • catalogs
  • catalog
  • catalog_file
  • licenses
  • license
  • license_songs
  • user
  • user_create
  • user_update
  • user_delete
  • stream
  • download
  • get_art
  • rate
  • flag
  • record_play
  • scrobble
  • followers
  • following
  • toggle_follow
  • last_shouts
  • timeline
  • friends_timeline
  • catalog_action
  • update_from_tags
  • update_artist_info
  • update_art
  • update_podcast

Control Methods

  • localplay
  • democratic

Request URL Examples

For the purpose of this example the Ampache host is 'localhost' and the path to Ampache is /ampache

Requesting all genres whose name starts with Rock

XML

http://localhost/ampache/server/xml.server.php?action=tags&auth=1234567890123456789012345678901&filter=Rock

JSON

http://localhost/ampache/server/json.server.php?action=tags&auth=1234567890123456789012345678901&filter=Rock

Requesting all song titles, with an offset of 5000

XML

http://localhost/ampache/server/xml.server.php?action=songs&auth=12345678901234567890123456789012&offset=5000

JSON

http://localhost/ampache/server/json.server.php?action=songs&auth=12345678901234567890123456789012&offset=5000