onedrive/onedrive-api-docs

Official documentation for the OneDrive API

OneDrive API Documentation

This repository is home to the OneDrive developer documentation. This includes documentation for a portion of the Microsoft Graph that accesses OneDrive and SharePoint content, and documentation for Office 365 file handlers and file pickers.

For easier navigation of content, we recommend consuming this content from the OneDrive Developer Portal or from https://docs.microsoft.com/onedrive/developer.

Contribute to OneDrive developer documentation

We welcome contributions from our community (users, customers, partners, MSFT employees, etc.) How you contribute depends on who you are:

• Community - minor updates: If you are contributing minor updates out of the goodness of your heart, you can find the article in this repository, or visit the article on https://docs.microsoft.com/onedrive/developer and click the Edit link in the article that goes to the GitHub source for the article. Then, just use the GitHub UI to make your updates. Or, you are welcome to fork the repository and submit updates from your fork.

• Community - new articles: If you're part of the OneDrive or SharePoint community and you want to create a new article, you need to work with an employee to help bring that new content in through a combination of work in the public and private repository.

• Employees: If you are a technical writer, program manager, or developer from the product team and it's your job to contribute to or author technical articles, you should use the repository in our Visual Studio instance. If you are making substantial changes to an existing article, adding or changing images, or contributing a new article, you need to fork this repository, install Git, a markdown editor, and learn some git commands. See the internal contributor's guide for more information.

About your contributions to OneDrive content

Minor corrections

Minor corrections or clarifications you submit for documentation and code examples in this repo are covered by the docs.microsoft.com Terms of Use.

Larger submissions

If you submit a pull request with new or significant changes to documentation and code examples, we'll send a comment in GitHub asking you to submit an online Contribution License Agreement (CLA) if you are not an employee of Microsoft. We need you to complete the online form before we can accept your pull request.

Tools and setup

Community contributors can use the GitHub UI or fork the repo to contribute. Employees should visit the internal contributor's guide for more information about how to contribute to the technical documentation set.

Repository organization

The content in the onedrive-api-docs repository follows the organization of documentation on https://docs.microsoft.com/onedrive/developer. This repository contains a few root folders:

\docs

The \docs folder contains the documentation articles formatted as markdown files with an .md extension.

The \docs folder contains the \media folder for root directory article media files, such as inline images.

\templates

The \templates folder contains markdown formatted topic templates when adding a new API or resource to the repository. Please use these templates when authoring a new topic.

\tests

The \tests folder contains configuration and Markdown-Scanner scenario definitions which are used for automated testing of the documentation. All pull requests to update the documentation will be validated using these tests, which validate consistency of the documentation and verify that the API implementation matches the documentation.

How to use markdown to format your topic

All the articles in this repository use GitHub flavored markdown. Here's a list of resources.

• Markdown basics

Microsoft Open Source Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

onedrive-api-docs's Issues

One drive API adding # after [Redirect URI]

I was quickly trying to get a access token by using a sample MVC project.

I tried to use "Token flow" and sent a request to

https://login.live.com/oauth20_authorize.srf?client_id={client_id}&scope={scope}
&response_type=token&redirect_uri={redirect_uri}

with my data filled in the {}.

The response I get back has following URL format (using {} identifier to omit long and actual query parameters values):
http://mytestdomain.com/my-apps-redirect-uri#access_token={access_token_demo_value}&authentication_token={authentication_token_demo_value}&token_type=bearer&expires_in={expires_in_demo_value}&scope={scope_demo_value}&user_id={user_id_demo_value}

If you look closely then you will observe that the URL contains a # right after the redirect URL.

Is this normal?
This makes it hard to extract all query string parameters within a controller's action. In this case it may work (not tried yet) if I make new exclusive entry for this type of URL pattern in my application's MVC route configurations to work around this, this would not be recommended IMO.

Ideally I (as an application) would expected a ? instead of #

Awaiting response from OneDrive API dev. team or a good reason on why # instead of standard ? to begin query string.

Thanks

@name.conflictBehaviour is set to replace by default

According to https://github.com/OneDrive/onedrive-api-docs/blob/master/items/create.md @name.conflictBehavior is set to "fail" by default. However, it appears to be set to "replace". I attempted to upload files using both the Simple item upload and the Resumable Upload. In both cases, the file was replaced unless I explicitly set it to "fail".

