REST reference

104 out of 149 rated this helpful - Rate this topic

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

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.

Object Description Valid object paths

Album

A user's album in OneDrive. Albums can contain combinations of photos, videos, audio, files, and folders.

/me/albums

/USER_ID/albums

/ALBUM_ID

An Album object can be returned as part of /ALBUM_ID/files, /me/skydrive/files, /me/skydrive/shared/files, /me/skydrive/shared/albums, or /USER_ID/skydrive/files.

Audio

A user's audio file in OneDrive.

/AUDIO_ID

An Audio object can be returned as part of /ALBUM_ID/files, /FOLDER_ID/files, /me/skydrive/files, or USER_ID/skydrive/files.

Calendar

A user's calendar.

/me/calendars

/USER_ID/calendars

/CALENDAR_ID

Comment

A comment that is made by a user on a photo or a video in OneDrive.

/PHOTO_ID/comments

/VIDEO_ID/comments

/COMMENT_ID

Contact

A user's Outlook.com contact. (If the contact's is_friend value is set to true, the contact is also the user's friend.)

/me/contacts

/USER_ID/contacts

/CONTACT_ID

Error

Info about an error that is returned by the Live Connect APIs.

None.

Event

An event on a user's calendar.

/me/events

/USER_ID/events

/CALENDAR_ID/events

File

A user's file in OneDrive.

/FILE_ID

A File object can be returned as part of /FOLDER_ID/files, /me/skydrive/files, /me/skydrive/shared, /me/skydrive/shared/files, or /USER_ID/skydrive/files.

Folder

A user's folder in OneDrive. Folders can contain combinations of photos, videos, audio, files (such as Microsoft Office documents), and subfolders.

/FOLDER_ID

A Folder object can be returned as part of /FOLDER_ID/files, /me/skydrive/files, /me/skydrive/shared/files, /USER_ID/skydrive/files, or /ALBUM_ID/files.

Friend

A user's friend. Friends are a subset of a user's contacts and reflect people that the user has a publicly visible relationship with. Explicit permission is not required to view a user's friends. Because Friend returns less data than Contact, it's more compact for scenarios where only the names and IDs of the user's friends are needed.

/me/friends

/USER_ID/friends

Permissions

A list of scopes.

/me/permissions

/USER_ID/permissions

Photo

A user's photo in OneDrive.

/PHOTO_ID

A Photo object can be returned as part of /ALBUM_ID/files, /ALBUM_ID/photos, /FOLDER_ID/files, /me/skydrive/files, /me/skydrive/shared/photos, or USER_ID/skydrive/files.

Search

Info about the files and folders in the user's OneDrive that match the search query.

/me/skydrive/search

Tag

A tag that is associated with a photo or a video in OneDrive.

/PHOTO_ID/tags

/VIDEO_ID/tags

/TAG_ID

User

A user.

/me

/USER_ID

Video

A user's video in OneDrive.

/VIDEO_ID

A Video object can be returned as part of /ALBUM_ID/files, /ALBUM_ID/videos, /FOLDER_ID/files, /me/skydrive/files, /me/skydrive/shared/videos, or USER_ID/skydrive/files.

 

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.

Note  In the JSON-formatted object that's returned, you can look in the paging object for the previous and next structures to get the offset and limit parameter values of the previous and next entries.

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.

Note  In the JSON-formatted object that's returned, you can look in the paging object for the previous and next structures to get the offset and limit parameter values of the previous and next entries.

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.

Note  In the JSON-formatted object that's returned, you can look in the paging object for the previous and next structures to get the offset and limit parameter values of the previous and next entries.

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.

StructureTypeR/WRequired on createDescription

data

array

R

An array container for Album objects when a collection of objects is returned.

id

string

R

The Album object's ID.

from

object

R

Info about the user who authored the album.

name (from object)

string

R

The name of the user who authored the album.

id (from object)

string

R

The Live ID of the user who authored the album.

name

