Listly API V4 Documentation

HTTP Status Codes & Response

400 Bad Request

If an APi call fails because of incorrect parameters or data related errors, the API will return a 400 Bad Request

HTTP Status Code: 400
{errors: [{status: 400, message: "List Title should be atleast 5 characters"}]}

401 Signin Required

Many API endpoints require that an authenticated user makes the request. If an endpoint requires an authenticated user, but the authentication_token is missing or incorrect, the API will return the following response.

HTTP Status Code: 401
{errors: [{status: 401, message: "Signin to use Listly"}]}

If the client gets the 401 status, it can take the user to the Signin Screen with the message:

Signin to use Listly

403 Forbidden

Many API endpoints require that an authenticated user also be authorized to perform the specified operation. If the user is not authorized for that operation, the API will return the following response.

HTTP Status Code 403
{errors: [{status: 403, message: "You don't have permissions for that"}]}

Theoretically, this should never happen because the client will only expose functionality to the user that they have permissions for. If the client is hacked and is enabled to make unauthorized requests, it will handle the 403 status with this message:

You don't have permissions for that

426 Upgrade Required

If the user performs something that requires an upgrade (over quota, premium features), the API will return this message:

HTTP Status Code 426
{errors: [{status: 426, message: "Upgrade Required: More than 10 items a day"}]}

The user sees this message:

Upgrade Required: More than 10 items a day. <>

500 Unexpected Error

If an unexpected error happened, it will be logged on the server for debugging and eventual fix. The API will return the following reponse.

HTTP Status Code 500
{errors: [{status: 500, message: "Something unexpected happened. It's been logged and we're on it"}]}

The user sees this message:

Something unexpected happened. It's been logged and we're on it

404 Not Found

If a resource is not found (list, item, comment, user etc), the API will return the following reponse.

HTTP Status Code 404
{errors: [{status: 404, message: "Resource Not Found"}]}

Server Error

If the server is down or timesout, there will be an unexpected non JSON response. The client can handle that based on different scenarios including "Cannot reach Listly. Please try later"

List Object

{
  "list": {
    "id": "G",
    "title": "Top ten wonders of the world",
    "description": "<p>From Taj Mahal to Eiffel Tower, here are the top wonders of the world</p>\n",
    "stats": {
      "views": 0,
      // The number of views for the list

      "helperCount": 0,
      // the number of helpers for the list (users that have added items)

      "publishedItemCount": 0,
      // the number of items in the list

      "queuedItemCount": 0,
      // the number of items in the queue waiting for moderation

      "favoritesCount": 0
      // The number of people that have favorited the list

      "followerCount": 0
      // Same as favoritesCount. Kept for backward compatibility

    },
    "configuration": {
      "isModerated": false,
      // if isModerated is true, any addition to a list by anyone other than owner 
      // or users with editor privileges will be added to the queue for moderation

      "isPrivate": false,
      // If isPrivate is true, the list can be viewed only by the owner 


      "userCanAdd": true,
      // if userCanAdd is true, then anyone can contribute items to the list


      "userCanComment": true,
      // if userCanComment is true, then comment is enabled for items in the list
      // if false, comment feature will be disabled

      "userCanSeeQueue": true,
      // if userCanSeeQueue is true, then anyone can see the items in the queue
      // if false, only owner and editors can see queue. Others won't see the option to view the queue.

      "userCanVote": true,
      // if userCanVote is true, then upvoting is enabled, otherwise all voting is turned off


      "anonymousCanVote": true,
      // if anonymousCanVote is true, then voting is enabled for anonymous users
      // if false, then anonymous users clicking on voting button should take user to signin page


      "votingClosed": false,
      // if votingClosed is true, then clicking on voting button should alert users that "Voting is closed"


      "emojiVoting": true,
      // if emojiVoting is true, then show emoji voting button
      // if false, hide emojiVoting button. Upvote can still be shown based on "userCanVote"

      "defaultSort": "crowdrank",
      // the initial sort when the list is displayed. One of "crowdRank", "newest", "alpha", "curated", "chronological"

      "defaultLayout": "full"
      // default layout for list.  One of "list", "gallery", "slideshow", "minimal", "magazine"

    },
    "headline": "https://pigment.github.io/fake-logos/logos/medium/color/7.png",
    "created_at": "2016-05-04T00:53:06-07:00",
    "updated_at": "2016-05-04T00:53:06-07:00",
    "item_tags": [

    ],
    "user_data": {
      "ownedByMe": false,
      // true if list is owned by the authenticated user making the API request

      "editablebyMe": false,
      // true if list is owned or otherwise editable by the authenticated user making the API request
      // show "edit", "delete" functionality for list if this is true

      "favoritedByMe": false
      // true if list is favorited by the authenticated user making the API request

    },
    "owner": {
      "id": 739,
      "name": "Benton Mayert",
      "screen_name": "jules_rippin",
      "email": "brielle@homenick.co",
      "profile_image": "https://robohash.org/utetet.png?size=300x300&set=set1",
      "stats": {
        "listCount": 1,
        "followerCount": 0,
        "followingCount": 0,
        "helperCount": 0,
        "embedCount": 0,
        "viewCount": 6573,
        "mojoPoints": 180
      },
      "bio": "",
      "status": {
        "isCurator": false,
        "hasPro": false
      },
      "user_data": {
        "userIsMe": false,
        "followedByMe": false
      }
    },
    "curators": [

    ],
    "last_helpers": [

    ]
  }
}

