REST reference

The Live Connect Representational State Transfer (REST) API enables apps that work with Live Connect to access info programmatically about users, their contacts and friends, their web-based activities and personal status, their media stored on Microsoft OneDrive, and more.

This topic contains the following sections:

• Supported HTTP verbs
• Support for resumable downloads
• Understanding the objects
• Query parameters
• Structure value options
• Album object
• Audio object
• Calendar object
• Comment object
• Contact object
• Error object
• Event object
• File object
• Folder object
• Friend object
• Permissions object
• Photo object
• Search object
• Tag object
• User object
• Video object
• Additional URL parameters

Supported HTTP verbs

The Live Connect REST API supports the standard HTTP verbs.

• GET—Returns a representation of a resource.
• POST—Adds a new resource to a collection.
• PUT—Updates a resource at the location pointed by the URL or creates a new resource, if it doesn't exist.
• DELETE—Deletes a resource.
• MOVE—Moves the location of a resource.
• COPY—Duplicates a resource.

Request URLs must reference https://apis.live.net/v5.0/, followed by the path for the object you are working with, any parameters, and finally, the access token (represented here as ACCESS_TOKEN).

https://apis.live.net/v5.0/me/albums?access_token=ACCESS_TOKEN

Top

Support for resumable downloads

Live Connect provides support for resumable downloads by using the HTTP Range header. If a download is interrupted, an app can continue the download at a later time by requesting only the byte range for the remainder of the file. This is particularly useful when downloading larger files, or in situations where network reliability is less than optimal.

Top

Understanding the objects

In the Live Connect REST API, each category of info is contained in an object. Objects consist of a combination of child objects, arrays, and values. To access a specific object, you need to know the unique path to, and in many cases, the unique ID of, that object.

The following table lists the objects that are supported by Live Connect REST API requests, along with valid object paths.

In the preceding table, replace USER_ID, CONTACT_ID, ALBUM_ID, PHOTO_ID, VIDEO_ID, AUDIO_ID, or FOLDER_ID with the target user ID, Contact object ID, Album object ID, Photo object ID, Video object ID, Audio object ID, or Folder object ID respectively.

In the preceding table, you can use /me as a shortcut for the signed-in user instead of specifying /USER_ID. However, you cannot use /me unless you also provide an access token.

The Live Connect REST API exchanges info between apps, Live Connect, and OneDrive in JavaScript Object Notation (JSON) format. (Because of this, the JSON terms structure, object, array, and value are used throughout this reference.)