string

RW

Yes

The name of the album.

description

string/null

RW

A description of the album, or null if no description is specified.

parent_id

string

R

The resource ID of the parent.

upload_location

string

R

The URL to upload items to the album, hosted in OneDrive. Requires the wl.skydrive scope.

is_embeddable

true/false

R

A value that indicates whether this album can be embedded. If this album can be embedded, this value is true; otherwise, it is false.

count

number

R

The total number of items in the album.

link

string

R

A URL of the album, hosted in OneDrive.

type

string

R

The type of object; in this case, "album".

shared_with

object

R

The object that contains permissions info for the album. Requires the wl.skydrive scope.

access (shared_with object)

string

R

A localized string that contains info about who can access the album. The options are:

  • People I selected
  • Just me
  • Everyone (public)
  • Friends
  • My friends and their friends
  • People with a link
The default is Just me.

created_time

string

R

The time, in ISO 8601 format, at which the album was created.

updated_time

string

R

The time, in ISO 8601 format, that the system updated the album last.

client_updated_time

string

R

The time, in ISO 8601 format, that the file was last updated.

 

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.

Note  To get an album's cover image, call /ALBUM_ID/picture.

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.

StructureTypeR/WRequired on createDescription

data

array

R

An array of Audio objects, if a collection of objects is returned.

id

string

R

The Audio object's ID.

from

object

R

Info about the user who uploaded the audio.

name (from object)

string

R

The name of the user who uploaded the audio.

id (from object)

string

R

The ID of the user who uploaded the audio.

name

string

RW

Yes

The name of the audio.

description

string/null

RW

A description of the audio, or null if no description is specified.

parent_id

string

R

The id of the folder in which the audio is currently stored.

size

number

R

The size, in bytes, of the audio.

upload_location

string

R

The URL to use to upload a new audio to overwrite the existing audio.

comments_count

number

R

The number of comments associated with the audio.

comments_enabled

true/false

R

A value that indicates whether comments are enabled for the audio. If comments can be made, this value is true; otherwise, it is false.

is_embeddable

true/false

R

A value that indicates whether this audio can be embedded. If this audio can be embedded, this value is true; otherwise, it is false.

source

string

R

The URL to use to download the audio from OneDrive.

Warning  

This value is not persistent. Use it immediately after making the request, and avoid caching.

link

string

R

A URL to view the item on OneDrive.

type

string

R

The type of object; in this case, "audio".

title

string

RW

The audio's title.

artist

string

RW

The audio's artist name.

album

string

RW

The audio's album name.

album_artist

string

RW

The artist name of the audio's album.

genre

string

RW

The audio's genre.

duration

integer

R

The audio's playing time, in milliseconds.

picture

string

R

A URL to view the audio's picture on OneDrive.

shared_with

object

R

The object that contains permission info.

access (shared_with object)

string

R

Info about who can access the audio. The options are:

  • People I selected
  • Just me
  • Everyone (public)
  • Friends
  • My friends and their friends
  • People with a link
The default is Just me.

created_time

string

R

The time, in ISO 8601 format, at which the audio was created.

updated_time

string

R

The time, in ISO 8601 format, at which the audio was last updated.

 

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--

Note  

The boundary value (shown here as "AaB03x") can be any arbitrary string value.

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.

StructureTypeR/WRequired on createDescription

id

string

R

The Calendar object's ID.

name

string

RW

Yes

Name of the calendar.

description

string/null

RW

Description of the calendar.

created_time

string

R

The time, in ISO 8601 format, at which the calendar was created.

updated_time

string

R

The time, in ISO 8601 format, that the calendar was last updated.

from

object

R

Info about the user who owns the calendar.

name (from object)

string

R

The name of the user who uploaded the file.

id (from object)

string

R

The ID of the user who owns the calendar.

is_default

true/false

R

A value that indicates whether this calendar is the default calendar. If this calendar is the default calendar, this value is true; otherwise, it is false.