Item Object

{
   "id":19925,
   "name":"BEST CAR EVER FERRARI F40",
   "url":"http://www.youtube.com/watch?v=R3lgehIWXC8",
   "item_note":"<p>Whats the video about? The Ferrari f40 is the best super car ever, in this video Jeremy Clarkson reviews the f40 and explains why, leave your comments rate a...</p>\n",
   "created_at":"2012-03-30T09:06:53-07:00",
   "updated_at":"2016-04-21T06:42:04-07:00",

   "position": 7,
   // the curated position of the item in the list

   "latitude": null,
   // any associated latutude location information for the item

   "longitude": null,
   // any associated longitude location information for the item

   "location": null,
   // any location address for the item

   "images":{
      "small":"http://media-cdn.list.ly/production/3871/19925/hqdefault_185px.png",
      "large":"http://media-cdn.list.ly/production/3871/19925/hqdefault_600px.png"
   },
   "tags":[
      "ferarri",
      "f40"
   ],
   "stats":{

      "commentCount":0
      // total comments for the item

   },

   "media_source":"youtube",
   "media_type":"video",
   "media_url":"http://www.youtube.com/watch?v=R3lgehIWXC8",
   "media_stream_url":null,

   "user_data":{
      "createdByMe":false,
      // true if the item was created by the authenticated user making the API request
      "editableByMe":false
      // true if the item can be edited by the authenticated user making the API request
      // this will help show "edit", "delete", "accept into list", "move to queue" functionality
   },

   "reactions_data":[
      [
         ":thumbsup:",
         4.0
      ],
      [
         ":notes:",
         1.0
      ],
      [
         ":joy:",
         1.0
      ]
   ],
   "user_reactions_data":[

   ],
   "creator":{
      "id":8,
      "name":"George",
      "screen_name":"Carlin",
      "email":"shyam+gi@shyam.com",
      "profile_image":"http://media-cdn.list.ly/staging/profiles/8/picture.png?ver=9172092960",
      "stats":{
         "listCount":49,
         "followerCount":3,
         "followingCount":4,
         "helperCount":132,
         "embedCount":"30",
         "viewCount":52166,
         "mojoPoints":6237
      },
      "bio":"<p>It's \uf643</p>\n\n<p>T</p>\n",
      "status":{
         "isCurator":false,
         "hasPro":true
      },
      "user_data":{
         "userIsMe":false,
         "followedByMe":false
      }
   },
   "last_comments":[

   ]
}