Simple Developer API: Adding Pages to Instapaper

The Simple Instapaper API allows third-party applications to add URLs to Instapaper. If you want to do more than adding URLs from your application to an Instapaper customer’s account, use the Full API.

Use of the Simple API constitues agreement to the API Terms of Use.

Basics

All API methods are accessible via very simple HTTP calls. This is optimized for ease of implementation, so you won’t see any XMLRPC, SOAP, or anything containing the word “enterprise”.

Simply hit the provided URLs with their respective parameters, and a simple text response is sent. The HTTP status code reflects any information that you need to know.

For convenience and easy client processing, the resulting response body always contains just the numeric HTTP status code (except when the redirect option is specified). If you can read the status code from the header, there’s no reason to process the response body.

All parameters may be passed via POST or the query string (GET) or any mixed combination.

The API is available via HTTP or HTTPS. Please use HTTPS if possible.

Authentication can be done via HTTP Basic Auth instead of the username and password POST parameters. Please use Basic Auth when possible.

Authentication

This method validates an Instapaper username and password. Calling this before adding pages is not necessary. Use this if you want to only check credentials without adding a URL to Instapaper, such as when you first prompt the user for Instapaper credentials in a settings screen or on the first Instapaper request.

URL: https://www.instapaper.com/api/authenticate

Parameters:

username
password
jsonp — optional. See JSONP.

Or you can pass the username and password via HTTP Basic Auth.

Resulting status codes:

200: OK
403: Invalid username or password.
500: The service encountered an error. Please try again later.

Adding URLs to an Instapaper account

URL: https://www.instapaper.com/api/add

Parameters:

username and password (Or you can pass the username and password via HTTP Basic Auth.)
url
title — optional, plain text, no HTML, UTF-8. If omitted or empty, Instapaper will crawl the URL to detect a title.
selection — optional, plain text, no HTML, UTF-8. Will show up as the description under an item in the interface. Some clients use this to describe where it came from, such as the text of the source Twitter post when sending a link from a Twitter client.
redirect=close — optional. Specifies that, instead of returning the status code, the resulting page should show an HTML “Saved!” notification that attempts to close its own window with Javascript after a short delay. This is useful if you’re sending people directly to /api/add URLs from a web application.
jsonp — optional. See JSONP.

Resulting status codes:

201: This URL has been successfully added to this Instapaper account.
400: Bad request or exceeded the rate limit. Probably missing a required parameter, such as url.
403: Invalid username or password.
500: The service encountered an error. Please try again later.

If a URL is added that already exists, it will be marked unread and sent to the top of the list. A duplicate will not be created. For convenience, the 201 status will still be returned, even though a new record technically wasn’t created.

When a 201 is returned from this call, two additional response headers are set:

Content-Location: The saved URL for the newly created item, after any normalization and redirect-following.
X-Instapaper-Title: The saved title for the page, after any auto-detection.

About Instapaper credentials

Every user has a unique username (doesn’t have to be an email address, but often is). Passwords are not required, and most users do not have a password. Any interface prompting the user for credentials must accommodate this — for example, you cannot assume that an empty password is a user error.

Authentication behavior:

If an account has a password and an incorrect one is supplied, authentication fails.
If an account does not have a password, any value works.

Preferred language

Wherever possible, please conform to the interface standards of your environment.

When prompting for the username, please label the field “Email or username”, “Email address or username”, or “Username”. Do not label it only “Email”, since many usernames are not email addresses.

If possible, when prompting for an Instapaper password, clarify that it is only required if they actually have a password. For example, on the website’s login form, the box is labeled “Password, if you have one.”

Suggested button or menu titles for the save-URL action: “Send to Instapaper”, “Instapaper: Read Later”, “Read Later with Instapaper”, “Read Later”. Please avoid adding “you” or “me”, e.g. “your Instapaper account”, “my Instapaper”, etc. in this context. (But that’s fine when prompting for credentials.)

JSONP

To receive results as JSON to a specified callback function, pass a valid Javascript function name as the jsonp parameter to Add or Authenticate, e.g. jsonp=callbackName.

The API will return Javascript with an HTTP 200 status code of the format:

callbackName({"status":200});

When Add returns a 201 status, a url value is also included to indicate which URL you asked it to add:

callbackName({"status":201,"url":"whatever-you-sent"});

Any of the possible status values from the Add or Authenticate methods above may be returned.

Support

Sorry, but I am unable to answer basic HTTP programming questions with the Instapaper API.

Please make sure you are properly encoding the parameters. If you are having issues with credentials failing that you know are valid, this is very likely to be the issue. If you are crafting your GET query-string or POST request-body manually, you need to URL-encode the values.

Feedback

If you believe you have found a bug, or you’d like to request additional functionality (no guarantees), or you release something using this API, I’d love to hear from you: instapaper.non.support@marco.org.