subscription_location

string

RW

A public subscription URL with which Live Connect will synchronize properties and events periodically for this calendar. A NULL value indicates that this is not a subscribed calendar.

permissions

string

R

Role and permissions that are granted to the user for the calendar. The possible values are:

  • free_busy: The user can see only free/busy info.
  • limited_details: The user can see a subset of all details.
  • read: The user can only read the content of the calendar events.
  • read_write: The user can read and write calendar and events.
  • co_owner: The user is co-owner of this calendar.
  • owner: The user is the owner of this calendar.

 

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."
}

Warning  

The request body must not include the subscription_location property.

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.

StructureTypeR/WRequired on createDescription

data

array

R

An array of Comment objects, if a collection of objects is returned.

id

string

R

The Comment object's id.

from

object

R

Info about the user who created the comment.

name (from object)

string

R

The name of the user who created the comment.

id (from object)

string

R

The ID of the user who created the comment.

message

string

RW

Yes

The text of the comment. The maximum length of a comment is 10,000 characters.

created_time

string

R

The time, in ISO 8601 format, at which the comment was created.

 

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.

StructureRequired scopes TypeR/WRequired on createDescription

id

wl.basic

string

R

The Contact object's ID.

first_name

wl.basic

string/null

RW

Optional

The contact's first name, or null if no first name is specified.

last_name

wl.basic

string/null

RW

Optional

The contact's last name, or null if no last name is specified.

name

wl.basic

string

R

The contact's full name, formatted for location.

is_friend

wl.basic

true/false

R

A value that indicates whether the contact is set as a friend. If the contact is a friend, this value is true; otherwise, it is false.

is_favorite

wl.basic

true/false

RW

A value that indicates whether the contact is set as a favorite contact. If the contact is a favorite, this value is true; otherwise, it is false.

user_id

wl.basic

string/null

R

The contact's ID, if the contact has one. If not, this value is null.

email_hashes

wl.basic

array

R

An array containing a SHA-256 hash for each of the contact's email addresses. For more info, see Friend finder.

updated_time

wl.basic

string

R

The time, in ISO 8601 format, at which the user last updated the data.

birth_day

wl.basic and wl.contacts_birthday

number/null

R

The day of the contact's birth date, or null if no birth date is specified.

birth_month

wl.basic and wl.contacts_birthday

number/null

R

The month of the contact's birth date, or null if no birth date is specified.

 

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.

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.

Note  

If a Contact references a user, you can return a User object by making a GET request using the user_id value for the Contact.

To redirect a GET call to the URL of the picture of a contact who is a user, call /USER_ID/picture. (A User object's ID is not the same as a contact ID.)

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.

Structure TypeDescription

error

object

Info about the error.

code (error object)

string

The error code.

message (error object)

string

The error message.

 

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.

Structure TypeR/WRequired on createDescription

id

string

R

The ID of the event.

name

string

RW

Yes

The name of the event, with a maximum length of 255 characters. This structure is required.

created_time

string

R

The time, in ISO 8601 format, at which the event was created.

updated_time

string

R

The time, in ISO 8601 format, at which the event was updated. This structure is visible only in the Event object that is returned if the event was successfully created.

description

string

RW

Yes

A description of the event, with a maximum length of 32,768 characters. This structure is required.

calendar_id

object

R

The ID of the calendar that contains the event.

from

object

R

The object that contains the name and ID of the organizer.

name (from object)

string

R

The name of the organizer.

id (from object)

string

R

The ID of the organizer.

start_time

string

RW

Yes

The start time, in ISO 8601 format, of the event. When the event is being read, the time will be the user's local time, in ISO 8601 format.

end_time

string

RW

The end time, in ISO 8601 format, of the event. If no end time is specified, the default value is 30 minutes after start_time. This structure is optional when creating an event. When the event is being read, the time will be the user's local time, in ISO 8601 format.

location

string

RW

The name of the location at which the event will take place. The maximum length is 1,000 characters.

is_all_day_event

true/false

RW

A value that specifies whether the event is an all-day event. If the event is an all-day event, this value is true; otherwise, it is false. If this structure is missing, the default value is false.

is_recurrent

true/false

R

A value that specifies whether the event is recurring. If the event is recurring, this value is true; otherwise, it is false.

recurrence

string

R

The text description of the recurrence pattern, for example, "Occurs every week on Tuesday". The value is Null if this is not a recurrent event.

reminder_time

number

RW

The time, in minutes, before the event for the reminder alarm.

availability

string

RW

The user's availability status for the event. Valid values are:

  • free
  • busy
  • tentative
  • out_of_office
The default value is free.

visibility

string

RW

A value that specifies whether the event is publicly visible. Valid values are:

  • public—the event is visible to anyone who can view the calendar.
  • private"—the event is visible only to the event owner.
The default value is public.

 

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"
}

