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 API develop
Take a look at the API Changelog to keep an eye on changes between versions
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
The key that must be passed to Ampache 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)
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('APIKEY'). Below is a PHP example
$user = 'username';
$key = hash('sha256', 'myapikey');
$passphrase = hash('sha256', $user . $key);
Other handshake-related stuff
To standardize how to transfer Ampache connection information, the following Ampache scheme is defined.
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.
- 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
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" ?>
"auth": "%AUTHENTICATION TOKEN%",
All future interactions with the Ampache API must include the
AUTHENTICATION_TOKEN as a
GET variable named
All methods must be passed as
action=METHODNAME. All methods except the
handshake can take an optional
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.
All Auth methods return HTTP 200 responses
All Non-Data methods return HTTP 200 responses
All Data methods return HTTP 200 responses
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)
All Control methods return HTTP 200 responses
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