Allows moving a locker file to "trash" and also allows for removing a file from the trash. Trash must be emptied using the web UI. Locker storage calls use a different API URL than locker data calls. See the API URL's page for more information.


sid (required): A valid session id, received from the "login" method.
partner_token (required): A valid partner token. See Overview for more information.
action (optional): Used when restoring a track from the trash.

file key (required): A valid file key. Note the file key is not part of the query string, but rather part of the URL. See the examples below.

Example Request (moving a file to the trash:<file key>?output=xml&sid=<sid>&partner_token=9999999999

Example Request (restoring a file from the trash):<file key>?output=xml&sid=<sid>&partner_token=9999999999&action=restore

Example Unsuccessful Response:

HTTP/1.1 404 File not found
Date: Fri, 25 May 2007 21:58:50 GMT
Server: Apache
X-Powered-By: PHP/5.2.1
X-MP3tunes-ErrorNo: 404002
X-MP3tunes-ErrorString: File key 44a3380ca95cdaffba67efca26f92cxx could not be found
Connection: close
Content-Type: text/html

Note that special handling may be desired for the 503 error indicating the service is currently "read-only", which means files can be played and fetched from the service, but not modified. Included in the response header is a "Retry-After" value indicating a number of seconds to wait before trying the call again.

HTTP/1.1 503 Service Unavailable.
Date: Fri, 25 May 2007 22:44:05 GMT
Server: Apache
X-Powered-By: PHP/5.2.1
X-MP3tunes-ErrorNo: 503001
X-MP3tunes-ErrorString: Service Unavailable. We are currently performing system maintenance.
Retry-After: 900
Connection: close
Content-Type: text/html