Develop with the OneDrive API

The OneDrive API provides access to data stored within a user's OneDrive. Most interactions with OneDrive API resources follow RESTful patterns, but some function calls are also available for simplicity.

This API supports OData V4 at the minimum conformance level. Some of the features of the OneDrive API might not be available via the OData metadata or generated content. For more information, see OData Support.

Prerequisites

To use the OneDrive API, we assume that:

• You have an app to which you want to provide OneDrive support. Your app can be a Windows Universal app, iOS, Android, or Web app.
• You have a development environment, like Visual Studio or Android Studio, that is set up and ready for you to write code.
• You are familiar with REST and OAuth 2.0.

Getting started with OneDrive API

To get started, follow these steps.

1. Authenticate your app

OneDrive uses OAuth 2.0 for authentication. You get an access token that authenticates your app with a particular set of permissions for a user. You provide an access token through an HTTP header:

Authorization: bearer {token}

To obtain an access token and sign the user in, see OneDrive authentication or OneDrive for Business authentication.

2. Make calls against a URL root

Now that you've authenticated your app, you can call the OneDrive API with your access token against the URL root below, combined with one of the root resources. See Drive resource and Item resource for examples on how to make calls to the OneDrive API. OneDrive API URLs are relative to the following root unless otherwise noted.

Service	URL Root
OneDrive	https://api.onedrive.com/v1.0
OneDrive for Business	https://{tenant}-my.sharepoint.com/_api/v2.0

Note: Throughout this documentation, only partial syntax such as: GET /drive/items/{item-id} is used for the sake of brevity. Prefix the path with the correct root URL and version number in order to obtain the full resource path or URL.

Resource model

The OneDrive API exposes two major resource types:

• Drive (top-level object)
• Item (files, folders, and so on.)

The following is an example of a resource.

{
  "@content.downloadUrl":"http://public-sn3302.files.1drv.com/y2pcT7OaUEExF7EHOlpTjCE55mIUoiX7H3sx1ff6I-nP35XUTBqZlnkh9FJhWb_pf9sZ7LEpEchvDznIbQig0hWBeidpwFkOqSKCwQylisarN6T0ecAeMvantizBUzM2PA1",
  "createdDateTime": "2014-10-31T03:37:04.72Z",
  "cTag": "aYzpENDY0OEYwNkM5MUQ5RDNEITU0OTI3LjI1Ng",
  "eTag": "aRDQ2NDhGMDZDOTFEOUQzRCE1NDkyNy4w",
  "id":"D4648F06C91D9D3D!54927",
  "lastModifiedBy": {
    "user": {
      "displayName": "daron spektor",
      "id": "d4648f06c91d9d3d"
    }
  },
  "name":"BritishShorthair.jpg",
  "size":35212,
  "image":{
    "height":398,
    "width":273
  },
  "file": {
    "hashes":{
      "crc32Hash":"omY5NA==",
      "sha1Hash":"wmgPQ6jrSeMX7JP1XmstQEGM2fc="
    },
    "mimeType":"image/jpeg"
  }
}

Resources expose data in three different ways:

• Properties (like id and name) expose simple values.
• Facets (like file and photo) expose complex values. The presence of file or folder facets indicates the type of an Item.
• References (like children) point to collections of other resources.

You can expand references in your URL with the expand query parameter, for example, ?expand=children. Request specific properties and facets with the select query parameter, for example, ?select=id,name. By default, all properties and facets are returned, and all references are hidden. For efficiency, we recommend that you specify select and expand for the data you care about.

For details about resources and facets, see Resources and Facets.

Root resources

Use these root resources to access an item or drive.

Path	Resource
/drive	User's default Drive.
/drives	List Drives available to the authenticated user.
/drives/{drive-id}	Access a specific Drive by its ID.
/drives/{drive-id}/root/children	List items in the root of a specific Drive.
/drive/items/{item-id}	Access an Item by its ID.

Items can also be addressed by path, by putting a colon after any item or drive URL, and following it with the relative path to the item. The next table shows how to use a colon in the URL address. You might optionally transition back to addressing the resource model by putting another colon at the end. Ensure your request follows the path encoding requirements.

Path	Resource
/drive/root:/path/to/file	Access an Item by path under the root.
/drive/items/{item-id}:/path/to/file	Access an Item by its path relative to another item.
/drive/root:/path/to/file:/children	List children when accessing by path relative to the drive root.
/drive/items/{item-id}:/path/to/file:/children	List children when accessing by path relative to another item.

Drive resource

The Drive is the top level object within a user's OneDrive. A user will always have at least one Drive available--the default Drive.

In the next table, the examples use /drive, but /drives/{drive-id} is valid too.

