Ampache API

The Ampache API Provides methods for pulling out it's meta data in the form of simple XML (and JSON!) 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. 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.

Compatible Versions:

  • Ampache develop

Archived Version Documentation

After each release, a documentation page will be created to allow pruning old features from the current version. Note that API 4.1 docs cover all previous versions.

API 4.2 Documentation

API 4.1 Documentation

Changes in Ampache Develop

The next version of Ampache has a lot of breaking changes compared to the 4.x.x API, current changes are listed here and in the changelog.

All API code that used 'Tag' now references 'Genre' instead


  • 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::indexes added parameter 'include': (0,1) include song details with playlists
  • Add time to artist and album objects. (total time of all songs in seconds)
  • NEW API functions
    • Api::users (ID and Username of the site users)
    • Api::song_delete (Delete files when you are allowed to)
    • Api::user_preferences (Get your user preferences)
    • Api::user_preference (Get your preference by name)
    • Api::system_update (Check Ampache for updates and run the update if there is one.)
    • Api::system_preferences (Preferences for the system user)
    • Api::system_preference (Get a system preference by name)
    • Api::preference_create (Add a new preference to Ampache)
    • Api::preference_edit (Edit a preference value by name; optionally apply to all users)
    • Api::preference_delete (Delete a preference by name)
    • Api::labels (list your record labels)
    • Api::label (get a label by id)
    • Api::label_artists (get all artists attached to that label)
    • Api::get_bookmark (See if you've previously played the file)
    • Api::bookmarks (List all bookmarks created by your account)
    • Api::bookmark_create (Create a bookmark to allow revisting later)
    • Api::bookmark_edit (Edit a bookmark)
    • Api::bookmark_delete (Delete a bookmark by object id, type, user and client name)


  • Renamed functions:
    • tags => genres
    • tag => genre
    • tag_artists => genre_artists
    • tag_albums => genre_albums
    • tag_songs => genre_songs
  • Don't allow duplicate podcast feeds
  • Make filter optional in shares, genre_artists, genre_albums, genre_songs (Used as a general catch all method like genres)
  • Error Codes and response structure has changed
    • 4700 Access Control not Enabled
    • 4701 Received Invalid Handshake
    • 4703 Access Denied
    • 4704 Not Found
    • 4705 Missing Method
    • 4706 Depreciated Method
    • 4710 Bad Request
    • 4742 Failed Access Check
  • get_indexes: 'playlist' now requires include=1 for xml calls if you want the tracks
  • stats: Removed back compat from older versions. Only 'type' is mandatory
  • Return empty objects when the request was correct but the results were empty
  • record_play: Require 100 (Admin) permission to record plays for other users


  • Api::get_indexes; stop including playlist track and id in xml by default


  • Api::podcast_edit wasn't able to edit a podcast...
  • Api::democratic was using action from localplay in the return responses
  • Setting a limit of 'none' would slice away all the results
  • get_indexes for XML didn't include podcast indexes

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)


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):


In API 4.0.0 and higher; the key can be passed to Ampache using 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.


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.


  • 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.


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


<?xml version="1.0" encoding="UTF-8" ?>


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


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.

Auth Methods

All Auth methods return HTTP 200 responses

  • handshake
  • ping
  • goodbye

Non-Data Methods

All Non-Data methods return HTTP 200 responses

  • system_update (develop only)
  • users (develop only)
  • user_preferences (develop only)
  • bookmarks (develop only)

Data Methods

All Data methods return HTTP 200 responses

  • get_indexes
  • advanced_search
  • artists
  • artist
  • artist_songs
  • artist_albums
  • albums
  • album
  • album_songs
  • genres (develop only)
  • genre (develop only)
  • genre_artists (develop only)
  • genre_albums (develop only)
  • genre_songs (develop only)
  • songs
  • song
  • song_delete (develop only)
  • url_to_song
  • playlists
  • playlist
  • playlist_songs
  • playlist_create
  • playlist_edit
  • playlist_delete
  • playlist_add_song
  • playlist_remove_song
  • playlist_generate
  • shares
  • share
  • share_create
  • share_edit
  • share_delete
  • get_similar
  • search_songs
  • videos
  • video
  • podcasts
  • podcast
  • podcast_create
  • podcast_edit
  • podcast_delete
  • podcast_episodes
  • podcast_episode
  • podcast_episode_delete
  • stats
  • catalogs
  • catalog
  • catalog_file
  • licenses
  • license
  • license_songs
  • labels (develop only)
  • label (develop only)
  • label_artists (develop only)
  • user
  • user_create
  • user_update
  • user_delete
  • 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
  • user_preference (develop only)
  • system_preferences (develop only)
  • system_preference (develop only)
  • preference_create (develop only)
  • preference_edit (develop only)
  • preference_delete (develop only)
  • get_bookmark (develop only)
  • bookmark_create (develop only)
  • bookmark_edit (develop only)
  • bookmark_delete (develop only)

Binary Data Methods

All binary methods will not return XML/JSON responses. they will either return the requested file/data or an HTTP error code.

@return (HTTP 200 OK)

@throws (HTTP 400 Bad Request)

@throws (HTTP 404 Not Found)

  • stream
  • download
  • get_art

Control Methods

All Control methods return HTTP 200 responses

  • localplay
  • democratic

Access Levels

Some methods have a user access level requirement. Access goes from 0-100 and is split into the following types.

  • 5: Guest
  • 25: User
  • 50: Content Manager
  • 75: Catalog Manager
  • 100: Admin

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





Requesting all song titles, with an offset of 5000