Move, copy, create, or delete a file or folder on OneDrive (REST)

  • Article

Your apps can move, copy, create, or delete a user's files or folders on Microsoft OneDrive, by using the Live SDK REST API.

In this article
Prerequisites
Move or copy a file or folder
Delete a file
Create a folder
Delete a folder
Get a list of the user's most recently used documents
Traverse the OneDrive directory
Display a preview of a OneDrive item
Remarks

Your apps can also let your users get a list of their most recently used items, traverse the OneDrive directory, and display a preview of a OneDrive item.

Prerequisites

The user must be signed in with a Microsoft account. To learn how to sign users in from your app, see Signing users in with REST.

Note

You can't create files directly on OneDrive. Instead, you upload files to OneDrive. To upload files, see Downloading and uploading files (REST).

Move or copy a file or folder

To move a folder, file, photo, video, or audio, use code like this. The wl.skydrive_update scope is required. The source can be anything except the root, and the destination must be the folder to which the item will be moved. Change file ID to the file ID or folder ID of the file or folder you want to move. Change the folder ID to the folder ID of the destination folder.

Note

The destination of a move operation must be a folder. Also, OneDrive storage is structured so that move operations cannot occur between the OneDrive folder hierarchies of different users. For example, even if user A can read user B's files, user A cannot move them to his or her own OneDrive folders.

To copy a file, replace MOVE with COPY in the example. The wl.skydrive_update scope is required. Change file ID to the file ID of the file you want to copy. Change the folder ID to the folder ID of the destination folder.

Note

The destination of a copy operation must be a folder. Folders themselves cannot be copied. Also, OneDrive storage is structured so that copy operations cannot occur between the OneDrive folder hierarchies of different users. For example, even if user A can read user B's files, user A cannot copy them to his or her own OneDrive folders.

MOVE https://apis.live.net/v5.0/file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!126

Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "destination": "folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!114"
}

Delete a file

To remove a file, photo, video, or audio, use code like this. The wl.skydrive_update scope is required. Change the file ID to a different file ID, photo ID, video ID, or audio ID to remove a different file, photo, video, or audio.

DELETE https://apis.live.net/v5.0/file.b7c3b8f9g3616f6f.B7CB8F9G3626F6!225?access_token=ACCESS_TOKEN

Create a folder

To add a new folder, use code like this. The wl.skydrive_update scope is required. Change me/skydrive to the folder ID (or, in certain cases, the friendly name) of the folder in which the new folder will be created.

For details about the minimum required and optional structures that your app must provide to use POST, see the Folder object.

POST https://apis.live.net/v5.0/me/skydrive

Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "name": "My example folder"
}

Delete a folder

To remove a folder, use code like this. The wl.skydrive_update scope is required.

DELETE https://apis.live.net/v5.0/folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!114?access_token=ACCESS_TOKEN

Get a list of the user's most recently used documents

To get a list of OneDrive documents that the user has used most recently, use the wl.skydrive scope to make a GET request to /USER_ID/skydrive/recent_docs, where USER_ID is either me or the user ID of the consenting user. Here's an example.

GET https://apis.live.net/v5.0/me/skydrive/recent_docs?access_token=ACCESS_TOKEN

Traverse the OneDrive directory

To use the Live SDK to get info about a user's top-level folder in the OneDrive directory, you make a GET request to me/skydrive or USER_ID/skydrive.

In the JavaScript Object Notation (JSON)-formatted object that's returned, two structures are important to note: the id structure that represents the top-level folder's folder ID, and the upload_location structure that represents the location for the top-level folder to which you can upload files, photos, videos, and audio.

If you make a request to me/skydrive/files or USER_ID/skydrive/files, the JSON-formatted object that's returned contains info about all of the child folders, child albums, and files in the user's top-level folder only.

From there, you can traverse a user's entire OneDrive directory by making a request with FOLDER_ID/files or ALBUM_ID/files, where FOLDER_ID or ALBUM_ID represents the id structure that corresponds to a folder ID or album ID, respectively, anywhere in the directory.

As with a user's top-level OneDrive folder, you can use the upload_location structure for any folder or album to upload files to that folder or album. Additionally, you can use the upload_location structure for any file, photo, video, or audio to overwrite the contents of that file, photo, video, or audio.

