ShortReviews/LongReviews REST API v1.0

This documentation will always be available in its latest form at

An example site built with this site is available at, and the source for this site can be downloaded from


If the library you are using does not support DELETE requests, use a POST request with the parameter _method=DELETE

All requests are required to have the following parameters:
both of these can be found on your account settings page. All requests are rate limited by user, as specified on each method

Example request:

Requests can be in either json or xml format

Return Codes

200 - successful
400 - invalid request, probably missing required parameters
401 - outdated or incorrect userid/key
403 - probably rate limited
404 - failed request, item did not exist
406 - this method does not support the request type you provided (e.g. GET vs POST)

Error Returns:
code - the http error code
message - description of the error
wait - how many seconds to wait before retrying this request, only included on rate limit errors

{"error":{"code":403,"message":"Rate limited, no more than one request per second","wait":3}}

API Methods

Retrieve pages of reviews
Retrieve a review
Submit a review
Delete a review

Retrieve all items on a list
Add item to a list
Remove item from a list

Retrieve all your lists
Add a new list
Rename a list
Delete a list

Find item ID
Add a new item

GET /1/review.format

Description: Retrieves your review on a specified item
id - the ID of the item you reviewed
extended - optional, set this argument to 1 if you want the data to include the movie title and cover art

{"review":{"id":"1780","movie":12944,"rating":"2.0","type":"short","text":"Decent acting, but the story felt a bit disjointed. Some parts were interesting - others were pretty slow - but I would never describe it as exciting or suspenseful. If the cast had been worse this would have been a <i>terrible</i> film"}}

POST or PUT /1/review.format

Description: Submits a review, or overwrites if one exists already
id - the ID of the item you are reviewing
rating - the rating from 0-5 in increments of .5
text - the review

DELETE /1/review.format

Description: Deletes your review on a specified item
id - the ID of the item you reviewed

GET /1/reviews.format

Description: Retrieves pages of your reviews
sort - the ordering to use - dateasc, datedesc, rateasc, ratedesc
type - optional, media type - film, music, book, game
page - optional, (zero based) returns 15 reviews per page
extended - optional, set this argument to 1 if you want the data to include the movie title and cover art

{"reviews":[{"id":"1842","movie":"182105","rating":"2.5","type":"short","text":"Brooke Nevin and Jimmi Simpson are great, but replacing Nicole Steinwedell with Serinda Swan after one episode was a mistake as well as an odd script choice. The cast is slowly getting better each episode."},{"id":"1830","movie":"182093","rating":"4.0","type":"short","text":"Foreign with Subtitles. Reminds me of a 20th century Lara Croft. Thoroughly entertaining, but the police scenes were <a href=\"/review/146332-the-pink-panther/\" target=\"_blank\">The Pink Panther</a> quality bumbling, and not quite as funny as intended. Hopefully they'll make more in the series."},{"id":"1829","movie":"181241","rating":"0.5","type":"short","text":"This had potential to be suspenseful in the beginning, but then the terrible gunfights began. Unlimited ammo, trading shots and never hitting anything for minutes on end. The priest/church part of the story was an unnecessary plot device as well."},{"id":"1827","movie":"182092","rating":"3.0","type":"short","text":"Good casting, especially Vera Farmiga - she was perfect for that role. The ending could have been a bit more shocking/artistic if they had just cut it off, but it probably wouldn't have played as well with audiences."},{"id":"1826","movie":"182091","rating":"3.5","type":"short","text":"More action than your typical lawyer film. Good cast and decent script - a bit predictable in parts but still entertaining to watch."}],"count":988}

GET /1/search.format

Description: Find the ID of an item
type - film, music, book, game
title - The name/title of the item
author - Optional, only used for books. If you specify an author you may, but are not required, to specify a title.
artist - Optional, only used for music. If you specify an artist you may, but are not required, to specify a title.

