chillypenguin / onedrive-api-docs

Official documentation for the OneDrive API

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.

Use the OneDrive API

To use the OneDrive API, first get an access token that authenticates your app with a particular set of permissions for a user. Then call the OneDrive API with your access token against the URL root below, combined with one of the root resources.

URL root

OneDrive API URLs are relative to the following root unless otherwise noted.

Service	URL Root
OneDrive	https://api.onedrive.com/v1.0

API versions

OneDrive uses a version number in the URL. Be sure to include the version immediately after the host name, or the URL won't work.

https://api.onedrive.com/v1.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 in order to obtain the full resource path or URL.

Authentication

OneDrive uses OAuth 2.0 for authentication. You can provide an authentication token for each API call in two different ways:

• An HTTP header: Authorization: bearer {token}
• A query parameter: ?access_token={token}

For details about obtaining and authentication token and signing the user in, see authentication.

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, see Resources.

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.changes
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.changes	GET /drive/root:/{path}:/view.changes

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.

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/{id}/action.createLink	POST /drive/root:/{path}:/action.createLink

Programming notes

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

Related topics

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

• Addressing resources
• Case sensitivity
• Error responses
• HTTP verb tunneling
• Pretty printing
• Terms of use