Note  

If the call is successful, the Live Connect REST API returns the following JSON-formatted object.

{
   "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.

Tip  

The Live Connect REST API does not support creating or updating recurring events; however, you can delete recurring events the same way you would delete a nonrecurring event. Deleting a recurring event deletes all of its occurrences.

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.

StructureTypeR/WRequired on createDescription

data

array

R

An array of File objects, if a collection of objects is returned.

id

string

R

The File object's ID.

from

object

R

Info about the user who uploaded the file.

name (from object)

string

R

The name of the user who uploaded the file.

id (from object)

string

R

The ID of the user who uploaded the file.

name

string

RW

Yes

The name of the file.

description

string/null

RW

A description of the file, or null if no description is specified.

parent_id

string

R

The ID of the folder the file is currently stored in.

size

number

R

The size, in bytes, of the file.

upload_location

string

R

The URL to upload file content hosted in OneDrive.

Note  This structure is not available if the file is an Microsoft Office OneNote notebook.

comments_count

number

R

The number of comments that are associated with the file.

comments_enabled

true/false

R

A value that indicates whether comments are enabled for the file. If comments can be made, this value is true; otherwise, it is false.

is_embeddable

true/false

R

A value that indicates whether this file can be embedded. If this file can be embedded, this value is true; otherwise, it is false.

source

string

R

The URL to use to download the file from OneDrive.

Warning  

This value is not persistent. Use it immediately after making the request, and avoid caching.

Note  This structure is not available if the file is an Office OneNote notebook.

link

string

R

A URL to view the item on OneDrive.

type

string

R

The type of object; in this case, "file".

Note  If the file is a Office OneNote notebook, the type structure is set to "notebook".

shared_with

object

R

Object that contains permission info.

access (shared_with object)

string

R

Info about who can access the folder. The options are:

  • People I selected
  • Just me
  • Everyone (public)
  • Friends
  • My friends and their friends
  • People with a link
The default is Just me.

created_time

string

R

The time, in ISO 8601 format, at which the file was created.

updated_time

string

R

The time, in ISO 8601 format, that the system updated the file last.

client_updated_time

string

R

The time, in ISO 8601 format, that the client machine updated the file last.

sort_by

string

RW

Sorts the items to specify the following criteria: updated, name, size, or default.

 

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.

Tip  You can instruct the user's web browser to prompt the user to save the file that's being downloaded instead of having the web browser try to download and display the file directly in the browser. To do this, add the download=true query parameter after /content (for example, FILE_ID/content?download=true). The download=true query parameter works for all calls related to OneDrive that redirect to content or to returning URLs that point to content. For example, FOLDER_ID/files?download=true causes all source and thumbnail URLs in the response to be treated also as download links when they are used.

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": "..."
}

Tip  If the client has already requested the properties for a file, the download link will be in the source field.

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.

Important  On platforms that support the PUT request, use PUT whenever possible to upload files to OneDrive to avoid errors that can occur when POST is used.

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--

Note  

