POST (/1/content/{namespace}/collection/add)

Add tracks to a user's collection.

Remarks

Important
User authentication is mandatory for this API.

Provide a batch of IDs and the API will try to add them to the user's collection. In case of partial failure (when some of the tracks aren't added), the API will return an HTTP 200 error and you will need to parse the results to see which actions failed and why.

The number of tracks per batch is limited to 100.

For parameters common to every Groove RESTful API, see Parameters common to every Groove RESTful API. For a table of error codes, see Error (JSON). For HTTP status codes, see Groove RESTful API HTTP Status Codes.

URI parameters

Parameter Type Description
namespace string Required. The namespace to browse ("music" for example).
accessToken string A valid developer authentication Access Token, used to identify the 3rd party application using the Groove APIs.

Examples

Request object: TrackActionRequest (JSON).

Response object: TrackActionResponse (JSON).

Add tracks to collection

We will add one valid track ID, and one invalid ID (random-generated).

Request

POST /1/content/music/collection/add

Authorization: Bearer eyJlbmMiOiJB[...]

Content-Type: application/json
{
  "TrackIds": [
    "music.9bb2c5c5-455c-4c15-827c-f9bfd759a458",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933"
  ]
}

Response

{
  "TrackActionResults": [
    {
      "InputId": "music.9BB2C5C5-455C-4C15-827C-F9BFD759A458",
      "Error": {
        "ErrorCode": "COLLECTION-INVALID-ID",
        "Description": "Invalid collection id for this operation",
        "Message": "Collection ErrorCode=ArgumentInvalid, Details=ContentId"
      }
    },
    {
      "InputId": "music.A83EB907-0100-11DB-89CA-0019B92A3933",
      "Id": "music.AQQfZ78ml185KUqtiDc9dx6i6Ae5PqgAAQ"
    }
  ],
  "Error": {
    "ErrorCode": "COLLECTION-SOME-OPERATIONS-FAILED",
    "Description": "Some of the operations failed"
  }
}

Add too many tracks at once

The batch size is limited to 100 items.

Request

POST /1/content/music/collection/add

Authorization: Bearer eyJlbmMiOiJB[...]

Content-Type: application/json

{
  "TrackIds": [
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933",
    "music.A83EB907-0100-11DB-89CA-0019B92A3933"
  ]
}

Response

400 BadRequest

{
  "Error": {
    "ErrorCode": "COLLECTION-INVALID-OPERATION",
    "Description": "This operation is not supported",
    "Message": "Number of tracks for this operation is limited to 100"
  }
}

Add a track using XML instead of JSON

Request

POST /1/content/music/collection/add

Authorization: Bearer eyJlbmMiOiJB[...]

Content-Type: application/xml

<TrackActionRequest xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.microsoft.com/xboxmusic/2013/10/platform">
  <TrackIds xmlns:d2p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
    <d2p1:string>music.873FB507-0100-11DB-89CA-0019B92A3933</d2p1:string>
  </TrackIds>
</TrackActionRequest>

Response

<TrackActionResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.microsoft.com/xboxmusic/2013/10/platform">
  <TrackActionResults>
    <TrackActionResult>
      <Id>music.AQQfuiqlXWaDzk-j0Ht9qB6EWwe1P4cAAQ</Id>
      <InputId>music.873FB507-0100-11DB-89CA-0019B92A3933</InputId>
    </TrackActionResult>
  </TrackActionResults>
</TrackActionResponse>

Access is denied if the user authentication token is missing or invalid

Request

POST /1/content/music/collection/add

Authorization: Bearer [...]
Content-Type: application/json

{
  "TrackIds": [
    "music.A83EB907-0100-11DB-89CA-0019B92A3933"
  ]
}

Response

401 Unauthorized

{
  "Error": {
    "ErrorCode": "INVALID-AUTHORIZATION-HEADER",
    "Description": "Missing or invalid authorization header",
    "Message": "You need user authentication to use this API"
  }
}

Parent

Groove Service REST Reference