{"search":[{"id":"122246","title":"Mad Max","platform":"NES","reviews":"0","alt":"false","reviewed":"false","listed":"false"},{"id":"121582","title":"Max Payne 2: The Fall of Max Payne","platform":"PC","reviews":"1","alt":"false","reviewed":"false","listed":"false"},{"id":"127819","title":"Max Payne 2: The Fall of Max Payne","platform":"PS2","reviews":"0","alt":"false","reviewed":"false","listed":"false"},{"id":"130438","title":"Max Payne 2: The Fall of Max Payne","platform":"Xbox","reviews":"0","alt":"false","reviewed":"false","listed":"false"},{"id":"121258","title":"Blue Max","platform":"PC","reviews":"0","alt":"false","reviewed":"false","listed":"false"},{"id":"121581","title":"Max Payne","platform":"PC","reviews":"0","alt":"false","reviewed":"false","listed":"false"},{"id":"127818","title":"Max Payne","platform":"PS2","reviews":"0","alt":"false","reviewed":"false","listed":"false"},{"id":"130437","title":"Max Payne","platform":"Xbox","reviews":"0","alt":"false","reviewed":"false","listed":"false"},{"id":"122609","title":"The Adventures of Mighty Max","platform":"Genesis","reviews":"0","alt":"false","reviewed":"false","listed":"false"},{"id":"124362","title":"The Adventures of Mighty Max","platform":"SNES","reviews":"0","alt":"false","reviewed":"false","listed":"false"}]}

GET /1/list.format

Description: Retrieves all items on the specified list
id - the ID of the list

{"listitem":[{"id":"73","type":"film","rating":"4.0","title":"Blood and Chocolate"},{"id":"61","type":"film","rating":"4.5","title":"Dangerous Beauty"},{"id":"8068","type":"film","rating":"4.5","title":"Notting Hill"},{"id":"113765","type":"film","rating":"4.5","title":"Ondine"},{"id":"8197","type":"film","rating":"3.0","title":"One Night with the King"},{"id":"10337","type":"film","rating":"4.0","title":"Sweet Home Alabama"},{"id":"11","type":"film","rating":"4.5","title":"The Time Traveler's Wife"},{"id":"93","type":"film","rating":"3.0","title":"Wild Child"}]}

POST /1/list.format

Description: Add item to a list
id - the ID of the list
item - the ID of the item to add

DELETE /1/list.format

Description: Remove an item from a list
id - the ID of the list
item - the ID of the item to remove

GET /1/lists.format

Description: Show the names and IDs of all your lists
id - optional, specify an ID if you only want the title of a single list

{"list":[{"id":1,"title":"Wishlist"},{"id":2,"title":"Watched"},{"id":3,"title":"Blocked"},{"id":"86","title":"Favorite Feel-Good"},{"id":"78","title":"Favorite Comedy"},{"id":"79","title":"Favorite Action"},{"id":"80","title":"Favorite Classic"},{"id":"81","title":"Favorite Romance"},{"id":"87","title":"Favorite Quirky"},{"id":"105","title":"Childhood Cartoons"},{"id":"84","title":"Favorite Suspense"},{"id":"85","title":"Favorite Kids"},{"id":"88","title":"Favorite Drama"}]}

POST /1/lists.format

Description: Add a new list
name - the name of the list to add


PUT /1/lists.format

Description: Rename a list
id - the ID of list to rename
name - the new name for the list


DELETE /1/lists.format

Description: Delete a list
id - the ID of the list to delete

POST /1/item.format

Description: Add a new item. If you attempt to add an item that exists, the id for that item will be returned instead. Using this method as a search tool is a bad idea because existing data may vary slightly from what you are adding, resulting in duplicate titles

Note: This is subject to the same restrictions as normal additions on the site A 400 error will be returned if you don't have permission

type - film, music, book, game
title - The name/title of the item
author - Required for books
artist - Required for music
year - Required for films
platform - Required for games. Values: pc, nes, genesis, gameboy, gamegear, snes, saturn, ps1, n64, dreamcast, ps2, gba, gc, xbox, ds, psp, xbox360, wii, ps3