The boundary value (shown here as "AaB03x") can be any arbitrary string value.

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.

Tip  Before uploading a file, have your app check to make sure that there is enough available OneDrive storage space by making a GET call to USER_ID/skydrive/quota. For example, your app could get the size of the file in bytes and then compare it to the number of available storage bytes returned in the OneDrive quota call. For more info, see Common tasks in accessing Microsoft OneDrive from your app, in the "Getting a user's total and remaining OneDrive storage quota" 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.

StructureTypeR/WRequired on createDescription

data

array

R

An array container for Folder objects, if a collection of objects is returned.

id

string

R

The Folder object's ID.

from

object

R

Info about the user who created the folder.

name (from object)

string

R

The name of the user who created the folder.

id (from object)

string

R

The ID of the user who created the folder.

name

string

RW

Yes

The name of the folder.

description

string/null

RW

A description of the folder, or null if no description is specified.

count

number

R

The total number of items in the folder.

link

string

R

The URL of the folder, hosted in OneDrive.

parent_id

string

R

The resource ID of the parent.

upload_location

string

R

The URL to upload items to the folder hosted in OneDrive. Requires the wl.skydrive scope.

is_embeddable

true/false

R

A value that indicates whether this folder can be embedded. If this folder can be embedded, this value is true; otherwise, it is false.

type

string

R

The type of object; in this case, "folder".

created_time

string

R

The time, in ISO 8601 format, at which the folder was created.

updated_time

string

R

The time, in ISO 8601 format, that the system updated the file last.

client_updated_time

string

R

The time, in ISO 8601 format, that the client machine updated the file last.

shared_with

object

R

Permissions info for the folder. Requires the wl.skydrive scope.

access (shared_with object)

string

R

Info about who can access the folder. The options are:

  • People I selected
  • Just me
  • Everyone (public)
  • Friends
  • My friends and their friends
  • People with a link
The default is Just me.

sort_by

string

RW

Sorts the items to specify the following criteria: updated, name, size, or default.

 

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.

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.

StructureRequired scopes TypeDescription

data

wl.basic

array

An array container for Friend objects when a collection of objects is returned.

id

wl.basic

string

The friend's ID.

name

wl.basic

string

The friend's full name, formatted for locale.

 

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.

Note  

Photos that are uploaded to OneDrive through the API are limited to a maximum resolution of 2048 x 2048 pixels. Any photo over that resolution is scaled proportionally to fit within a maximum size of 2048 x 2048 pixels.

The Photo object contains the following structures.

StructureTypeR/WRequired on createDescription

data

array

R

An array of Photo objects, when a collection of objects is returned.

id

string

R

The Photo object's ID.

from

object

R

Info about the user who uploaded the photo.

name (from object)

string

R

The name of the user who uploaded the photo. Part of the from object.

id (from object)

string

R

The ID of the user who uploaded the photo. Part of the from object.

name

string

RW

Yes

The file name of the photo.

description

string/null

RW

A description of the photo, or null if no description is specified.

parent_id

string

R

The ID of the folder where the item is stored.

size

number

R

The size, in bytes, of the photo.

comments_count

number

R

The number of comments associated with the photo.

comments_enabled

true/false

R

A value that indicates whether comments are enabled for the photo. If comments can be made, this value is true; otherwise, it is false.

tags_count

number

R

The number of tags on the photo.

tags_enabled

true/false

R

A value that indicates whether tags are enabled for the photo. If users can tag the photo, this value is true; otherwise, it is false.

is_embeddable

true/false

R

A value that indicates whether this photo can be embedded. If this photo can be embedded, this value is true; otherwise, it is false.

picture

string

R

A URL of the photo's picture.

source

string

R

The download URL for the photo.

Warning  

This value is not persistent. Use it immediately after making the request, and avoid caching.

upload_location

string

R

The URL to upload photo content hosted in OneDrive. This value is returned only if the wl.skydrive scope is present.

images

array

