POST (/users/xuid(xuid)/lists/PINS/)
Inserts items into the list at the index based on the query string parameter insertIndex. The domain for these URIs iseplists.xboxlive.com.
- Remarks
- URI parameters
- Query string parameters
- Authorization
- HTTP status codes
- Required Request Headers
- Sample request
- Response body
Remarks
This call will insert items into the list at the index based on the query string parameter insertIndex (defaults to 0 or the beginning of the list). All items in the request body will be inserted at that point in the list. If the insertIndex is greater than the number of items in the existing list, the new items will be inserted at the end. Items to be inserted must have the required fields indicated in the functional spec; otherwise, an HTTP 400 will be returned. Similarly, if the result of the insert will exceed the maximum size of the list (defined per list type) then an HTTP 400 will be returned and nothing will be inserted. If the item is not to be inserted at the beginning or the end of the list, then the If-Match:versionNumber header is required to be included in the request. The header is optional if the insertion is for the beginning or the end. If present, the header will be validated regardless of the insert location. In the header VersionNumber is the current version number of the list. If it is not included and required, or does not match the current list version number, then an HTTP 412 (precondition failed) status code will be returned and the body of the response will contain the latest metadata of the list that includes the current version number. This is to guard against updates from different clients trampling on one another. Note that this call is not idempotent; repeated calls with the same data could result in multiple insertions. However, since no list currently supports duplicates, repeated calls will likely result in HTTP 400 codes being returned.URI parameters
Query string parameters
| Parameter| Type| Description| | --- | --- | --- | --- | --- | --- | | insertIndex| string| Optional. Defines where to insert items. Supported values: 0, positive integers, and “end”. Any index value greater than the number of list items will add the new item at the bottom of the list, and will not insert “blank” space in the list. Default value: 0.|Authorization
This call expects an XSTS SAML token in the Authorization header. A Xuid claim must exist within that SAML token to identify the caller. This value is used to determine if the caller has access rights to the list data in question. The list itself will be identified by the Xuid as well and will be included in the URI for the list. Using this, we may in the future support shared access to lists, but that is not a feature at this time. Currently, all lists that a user accesses will be their own and there is no shared access. Thus the Xuid in the URI must match the Xuid in the SAML claims token.Note:
Both XBL Auth 2.0 and 3.0 tokens are supported at present.