For example, here's what a user's OneDrive directory might look like conceptually.

GET https://apis.live.net/v5.0/me/skydrive?access_token=ACCESS_TOKEN
---
200 OK
{
    "id": "folder.a6b2a7e8f2515e5e", 
    ...
    "upload_location": "https://apis.live.net/v5.0/folder.a6b2a7e8f2515e5e/files",
    ...
    "type": "folder",
    ...
}
---
GET https://apis.live.net/v5.0/folder.a6b2a7e8f2515e5e/files?access_token=ACCESS_TOKEN
---
200 OK
{
    "data": [
        {
            "id": "folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!110", 
            ...
            "upload_location": "https://apis.live.net/v5.0/folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!110/files/"
            ...
            "type": "folder",
            ...
        }, {
            "id": "photo.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!131", 
            ...
            "upload_location": "https://apis.live.net/v5.0/photo.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!131/content/", 
            ...
            "type": "photo",
            ...
        }, {
            "id": "file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!119", 
            ...             
            "upload_location": "https://apis.live.net/v5.0/file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!119/content/", 
            ...
            "type": "file", 
            ...
        }
    ]
}

Display a preview of a OneDrive item

To display a preview of an item in OneDrive, make a GET request to /skydrive/get_item_preview?type=TYPE&url=URL. The optional type query-string parameter is one of the following:

  • thumbnail

  • small (to get a maximum 100 100-pixel preview)

  • album (maximum 200 200)

  • normal (maximum 800 800)

The required url query-string parameter is a shared link to the item in OneDrive. Here are two examples, one using a longer OneDriveURL and one using a shorter sdrv.ms URL (sdrv.ms is a URL-shortening service that's unique to OneDrive).

GET https://apis.live.net/v5.0/skydrive/get_item_preview?type=normal&url=https%3A%2F%2Fskydrive.live.com%2Fredir.aspx%3Fcid%3Da6b2a7e8f2515e5e%26amp%3Bresid%3DA6B2A7E8F2515E5E!132%26amp%3Bparid%3DA6B2A7E8F2515E5E!110%26amp%3Bauthkey%3D!ACuMMo37Ju8_xw0x

GET https://apis.live.net/v5.0/skydrive/get_item_preview?type=normal&url=http%3A%2F%2Fsdrv.ms%2FLTIvcyx

Note the following:

  • To make the get_item_preview request, you don't need to request any scopes or provide an access token.

  • If the item is not a photo, and a preview is associated with the item, a thumbnail preview is displayed and the type parameter is ignored even if provided.

  • A successful response has a responseStatus value of" 302 Found" with the link to the item preview in the "Location" response header.

  • If a particular size of preview doesn't exist, the next-largest size preview that's available is displayed. If no preview is associated with the item, a 404 (Not Found) error is returned.

  • You can get a shared link to an item in one of three ways:

    • Make a GET request to ITEM_ID/shared_read_link, where ITEM_ID is the OneDrive item's ID. Here's an example.

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

      You can find the shared link value in the JavaScript Object Notation (JSON)-formatted response object's link structure.

    • In the OneDriveUI, select the item, and then click Share. Click Get a link and then, next to View only, click Create. OneDrive displays the shared link value, which you can use in your get_item_preview request. The value should look something like this: https://onedrive.live.com/redir.aspx?cid=a6b2a7e8f2515e5e\&resid=A6B2A7E8F2515E5E\!132\&parid=A6B2A7E8F2515E5E\!110\&authkey=\!ACuMMo37Ju8\_xw0x.

    • In the OneDriveUI, select the item, and then click Share. Click Post to Twitter, follow the on-screen directions, and then click Post. The newly created Twitter post includes the shared link value, which you can use in your get_item_preview request. The value should look something like this: http://1drv.ms/LTIvcyx.

  • The url query-string parameter's value must be URL-encoded. For example, use %3A for the colon (":") character, %2F for the forward slash ("/") character, %3F for the question mark ("?") character, and %26 for the ampersand ("&") character.

Remarks

The destination of a move or copy operation must be a folder. Folders themselves cannot be copied. Also, OneDrive storage is structured so that move and copy operations cannot occur between the OneDrive folder hierarchies of different users. For example, even if user A can read user B's files, user A cannot copy or move them to his or her own OneDrive folders.