Move an Item's Position in a Watchlist

This endpoint moves the specified item from its current position to a different position in the specified watchlist.

HTTP Request

PUT<watchlist_id>/items/<item_id>?account_token=<account_token> -d 'position="<new position>"'

Query Parameters

Parameter Description Type Required
api_version Must be v3. String Yes (URL)
watchlist_id The ID of the watchlist containing the items to update. Must be a valid UUID linked to an existing watchlist associated with the user's account. If not specified, items are updated on the user's default watchlist. UUIDv4 OR String No (URL)
item_id The ID of the item retrieve. Must be a valid item (non-negative integer value) in the specified watchlist. String Yes (URL)
account_token Used by the Watchlist Service to reference the watchlist associated with a particular end user (identified by their UUID). For details, see Ooyala Account Token API. String Yes (URL body)
position The new position to move the item to. Must be a valid position in the specified watchlist. Once an item is moved, the positions of all other items in the specified watchlist are updated automatically.
  • If the new position value exceeds the number of items in the specified watchlist, then the new position is assumed to be the last index in the list of items. For example, if a user's watchlist contains 5 items, which occupy position 0 through 4, if the request attempts to move the item in position 3 to position 10, then the item is actually placed in position 4 (not 10).
  • If the specified position is a decimal number (such as 3.6), the integer portion is used, and the digits to the right of the decimal point are ignored.
String (Number) Yes (URL body)

Return Codes

Code Reason Description
200 OK PUT request succeeded. Item was updated successfully.
400 Request error Failed due to any of the following issues:
  • Parameters are missing or formatted incorrectly.
  • The specified item does not exist in the watchlist.
  • The specified watchlist_id is not empty and does not exist.
  • The specified position is not a positive integer.
401 Unauthorized The specified account_token is invalid.
404 Not found The server is down.
500 Internal server error An internal server error occurred.


    "position" : "2"
Response (Success)