R

Info about various sizes of the photo.

height (images array)

number

R

The height, in pixels, of this image of this particular size.

width (images array)

number

R

The width, in pixels, of this image of this particular size.

source (images array)

string

R

A URL of the source file of this image of this particular size.

type (images array)

string

R

The type of this image of this particular size. Valid values are:

  • full (maximum size: 2048 × 2048 pixels)

  • normal (maximum size 800 × 800 pixels)

  • album (maximum size 176 × 176 pixels)

  • small (maximum size 96 × 96 pixels)

link

string

R

A URL of the photo, hosted in OneDrive.

when_taken

string/null

R

The date, in ISO 8601 format, on which the photo was taken, or null if no date is specified.

height

number

R

The height, in pixels, of the photo.

width

number

R

The width, in pixels, of the photo.

type

string

R

The type of object; in this case, "photo".

location

object

R

The location where the photo was taken.

Note  The location object is not available for shared photos.

latitude (location object)

double

R

The latitude portion of the location where the photo was taken, expressed as positive (north) or negative (south) degrees relative to the equator.

longitude (location object)

double

R

The longitude portion of the location where the photo was taken, expressed as positive (east) or negative (west) degrees relative to the Prime Meridian.

altitude (location object)

double

R

The altitude portion of the location where the photo was taken, expressed as positive (above) or negative (below) values relative to sea level, in units of measurement as determined by the camera.

camera_make

string

R

The manufacturer of the camera that took the photo.

camera_model

string

R

The brand and model number of the camera that took the photo.

focal_ratio

double

R

The f-number that the photo was taken at.

focal_length

double

R

The focal length that the photo was taken at, typically expressed in millimeters for newer lenses.

exposure_numerator

double

R

The numerator of the shutter speed (for example, the "1" in "1/15 s") that the photo was taken at.

exposure_denominator

double

R

The denominator of the shutter speed (for example, the "15" in "1/15 s") that the photo was taken at.

shared_with

object

R

The object that contains permissions info for the photo.

access (shared_with object)

string

R

Info about who can access the photo. The options are:

  • People I selected
  • Just me
  • Everyone (public)
  • Friends
  • My friends and their friends
  • People with a link
The default is Just me.

created_time

string

R

The time, in ISO 8601 format, at which the photo was created.

updated_time

string

R

The time, in ISO 8601 format, at which the photo was last updated.

 

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.

Note  You can also get a collection of Photo objects by calling either /ALBUM_ID/photos, or /FOLDER_ID/photos.

Note  To display a photo, call /PHOTO_ID/picture. To display a photo of a specific image size, follow /PHOTO_ID/picture with ?type= and one of the following: thumbnail, small, album, normal, or full. The default is normal. The following is an example of a call that displays a thumbnail image.

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--

Note  

The boundary value (shown here as "AaB03x") can be any arbitrary string value.

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.

StructureTypeR/WRequired on createDescription

data

array

R

An array of file and folder objects found in a user's OneDrive that match the search query.

paging

object

R

The path strings that reference the next and previous sets in a paginated response.

 

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.

StructureTypeR/WRequired on createDescription

data

array

R

An array of Tag objects, if a collection of objects is returned.

id

string

R

The Tag object's ID.

user

object

RW

The user object for the tagged person.

name (user object)

string

RW

The name of the tagged person.

id (user object)

string

RW

The user ID of the tagged user if they have one; otherwise, null.

x

number

RW

The center of the tag's horizontal position, measured as a floating-point percentage from 0 to 100, from the left edge of the photo. This value is not returned for Video objects.

y

number

RW

The center of the tag's vertical position, measured as a floating-point percentage from 0 to 100, from the top edge of the photo. This value is not returned for Video objects.

created_time

string

R

The time, in ISO 8601 format, at which the tag was created.

 

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"
}

Note  

Information about the tagged user is stored in the user attribute.

The x and y members are not present on tags that are returned from a video object.

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.

