API Documentation

New - Making an iPhone app? Add full RIL 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
Text - New!
  • Text - Get the text only version of a url
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 reading 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 char string a-z,0-9,-,_ The user's username
password 1-20 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
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.

Send Changes to List

This method allows you to make changes to a user's reading 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-20 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"
    },
    "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:

Tags: Tagging, though active in native RIL applications, the implementation in the public API is still under development. If you'd like your app to make use of tags and would like to help test this feature, please contact me.

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-20 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-20 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 reading list everytime. Abuse of this method may result in your access being disabled.

Tags: Tagging, though active in native RIL applications, the implementation in the public API is still under development. If you'd like your app to make use of tags and would like to help test this feature, please contact me.

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 Read It Later 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-20 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-20 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.

Get Text Only Version

This method will return the text-only version of any url.

Method URL: - Note: this is different than other methods

https://text.readitlaterlist.com/v2/text

Parameters (GET or POST)
apikey string Your app's API key (Get a key)
url UTF-8 url encoded string url of article
mode 'less' or 'more' optional, default=less (see note) version of text view
images 1 or 0 optional, default=0 include image tags in content
Example:
https://text.readitlaterlist.com/v2/text?apikey=yourapikey&url=http://readitlaterlist.com/api/docs
Response:

See Responses for standard header responses.

Unique Responses:

The HTML content of the text view will be returned as the content of the page. In addition there are some other headers to look for:

X-Title - This is the title of the page as detected by RIL.

X-Login-Found - It looks like there may be a login form on this page. If the user needs to login to view the content and you have access to their cookies you may want to provide a fallback generator.

X-Next - If the page appears to be a multi-page article (ex: had a 'next page' link), this will return the url of the next page.

Content-Type - It's important to use the correct character set when displaying the content to the user. Make use of the information in the Content-Type, for example applying it to your Content-Type meta tag in the head of your document.

Important Notes:

New: This method is very new, please report any problems to me. If you have anything you'd like to be added let me know.

Modes: There are two different text modes: less and more. The less view tries to strip all page content except for just the main body of an article. If this fails, it may not return anything. As a fall back you can offer the 'more' mode which shows more of the surrounding page content, but almost always as the content of the article as well.

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