Common task	HTTP method
Get user's default Drive metadata	GET /drive
Get Drive metadata of another Drive	GET /drives/{drive-id}
Get root folder for user's default Drive	GET /drive/root
List children under the Drive	GET /drive/root/children
List changes for all Items in the Drive	GET /drive/root/view.delta
Search for Items in the Drive (preview)	GET /drive/root/view.search
Access special folder	GET /drive/special/{name}

For more info about Drives, see Drive.

Item resource

Items are the objects inside the OneDrive file system. They can be accessed by their id using the /items/{item-id} syntax, or by their file system path using the /drive/root:/path/to/file syntax. Items have Facets that expose data about their identities and capabilities. Folders have a Folder facet and files have a File facet. Images have an Image facet in addition to their File facet.

Folders act as containers of items, and have a children reference pointing to a collection of items under the folder.

Common task	HTTP method (by ID)	HTTP method (by path)
Get metadata for an Item	GET /drive/items/{id}	GET /drive/root:/{path}
List an Item's children	GET /drive/items/{id}/children	GET /drive/root:/{path}:/children
Create an Item	PUT /drive/items/{parent-id}/children/{name}	PUT /drive/root:/{parent-path}/{name}
Upload an Item's contents	PUT /drive/items/{parent-id}/children/{name}/content	PUT /drive/root:/{parent-path}/{name}:/content
Update an Item's contents	PATCH /drive/items/{id}	PATCH /drive/root:/{path}
Delete an Item	DELETE /drive/items/{id}	DELETE /drive/root:/{path}
Move an Item	PATCH /drive/items/{id}	PATCH /drive/root:/{path}
Copy an Item	POST /drive/items/{id}/action.copy	POST /drive/root:/{path}:/action.copy
Download an Item's contents	GET /drive/items/{id}/content	GET /drive/root:/{path}:/content
Search for an Item	GET /drive/items/{id}/view.search	GET /drive/root:/{path}:/view.search
View changes on an Item	GET /drive/items/{id}/view.delta	GET /drive/root:/{path}:/view.delta
Get thumbnails for an Item	GET /drive/items/{id}/thumbnails	GET /drive/root:/{path}:/thumbnails

Special folders

Commonly used folders like Documents and Photos can be accessed with static names regardless of the folder's actual name and location in a user's OneDrive.

To learn more about addressing a folder, see special folders.

Shared folders and remote items

Users can add one or more shared items from another drive to their OneDrive. These shared items appear as an item in the children collection with a remoteItem facet.

For more information on working with shared folders and remote items, see Remote items and shared folders.

Sharing and permissions

Items can be shared with other people through a a unique link for the recipient to access the shared items.

• New permissions can only be created with the createLink action.

Task	HTTP method (by ID)	HTTP method (by Path)
Create a sharing link	POST /drive/items/{item-id}/action.createLink	POST /drive/root:/{path}:/action.createLink
Read permissions	GET /drive/items/{item-id}/permissions	GET /drive/root:/{path}:/permissions
Remove permissions	DELETE /drive/items/{item-id}/permissions/{id}	DELETE /drive/root:/{path}:/permissions/{id}
Update permissions	PATCH /drive/items/{item-id}/permissions/{id}	PATCH /drive/root:/{path}:/permissions/{id}

Programming notes

API Compatibility

The OneDrive API will continue to evolve and gain additional functionality. The API includes a version number as part of the URL path, to ensure that we can make breaking changes to the API without impacting existing implementations. Breaking changes will be made by incrementing the version number in the URL, for calls that work differently than before.

We define a breaking change as a change in the format of a request or response that removes an existing documented behavior, or alters an existing documented behavior.

It is possible that the API will expose additional undocumented features from time to time. These features should not be depended on until they are documented. Do not assume that current behavior that deviates from the documentation will persist.

We will continue to make non-breaking changes to the existing version of the API, including adding facets, properties, and resources to the API. As such, any code calling the OneDrive API needs to:

• Be resilient to additional properties being added to JSON responses. Ignoring them is OK.
• Have no dependency on the order of properties returned in JSON responses.
• Use documented API paths, resources, properties, and enumerated values only. Non-documented values are not guaranteed to remain consistent.

Throttling

OneDrive has limits in place to make sure that individuals and apps do not adversely affect the experience of other users. When an activity exceeds OneDrive's limits, API requests will be rejected for a period of time. OneDrive may also return a Retry-After header with the number of seconds your app should wait before sending more requests.

HTTP/1.1 429 Too Many Requests  
Retry-After: 3600

Working with OneNote Notebooks

Note: Although OneDrive stores OneNote notebooks, you shouldn't use the OneDrive API to work with OneNote notebooks. Instead, use the OneNote API.

Related topics

The following topics contain high level overviews of other concepts that apply to the OneDrive API.

• Authentication and sign in
• Addressing resources
• Case sensitivity
• Error responses
• HTTP verb tunneling
• Pretty printing
• Terms of use

Documentation Validation Status

Our documentation is tested against the service on every change.