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.
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.
OneDrive API URLs are relative to the following root unless otherwise noted.
Service | URL Root |
---|---|
OneDrive | https://api.onedrive.com/v1.0 |
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.
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.
The OneDrive API exposes two major resource types:
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
andname
) expose simple values. - Facets (like
file
andphoto
) expose complex values. The presence offile
orfolder
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.
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. |
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.
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 |
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.
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 |
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
The following topics contain high level overviews of other concepts that apply to the OneDrive API.