Skip to main content

Ampache API

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.

News​

Ampache8 ships a new API (API8) based on API6. Changes are kept to a minimum so API8 can be used as a drop in replacement for API6.

Ampache8 introduces a fully compatible RESTful API implementation supporting all formats and versions.

As of 7.7.1 (API 6.9.0) Ampache fully supports POST data requests for all API methods.

POST requests offer more privacy than a regular GET request because data is sent in the body, not the URL, avoiding exposure in browser history and logs.

Parameters for POST, PUT, PATCH and DELETE requests may be supplied in any of three ways, and may be mixed with query-string parameters (the body takes precedence on conflicts):

  • a query string (as with GET)
  • a form-encoded body (Content-Type: application/x-www-form-urlencoded)
  • a JSON body (Content-Type: application/json)

For example, these are equivalent:

curl "https://music.com.au/server/json.server.php?action=song&filter=54&auth=API_SESSION"
curl -X POST "https://music.com.au/server/json.server.php" -d "action=song&filter=54&auth=API_SESSION"
curl -X POST "https://music.com.au/server/json.server.php" -H "Content-Type: application/json" -d '{"action":"song","filter":"54","auth":"API_SESSION"}'

Archived Version Documentation​

After each release, a documentation page will be created to allow pruning old features from the current version.

API8 is the current version and is documented on these pages: JSON methods, XML methods and the REST/OpenAPI reference. The pages below document the last major release of the older versions:

Ampache serves API versions 3, 4, 5, 6 and 8 (version 7 was skipped). You can also check out the past releases page for some historical detail but DO NOT use these pages as a guide for API development.

API Changelog​

Take a look at the API Changelog to keep an eye on changes between versions

Before you begin​

Ampache 5.2.0+ supports multiple API versions. This means that you can send your handshake with a specific version (e.g. 390001, 440001, 5.2.0, 6.0.0 or 8.0.0) and you will be sent API3, API4, API5, API6 or API8 responses in return. Version 7 was skipped; the default version is 8.

To change from API3 to API5 you can send a ping with a new version parameter to update your session (or send goodbye to log off and start again.)

API3 is not recommended for use outside of running old applications and it is recommended that you turn off API versions you don't use.

Sending Handshake Request​

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

NOTE if you use a Bearer Token you do not need to send a handshake request.

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=8.0.0&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=8.0.0

If you are using Ampache 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);

HTTP Header Authentication​

Ampache supports sending your auth parameter to the server using a Bearer Token.

The auth parameter does not need to be sent with your URL. We will check your header for a token first

GET https://demo.ampache.dev/server/json.server.php?action=handshake&version=8.0.0 HTTP/1.1
Authorization: Bearer 000111112233334444455556667777788888899aaaaabbbbcccccdddeeeeeeff

QuickConnect Authentication​

Ampache 8.2.0+

QuickConnect pairs a new client without typing a password or API key: the client requests a short pairing code, shows it to the user, and polls until it is approved from another session that is already signed in (the Preferences page, or the same flow used by the Jellyfin-compatible API).

It is off by default; an administrator must enable the quickconnect_enable preference before either method below responds.

secret is a bearer credential for the pairing — anyone who has it can complete the sign-in — so send it as POST data rather than a query string parameter, the same way you would an auth token.

  1. Call quickconnect_initiate to get a secret (keep this private, it is what step 3 polls with) and a short code (show this to the user)
curl -X POST "http://localhost/ampache/server/json.server.php" -d "action=quickconnect_initiate&device_name=My+App"
  1. Have the user approve the code from their Preferences page, on a session that is already signed in
  2. Poll quickconnect_status with the secret from step 1
curl -X POST "http://localhost/ampache/server/json.server.php" -d "action=quickconnect_status&secret=SECRET"

While the code is still waiting for approval, the response is just {"authorized": false}. Once it is approved, authorized is true and the response also carries a minted session — the same fields handshake returns (auth, session_expire, server counts, ...) — so no separate handshake call is needed.

Ampache scheme​

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

Stream Token's​

Ampache6+ allows you to create a Stream Token for a user.

The biggest bonus here is that these static tokens let you can create links that avoid the risk of the session expiring and don't require a handshake to create a session.

Once a user has been given a streaming token; all Democratic, Song, Podcast Episode and Video streams will use this session token.

e.g. https://music.com.au/play/index.php?ssid=supercoolstreamingtoken&type=song&oid=1511&uid=1&player=api&name=The%20Smashing%20Pumpkins%20-%20Wound.flac

This token does not allow a user to do anything except stream music and it requires an Admin to create the token for the user.

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><![CDATA[cfj3f237d563f479f5223k23189dbb34]]></auth>
  <api><![CDATA[8.0.0]]></api>
  <session_expire><![CDATA[2022-08-17T04:34:55+00:00]]></session_expire>
  <update><![CDATA[2021-07-21T02:51:36+00:00]]></update>
  <add><![CDATA[2021-08-03T00:04:14+00:00]]></add>
  <clean><![CDATA[2021-08-03T00:05:54+00:00]]></clean>
  <songs><![CDATA[75]]></songs>
  <albums><![CDATA[9]]></albums>
  <artists><![CDATA[17]]></artists>
  <genres><![CDATA[7]]></genres>
  <playlists><![CDATA[2]]></playlists>
  <searches><![CDATA[17]]></searches>
  <playlists_searches><![CDATA[19]]></playlists_searches>
  <users><![CDATA[4]]></users>
  <catalogs><![CDATA[4]]></catalogs>
  <videos><![CDATA[2]]></videos>
  <podcasts><![CDATA[2]]></podcasts>
  <podcast_episodes><![CDATA[13]]></podcast_episodes>
  <shares><![CDATA[2]]></shares>
  <licenses><![CDATA[14]]></licenses>
  <live_streams><![CDATA[3]]></live_streams>
  <labels><![CDATA[3]]></labels>