Logged-in user profile

I want to get the logged-in user's email address and other information.

In the old API, I got it through this URL: https://apis.live.net/v5.0/me
and by specifying the wl.emails scope.

In the new OneDrive API, I tried this URL: https://api.onedrive.com/v1.0/drives/me
and specified the wl.emails scope but only got the following information:

{
"quota": {
"total": 32212254720,
"remaining": 1562125249,
"used": 30650129471,
"deleted": 57979,
"state": "nearing"
},
"id": "",
"driveType": "personal",
"@odata.context": "https://api.onedrive.com/v1.0/$metadata#drives/$entity",
"owner": {
"user": {
"displayName": "My Name",
"id": ""
}
}
}

Does someone know how to get more user information through the new API?
Thank you !

Item resource doesn't include sharing information

Looking at the item resource, there's not information about the sharing of the item.

For example, if a folder is shared (View Only) with email [email protected], and (Edit) with email [email protected], that information is not available in any facet.

problem with error response json format

did the following 2 different operation

1. GET /driv
   wrong spelling for drive
2. GET /drive/item/1D641CFAE05579A4!1160
   wrong spelling for items
3. GET /drive/items/1D641CFAE05579A4!1160 (this folder has been deleted)
   nothing wrong in uri

following are the response received

1. & 2) same correct error response
   

2. something wrong with error response message
   

i think this question has been raised before also, but the question arise for wht kind of uri/operations is inproper json response is been send from the server

Clarify OAuth Scope Documentation

I had a hard time finding information on scope for OAuth token creation.

• I read the OAuth page
• I searched the repository for "scope"

There are actually values posted here. These don't seem to show up well in the repository search, and the links in the above section skip down to token and code flow, which may cause users to skip over it.

Does this seem like an issue worth starting a conversation on?

Writable File Metadata

Are metadata options like 'description' or 'tags' going to be re-implemented into this API?

It's rather useful to have custom metadata to sort and search by.

resumable upload return bad request

I try to use resumable upload and got bad request but I have not idea what is wrong with my requests

command upload file named '20M' to 'M870/Sheet Music/I.Orchestra Works(Symphonies, Concertos, Overtures...)/Peter Ilyitch Tchaikovsky(1840-1893)/II. Overtures and Symphonic Fantasies/The Tempest, Symphonic Fantasia after Shakespeare/b'

the response is:
HTTP Error 400. The request URL is invalid.

but if I use simple upload api to upload to the same path, the result is OK.

if I shorten the destination to 'M870/Sheet Music/I.Orchestra Works(Symphonies, Concertos, Overtures...)/Peter Ilyitch Tchaikovsky(1840-1893)/II. Overtures and Symphonic Fantasies/The Tempest, Symphonic Fantasia after/b', it works fine.

I have no idea about this situation and I think I do not exceed the max folder path length.
or there's any reserved word I met?

If conflictBehavior is set to rename, Item resource is returned for original file instead of newly created one

Hi,

I'm experimenting with the resumable item upload. Since I haven't implemented the other upload methods yet, I don't know if this issue is isolated to this upload method.

I'm setting the "@name.conflictBehavior": "rename" option in the upload session, and uploading a simple file.

When the file is completely uploaded, I get a 201 created response from the server. However, the server response body contains the information about the original file.

For example, I'm uploading "a.txt", which already exists. I try to upload "a.txt" with the conflict behaviour set to rename. It correctly creates the file ("a 1.txt", for example). However, the response contains the Item resource for the conflicted file name ("a.txt") and not the newly created one.

I don't see how I can get the correct Item resource for the newly created file.

error code and error message problem, when requesting for operations using access_token (expired) passed in request header

did the following 4 operations

1. GET /drive/root
   with access_token expired in the request header
2. GET /drive/root
   without passing access_token in the request header
3. GET /drive/root
   with access_token expired in the query parameter
4. GET /drive/root
   without passing access_token in the query parameter

the following are the response received
1)
with access_token expired in the request header

without passing access_token in the request header

with access_token expired in the query parameter header

without passing access_token in the query parameter

comparison

Q1) some thing when passing expired access_token as request header?
Q2) why same type response is received when access_token is not passed as request header/query parameter compared with expired access_token in query paraemter???

