Downloading and uploading files on OneDrive (REST)

  • Article

Your apps can use Live SDK REST API to download or upload files on Microsoft OneDrive.

In this article
Prerequisites
Upload a file
Download a file
Update a file
Summary

Prerequisites

We assume that the user has already signed in and consented to the wl.skydrive scope for reading file or folder properties. If you have not added user sign-in to your apps, see Signing users in with REST.

We assume that you are familiar with the REST API and JSON.

Upload a file

To add contents for an existing file, photo, video, or audio, use PUT or POST, depending on your platform's recommended approach. You can upload file sizes up to 100 megabytes.

Note

On platforms that support the PUT request, PUT should be used to upload files to OneDrive when possible to avoid errors that can occur when POST is used.

This example uses PUT.

PUT https://apis.live.net/v5.0/me/skydrive/files/HelloWorld.txt?access_token=ACCESS_TOKEN

Hello, World!

If you're using POST as shown here, you must format the request as multipart/form-data. You provide the file to upload in a multipart section, while you provide the file name in the Content-Disposition header's filename parameter. For more info, see RFC 2388. Note that only one multipart section is supported in the body of the request.

Also, you can use any of these.

  • me/skydrive/files

  • FOLDER_ID/files, where FOLDER_ID is the ID of the parent folder.

  • The value of the upload_location structure for the folder to which the file, photo, video, or audio will be uploaded.

POST https://apis.live.net/v5.0/me/skydrive/files?access_token=ACCESS_TOKEN

Content-Type: multipart/form-data; boundary=A300x

--A300x
Content-Disposition: form-data; name="file"; filename="HelloWorld.txt"
Content-Type: application/octet-stream

Hello, World!
--A300x--

You can instruct OneDrive to notify the web browser when the upload finishes. You can also attach a unique identifier to each upload request so that you can identify a particular file if you are uploading multiple files in quick succession. To do this, use a POST multipart/form-data request, like this. Replace the folder ID with your target folder ID; replace the state query-string parameter value with your unique identifier; and replace the redirect_uri parameter with the path to your callback page.

Note

The domain portion of the path must match the redirect domain that you specified in the Live SDK app management site for the corresponding client ID.

POST https://apis.live.net/v5.0/folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!110/files?state=MyNewFileState&redirect_uri=http%3A%2F%2Fwww.contoso.com%2Fcallback.htm&access_token=ACCESS_TOKEN

Content-Type: multipart/form-data; boundary=AaB03x

--AaB03x
Content-Disposition: form-data; name="file"; filename="MyNewFile.txt"
Content-Type: text/plain

These are the contents of my new file.
--AaB03x--

OneDrive returns HTML-formatted code similar to the following.

<html>
    <head>
        <script type="text/javascript">
            window.location = "http://www.contoso.com/callback.htm#state=MyNewFileState&result=%7B%22id%22%3A%22file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!184%22%2C%22source%22%3A%22http%3A%2F%2Fstorage.live.com%2Fs1pasGKzgXFvuEQCbxGtOyIpboUVH1OCHoRzUJNDDwL0zVoidb0RRrNVk88hUrOEve5OMT7eCkuxPbop7dV9tMJQ-eE8SCQ28vFv9ZgPnDGwQMRm-0FeG3-KEY4HL9dQSw9%2FMyNewFile.txt%3ABinary%2CDefault%2FMyNewFile.txt%22%7D";
        </script>
    </head>
</html>

When decoded, the result response parameter is similar to this.

{
    "id": "file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!184",
    "source": "http://storage.live.com/s1pasGKzgXFvuEQCbxGtOyIpboUVH1OCHoRzUJNDDwL0zVoidb0RRrNVk88hUrOEve5OMT7eCkuxPbop7dV9tMJQ-eE8SCQ28vFv9ZgPnDGwQMRm-0FeG3-KEY4HL9dQSw9/MyNewFile.txt:Binary,Default/MyNewFile.txt"
}

Note

By default, the file, photo, video, or audio with the same name will be overwritten, if it already exists. You can add an overwrite query-string parameter with a value of false to not overwrite the existing file, photo, video, or audio. Or you can add an overwrite query-string parameter of ChooseNewName if you want to upload a duplicate copy of the file but let OneDrive choose a new file name for the uploaded file.

Before uploading a file, have your app check to make sure that there is enough available OneDrive storage space by making a GET call to USER_ID/skydrive/quota. For example, your app could get the size of the file in bytes and then compare it to the number of available storage bytes returned in the OneDrive quota call. For more info, see Get a user's total and remaining OneDrive storage quota.

If your app tries to upload the file when there's not enough available OneDrive storage space, the upload request will fail and OneDrive will return the following error.

{
    "error": {
        "code": "resource_quota_exceeded", 
        "message": "The user has reached his or her storage quota limit."
    }
}

Download a file

Users can get the contents of a file, photo, video, or audio. The wl.skydrive scope is required.

Note

You can instruct the user's web browser to prompt the user to save the file that's downloading instead of having the browser try to download and display the file directly in its own window. To do this, add the download=true query-string parameter after /content (for example, FILE_ID/content?download=true). This call adds the Content-Disposition: attachment header to the response.

GET https://apis.live.net/v5.0/file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!126/content?access_token=ACCESS_TOKEN

To get a download link to the contents of a file, photo, video, or audio, use code like this.

GET https://apis.live.net/v5.0/file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!126/content?suppress_redirects=true?
    access_token=ACCESS_TOKEN

Update a file

To change contents for an existing file, photo, video, or audio, use Upload a file, and append overwrite=true.

Summary

This topic showed you how you can let users download or upload files on OneDrive. Next, see Move, copy, create, or delete a file or folder (REST), to let your users perform other file or folder taks on OneDrive.