1--- 2title: "API 5" 3metaTitle: "API 5" 4metaDescription: "API documentation" 5--- 6 7The [Ampache API](https://ampache.org/api/) Provides methods for pulling out it's meta data in the form of 8simple XML (and JSON!) documents. This was originally created for use by [Amarok](https://ampache.org/api/http://amarok.kde.org/), 9but there is no reason it couldn't be used to create other front-ends to the Ampache data. 10 11Access to the API is controlled by the Internal [Access Control Lists](https://ampache.org/api/api-acls). 12Currently all requests are limited to a maximum of 5000 results for performance reasons. To get additional results 13pass offset as an additional parameter. 14 15If you have any questions or requests for this API please submit a [Feature Request](https://github.com/ampache/ampache/issues/new?assignees=&labels=&template=feature_request.md&title=%5BFeature+Request%5D). 16All dates in the API calls should be passed as [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) dates. 17 18## Current Stable Release 19 20The current stable release is documented under it's own version page. 21Refer to the taged versions if you just want to follow the stable releases. 22 23* [Ampache 4.4.3-release](https://github.com/ampache/ampache/releases/tag/4.4.3) 24* [API 4 Documentation](https://ampache.org/api/api-4) 25 26## Archived Version Documentation 27 28After each release, a documentation page will be created to allow pruning old features from the current version. 29Note that API 4.1 docs cover all previous versions. 30 31* [API 4.3 Documentation](https://ampache.org/api/versions/api-4.3) 32* [API 4.2 Documentation](https://ampache.org/api/versions/api-4.2) 33* [API 4.1 Documentation](https://ampache.org/api/versions/api-4.1) 34 35## Changelog API 5.0.0-develop 36 37Take a look at the [API Changelog](https://ampache.org/api/api-changelog) to keep an eye on changes between versions 38 39## Sending Handshake Request 40 41Multiple authentication methods are available, described in the next sections. 42 43### User / Password 44 45The handshake is a combination of the following three things 46 47* Encoded Passphrase 48* Timestamp 49* Username 50 51The key that must be passed to Ampache is `SHA256(TIME+KEY)` where `KEY` is `SHA256('PASSWORD')`. Below is a PHP example 52 53```PHP 54$time = time(); 55$key = hash('sha256','mypassword'); 56$passphrase = hash('sha256',$time . $key); 57``` 58 59Once you've generated the encoded passphrase, you can call the following URL (localhost/ampache is the location of your Ampache installation) 60 61```Text 62http://localhost/ampache/server/xml.server.php?action=handshake&auth=PASSPHRASE×tamp=TIME&version=350001&user=USER 63``` 64 65### Api Key 66 67The 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): 68 69```Text 70http://localhost/ampache/server/xml.server.php?action=handshake&auth=API_KEY&version=350001 71``` 72 73In 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 74 75```PHP 76$user = 'username'; 77$key = hash('sha256', 'myapikey'); 78$passphrase = hash('sha256', $user . $key); 79``` 80 81### Other handshake-related stuff 82 83#### Ampache sheme 84 85To standardize how to transfer Ampache connection information, the following Ampache scheme is defined. 86 87```Text 88ampache://authentication@hostname[:port]/subdirectory[#parameters] 89``` 90 91for example: 92 93* ampache://myuser:mypwd@localhost/ampache 94* ampache://yourapikey@localhost:993/ampache#ssl=true 95 96#### Application Name 97 98By 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. 99 100#### Geolocation 101 102* Latitude 103* Longitude 104* Place name 105 106Optionally, 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`. 107 108### Result 109 110If your authenticated User and IP match a row in the Access List the following will be returned. 111 112For XML 113 114```XML 115<?xml version="1.0" encoding="UTF-8" ?> 116<root> 117 <auth><%AUTHENTICATION TOKEN%></auth> 118 <api><%APIVERSION%></api> 119 <session_expire><![CDATA[2019-12-03T09:36:46+10:00]]></session_expire> 120 <update><![CDATA[2019-11-26T16:35:05+10:00]]></update> 121 <add><![CDATA[2019-12-03T06:42:55+10:00]]></add> 122 <clean><![CDATA[2019-12-03T06:41:02+10:00]]></clean> 123 <songs><![CDATA[268302]]></songs> 124 <albums><![CDATA[25686]]></albums> 125 <artists><![CDATA[11055]]></artists> 126 <playlists><![CDATA[20]]></playlists> 127 <videos><![CDATA[0]]></videos> 128 <catalogs><![CDATA[4]]></catalogs> 129</root> 130``` 131 132For JSON 133 134```JSON 135{ 136 "auth": "%AUTHENTICATION TOKEN%", 137 "api": "%APIVERSION%", 138 "session_expire": "2020-01-28T13:59:24+10:00", 139 "update": "2020-01-24T19:29:35+10:00", 140 "add": "2020-01-28T04:49:18+10:00", 141 "clean": "2020-01-28T04:47:28+10:00", 142 "songs": "274209", 143 "albums": "26275", 144 "artists": "11275", 145 "playlists": 31, 146 "videos": "0", 147 "catalogs": "4" 148} 149``` 150 151All future interactions with the Ampache API must include the `AUTHENTICATION_TOKEN` as a `GET` variable named `auth`. 152 153## Methods 154 155All 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. 156 157You can also pass it `limit=none` to overcome the `limit` limitation and return **all** the matching elements. 158 159For more in depth information regarding the different api servers you can view the following documentation pages. 160 161* [XML Documentation](https://ampache.org/api/api-xml-methods) 162* [JSON Documentation](https://ampache.org/api/api-json-methods) 163 164### Auth Methods 165 166All Auth methods return HTTP 200 responses 167 168* handshake 169* ping 170* goodbye 171 172### Non-Data Methods 173 174All Non-Data methods return HTTP 200 responses 175 176* system_update 177* users 178* user_preferences 179* bookmarks 180 181### Data Methods 182 183All Data methods return HTTP 200 responses 184 185* get_indexes 186* [advanced_search](https://ampache.org/api/api-advanced-search) 187* artists 188* artist 189* artist_songs 190* artist_albums 191* albums 192* album 193* album_songs 194* genres 195* genre 196* genre_artists 197* genre_albums 198* genre_songs 199* songs 200* song 201* song_delete 202* url_to_song 203* playlists 204* playlist 205* playlist_songs 206* playlist_create 207* playlist_edit 208* playlist_delete 209* playlist_add_song 210* playlist_remove_song 211* playlist_generate 212* shares 213* share 214* share_create 215* share_edit 216* share_delete 217* get_similar 218* search_songs 219* videos 220* video 221* podcasts 222* podcast 223* podcast_create 224* podcast_edit 225* podcast_delete 226* podcast_episodes 227* podcast_episode 228* podcast_episode_delete 229* stats 230* catalogs 231* catalog 232* catalog_file 233* licenses 234* license 235* license_songs 236* labels 237* label 238* label_artists 239* user 240* user_create 241* user_update 242* user_delete 243* rate 244* flag 245* record_play 246* scrobble 247* followers 248* following 249* toggle_follow 250* last_shouts 251* timeline 252* friends_timeline 253* catalog_action 254* update_from_tags 255* update_artist_info 256* update_art 257* update_podcast 258* user_preference 259* system_preferences 260* system_preference 261* preference_create 262* preference_edit 263* preference_delete 264* get_bookmark 265* bookmark_create 266* bookmark_edit 267* bookmark_delete 268* deleted_songs 269* deleted_podcast_episodes 270* deleted_videos 271 272### Binary Data Methods 273 274All binary methods will not return XML/JSON responses. they will either return the requested file/data or an HTTP error code. 275 276@return (HTTP 200 OK) 277 278@throws (HTTP 400 Bad Request) 279 280@throws (HTTP 404 Not Found) 281 282* stream 283* download 284* get_art 285 286### Control Methods 287 288All Control methods return HTTP 200 responses 289 290* localplay 291* democratic 292 293## Access Levels 294 295Some methods have a user access level requirement. Access goes from 0-100 and is split into the following types. 296 297* 5: Guest 298* 25: User 299* 50: Content Manager 300* 75: Catalog Manager 301* 100: Admin 302 303## Request URL Examples 304 305For the purpose of this example the Ampache host is 'localhost' and the path to Ampache is /ampache 306 307### Requesting all genres whose name starts with Rock 308 309XML 310 311```XML 312http://localhost/ampache/server/xml.server.php?action=tags&auth=1234567890123456789012345678901&filter=Rock 313``` 314 315JSON 316 317```JSON 318http://localhost/ampache/server/json.server.php?action=tags&auth=1234567890123456789012345678901&filter=Rock 319``` 320 321### Requesting all song titles, with an offset of 5000 322 323XML 324 325```XML 326http://localhost/ampache/server/xml.server.php?action=songs&auth=12345678901234567890123456789012&offset=5000 327``` 328 329JSON 330 331```JSON 332http://localhost/ampache/server/json.server.php?action=songs&auth=12345678901234567890123456789012&offset=5000 333``` 334