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