StructureRequired scopesTypeDescription

id

None

string

The user's ID.

name

None

string

The user's full name.

first_name

None

string/null

The user's first name.

last_name

None

string/null

The user's last name.

link

wl.basic

string

The URL of the user's profile page.

birth_day

wl.birthday

number/null

The day of the user's birth date, or null if no birth date is specified.

birth_month

wl.birthday

number/null

The month of the user's birth date, or null if no birth date is specified.

birth_year

wl.birthday

number/null

The year of the user's birth date, or null if no birth date is specified.

work

wl.work_profile

array

An array that contains the user's work info.

employer (work array)

wl.work_profile

object

Info about the user's employer.

name (employer object)

wl.work_profile

string/null

The name of the user's employer, or null if the employer's name is not specified.

position (work array)

wl.work_profile

object

Info about the user's work position.

name (position object)

wl.work_profile

string/null

The name of the user's work position, or null if the name of the work position is not specified.

emails

wl.emails

object

The user's email addresses.

preferred (emails object)

wl.emails

string/null

The user's preferred email address, or null if one is not specified.

account (emails object)

wl.emails

string

The email address that is associated with the account.

personal (emails object)

wl.emails

string/null

The user's personal email address, or null if one is not specified.

business (emails object)

wl.emails

string/null

The user's business email address, or null if one is not specified.

other (emails object)

wl.emails

string/null

The user's "alternate" email address, or null if one is not specified.

addresses

wl.postal_addresses

object

The user's postal addresses.

personal (addresses object)

wl.postal_addresses

object

The user's personal postal address.

street (personal object)

wl.postal_addresses

string/null

The user's personal street address, or null if one is not specified.

street_2 (personal object)

wl.postal_addresses

string/null

The second line of the user's personal street address, or null if one is not specified.

city (personal object)

wl.postal_addresses

string/null

The city of the user's personal address, or null if one is not specified.

state (personal object)

wl.postal_addresses

string/null

The state of the user's personal address, or null if one is not specified.

postal_code (personal object)

wl.postal_addresses

string/null

The postal code of the user's personal address, or null if one is not specified.

region (personal object)

wl.postal_addresses

string/null

The region of the user's personal address, or null if one is not specified.

business(addresses object)

wl.postal_addresses

object

The user's business postal address.

street (business object)

wl.postal_addresses

string/null

The user's business street address, or null if one is not specified.

street_2 (business object)

wl.postal_addresses

string/null

The second line of the user's business street address, or null if one is not specified.

city (business object)

wl.postal_addresses

string/null

The city of the user's business address, or null if one is not specified.

state (business object)

wl.postal_addresses

string/null

The state of the user's business address, or null if one is not specified.

postal_code (business object)

wl.postal_addresses

string/null

The postal code of the user's business address, or null if one is not specified.

region (business object)

wl.postal_addresses

string/null

The region of the user's business address, or null if one is not specified.

phones

wl.phone_numbers

object

The user's phone numbers.

personal (phones object)

wl.phone_numbers

string/null

The user's personal phone number, or null if one is not specified.

business (phones object)

wl.phone_numbers

string/null

The user's business phone number, or null if one is not specified.

mobile (phones object)

wl.phone_numbers

string/null

The user's mobile phone number, or null if one is not specified.

locale

None

string

The user's locale code.

updated_time

wl.basic

string

The time, in ISO 8601 format, at which the user last updated the object.

 

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.

Note  To redirect a GET call to the URL of a user's picture, you can call /me/picture or /USER_ID/picture. You can get different sizes of a user's picture, if they exist, by calling /me/picture?type=SIZE or /USER_ID/picture?type=SIZE, where SIZE is one of the following: small (to get a 96 × 96-pixel picture), medium (180 × 180), or large (360 × 360). If a particular size picture doesn't exist, the next-largest size picture that's available is returned. In any event, a 96 × 96-pixel picture is returned (unless no picture is associated with the user, in which case a default user picture is returned).

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.