Clarify example requests to include version

On the documentation overview page, a bunch of example HTTP requests are provided. These examples are super useful. But these requests don't actually work.

If you send a query for GET /drive, the API will return a 400. API users actually need to send GET /v1.0/drive. This was initially confusing for me and led to errors.

I know that the URL root section tries to clarify this, but the examples should be accurate if they are being described in precise terms as HTTP requests.

wrong HTTP method used when requesting for access_token

steps followed
step 1) requesting for access_token, using the url on different clients
a. firefox
b. advanced REST client (crome addon)

POST https://login.live.com/oauth20_token.srf
Content-Type: application/x-www-form-urlencoded

client_id={client_id}&redirect_uri={redirect_uri}&client_secret={client_secret}
&refresh_token={refresh_token}&grant_type=refresh_token

*** following are the response received from different clients

1. advanced REST client (crome browser addon)
   Receiving the error, refer snapshot
   

2. firefox broswer
   Successfully received access_token
   

comparison

when used GET method for the same from advanced REST client
successfully received access_token

so the request should be GET not POST(as mention in github page)

support for MD5 checksums

This is a request to support MD5 checksum. Google Drive provides this value as part of their API, way back to their original API. It comes in handy to have a MD5 value to check to validate the integrity of files.

Wrong file size reported for small images

When a PNG file is displayed in win7 operating system disk file size is 158 bytes, and the file is uploaded to onedrive display the file size is 376 bytes, and why?

received wrong response (wrong parameter) for access_token (request)

did the following steps (grant_type=authorization_code)
step1) requested for authorization_code -> received successfully
step2) using the code(from step1) requesting for access_token -> receives the access_token successfully with other parameters

***the json format received was not as been mention in the github page(https://github.com/OneDrive/onedrive-api-docs/blob/master/auth/msa_oauth.md)

eg
{
"token_type":"bearer",
"expires_in": 3600,
"scope":"wl.basic onedrive.readwrite",
"access_token":"EwCo...AA==",
"authentication_token":"eyJh...93G4",
"refresh_token":"eyJh...9323"
}

the problem is with parameter "authentication_user", never received this parameter in response

we are receiving parameter "user_id" which is not mention on github page

NuGet package?

Is there a plan to create a NuGet package for the new API?

In pure WebAPI model, how to use serverside LiveSDK ?

Hi,

I am writing an WebAPI application, which authenticates user with their LiveID credentials from server side.
I have written a filter implementing System.Web.Http.Filters.IAuthenticationFilter which defines the method
AuthenticateAsync(HttpAuthenticationContext context, CancellationToken cancellationToken)

for authentication. The method has parameter HttpAuthenticationContext. However when I try to use below code, I cant get the required context.

LiveAuthClient authClient = new LiveAuthClient(...)
var result = await authClient.ExchangeAuthCodeAsync(???);

the ExchangeAuthCodeAsync() expects HttpContextBase parameter.

In my MVC application, the IAuthorizationFilter.OnAuthorization(AuthorizationContext filterContext) provides the HttpContextBase from its RequestContext as below.

var result2 = await authclient.ExchangeAuthCodeAsync(
filterContext.RequestContext.HttpContext.ApplicationInstance.Context)

Is there equivalent in API ? I am trying to avoid using System.Web.HttpContext.Current for cleaner code.

Regards,
Amit Rangari

Upload sessions don't support zero length files

Upload sessions don't appear to support 0-length files. Is this intended?

In the first upload fragment, I tried setting the "Content-Length" to 0, and setting the "Content-Range" to values like: "0/0", "0-0/0", or not using that header at all, but I get a 400 Invalid Argument error.

I ended up using the Simple Item upload method to implement this.

Should the documentation be updated, or should the upload session support empty files?

How do I update the sharing of a file/folder

As a follow-up to issue #56, is there a way to set the sharing details of an item?

For example, assign Edit "permissions" to email [email protected] ??

id value not returned in response to select query as specified

wanna bring in notice
http://stackoverflow.com/questions/29006895/id-value-not-returned-in-response-to-select-query-as-specified

User sign out not working properly

How does the user signing out work? According to the API docs I need to make a call to the below url

GET https://login.live.com/oauth20_logout.srf?client_id={client_id}&redirect_uri={redirect_uri}

But if I don't pass the access_token/refresh_token, how the end user is supposed to be logged out of the system? What does the above API do actually? Because after making a call to the above API, I can still use the old access_token to make calls; tokens are not getting revoked. So how to sign out/revoke the access for an end user?

the query parameter "lc" not received in the error_response uri

the following steps perform on android device (using webview client)

1. made the first request to get code using the uri
   "https://login.live.com/oauth20_authorize.srf?client_id=000000004813EF9B&scope=wl.signin%20wl.offline_access%20onedrive.readwrite%20wl.emails&response_type=code&redirect_uri="
   

2)successfully submitted username and password