When your app makes a GET request for an object, the Live Connect REST API returns the requested info as a JSON-formatted structure. Similarly, when your app makes a POST or PUT request, the Live Connect REST API requires the info to be submitted to it as a JSON-formatted structure. For more info about JSON, see Introducing JSON (http://www.json.org).

Top

Query parameters

Query parameters can be added to the end of the request URL to modify the information returned in the response. The parameters described in this section are used to specify a particular subset of the response. Additional URL parameters can also be added to specify how to return the results.

Filter query parameter

You can use the filter query parameter to specify the types of items to return when requesting OneDrive items, as shown here.

/FOLDER_ID/files?filter=albums

The following values are supported:

• albums

• audio

• folders

• photos

• videos

When specifying multiple values, use a comma-delimited list like this.

/FOLDER_ID/files?filter=videos,audio

The filter query parameter is supported for any request that returns a list of OneDrive items, for example, queries ending in /files, or /shared.

Limit query parameter

The limit parameter restricts the number of entries returned. This example uses the limit query parameter so that the command returns only the first two of the user's contacts.

me/contacts?limit=2

You can use this parameter with the offset parameter to select specific entries within a collection.

Offset query parameter

The offset parameter specifies the first entry to return from a collection. This example uses the offset parameter with the limit parameter to return two of the user's calendar entries, starting with the third one. That is, it will return entries 3 and 4 from the user's calendar.

me/calendars?limit=2&offset=3

You can use this parameter with the limit parameter to select specific entries within a collection.

Search query parameter

The q parameter is used to search a user's OneDrive for objects that contain the specified text. See the Search object for more info about the search results.

This example returns all objects in the user's OneDrive that contain the string, "family".

me/skydrive/search?q=family

You can also use the limit and the offset parameters to select specific entries within the search results. With a search operation, a default value of 100 is used if the limit parameter is not specified. Consequently, large search results will be automatically returned in groups of 100, if a limit parameter is not specified.

Top

Structure value options

In the following sections, the column labeled "R/W" indicates whether a value is read-only or read/write, and the column labeled "Required on create" indicates whether a value is required for the creation of an object.

Top

Album object

The Album object contains info about a user's albums in Microsoft OneDrive. Albums are stored at the root level of a user's OneDrive directory, and can contain combinations of photos, videos, audio, files, and folders. The Live Connect REST API supports reading Album objects. Use the wl.photos scope to read a user's Album objects. Use the wl.skydrive scope to read a user's files. Use the wl.contacts_photos scope to read any albums, photos, videos, and audio that other users have shared with the user.

The Album object contains the following structures.

The following is an example of a collection of Album objects. (For brevity, only the first object is shown.)

{
   "data": [
      {
         "id": "album.8c8ce076ca27823f.8C8CE076CA27823F!126",
         "from": {
            "name": "Roberto Tamburello",
            "id": "8c8ce076ca27823f"
         },
         "name": "My Sample Album 1", 
         "description": "",
         "parent_id": "folder.de57f4126ed7e411",
         "upload_location": "https://apis.live.net/v5.0/folder.de57f4126ed7e411.DE57F4126ED7E411!126/files/",
         "is_embeddable": true
         "count": 4, 
         "link": "https://cid-8c8ce076ca27823f.skydrive.live.com/redir.aspx?page\u003dself\u0026resid\u003d8C8CE076CA27823F!126\u0026type\u003d5", 
         "type": "album",
         "shared_with": {
            "access": "Everyone (public)"
         },
         "created_time": "2011-04-21T23:19:47+0000", 
         "updated_time": "2011-04-22T19:18:12+0000"
      }, {
         ...
      }
   ]
}

To get a collection of Album objects by using the Live Connect REST API, make a GET request to /me/albums.

To create a new Album resource, make a POST request to /me/albums. Pass the name and description attributes in the request body, as shown here.

{
   "name": "Vacation 2011",
   "description": "Photos from our fun vacation."
}

To update the properties of an Album, make a PUT request to /ALBUM_ID. Pass the attributes to update in the request body, as shown here.

{
   "name": "Maui Vacation 2011",
   "description": "Photos from our vacation on Maui."
}

To delete an album, make a DELETE request to /ALBUM_ID.

Top

Audio object

The Audio object contains info about a user's audio in OneDrive. The Live Connect REST API supports creating, reading, updating, and deleting Audio objects. Use the wl.skydrive scope to read Audio objects. Use the wl.contacts_skydrive scope to read any audio that other users have shared with the user. Use the wl.skydrive_update scope to create, update, or delete Audio objects.

The Audio object contains the following structures.

The following is an example of a collection of Audio objects. (For brevity, only the first object is shown.)

{
   "data": [
      {
         "id": "file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!144", 
         "from": {
            "name": "Stig Struve-Christensen", 
            "id": "a6b2a7e8f2515e5e"
         }, 
         "name": "SampleAudio.mp3", 
         "description": null, 
         "parent_id": "folder.a6b2a7e8f2515e5e", 
         "size": 8414449,
         "upload_location": "https://apis.live.net/v5.0/file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!144/content/",  
         "comments_count": 0, 
         "comments_enabled": false, 
         "is_embeddable": false, 
         "source": "http://storage.live.com/s1p60U8Xs4UzIXTScrTioalE-ZaVFiDQBA15MS2BwcsuNjfG64Z2fw-DAjXnPuqC47YR40_xAoPD8aRGhtna9ZFZ9_oO4BTz4CWF973DTXMxc5U3TntcQ9qEA/SampleAudio.mp3:Binary", 
         "link": "https://skydrive.live.com/redir.aspx?cid\u003d22688711f5410e6c\u0026page\u003dview\u0026resid\u003d22688711F5410E6C!582\u0026parid\u003d22688711F5410E6C!581",
         "type": "audio",
         "title": "My Sample Audio",
         "artist": "My Favorite Artist",
         "album": "My Favorite Album",
         "album_artist": "My Favorite Artist", 
         "genre": "Easy Listening", 
         "duration": 225000,
         "picture": "https://storage.live.com/items/A6B2A7E8F2515E5E!144:MobileReady/SampleAudio.mp3?psid=1&ck=0&ex=720"   
         "shared_with": {
            "access": "Just me"
         }, 
         "created_time": "2012-09-23T22:00:57+0000", 
         "updated_time": "2012-09-03T22:00:57+0000"
      }, {
         ...
      }
   ]      
}

To create a new Audio resource, you can make either a PUT request with the audio in the body or a POST request with the audio in a multipart form body. For POST, make a POST request to the /UPLOAD_LOCATION for the target folder, or a POST request to /FOLDER_ID/files. You must format the request as a multipart/form-data media type as described in RFC 2388. You must specify the Content-Type as multipart/form-data, and specify the boundary like this.

Content-Type: multipart/form-data; boundary=AaB03x

Provide the item to upload on a multipart section, and the name of the audio as the value of the filename parameter of the Content-Disposition header, as shown here.

Content-Type: multipart/form-data; boundary=AaB03x
--AaB03x
Content-Disposition: form-data; name="file"; filename="SampleAudio.wav"
Content-Type: audio/mp3

...contents of SampleAudio.wav...
--AaB03x--

Only one multipart section per request is supported. For a PUT request, leave the Content-Type blank and put the contents of the file in the request body.

Upon successful creation, the location header points to the location for the newly created audio, and the response body contains the following properties.

{
   "id": "ID of the new audio",
   "name": "The file's name and file extension",
   "source": "URL where the audio can be downloaded from"
}

You can upload an audio to an existing resource in any of the following ways.

• Make a PUT request to /UPLOAD_LOCATION/FILE_NAME for the folder you would like to upload to.

• Make a PUT request to /FOLDER_ID/files/FILE_NAME.

• Make a PUT request to /ALBUM_ID/files/FILE_NAME.

• Make a PUT request to /UPLOAD_LOCATION for the file to update.

• Make a PUT request to /AUDIO_ID/content.

To update the properties for an Audio resource, make a PUT request to /AUDIO_ID, and specify the changes in the request body, as shown here.

{
   "name": "SampleAudioChanged.wav"
   "description": "Holiday Concert"
}

To delete an audio, make a DELETE request to /AUDIO_ID.

To move an audio, make a MOVE request to /AUDIO_IF or /FOLDER_ID, and specify the ID of the destination folder in the request body, as shown here.

{
   "destination": "FOLDER_ID"
}

To copy an audio, make a COPY request to /AUDIO_ID or /FOLDER_ID, and specify the ID of the destination folder in the request body, as shown here.

{
   "destination": "FOLDER_ID"
}

For PUT and POST requests, you can use the overwrite query string parameter to indicate whether the request should fail if the resource already exists, as shown here. Optionally you can specify an overwrite query-string parameter value of ChooseNewName if you want to upload a duplicate copy of the file but let OneDrive choose the uploaded file's new file name. Note that MOVE and COPY do not support overwriting at this time.

overwrite=true
overwrite=false
overwrite=ChooseNewName

If the value of the overwrite query string parameter is set to true, and the audio exists, it is overwritten. If the value is set to false, the audio is not overwritten, and a resource_already_exists error is returned. If no overwrite query string parameter is specified, the default value is true.

Top

Calendar object

The Calendar object contains info about a user's Outlook.com calendar. The Live Connect REST API supports creating, reading, updating, and deleting calendars. Use the wl.calendars scope to read a user's Calendar objects. Use the wl.calendars_update scope to create Calendar objects for a user. Use the wl.contacts_calendars scope to read a user's friends' Calendar objects.

The Calendar object contains the following structures.

The following is an example of a collection of Calendar objects. (For brevity, only the first object is shown.)

{
   "data": [
      {
         "id": "calendar.42d4dbc866f94c83849c88c6eb9985bc", 
         "name": "Birthday calendar", 
         "description": "If you have birthdays listed for your contacts, they'll appear on this calendar. You can add more birthdays, but you can't add other types of events.", 
         "created_time": "2011-08-05T19:41:04+0000", 
         "updated_time": "2011-08-05T19:41:04+0000", 
         "from": {
            "name": null, 
            "id": null
         }, 
         "is_default": false, 
         "subscription_location": null, 
         "permissions": "read"
      },{
         ...
      }
   ]
}

To get a collection of Calendar objects by using the Live Connect REST API, make a GET request to either /me/calendars, or /USER_ID/calendars.

To get the properties for a particular Calendar object, make a GET request with the ID of the calendar.

https://apis.live.net/v5.0/calendar.b4466224b2ca42798c3d4ea90c75aa56?access_token=ACCESS_TOKEN

To create a new Calendar, make a POST request to either /me/calendars, or /USER_ID/calendars. Pass the name (required) and summary (optional) strings as properties in the request body. The properties for the new calendar are returned in the response body, and the Location header contains the Uniform Resource Identifier (URI) for the newly created calendar.

{
   "name": "Summer Events",
   "summary": "Things we are doing this summer."
}

To subscribe to a public calendar, make a POST request to either /me/calendars or /USER_ID/calendars. Pass the name and subscription_location strings as properties in the request body. The value of subscription_location must be a valid online iCal calendar. Both properties are required.

{
   "name": "Soccer League"
   "subscription_location": "ical.sharedcalendars.com/98754auv"
}

To update a Calendar, make a PUT request to /CALENDAR_ID. Include the properties to update in the request body, as shown here.

{
   "name": "Fall Happenings"
}

To delete a Calendar, make a DELETE request to /CALENDAR_ID.

In the preceding examples, replace CALENDAR_ID with the target calendar ID.

Top

Comment object

The Comment object contains info about comments that are associated with a photo, audio, or video on OneDrive. The Live Connect REST API supports reading Comment objects. Use the wl.photos scope to read Comment objects. Use the wl.contacts_photos scope to read the Comment objects that are associated with any albums, photos, and videos that other users have shared with the user.

The Comment object contains the following structures.

The following is an example of a collection of Comment objects. (For brevity, only the first object is shown.)

{
   "data": [
      {
         "id": "comment.22688711f5410e6c.22688711f0410e6c!818.22688711F5410E6C!979",
         "from": {
            "name": "Roberto Tamburello", 
            "id": "8c8ce076ca27823f"
         }, 
         "message": "A lighthouse built on some rocks.", 
         "created_time": "2011-04-21T23:21:28+0000"
      }, {
         ...
      }
   ]
}

To get a collection of Comment objects by using the Live Connect REST API, make a GET request to /RESOURCE_ID/comments.

Top

Contact object

The Contact object contains info about a user's Outlook.com contacts. The Live Connect REST API supports reading Contact objects.

The Contact object contains the following structures.

When creating a new Contact object, at least one of the following attributes must be provided. These are marked as Optional in the preceding structures table.

• first_name
• last_name
• preferred (User object, emails structure)
• personal (User object, emails structure)
• business (User object, emails structure)
• other (User object, emails structure)
• name (User object, work array, employer structure)

The preferred, personal, business, other, and name structures belong to the User object. These attributes are not returned when getting a Contact object instance. However, it is possible to add these attributes when creating a new Contact object. Although the value cannot be directly returned, this behavior is handy in situations when you add a new contact by email address only, or if you want to create a contact that is a company. To ensure that the company name or email address appear in place of the contact name, omit the first_name and last_name fields. The email address or company name that you specify appears in place of the name in the returned Contact object instance.

Use the following JSON as a guide for defining the attributes in your request.

{
   "first_name": "",
   "last_name": "",
   "emails": {
      "preferred": "",
      "personal": "",
      "business": "",
      "other": ""
   },
   "work": [
      {
         "employer": {
            "name": ""
         }
      }
   ]
}

The following is an example of a collection of Contact objects. (For brevity, only the first object is shown.)

{
   "data": [
      {
         "id": "contact.b4466224b2ca42798c3d4ea90c75aa56", 
         "first_name": "Henrik", 
         "last_name": "Jensen", 
         "name": "Henrik Jensen", 
         "is_friend": false, 
         "is_favorite": false, 
         "user_id": null, 
         "email_hashes": [
            "9ecdb19f4eb8e04304c5d1280368c42e85b6e4fe39f08b0c837ec592b905a620", 
            "fc05492f50da6488aa14dcf221d395bcb29a4e43b43b250d60c68df4f831cad3"
         ], 
         "updated_time": "2011-04-22T00:11:13+0000", 
         "birth_day": 29, 
         "birth_month": 3 
         
      }, {
         ...
      }
   ]
}

To get a collection of Contact objects by using the Live Connect REST API, make a GET request to /me/contacts.

Top

Error object

The Error object contains info about an error that is returned by the Live Connect APIs.

The Error object contains the following structures.

The following is an example of an Error object.

{
   "error": {
      "code": "request_token_expired", 
      "message": "The provided access token has expired."
   }
}

Top

Event object

The Event object contains info about events on a user's Outlook.com calendars. The Live Connect REST API supports creating Event objects. Use the wl.events_create scope to create Event objects on the user's default calendar only. Use the wl.calendars scope to read Event objects on the user's calendars. Use wl.calendars_update to create Event objects on any of the user's calendars. Use the wl.contacts_calendars scope to read Event objects from the user's friend's calendars.

The Event object contains the following structures.

The following is an example of an Event object.

{
   "id": "event.611afb17fa9448f28cdb8277e8ffeb77.e9f015000d0249ce847c5306a25d7d75", 
   "name": "Global Project Risk Management Meeting", 
   "description": "Generate and assess risks for the project",
   "calendar_id": "calendar.611afb17fa9448f28cdb8277e8ffeb77",
   "from": {
      "name": "William Flash",
      "id": "de57f4126ed7e411"
   }, 
   "start_time": "2011-04-20T01:00:00+0000", 
   "end_time": "2011-04-20T02:00:00+0000", 
   "location": "Building 81, Room 9981, 123 Anywhere St., Redmond WA 19599", 
   "is_all_day_event": false, 
   "is_recurrent": false,
   "recurrence": null,
   "reminder_time": null,
   "availability": "busy", 
   "visibility": "public", 
   "created_time": "2011-03-14T23:01:31+0000",
   "updated_time": "2011-04-19T20:23:03+0000"
}

To return a list of events for a calendar by using the Live Connect REST API, make a GET request to /CALENDAR_ID/events. This will return all events between now and the next 30 days by default.

To return a list of events for a user, make a GET request to either /me/events, or /USER_ID/events.

To retrieve the properties for an Event, make a GET request to /EVENT_ID.

To create an Event object on the user's default calendar by using the Live Connect REST API, make a POST request to /me/events. Pass the properties for the event in the request body, as shown here.

Content-Type: application/json

{
    "name": "Global Project Risk Management Meeting",
    "description": "Generate and assess risks for the project",
    "start_time": "2011-04-20T01:00:00-07:00",
    "end_time": "2011-04-20T02:00:00-07:00",
    "location": "Building 81, Room 9981, 123 Anywhere St., Redmond WA 19599",
    "is_all_day_event": false,
    "availability": "busy",
    "visibility": "public"
}

{
   "name": "Global Project Risk Management Meeting", 
   "description": "Generate and assess risks for the project", 
   "start_time": "2011-04-20T01:00:00+0000", 
   "end_time": "2011-04-20T02:00:00+0000", 
   "location": "Building 81, Room 9981, 123 Anywhere St., Redmond WA 19599", 
   "is_all_day_event": false,
   "is_recurrent": false,
   "recurrence": null,
   "reminder_time": null, 
   "availability": "busy", 
   "visibility": "public", 
   "updated_time": "2011-04-19T20:23:03+0000"
}

To delete an Event, make a DELETE request to /EVENT_ID.

Top

File object

The File object contains info about a user's files in OneDrive. The Live Connect REST API supports creating, reading, updating, and deleting File objects. Use the wl.skydrive scope to read File objects. Use the wl.contacts_skydrive scope to read any files that other users have shared with the user. Use the wl.skydrive_update scope to create, update, or delete File objects.

The File object contains the following structures.

The following is an example of a File object.

{
   "data": [
      {
         "id": "file.22688711f5410e6c.22688711F5410E6C!942", 
         "from": {
            "name": "William Flash", 
            "id": "22688711f5410e6c"
         }, 
         "name": "Processing.docx", 
         "description": null, 
         "parent_id": "folder.22688711f5410e6c.22688711F5410E6C!479", 
         "size": 12692, 
         "upload_location": "https://apis.live.net/v5.0/file.22688711f5410e6c.22688711F5410E6C!942/content/", 
         "comments_count": 0, 
         "comments_enabled": true, 
         "is_embeddable": false, 
         "source": "http://storage.live.com/s1pEwo9qzyT4_BJZqMNm-aVzgLo-WRsQGzjzFsXjyREuQG5pDYr237vKz3i2pmqFuniYPzsuIZAOCUMB_gdfKCUpLpVcaAMXGrk4T7jOWenRniCv9vex7GWfSvy-XCVBVnU/Processing.docx:Binary", 
         "link": "https://skydrive-df.live.com/redir.aspx?cid\u003d22688711f5410e6c\u0026page\u003dview\u0026resid\u003d22688711F5410E6C!942\u0026parid\u003d22688711F5410E6C!479", 
         "type": "file", 
         "shared_with": {
            "access": "Everyone (public)"
         }, 
         "created_time": "2011-10-12T23:18:23+0000", 
         "updated_time": "2011-10-12T23:18:23+0000"
      },{
         ...
      }
   ]
}

To get properties for a File resource, make a GET request to /FILE_ID (the target file ID).

To download the content of a File resource, make a GET request to/FILE_ID/content. The file content is returned in the response body.

To return a download link for a File resource, make a GET request to /FILE_ID/content with the suppress_redirects=true parameter. The URL is returned in the response body in the following format.

{
   "location": "..."
}

To create a new File resource, you can either make a PUT request with the file in the body, or you can make a POST request with the file in a multipart form body. You can make a POST request to the /UPLOAD_LOCATION for the target folder, a POST request to /FOLDER_ID/files, or a PUT request to /FOLDER_ID/files/<file name>. For a POST request, you must also format the request as a multipart/form-data media type as described in RFC 2388. You must specify the Content-Type as multipart/form-data, and specify the boundary like this.

Content-Type: multipart/form-data; boundary=AaB03x

Provide the item to upload on a multipart section, and the name of the file as the value of the filename parameter of the Content-Disposition header, as shown here.

--AaB03x
Content-Disposition: form-data; name="file"; filename="file1.txt"
Content-Type: text/plain

...contents of file1.txt...
--AaB03x--

We support only one multipart section per request. For a PUT request, leave the Content-Type blank and put the contents of the file in the request body.

Upon successful creation, the location header points to the location for the newly created file, and the response body contains the following properties.

{
   "id": "ID of the new file",
   "name": "The file's name and file extension",
   "source": "URL where the file can be downloaded from"
}

You can instruct OneDrive to return an HTML response that can be used inside a web browser after the file is created. You can also attach a unique identifier to each upload request so that you can identify a particular upload if you are uploading multiple files in quick succession, which is especially useful for <form> multipart posts. To do this, use a POST multipart/form-data request, like this.

POST https://apis.live.net/v5.0/folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!110/files?state=MyNewFileState&redirect_uri=http%3A%2F%2Fwww.contoso.com%2Fcallback.htm&access_token=ACCESS_TOKEN

Content-Type: multipart/form-data; boundary=AaB03x

--AaB03x
Content-Disposition: form-data; name="file"; filename="MyNewFile.txt"
Content-Type: text/plain

These are the contents of my new file.
--AaB03x--

In this example, replace the folder ID with your target folder ID; replace the state query-string parameter value with your unique identifier; and replace the redirect_uri query-string parameter with the path to your callback page. Note that the domain portion of the path must match the redirect domain that you specified in the Live Connect app management site for the corresponding client ID.

OneDrive returns HTML-formatted code similar to the following.

<html>
    <head>
        <script type="text/javascript">
            window.location = "http://www.contoso.com/callback.htm#state=MyNewFileState&result=%7B%22id%22%3A%22file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!184%22%2C%22source%22%3A%22http%3A%2F%2Fstorage.live.com%2Fs1pasGKzgXFvuEQCbxGtOyIpboUVH1OCHoRzUJNDDwL0zVoidb0RRrNVk88hUrOEve5OMT7eCkuxPbop7dV9tMJQ-eE8SCQ28vFv9ZgPnDGwQMRm-0FeG3-KEY4HL9dQSw9%2FMyNewFile.txt%3ABinary%2CDefault%2FMyNewFile.txt%22%7D";
        </script>
    </head>
</html>

When decoded, the result response parameter is similar to this.

{
    "id": "file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!184",
    "name: "MyNewFile.txt",
    "source": "http://storage.live.com/s1pasGKzgXFvuEQCbxGtOyIpboUVH1OCHoRzUJNDDwL0zVoidb0RRrNVk88hUrOEve5OMT7eCkuxPbop7dV9tMJQ-eE8SCQ28vFv9ZgPnDGwQMRm-0FeG3-KEY4HL9dQSw9/MyNewFile.txt:Binary,Default/MyNewFile.txt"
}

You can upload a file to an existing resource in any of the following ways.

• Make a PUT request to /UPLOAD_LOCATION/FILE_NAME of the parent folder's ID.

• Make a PUT request to /FOLDER_ID/files/FILE_NAME.

• Make a PUT request to /UPLOAD_LOCATION for the file to update.

• Make a PUT request to /FILE_ID/content.

To update the properties for a File resource, make a PUT request to /FILE_ID, and specify the changes in the request body, as shown here. In this example, both the file name and the description are updated. Note that the filename extension is required when updating the file name.

{
   "name": "UFO_Sightings_1979.docx"
   "description": "The detailed accounts of all UFO sightings in 1979."
}

To delete a file, make a DELETE request to /FILE_ID.

To move a file, make a MOVE request to /FILE_ID or /FOLDER_ID, and specify the ID of the destination folder in the request body, as shown here.

{
   "destination": "FOLDER_ID"
}

To copy a file, make a COPY request to /FILE_ID or /FOLDER_ID, and specify the ID of the destination folder in the request body, as shown here.

{
   "destination": "FOLDER_ID"
}

For PUT and POST requests, you can use the overwrite query string parameter to indicate whether the request should fail if the resource already exists, as shown here. Optionally you can specify an overwrite query-string parameter value of ChooseNewName if you want to upload a duplicate copy of the file but let OneDrive choose the uploaded file's new file name.

overwrite=true
overwrite=false
overwrite=ChooseNewName

If the value of the overwrite query string parameter is set to true, and the file exists, it is overwritten. If the value is set to false, the file is not overwritten and a resource_already_exists error is returned. If no overwrite query string parameter is specified, the default value is true.

In all of the preceding cases, you can replace FILE_ID with either me/skydrive/FRIENDLY_FOLDER_NAME or USER_ID/skydrive/FRIENDLY_FOLDER_NAME, where me represents the current consenting user, USER_ID represents the consenting user's ID, and FRIENDLY_FOLDER_NAME represents an allowed friendly folder name like my_documents to represent the Documents folder. For more info, see the Common tasks in accessing Microsoft OneDrive from your app topic's "Using friendly names to access certain OneDrive folders" section.

Top

Folder object

The Folder object contains info about a user's folders in OneDrive. Folders can contain combinations of photos, videos, audio, and subfolders. The Live Connect REST API supports reading Folder objects. Use the wl.photos scope to read Folder objects. Use the wl.contacts_photos scope to read any albums, photos, videos, and audio that other users have shared with the user.

The Folder object contains the following structures.

The following is an example of a collection of Folder objects. (For brevity, only the first object is shown.)

{
   "data": [
      {
         "id": "folder.8c8ce076ca27823f.8C8CE076CA27823F!142", 
         "from": {
            "name": "Roberto Tamburello", 
            "id": "8c8ce076ca27823f"
         }, 
         "name": "My Sample Folder in Album 1", 
         "description": "",
         "parent_id": "folder.de57f4126ed7e411", 
         "upload_location": "https://apis.live.net/v5.0/folder.de57f4126ed7e411.DE57F4126ED7E411!126/files/", 
         "is_embeddable": true, 
         "count": 3, 
         "link": "https://cid-8c8ce076ca27823f.skydrive.live.com/redir.aspx?page\u003dself\u0026resid\u003d8C8CE076CA27823F!142\u0026parid\u003d8C8CE076CA27823F!126\u0026type\u003d5", 
         "type": "folder", 
         "shared_with": {
             "access": "Just me"
         },
         "created_time": "2011-04-22T00:36:30+0000", 
         "updated_time": "2011-04-22T19:18:12+0000"
      }, {
         ...
      }
   ]
}

To get the root Folder resource by using the Live Connect REST API, make a GET request to either /me/skydrive or /USER_ID/skydrive.

To get a subfolder resource, make a GET request to /FOLDER_ID.

To enumerate the contents of a folder, make a GET request to /FOLDER_ID/files.

A folder may contain the following objects.

• Folder object
• File object
• Album object
• Photo object
• Video object
• Audio object

To create a new Folder resource, make a POST request to /FOLDER_ID. Pass the name and description attributes in the request body, as shown here.

{
   "name": "Informative Spreadsheets",
   "description": "A folder full of useful data visualizations."
}

The folder is created as a child of the folder that is specified in the request URL. The location header points to the newly created folder location, and the response body contains properties for the newly created folder.

To update the properties of a Folder, make a PUT request to /FOLDER_ID. Pass the attributes to update in the request body, as shown here.

{
   "name": "Very Informative Spreadsheets",
   "description": "A folder full of even more useful data visualizations."
}

To delete a folder, make a DELETE request to /FOLDER_ID.

In the preceding examples, replace FOLDER_ID with the target folder ID.

Top

Friend object

The Friend object contains info about a user's friends. A Friend object represents a user's contact whose is_friend value is set to true. The Live Connect REST API supports reading Friend objects.

The Friend object contains the following structures.

The following is an example of a collection of Friend objects. (For brevity, only the first object is shown.)

{
   "data": [
      {
         "id": "d09ea18fafc39a0c", 
         "name": "Henrik Jensen" 
      }, {
         ...
      }
   ]
}

To get a collection of Friend objects by using the Live Connect REST API, make a GET request to /me/friends.

Top

Permissions object

The Permissions object contains a list of scopes, showing those scopes to which the user has consented. The response body contains a JSON object that lists all consented scopes as a name/value pair. Each scope to which the user consented is present as a key.

The following is an example of a Permissions object. (For brevity, not all scopes are shown.)

{
   "data": [
        {         
            "wl.basic": 1,
            "wl.offline_access": 1,
            "wl.signin": 1,
            ...
        }
    ]
}

To get a Permissions object by using the Live Connect REST API, make a GET request to /me/permissions.

Top

Photo object

The Photo object contains info about a user's photos on OneDrive. The Live Connect REST API supports creating, reading, updating, and deleting Photo objects. Use the wl.photos scope to read Photo objects. Use the wl.contacts_photos scope to read any albums, photos, videos, and audio that other users have shared with the user. Use the wl.skydrive_update scope to create, update, or delete Photo objects.

The Photo object contains the following structures.

The following is an example of a collection of Photo objects. (For brevity, only the first object is shown.)

{
   "data": [
      {
         "id": "file.de57f4126ed7e411.DE57F4126ED7E411!128", 
         "from": {
            "name": "Nuno Bento", 
            "id": "de57f4126ed7e411"
         }, 
         "name": "Maui-2012_0034.JPG", 
         "description": null, 
         "parent_id": "folder.de57f4126ed7e411.DE57F4126ED7E411!126", 
         "size": 561683, 
         "comments_count": 1, 
         "comments_enabled": true, 
         "tags_count": 0, 
         "tags_enabled": true,
         "is_embeddable": true, 
         "picture": "http://storage.live.com/s1pKk5vzd-gdPanbzKYhB0nQGn8wGq5DSgqvrgIHU1NTXA4e2-spGkAhQjW1d9pcgKAGLB4NsEsSvDoREmdx5w-JiFrinEJJuEoz08Ws_IFupkX2bPSvy5qmths9ijwvDrXi1OBCWk9GW9Kt-qNNOAA9g/Maui09_0034.JPG:Thumbnail", 
         "source": "http://storage.live.com/s1pKk5vzd-gdPanbzKYhB0nQGn8wGq5DSgqvrgIHU1NTXA4e2-spGkAhQjW1d9pcgKAGLB4NsEsSvDoREmdx5w-JiFrinEJJuEoz08Ws_IFupkX2bPSvy5qmths9ijwvDrXi1OBCWk9GW9Kt-qNNOAA9g/Maui09_0034.JPG:HighRes", 
         "upload_location": "https://apis.live.net/v5.0/file.de57f4126ed7e411.DE57F4126ED7E411!128/content/", 
         "images": [
            {
               "height": 450, 
               "width": 600, 
               "source": "http://storage.live.com/s1pKk5vzd-gdPanbzKYhB0nQGn8wGq5DSgqvrgIHU1NTXA4e2-spGkAhQjW1d9pcgKAGLB4NsEsSvDoREmdx5w-JiFrinEJJuEoz08Ws_IFupkX2bPSvy5qmths9ijwvDrXi1OBCWk9GW9Kt-qNNOAA9g/Maui09_0034.JPG:WebReady", 
               "type": "normal"
            }, {
               "height": 132, 
               "width": 176, 
               "source": "http://storage.live.com/s1pKk5vzd-gdPanbzKYhB0nQGn8wGq5DSgqvrgIHU1NTXA4e2-spGkAhQjW1d9pcgKAGLB4NsEsSvDoREmdx5w-JiFrinEJJuEoz08Ws_IFupkX2bPSvy5qmths9ijwvDrXi1OBCWk9GW9Kt-qNNOAA9g/Maui09_0034.JPG:MobileReady", 
               "type": "album"
            }, {
               "height": 72, 
               "width": 96, 
               "source": "http://storage.live.com/s1pKk5vzd-gdPanbzKYhB0nQGn8wGq5DSgqvrgIHU1NTXA4e2-spGkAhQjW1d9pcgKAGLB4NsEsSvDoREmdx5w-JiFrinEJJuEoz08Ws_IFupkX2bPSvy5qmths9ijwvDrXi1OBCWk9GW9Kt-qNNOAA9g/Maui09_0034.JPG:Thumbnail", 
               "type": "thumbnail"
            }, {
               "height": 1200, 
               "width": 1600, 
               "source": "http://storage.live.com/s1pKk5vzd-gdPanbzKYhB0nQGn8wGq5DSgqvrgIHU1NTXA4e2-spGkAhQjW1d9pcgKAGLB4NsEsSvDoREmdx5w-JiFrinEJJuEoz08Ws_IFupkX2bPSvy5qmths9ijwvDrXi1OBCWk9GW9Kt-qNNOAA9g/Maui09_0034.JPG:HighRes", 
               "type": "full"
            }
         ], 
         "link": "https://skydrive.live.com/redir.aspx?cid\u003dde57f4126ed7e411\u0026page\u003dview\u0026resid\u003dDE57F4126ED7E411!128\u0026parid\u003dDE57F4126ED7E411!126", 
         "when_taken": "2008-03-24T23:41:53+0000", 
         "height": 1200, 
         "width": 1600, 
         "type": "photo",
         "location": {
             "latitude": 47.65316, 
             "longitude": -122.135911,
             "altitude": 43
         }, 
         "camera_make": "MyManufacturer",
         "camera_model": "MyModel",
         "focal_ratio": 2.8,
         "focal_length": 3.85,
         "exposure_numerator": 1,
         "exposure_denominator": 15, 
         "shared_with": {
            "access": "Everyone (public)"
         }, 
         "created_time": "2012-12-03T18:14:03+0000", 
         "updated_time": "2012-12-03T18:31:01+0000"
      }, {
         ...
      }
   ]      
}

To get a collection of Photo objects by using the Live Connect REST API, make a GET request to /ALBUM_ID/files.

https://apis.live.net/v5.0/PHOTO_ID/picture?type=thumbnail&access_token=ACCESS_TOKEN

In the preceding examples, replace ALBUM_ID and PHOTO_ID with the target album or photo ID.

To create a new Photo resource, you can make either a PUT request with the photo in the body or a POST request with the photo in a multipart form body. For POST, make a POST request to the /UPLOAD_LOCATION for the target folder or a POST request to /FOLDER_ID. You must format the request as a multipart/form-data media type as described in RFC 2388. You must specify the Content-Type as multipart/form-data, and specify the boundary like this.

Content-Type: multipart/form-data; boundary=AaB03x

Provide the item to upload on a multipart section, and the name of the photo as the value of the filename parameter of the Content-Disposition header, as shown here.

Content-Type: multipart/form-data; boundary=AaB03x
--AaB03x
Content-Disposition: form-data; name="file"; filename="hovering_orbs.jpg"
Content-Type: image/jpeg

...contents of hovering_orbs.jpg...
--AaB03x--

Only one multipart section per request is supported. For a PUT request, leave the Content-Type blank and put the contents of the file in the request body.

Upon successful creation, the location header points to the location for the newly created photo, and the response body contains the following properties.

{
   "id": "ID of the new photo",
   "name": "The file's name and file extension",
   "source": "URL where the photo can be downloaded from"
}

You can upload a photo to an existing resource in any of the following ways.

• Make a PUT request to /UPLOAD_LOCATION/FILE_NAME for the folder you would like to upload to.

• Make a PUT request to /FOLDER_ID/files/FILE_NAME.

• Make a PUT request to /ALBUM_ID/files/FILE_NAME.

• Make a PUT request to /UPLOAD_LOCATION for the file to update.

• Make a PUT request to /PHOTO_ID/content.

By default, if an uploaded photo is larger than 2048 × 2048 pixels in size, OneDrive automatically attempts to shrink it to fit within this 2048 × 2048-pixel size constraint. To override this behavior, set the downsize_photo_uploads query-string parameter to false—for example, /FOLDER_ID/files?downsize_photo_uploads=false for POST or /FOLDER_ID/files/FILENAME?downsize_photo_uploads=false for PUT.

To update the properties for a Photo resource, make a PUT request to /PHOTO_ID, and specify the changes in the request body, as shown here.

{
   "name": "fast-moving_orbs.jpg"
   "description": "Fast moving objects."
}

To delete a photo, make a DELETE request to /PHOTO_ID.

To move a photo, make a MOVE request to /PHOTO_ID or /FOLDER_ID, and specify the ID of the destination folder in the request body, as shown here.

{
   "destination": "FOLDER_ID"
}

To copy a photo, make a COPY request to /PHOTO_ID or /FOLDER_ID, and specify the ID of the destination folder in the request body, as shown here.

{
   "destination": "FOLDER_ID"
}

For PUT and POST requests, you can use the overwrite query string parameter to indicate whether the request should fail if the resource already exists, as shown here. Optionally you can specify an overwrite query-string parameter value of ChooseNewName if you want to upload a duplicate copy of the file but let OneDrive choose the uploaded file's new file name. Note that MOVE and COPY do not support overwriting at this time.

overwrite=true
overwrite=false
overwrite=ChooseNewName

If the value of the overwrite query string parameter is set to true, and the file exists, it is overwritten. If the value is set to false, the file is not overwritten, and a resource_already_exists error is returned. If no overwrite query string parameter is specified, the default value is true.

Top

Search object

The Search object contains info about the objects found in a user's OneDrive that match the search query. See Search query parameters for info about formatting a search query request.

The Search object contains the following structures.

Top

Tag object

The Tag object contains info about tags that are associated with a photo or a video on OneDrive. The Live Connect REST API supports reading Tag objects. Use the wl.photos, and wl.skydrive scopes to read Tag objects. Use the wl.contacts_photos and wl.contacts_skydrive scopes to read the Tag objects that are associated with any photos that other users have shared with the user.

The Tag object contains the following structures.

The following is an example of a collection of Tag objects. (For brevity, only the first object is shown.)

{
    "id": "tag.22688711f5410e6c.22688711f5410e6c!767.PRaXZrdHI1uYGQYi9CU0StrzHak",
    "user": {
        "name": "Roberto Tamburello",
        "id": "8c8ce076ca27823f"
    },
    "x": 43.8986,
    "y": 54.4138,
    "created_time": "2011-04-22T01:17:00+0000"
}

To get a collection of Tag objects by using the Live Connect REST API, make a GET request to /RESOURCE_ID/tags.

Top

User object

The User object contains info about a user. The Live Connect REST API supports reading User objects.

The User object contains the following structures.

The following is an example of a User object.

{
   "id": "8c8ce076ca27823f", 
   "name": "Roberto Tamburello", 
   "first_name": "Roberto", 
   "last_name": "Tamburello", 
   "link": "http://cid-8c8ce076ca27823f.profile.live.com/", 
   "birth_day": 20, 
   "birth_month": 4, 
   "birth_year": 2010, 
   "work": [
      {
         "employer": {
            "name": "Microsoft Corporation"
         }, 
         "position": {
            "name": "Software Development Engineer"
         }
      }
   ], 
   "emails": {
      "preferred": "Roberto@contoso.com",
      "account": "Roberto@contoso.com", 
      "personal": "Roberto@fabrikam.com", 
      "business": "Robert@adatum.com",
      "other": "Roberto@adventure-works.com"
   },
   "addresses": {
      "personal": {
         "street": "123 Main St.", 
         "street_2": "Apt. A", 
         "city": "Redmond", 
         "state": "WA", 
         "postal_code": "12990", 
         "region": "United States"
      }, 
      "business": {
         "street": "456 Anywhere St.", 
         "street_2": "Suite 1", 
         "city": "Redmond", 
         "state": "WA", 
         "postal_code": "12399", 
         "region": "United States"
      }
   }, 
   "phones": {
      "personal": "(555) 555-1212", 
      "business": "(555) 111-1212", 
      "mobile": null
   }, 
   "locale": "en_US", 
   "updated_time": "2011-04-21T23:55:34+0000"
}

To get a User object by using the Live Connect REST API, make a GET request to either /me, or /USER_ID.

Top

Video object

The Video object contains info about a user's videos on OneDrive. The Live Connect REST API supports creating, reading, updating, and deleting Video objects. Use the wl.photos scope to read Video objects. Use the wl.contacts_photos scope to read albums, photos, and videos that other users have shared with the user. Use the wl.skydrive_update scope to create, update, or delete Video objects.

The Video object contains the following structures.

The following is an example of a collection of Video objects. (For brevity, only the first object is shown.)

{
    "data": [
      {
         "id": "file.de57f4126ed7e411.DE57F4126ED7E411!135", 
         "from": {
            "name": "Nuno Bento", 
            "id": "de57f4126ed7e411"
         }, 
         "name": "Wildlife.wmv", 
         "description": null, 
         "parent_id": "folder.de57f4126ed7e411.DE57F4126ED7E411!126", 
         "size": 26246026, 
         "comments_count": 0, 
         "comments_enabled": true, 
         "tags_count": 0, 
         "tags_enabled": true, 
         "is_embeddable": true,
         "picture": "http://storage.live.com/s1pKk5vzd-gdPaJ5Q1MKN34itsyRlUkAYzD_zsr0Dg-5r4bH8Qo8XRgsunA0M-V4G-XPpu1spowx4xwfjCuDcWQVa7aWld2WCdfeWjBK_coPqaQqzoE26BJP3OZAITB5i_DRPK8jK3ZLilSbNJd-onrOA/Wildlife.wmv:Thumbnail", 
         "source": "http://storage.live.com/s1pKk5vzd-gdPaJ5Q1MKN34itsyRlUkAYzD_zsr0Dg-5r4bH8Qo8XRgsunA0M-V4G-XPpu1spowx4xwfjCuDcWQVa7aWld2WCdfeWjBK_coPqaQqzoE26BJP3OZAITB5i_DRPK8jK3ZLilSbNJd-onrOA/Wildlife.wmv:VideoMain", 
         "upload_location": "https://apis.live.net/v5.0/file.de57f4126ed7e411.DE57F4126ED7E411!135/content/", 
         "link": "https://skydrive.live.com/redir.aspx?cid\u003dde57f4126ed7e411\u0026page\u003dview\u0026resid\u003dDE57F4126ED7E411!135\u0026parid\u003dDE57F4126ED7E411!126", 
         "height": 720, 
         "width": 1280, 
         "duration": 30093, 
         "bitrate": 5942130, 
         "type": "video", 
         "shared_with": {
            "access": "Everyone (public)"
         }, 
         "created_time": "2011-08-23T23:41:18+0000", 
         "updated_time": "2011-08-23T23:41:32+0000"
      }, {
         ...
      } 
   ]
}

To get a collection of Video objects by using the Live Connect REST API, make a GET request to /ALBUM_ID/files.

In the preceding examples, replace ALBUM_ID with the target Live Connect album ID.

To create a new Video resource, you can make either a PUT request with the video in the body or a POST request with the video in a multipart form body. For POST, make a POST request to the /UPLOAD_LOCATION for the target folder or a POST request to /FOLDER_ID. You must format the request as a multipart/form-data media type as described in RFC 2388. You must specify the Content-Type as multipart/form-data and specify the boundary, as shown here.

Content-Type: multipart/form-data; boundary=AaB03x

Provide the item to upload on a multipart section, and the name of the photo as the value of the filename parameter of the Content-Disposition header, as shown here.

Content-Type: multipart/form-data; boundary=AaB03x
--AaB03x
Content-Disposition: form-data; name="file"; filename="strange_lights.avi"
Content-Type: video/x-msvideo

...contents of strange_lights.avi...
--AaB03x--

Only one multipart section per request is supported. For a PUT request, leave the Content-Type blank and put the contents of the file in the request body.

Upon successful creation, the location header points to the location for the newly created video, and the response body contains the following properties.

{
   "id": "ID of the new video",
   "name": "The file's name and file extension",
   "source": "URL where the video can be downloaded from"
}

You can upload a video to an existing resource in any of the following ways.

• Make a PUT request to /UPLOAD_LOCATION/FILE_NAME of the parent folder's ID.

• Make a PUT request to /FOLDER_ID/files/FILE_NAME.

• Make a PUT request to /ALBUM_ID/files/FILE_NAME.

• Make a PUT request to /UPLOAD_LOCATION for the file to update.

• Make a PUT request to /VIDEO_ID/content.

To update the properties for a Video resource, make a PUT request to /VIDEO_ID, and specify the changes in the request body, as shown here.

{
   "name": "triangle_formation.avi"
   "description": "Sightings of UFOs in triangle formation."
}

To delete a video, make a DELETE request to /VIDEO_ID.

To move a video, make a MOVE request to /VIDEO_ID or /FOLDER_ID, and specify the ID of the destination folder in the request body, as shown here.

{
   "destination": "FOLDER_ID"
}

To copy a video, make a COPY request to /VIDEO_ID or /FOLDER_ID, and specify the ID of the destination folder in the request body, as shown here.

{
   "destination": "FOLDER_ID"
}

For PUT and POST requests, you can use the overwrite query string parameter to indicate whether the request should fail if the resource already exists, as shown here. Optionally you can specify an overwrite query-string parameter value of ChooseNewName if you want to upload a duplicate copy of the file but let OneDrive choose the uploaded file's new file name.

overwrite=true
overwrite=false
overwrite=ChooseNewName

If the value of the overwrite query string parameter is set to true, and the file exists, it is overwritten. If the value is set to false, the file is not overwritten and a resource_already_exists error is returned. If no overwrite query string parameter is specified, the default value is true.

Top

Additional URL parameters

You can specify additional parameters, as part of the URL of a GET request to the Live Connect REST API, to instruct the Live Connect APIs how to return its results. The following table explains these parameters.

For example, the following URL makes a GET request for the user's contacts list, with the pretty parameter set to false.

https://apis.live.net/v5.0/me/contacts?pretty=false&access_token=ACCESS_TOKEN

Top