StructureTypeR/WRequired on createDescription

data

array

R

An array of Video objects, if a collection of objects is returned.

id

string

R

The Video object's ID.

from

object

R

Info about the user who uploaded the video.

name (from object)

string

R

The name of the user who uploaded the video.

id (from object)

string

R

The ID of the user who uploaded the video.

name

string

RW

Yes

The file name of the video.

description

string/null

RW

A description of the video, or null if no description is specified.

parent_id

string

R

The id of the folder where the item is stored.

size

number

R

The size, in bytes, of the video.

comments_count

number

R

The number of comments that are associated with the video.

comments_enabled

true/false

R

A value that indicates whether comments are enabled for the video. If comments can be made, this value is true; otherwise, it is false.

tags_count

number

R

The number of tags on the video.

tags_enabled

true/false

R

A value that indicates whether tags are enabled for the video. If tags can be set, this value is true; otherwise, it is false.

is_embeddable

true/false

R

A value that indicates whether this video can be embedded. If this video can be embedded, this value is true; otherwise, it is false.

picture

string

R

A URL of a picture that represents the video.

source

string

R

The download URL for the video.

Warning  

This value is not persistent. Use it immediately after making the request, and avoid caching.

upload_location

string

R

The URL to upload video content, hosted in OneDrive. This value is returned only if the wl.skydrive scope is present.

link

string

R

A URL of the video, hosted in OneDrive.

height

number

R

The height, in pixels, of the video.

width

number

R

The width, in pixels, of the video.

duration

number

R

The duration, in milliseconds, of the video run time.

bitrate

number

R

The bit rate, in bits per second, of the video.

type

string

R

The type of object; in this case, "video".

shared_with

object

R

The object that contains permission info.

access (shared_with object)

string

R

Info about who can access the file. The options are:

  • People I selected
  • Just me
  • Everyone (public)
  • Friends
  • My friends and their friends
  • People with a link
The default is Just me.

created_time

string

R

The time, in ISO 8601 format, at which the video was created.

updated_time

string

R

The time, in ISO 8601 format, at which the video was last updated.

 

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.

Note  You can also get a collection of Video objects by calling either /ALBUM_ID/videos, or /FOLDER_ID/videos.

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--

Note  

The boundary value (shown here as "AaB03x") can be any arbitrary string value.

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.

ParameterDescriptionValid valuesDefault valueExamples

pretty

When this value is set to true, Live Connect returns the response in a more human-readable format. When this value is set to false, white space and new lines are not included, which improves performance but makes the response less readable.

true/false

true

pretty=false

callback

The name of the function that handles the JSON with padding (JSONP) function call. When this parameter is specified, all error responses use the HTTP status code 200 to help ensure proper handling in the web browser.

A string that represents the name of the callback function.

None

callback=onResponse

suppress_response_codes

When this value is set to true, Live Connect returns the HTTP status code 200 for all error responses. This option is useful with web-browser plug-ins like Microsoft Silverlight or Adobe Flash Player.

true/false

false

suppress_response_code=true

method

The name of the HTTP method that is used for request processing instead of GET.

A string that represents the HTTP request method, such as POST.

None

method=POST

locale

The locale that determines the format in which Live Connect returns values. In particular:

  • Canonical folder names are translated to the language specified by the locale.
  • Profile data is returned in the format that is appropriate to the locale.
  • Contact data is returned in the format that is appropriate to the locale.

A culture name string from the table in Supported locales.

None

locale=es

return_ssl_resources

By default, Live Connect uses Secure Hypertext Transfer Protocol (HTTPS) to refer to the resources it returns, such as the source URLs for OneDrive items. This helps prevent web-browser warnings when an originating website also uses HTTPS.

Set this parameter to false if you don't want the returned resource to use HTTPS. When set to false, the returned resources will use HTTP.

true/false

true

return_ssl_resources=false

 

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

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.