3)new page pop up to get permission/scope to let app use info

***4) pressed no

***5)in RESPONSE should get error uri as specified
eg "https://login.live.com/err.srf?lc=1033#error=unauthorized_client&error_description=The%20client%20does%20not%20exist.%20If%20you%20are%20the%20application%20developer%2c%20configure%20a%20new%20application%20through%20the%20application%20management%20site%20at%20https://manage.dev.live.com/."

with the query parameter (https://github.com/OneDrive/onedrive-api-docs/blob/master/auth/msa_oauth.md)
1)lc
2)error
3)error_description

the problem arise here, in RESPONSE received only the following parameter
1)error
2)error_description

the query parameter "lc" not received in the uri

the above mention problem is creating a lot problem with the app in which we are integrating the onedrive, due to change in response error structure, code written couldnot detect the error

change list information question

I move a folder into other folder

the change list return will contain all the sibling folder.

e.g.
folder A contain B, C, D folder
I move folder E into A
the changelist return will contain B, C, D

I think it is strange to get change about B, C, D

Is this a bug?

Thanks.

why access_token valid even after changing the password

did the following steps:

1. got the new access_token and refresh_token
2. query using the obtained access token
   *** 3) now changed the password of the account
3. still can query using the old access token(step 1)

why still old access token valid??? it should not be valid once password changed otherwise for 1 hr it is vulnerable

continued with the steps
5) tried to get new access token and refresh token using the old refresh_token obtained from step 1

got the following response
{"error":"invalid_grant","error_description":"The user could not be authenticated or the grant is expired. The user must first sign in and if needed grant the client application access to the requested scope."}

6. even after getting the above error ,still can query using the access_token(step 1)

why so access_token is valid after changing password also and getting error for demanding new access_token(step 5)???

action.copy does not work for files

