Read Later API

The Instapaper API allows third-party applications to add URLs to Instapaper.

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

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

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
  • password
  • url
  • title — optional, plain text, no HTML, UTF-8
  • selection — optional, plain text, no HTML, UTF-8
  • auto-title=1 — optional, replaces title. Instapaper will crawl the URL to detect a title. Use this if you do not know a title for the URL, such as when it’s an inline link somewhere that hasn’t been opened.
  • 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.

Resulting status codes:

  • 201: This URL has been successfully added to this Instapaper account.
  • 400: Bad request. 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 Instapaper “go” URL for the newly created item. Note that under default user settings, following this URL will mark the story as read and archive it, so please do not follow it under normal circumstances.
  • X-Instapaper-Title: The title saved with the page. Useful if you’re using auto-title=1.

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 “Username”, “Email or username”, or “Email address or username”. (Do not call 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: “Read Later”, “Read Later with Instapaper”, “Send to Instapaper”, “Save with Instapaper”, “Instapaper: Read Later”. When writing your own, 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.)

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@marco.org.

Tags: api