Read, create, or delete tags (REST)

  • Article

Your apps can read, create, and delete tags (a type of comment) that users can add to photos, videos, and audio, using the REST API.

In this article
Prerequisites
Read a tag
Create a tag
Delete a tag
Remarks

Prerequisites

We assume that the user has already signed in and consented to the wl.skydrive scope for reading file or folder properties. If you have not added user sign-in to your apps, see Signing users in with REST.

We assume that you are familiar with the REST API and JSON.

Read a tag

To get info about tags, use code like this. The wl.skydrive scope is required. You can change the photo ID to a different photo ID, video ID, or audio ID, to get info about the tags for another photo, video, or audio. Specify a tag's ID to get info about that individual tag.

You can also:

  • Get a limited number of tags by using the limit parameter in the example code to specify the number of items to get. For example, to get the first two tags, use PHOTO_ID/tags?limit=2.

  • Set the first tag to start getting by using the offset parameter in the preceding code to specify the index of the first item to get. For example, to get two items starting at the third item, use PHOTO_ID/tags?limit=2&offset=3.

    Note

    In the JavaScript Object Notation (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.

GET https://apis.live.netv/5.0/file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!131/tags?access_token=ACCESS_TOKEN

Create a tag

To create a tag, use code like the following. Change the photo ID to a different photo ID, video ID, or audio ID, to add a tag to another photo or video. The wl.skydrive_update scope is required.You can create tags for items that are owned by, or shared with, the signed-in user.

  • To create a tag for an item that is owned by the signed-in user, replace the photo ID with the item's ID in the code that follows.

  • To create a tag for an item that is shared with the signed-in user, first use the wl.contacts_skydrive scope to make a GET request to /USER_ID/skydrive/shared, where USER_ID is either me or the user ID of the consenting user. Note that the consenting user must be a contact of the signed-in user. Then, if the item is included in the response, replace the photo ID with the item's ID in the code that follows.

POST https://apis.live.net/v5.0/file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!131/tags

Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "user": {
            "name": "Stig Struve-Christensen",
            "id": "a6b2a7e8f2515e5f"
    },
    "x": 0.5, 
    "y": 0.5 
}

Delete a tag

To delete a tag, use code like the this. Change the tag ID to the tag ID of the tag that you want to remove. The wl.skydrive_update scope is required.

Note

Only the owner of an item can delete that item's tags.

DELETE https://apis.live.net/v5.0/tag.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!131.PlP_Zr6OeZfqtMa%3DJVLP11mNcD0?access_token=ACCESS_TOKEN

Remarks

For details about the required and optional structures that your app must provide to use POST, see Tag object.