[Forking bug from https://github.com//issues/15 to track the issues separately]

It appears as though such a copy request gets stuck in a state whereby it's not processed.

What is OAuth authentication_token used for?

At OneDrive authentication and sign-in page, in Code flow section.

"Step 2. Redeem the code for access tokens" returns response that contains "authentication_token" along with other data like access and refresh token.

I might be asking silly question here but as I am not aware yet, I would like to know - what is "authentication_token" used for?

Context: access_token is used for authenticated calls to API and refresh_token used for fetching new access_token when the current one expires. authentication_token is used for .... ?

Thanks

status code differed with the API doc if Insufficient Storage

I try to test the quota full exception and got the response:
< Response [500] > {u'error': {u'message': u'Insufficient Space Available', u'code': u'generalException'}}

But according to http://onedrive.github.io/misc/errors.htm,
the insufficient storage should return status_code with 507.

If this is a bug, would this status code changed to 507 in the future?
Thanks.

Access to all special folders

While I can access every special folder in the root directory using the /drive/special/{special-folder-name} syntax (even "music", which is not documented), it seems to be impossible to access nested special folders, like "xboxGameDVR", "savedPictures" and "mobilePhotos", all under the "photos" folder.

Is there a way to do that. Am I missing something?

I'm trying to develop an app which saves pictures to OneDrive, and I'd like to use the "savedPictures" folder.

rename could not use path-based uri

when rename an item, I got error when use the path-base URI.

Now I use item_id instead, is this a bug ?

Thanks!

need to be more clear what the payload is for "Simple item upload to OneDrive using PUT"

need to be more clear what the payload is for "Simple item upload to OneDrive using PUT"
http://onedrive.github.io/items/upload_put.htm

have no idea what kind of content i should put into payload, e.g if i want to upload an png or jpeg, do i just dump all the binary there? (doesn`t seems like the case)

/drives endpoint

/drives List Drives available to the authenticated user.

There is Drives endpoint which returns available drives for user. And I can't understand how to add second drive to my personal account to test it. Can user have several drives in his account? How can I add second drive to my account?

Upload sessions with fail conflictBehavior return error after first fragment rather than upon creation

If an upload session is created with @name.conflictBehavior set to "fail", the item path is specified at that time. It should be possible to check for the conflict at that time.

However, instead the API returns a 409 Conflict after the first fragment is uploaded.

Is this intended behaviour? Note that if the conflicted remote file is deleted between the session creation and first fragment, no error occurs.

Contrast this with the behaviour when the parent folder does not exist, where the error is returned on the creation of the upload session.

API call to get email address

pls include api call to get the "email address" of the OneDrive account

Large file upload does not work with non-ascii file names

How to reproduce:

1. Create upload session for file name with non-ascii characters
   POST https://api.onedrive.com/v1.0/drive/root:/Документ.docx:/upload.createSession
   It will respond with 200 OK and file upload URL
2. Try to use this url to upload file or check session state
   GET UploadUrl
   It will report 400 Bad Request
   Body contains
   {"error":{"code":"invalidArgument","message":"Upload session failed","innererror":{"code":"uploadSessionFailed"}}}

Also it works fine for simple uploads like
PUT https://api.onedrive.com/v1.0/drive/root:/Документ.docx:/content

Documentation missing 509 Error response

Here, various errors are listed http://onedrive.github.io/misc/errors.htm

I was able to get a 509 error code (bandwidth limited exceeded) when downloading files, which isn't listed in the table The header returns an "x-clienterrorcode" of "UsageRestricted". There is also no "Retry-After" header or JSON object returned.

how long is alive @content.downloadUrl?

how long is alive @content.downloadUrl?
I want to save time by not requesting a new url every time I need it.

Clarify scope for creating share link

Seems like the scope required to create share links is onedrive.readwrite, would be nice to add a note about that

http://onedrive.github.io/items/sharing_createLink.htm
https://github.com/OneDrive/onedrive-api-docs/blob/master/items/sharing_createLink.md

Creating a folder returns an invalid location header

Creating a folder with POST /v1.0/drive/items/{itemId} returns a location header of the format https://api.onedrive.com/v1.0/drives('{driveId}')/items('{itemId}')/children('{newFolderId}'). However this URL is not valid, following it returns a 404 Not Found error. In addition I wonder why a location header is present in the response at all - all necessary information is included in the item which is returned in the response body.

optinal request headers such as "if-none-match: etag"

as mention on the github page items/get.md, items/list.md and others...
"if-none-match : If this request header is included and the etag provided matches the current etag on the file, an HTTP 304 Not Modified response is returned."

so providing the same eTag value that at the server, still in response getting items object with response code 200, never get 304 code in response, as specified above

onedrive api in localhost

Hi,

How to test the onedrive api in localhost ?

Thanks,
SVNindia

lastModifiedDateTime from Item does not match OneDrive Web/Desktop UI

Files and folders in OneDrive don't seem to have Modified dates that match between OneDrive Web and Desktop and the API.

Note: My local timezone is UTC-4; it was UTC-5 at the time of creation.

For example, I have one file with the following properties:
Web UI: Modified: 11/18/2014
Windows 8.1 OneDrive Sync: Date modified: 11/18/2014 10:32:34PM
Item resource lastModifiedDateTime: 2015-03-25T19:13:08.283Z
(The Item resource createdDateTime is: 2015-03-25T19:13:08.283Z)

The folder:
Web UI: Modified: 2/17/2015
Windows 8.1 OneDrive Sync: Date modified: 2/17/2015 3:44:23AM
Item resource lastModifiedDateTime: 2015-03-25T19:46:20.57Z
(The item resource createdDateTime is: 2015-02-17T08:44:23.903Z)

Are the OneDrive Web UI and Desktop clients using some other metadata to store modified dates? Is this accessible to the OneDrive API?

Is it possible to delete a file into recycle bin ?

Is there any way to implement delete operation like WEB UI does to move items into recycle bin?

Or I could use move command and indicate specific folder name recyclebin ?

I have been search for this for old API, but it does not support and found that:
http://stackoverflow.com/questions/23845368/is-there-any-way-of-accessing-recycle-bin-functions-of-onedrive

I wonder if this could be pulled as a request? cause I think its more safe to move file into recycle bin rather than real delete it.

thanks!

attribute 'picture' is missing in video items

Hi,
Attribute 'picture' is missing in video items.
it is present in video object in skydrive api.
Refer: https://msdn.microsoft.com/en-us/library/dn631849.aspx

Facing problem with logout

did the following steps for logout

1. GET "https://login.live.com/oauth20_logout.srf?client_id=000000004813EF9B&redirect_uri="

response received -> "https://login.live.com/err.srf?lc=1033#error=invalid_request&error_description=The+provided+request+must+include+a+'redirect_uri'+input+parameter."

    Q1) why "redirect_uri" query parameter value is being demanded???

Response to fragment upload does not include nextExpectedRanges property

According to http://onedrive.github.io/items/upload_large_files.htm the response to a fragment upload shall include a nextExpectedRanges property if the response status code is 202. This property is missing in the response.

Reproduced with apigee.com:

--- Request: ---
PUT /up/{uploadSessionPath} HTTP/1.1
Authorization: Bearer {authToken}
Host: api.onedrive.com
Content-Length: 2
X-Target-URI: https://api.onedrive.com
Content-Type: text/plain; charset=UTF-8
Connection: Keep-Alive
Content-Range: bytes 0-1/16

AB
--- Response: ---
HTTP/1.1 202 Accepted
Date: {date}
X-MSNSERVER: {...}
P3P: CP="BUS CUR CONo FIN IVDo ONL OUR PHY SAMo TELo"
Content-Length: 58
Via: {...}
Connection: keep-alive
X-AsmVersion: UNKNOWN; 19.15.0.0
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0 Microsoft-HTTPAPI/2.0
X-WLSPROXY: {...}

{
"expirationDateTime": "2015-03-28T01:51:08.2520582+00:00"
}

Resumable Upload does not give nextExpectedRanges

When I have one thread PUTting partial content (e.g., bytes 0-65360/123456789) on the uploadUrl given by uploadSession, the response is simply HTTP 202 with body

{'expirationDateTime': '2015-03-13T03:42:23.7511359+00:00'}

without key nextExpectedRangs.
I thought I would get a nextExpectedRanges like ['655361-123456789']. Might this be a bug? If not then this behavior better be documented as I haven't read any indication that this param is optional.

Thanks for this new API! It is much better than the old Live API + BITS API combined.

Create.md specifies @name.conflictBehavior as a query string

This should be an instance annotation on the item itself, not a query string parameter.

Resume uploads can't replace

when use "@name.conflictBehavior": "replace", in uploading.

Still return file conflict error........
{"error":{"code":"nameAlreadyExists","message":"Relationship name already exists under the parent","innererror":{"code":"itemAlreadyExists","innererror":{"code":"relationshipNameAlreadyExists"}}}}

URLs for stylesheets/scripts and links in header are broken in subfolders

The various relative URLs for stuff are broken on the site when not in the root folder. For example, check the source on the page about viewing changes:

<link rel="stylesheet" href="..\stylesheet.nav.css" />
<!-- [...] -->
<img src="..\onedrive_api_blue.png" height="24" alt="OneDrive API" align="absmiddle">
<!-- [...] -->
<li class="active"><a href="..\README.htm">Documentation</a></li>
<!-- [...] -->
<li ><a href="..\sample-code.htm">Samples</a></li>
<!-- [...] -->
<script src="..\ie10-viewport-bug-workaround.js"></script>

This causes those images/scripts to not load and the links to not work.

AsyncOperationStatus status strings mismatch

In the document page http://onedrive.github.io/resources/asyncJobStatus.htm,
the status strings are like "notStarted", but what is really returned can be "NotStarted" as in

{
'status': 'NotStarted', 
'statusDescription': 'Completed 0/0 files; 0/0 bytes', 
'percentageComplete': 0.0, 
'operation': 'ItemCopy'
}

This may be a typo and better be corrected for consistency.

(BTW, I have been waiting for one hour for this ItemCopy thing to complete, but it hasn't even started...)