API Documentation

IMPORTANT We have not yet officially updated the API to reflect our new domain name. You should continue to use readitlaterlist.com for all API calls. We will provide more information and an update in the near future.

Making an iPhone app? Add full Pocket support to your app in 1 line of code! - iPhone Library

Methods

List Management
  • Add - Add a page to a user's list
  • Send - Mark items as read, add multiple pages, change titles, or set tags
  • Get - Retrieve a user's reading list
  • Stats - Retrieve information about a user's list
Account Management
Article View
API
  • API - Return stats / current rate limit information about your API key

What else you'll need to know

API Methods

Add a New Page

This method allows you to add a page to a user's list.

For a simplified method of saving that may be applicable to some types of applications, see Saving Methods.

Method URL:

https://readitlaterlist.com/v2/add

Parameters (GET or POST)
apikey string Your app's API key (Get a key)
username 1-20 character string The user's username
password 1-100 character string The user's password
url UTF-8 url encoded string url of page to save
title UTF-8 encoded string optional (see note) title of page to save
ref_id UTF-8 encoded string twitter clients: see note tweet id
Example:
https://readitlaterlist.com/v2/add?username=name&password=123&apikey=yourapikey&url=http://google.com&title=Google
Response:

See Responses.

Important Notes:

Batching: The add method is provided as a quick way to save one link to a users list. If you have more than one link to save do not use this method. Instead, use the send method which allows you to send multiple changes in one request.

Titles: For the best user experience, if you do not have a title, supply some unique context if possible. For example, a twitter client might use the tweet that went along with the link.

ref_id: If you are adding Pocket support to a Twitter client, please send along a reference to the tweet status id in the ref_id parameter. This allows Pocket to show the original message alongside the article. See this post for an example.

Send Changes to List

This method allows you to make changes to a user's list. It supports adding new pages, marking pages as read, changing titles, or updating tags. Multiple changes to items can be made in one request.

Method URL:

https://readitlaterlist.com/v2/send

Parameters (GET or POST)
apikey string Your app's API key (Get a key)
username 1-20 char string a-z,0-9,-,_ The user's username
password 1-100 character string The user's password
new JSON object (see format) optional new page(s) to add to list
read JSON object (see format) optional page(s) to be marked as read
update_title JSON object (see format) optional changed titles for items
update_tags JSON object (see format) optional new set of tags for item (see note)
Example:
https://readitlaterlist.com/v2/send?username=name&password=123&apikey=yourapikey...(see format sections below)
Response:

See Responses.

new Format: (JSON)
{
    "0":{
	"url":"http://google.com",
	"title":"Google"
	"ref_id":"123456709" //for twitter clients only: see note
    },
    "1":{
	"url":"http://ideashower.com",
	"title":"The Idea Shower"
    }
}
read Format: (JSON)
{
    "0":{
	"url":"http://google.com"
    },
    "1":{
	"url":"http://ideashower.com"
    }
}
update_title Format: (JSON)
{
    "0":{
	"url":"http://google.com",
	"title":"Google"
    },
    "1":{
	"url":"http://ideashower.com",
	"title":"The Idea Shower"
    }
}
update_tags Format: (JSON)

NOTE: This replaces all of the tags for the item with the new ones you provide.

{
    "0":{
	"url":"http://google.com",
	"tags":"comma,seperated,list"
    },
    "1":{
	"url":"http://ideashower.com",
	"tags":"ideas,developer,nate weiner"
    }
}
Important Notes:

ref_id: If you are adding Pocket support to a Twitter client, please send along a reference to the tweet status id in the ref_id parameter. This allows Pocket to show the original message alongside the article. See this post for an example.

Retreive information about a user's list

This method returns some information about a user's list.

Method URL:

https://readitlaterlist.com/v2/stats

Parameters (GET or POST)
apikey string Your app's API key (Get a key)
username 1-20 char string a-z,0-9,-,_ The user's username
password 1-100 character string The user's password
format json or xml, default=json optional response format
Example:
https://readitlaterlist.com/v2/stats?username=name&password=123&apikey=yourapikey
Response:

See Responses for response headers and possible error codes. A successful response will return a list in either JSON or XML format:

Example JSON Response:
{
   "user_since":"1245626956',		// unix time user account was created
   "count_list":"333',		// number of items in user list
   "count_unread":"100',		// number of items unread
   "count_read":"233',		// number of items read
}
Example XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<user_since>1245626956</user_since>
<count_list>333</count_list>
<count_unread>100</count_unread>
<count_read>233</count_read>
Important Notes:

Be Gentle, Cache When Possible: If you manage/sync/get the user's list using the get method, you should calculate these counts yourself. This method is provided for simpler applications that do not need to retrieve the entire user's list.

Retreive a User's List

This method allows you to retrieve a user's list. It supports retrieving items changed since a specific time to allow for syncing.

Method URL:

https://readitlaterlist.com/v2/get

Parameters (GET or POST)
apikey string Your app's API key (Get a key)
username 1-20 char string a-z,0-9,-,_ The user's username
password 1-100 character string The user's password
format json or xml, default=json optional response format
state read or unread (leave empty for all) optional which type of items to retrieve
myAppOnly 0 or 1, default = 0 optional, (see note) only retrieve pages saved from your api key
since unix epoch time optional, (see note) only get changed/added items since this time
count integer (leave empty for all) optional, (see note) number of items to retrieve
page integer optional used with count to paginate results
tags 1 or 0, default=0 optional retrieve tags with items (see note)
Example:
https://readitlaterlist.com/v2/get?username=name&password=123&apikey=yourapikey&since=1245638446
Response:

See Responses for response headers and possible error codes. A successful response will return a list in either JSON or XML format:

Note: Items are returned ordered by time_updated, descending

Example JSON Response:
{
   "status":"1",			// 1=normal, 2=no changes since your provided 'since'
   "since":"1245626956',		// timestamp of this response
   "list":{
      "93817":{
         "item_id":"93817"		    // unique id identifying the url
         "url":"http://url.com",
         "title":"Page Title",
         "time_updated":"1245626956",       // time the item was last added/changed
         "time_added":"1245626956",	    // time item was added to list
         "tags":"comma,seperated,list",
         "state":"0",                       // 0=unread, 1=read
      },
      "935812":{
         "item_id":"935812"		    // unique id identifying the url
         "url":"http://google.com",
         "title":"Google",
         "time_updated":"1245626956",       // time the item was last added/changed
         "time_added":"1245626956",	    // time item was added to list
         "tags":"comma,seperated,list",
         "state":"1",                       // 0=unread, 1=read
      }
   }
}
Example XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<status>1</status>
<since>1245626956</since>
<list>
	<item>
		<item_id>93817</item_id>
		<url>http://url.com</url>
		<title>Title</title>
		<time_updated>1245626956</time_updated>
		<time_added>1245626956</time_added>
		<tags>comma,seperated,tags</tags>
		<state>0</state>
	</item>
	<item>
		<item_id>9243817</item_id>
		<url>http://google.com</url>
		<title>Homepage</title>
		<time_updated>1245626956</time_updated>
		<time_added>1245626956</time_added>
		<tags>comma,seperated,tags</tags>
		<state>1</state>
	</item>
</list>
Important Notes:

Retrieving Full List: Whenever possible, you should use the since, count, and page parameters when retrieving a user's list. After retrieving the list, you should store the current time (which is provided along with the list response) and pass that in the next request for the list. This way the server only needs to return a small set (changes since that time) instead of the user's entire list every time. Abuse of this method may result in your access being disabled.

myAppOnly: Use this parameter to only retrieve items saved by your application. This is helpful if you'd like to provide a way for users to see pages they've saved to Pocket directly from inside your application.

Authentication

The authentication method is used to verify a supplied username and password is correct (for example when prompting a user for their credentials for the first time). It does not need to be called before using any methods below.

Method URL:

https://readitlaterlist.com/v2/auth

Parameters (GET or POST)
apikey string Your app's API key (Get a key)
username 1-20 char string a-z,0-9,-,_ The user's username
password 1-100 character string The user's password
Example:
https://readitlaterlist.com/v2/auth?username=name&password=123&apikey=yourapikey
Response:

See Responses.

Register a New User

This method allows you to create a new user account.

Method URL:

https://readitlaterlist.com/v2/signup

Parameters (GET or POST)
apikey string Your app's API key (Get a key)
username 1-20 char string a-z,0-9,-,_ The user's username
password 1-100 character string The user's password
Example:
https://readitlaterlist.com/v2/signup?username=name&password=123&apikey=yourapikey
Response:

See Responses.

Special Case: The 401 status code will be returned when the supplied username is already taken. The X-Error header will also say this in english.

API Status

This method allows you to check your current rate limit status. Calls to this method do not count against the rate limit.

Method URL:

https://readitlaterlist.com/v2/api

Parameters (GET or POST)
apikey string Your app's API key (Get a key)
Example:
https://readitlaterlist.com/v2/api?apikey=yourapikey
Response:

See Responses.

Response, Status, and Error Codes

Each call to the API will return a number of informational headers. The most important of which is the status header which indicates if the call was successful or not.

Example Response Headers
Status: 200 OK
X-Limit-User-Limit: 100
X-Limit-User-Remaining: 43
X-Limit-User-Reset: 25
X-Limit-Key-Limit: 5000
X-Limit-Key-Remaining: 3520
X-Limit-Key-Reset: 25
List of Possible Headers

Status:

  • 200 - Request was successful
  • 400 - Invalid request, please make sure you follow the documentation for proper syntax
  • 401 - Username and/or password is incorrect
  • 403 - Rate limit exceeded, please wait a little bit before resubmitting
  • 503 - Read It Later's sync server is down for scheduled maintenance.

NOTE: If there was an error, look at the X-Error header for a description of the problem

X-Error: More detailed description of the error. Also in the case of a 503 status (when RIL is undergoing maintenance, this will provide information to display to the user. Ex: 'Read It Later is upgrading its servers and will return in 30 minutes')

X-Limit-User-Limit: Current rate limit enforced per user

X-Limit-User-Remaining: Number of calls remaining before hitting user's rate limit

X-Limit-User-Reset: Seconds until user's rate limit resets

X-Limit-Key-Limit: Current rate limit enforced per API key

X-Limit-Key-Remaining: Number of calls remaining before hitting API key's rate limit

X-Limit-Key-Reset: Seconds until API key rate limit resets