</root>

For JSON

{
    "auth": "cfj3f237d563f479f5223k23189dbb34",
    "api": "8.0.0",
    "session_expire": "2022-08-17T06:21:00+00:00",
    "update": "2021-07-21T02:51:36+00:00",
    "add": "2021-08-03T00:04:14+00:00",
    "clean": "2021-08-03T00:05:54+00:00",
    "songs": 75,
    "albums": 9,
    "artists": 17,
    "genres": 7,
    "playlists": 2,
    "searches": 17,
    "playlists_searches": 19,
    "users": 4,
    "catalogs": 4,
    "videos": 2,
    "podcasts": 2,
    "podcast_episodes": 13,
    "shares": 2,
    "licenses": 14,
    "live_streams": 3,
    "labels": 3
}

All future interactions with the Ampache API must include the AUTHENTICATION_TOKEN. Send it as an Authorization: Bearer <token> header (an Authorization: ApiKey <token> or a plain auth header are also accepted), or as an auth parameter in the query string or a POST/JSON body. The header forms are preferred; the query-string auth is a legacy fallback and is deprecated for privacy.

Methods​

All methods must be passed as action=METHODNAME. All data methods 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
  • goodbye
  • ping
  • register
  • lost_password Ampache 6.1.0+
  • quickconnect_initiate Ampache 8.2.0+
  • quickconnect_status Ampache 8.2.0+

Non-Data Methods​

All Non-Data methods return HTTP 200 responses

  • bookmarks
  • system_update
  • users
  • user_preferences

Data Methods​

All Data methods return HTTP 200 responses

  • advanced_search
  • albums
  • album
  • album_songs
  • album_disks Ampache 8.0.0+
  • album_disk Ampache 8.0.0+
  • album_disk_songs Ampache 8.0.0+
  • artists
  • artist
  • artist_albums
  • artist_songs
  • bookmark Ampache 6.1.0+
  • bookmark_create
  • bookmark_delete
  • bookmark_edit
  • browse
  • catalogs
  • catalog
  • catalog_action
  • catalog_add
  • catalog_delete
  • catalog_file
  • catalog_folder
  • deleted_podcast_episodes
  • deleted_songs
  • deleted_videos
  • flag
  • folders Ampache 8.0.0+
  • followers
  • following
  • friends_timeline
  • genres
  • genre
  • genre_albums
  • genre_artists
  • genre_songs
  • get_bookmark
  • get_external_metadata Ampache 7.4.0+
  • get_indexes (Removed in Ampache 8.0.0+)
  • get_lyrics Ampache 7.8.0+
  • get_similar
  • index Ampache 6.3.0+
  • labels
  • label
  • label_artists
  • last_shouts
  • licenses
  • license
  • license_songs
  • list (Replaces get_indexes)
  • live_streams
  • live_stream
  • live_stream_create
  • live_stream_delete
  • live_stream_edit
  • now_playing Ampache 6.3.1+
  • player Ampache 6.4.0+
  • playlists
  • playlist
  • playlist_add Ampache 6.3.0+ (Replaces playlist_add_song)
  • playlist_add_song (Removed in Ampache 8.0.0+)
  • playlist_create
  • playlist_delete
  • playlist_edit
  • playlist_generate
  • playlist_hash Ampache 6.6.0+
  • playlist_remove (Replaces playlist_remove_song) Ampache 8.0.0
  • playlist_remove_song (Deprecated, will be removed in API9 — use playlist_remove)
  • playlist_songs
  • podcasts
  • podcast
  • podcast_create
  • podcast_delete
  • podcast_edit
  • podcast_episodes
  • podcast_episode
  • podcast_episode_delete
  • preference_create
  • preference_delete
  • preference_edit
  • rate
  • record_play
  • scrobble
  • search_group Ampache 6.3.0+
  • search Ampache 6.3.0+ (alias for advanced_search)
  • search_rules Ampache 7.6.0+
  • search_songs
  • shares
  • share
  • share_create
  • share_delete
  • share_edit
  • smartlists Ampache 7.8.0+
  • smartlist Ampache 7.8.0+
  • smartlist_songs Ampache 7.8.0+
  • smartlist_delete Ampache 7.8.0+
  • songs
  • song
  • song_delete
  • song_tags Ampache 7.5.0+
  • stats
  • system_preference
  • system_preferences
  • timeline
  • toggle_follow
  • update_art
  • update_artist_info
  • update_from_tags
  • update_podcast
  • url_to_song
  • user
  • user_create
  • user_delete
  • user_edit (Replaces user_update)
  • user_playlists Ampache 6.3.0+
  • user_preference
  • user_smartlists Ampache 6.3.0+
  • user_update (Removed in Ampache 8.0.0+)
  • videos
  • video

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.

For information about about how playback works and what a client can expect from Ampache check out API Media Methods

@return (HTTP 200 OK)

@throws (HTTP 400 Bad Request)

@throws (HTTP 404 Not Found)

@throws (HTTP 416 Range Not Satisfiable)

  • download
  • get_art
  • random Ampache 8.0.0+
  • stream

Control Methods​

All Control methods return HTTP 200 responses

  • democratic
  • localplay
  • localplay_songs

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​

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