Build on the Readplace API

The Readplace API lets an integration save links, list and read articles, and file them into readlists, for a reader who approves it.

What you can build

The API speaks Siren (application/vnd.siren+json), a hypermedia format: every answer carries the links and actions you can take next. Articles also come as Markdown documents (text/markdown).

An integration acts for one reader, who approves it with their Readplace account. Create an account to try it.

A typical integration is a scheduled job that drains a readlist: it lists what's in it, reads each article as Markdown, hands it on, then takes it out of the readlist. The walkthrough at the end follows that flow. Nothing is pushed to you, so the job polls.

Readplace's own apps use the same API:

  • Firefox
  • Chrome
  • iPhone
  • Android

Register your app and get a token

Readplace is its own OAuth 2.0 authorization server. Its metadata is at /.well-known/oauth-authorization-server, and the protected resource metadata at /.well-known/oauth-protected-resource points to it.

Register

Register once with Dynamic Client Registration (RFC 7591): send a POST with JSON to /oauth/register.

  • Each redirect URI is https, on any host (https://localhost included), or plain http on 127.0.0.1 or [::1]. http://localhost and custom schemes are refused with 400 invalid_redirect_uri.
  • redirect_uris holds 1 to 32 URIs of up to 2,048 characters each.
  • client_name is optional and up to 120 characters, and the reader sees it when approving your app. Without it, Readplace names your app after the host of the first redirect URI, without its port.
  • There's no client secret. If you send token_endpoint_auth_method, it must be none.
  • The 201 answer carries your client_id. Sending the same registration again returns the same client_id.
  • A registration that never gets a token expires after 48 hours. Once it has one, it stays registered until 365 days after its latest token, refreshes included.
  • /oauth/register and /oauth/token limit how often one IP address can call them. Over the limit, they answer 429 with a Retry-After header.

Authorize

Send the reader's browser to /oauth/authorize with a PKCE challenge, using S256. Readplace asks the reader to sign in if needed and to approve your app, then redirects to your redirect URI with code and state.

redirect_uri must match a registered URI exactly, port included, so register the exact loopback port your app listens on.

Leave out scope. Every token gets full access to the reader's account, and a refresh that sends scope is refused with 400 invalid_scope. The protected resource metadata lists that one access level in scopes_supported as account.

resource is optional, because Readplace is both the authorization server and the API, so every token it issues is already for this API.

Get tokens

Exchange the code with your PKCE verifier:

The answer is JSON with access_token, refresh_token, token_type and expires_in.

Access tokens are short-lived. Read expires_in from each token answer, and refresh when a request answers 401 with invalid_token.

Refresh tokens last 180 days and rotate: every refresh returns a new pair and retires the refresh token you sent. Store the new pair before you use it.

  • A refused refresh answers JSON with error and readplace_reason, with status 400. A refused code exchange answers JSON with error and error_description.
  • invalid_grant means the grant is gone: the refresh token was already used, has expired or was revoked, or the reader signed your app out from all devices or changed or reset their password. Send the reader through authorize again.
  • invalid_client means no registration that allows refresh exists for your client_id: it expired, or it was registered without the refresh_token grant. Register again, leaving grant_types out.
  • 503 with temporarily_unavailable means try again later with the same refresh token.

Disconnect

/oauth/revoke takes an access token or a refresh token, and revoking either drops the other too. Readers can also disconnect your app under Connected apps in their account.

Connected apps lists your app as AI assistant, connected from the host of your first redirect URI, or from an app on your computer when that URI is on 127.0.0.1 or [::1]. A client_name that matches a supported assistant's name, in any letter case, lists your app as that assistant instead.

create-session, on every collection, answers 204 with a browser session cookie, for an app that opens Readplace's reader in its own web view. Most integrations skip it. Revoking the token, or the reader disconnecting your app, doesn't end a session it made, so clear the cookie from your web view when your app is disconnected. A password change or reset does end it.

create-browser-handoff, on every collection, answers 200 with a single-use, short-lived code. A browser that opens the handoff page with that code is signed in as the reader. Most integrations skip it.

Start from one URL

Every request carries the reader's access token and the Siren media type. Start at /.

It answers with the reader's collection:

  • Follow every redirect yourself, sending the token and the Accept header again. Some HTTP clients drop Authorization when they follow a redirect, and the API then answers 401.
  • Hard-code only /, the two media types, the action names you use, what the fields you fill in mean, the link rels you follow, and the frontmatter keys you read. Read everything else from the answers: every href, method and field list.
  • Treat every href as opaque. Follow it or submit to it as given, and never build or edit one.
  • Skip what you don't recognise. New actions, links and properties can appear at any time.

Read a collection

A collection is one page of a readlist's articles, in one tab. Its entities are the articles, and its properties link to the rest:

  • tabs: the To Read and Read tabs, each a {label, rel, href}. The tab you're on has the rel current. A listing holds one tab only, so walk both to see everything.
  • pages: one {label, rel, href} per page, where the page you're on has the rel current. The next and prev links step one page at a time, and the self link is the page you're on.
  • readlists: All and each named readlist, each a {label, rel, href}. Follow an href to open that readlist, or send it in a save's readlists field.
  • total: a {label} to show the reader, not a number to compute with.
  • sort: one {label, rel, order, href} per order, where the order you're on has the rel current. Follow an href to change the order.
  • pageSize: presentation. The server picks the page size.
  • appearance: presentation.
  • warning: appears only on a 422 answer to save-article.
  • messages: on a listing, these are only for Readplace's own apps.

Other links serve Readplace's own apps, so ignore the ones you don't use.

search lists articles with these fields:

  • status: unread or read.
  • order: asc or desc.
  • page: 1 or more.
  • url: keeps only the article saved under that URL, if it's on the page you asked for.

A value Readplace doesn't accept is dropped, not refused. search always lists All, so inside a named readlist, follow its tabs and pages hrefs instead.

Read an article

Each article entity carries these properties:

  • id: the article's id.
  • url: the article's URL. When the saved link redirected, it's the destination.
  • title: what to show.
  • siteName: what to show.
  • excerpt: what to show.
  • imageUrl: an image URL, or null.
  • readTime: {value, label}, where value is the minutes as a string and label is display text such as 5 min read, or null when Readplace has no word count for the article.
  • sectionCount: present on a document with sections, such as a PDF: how many it has.
  • status: unread or read.
  • isRead: the same fact as status, as a boolean.
  • savedAt: an ISO 8601 UTC timestamp.
  • readAt: an ISO 8601 UTC timestamp, or null until the article is read.
  • publishedOn: the date the source published the article, as YYYY-MM-DD, or null when Readplace doesn't know it.
  • needsBrowserCapture: true when the site blocked Readplace's fetch, so a capture from the reader's browser through save-content would get the article.
  • contentState: available, processing or unavailable: whether the article has readable content, is still being prepared, or ended without any.
  • contentVersion: changes when the article's content, metadata, crawl outcome or summary changes. Fetch the document again when it does.
  • mediaKind: the kind of an uploaded file, such as "book" or "audio"; null for a saved link.
  • durationSeconds: the length in seconds of an uploaded audio file the reader owns; null otherwise.
  • processing: present only while Readplace is still working on the article. label is display text, estimate is an optional time left, and refresh gives the href to fetch after afterSeconds for the article's next version. When the next version has no processing, the work has settled or Readplace has stopped waiting, and a messages warning may say why.
  • messages: server-authored messages to show the reader, present only when there are any; see Save links and pages.

Follow an article's read link with the token and the Markdown media type to get the article as a document:

Check the status first, then the Content-Type, because the 401 and 404 answers have Markdown bodies too. A 404 means the article isn't this reader's.

The document opens with YAML frontmatter. A key whose value is absent is left out, never null:

  • title: the article's title.
  • source: the article's URL.
  • site: the article's site.
  • description: when Readplace has it.
  • words: when Readplace has it.
  • created: when the reader saved it.
  • published: the date the source published the article, as YYYY-MM-DD, when Readplace knows it.
  • readplace_id: the article's id in Readplace.
  • readplace_url: a link to the article in Readplace. Treat the link as opaque.
  • readplace_status: the article's status.
  • readplace_read_at: once it's read.
  • readplace_read_time: in minutes, when known.
  • readplace_readlists: the labels of the readlists that hold it.
  • readplace_content_status: processing, ready, failed or not-an-article.
  • readplace_summary_status: while the content is processing or ready: pending, ready, failed or skipped.
  • readplace_summary: appears once the summary is ready.

A document is final once readplace_content_status is failed or not-an-article, or it's ready and readplace_summary_status is ready, failed or skipped. Fetch an incomplete one again later. Final isn't frozen: read state, readlist membership and a re-crawl still change it.

Save links and pages

save-article saves a link, and every save lands in All. To file it in other readlists too, send their hrefs from properties.readlists in its readlists field, up to the field's maxItems. A save from a named readlist's collection also files it in that readlist.

  • 201: the saved article, with messages to show and a collection link. Saving a link again answers 201 too, with a message that it was already saved.
  • 409: Readplace accepted the save and is still finding the original article behind a wrapper link, such as a redirect or tracking link. The article appears later. Show the message and don't send the save again: each resubmission starts another save.
  • 422 with an error entity whose code is invalid-url: the URL is malformed.
  • 422 with the collection and a warning of {code, message}: Readplace can't reach that URL, such as a file: link or a local address. That collection isn't scoped to a tab and isn't meant for paging.
  • 500 with save-failed: try again later.

save-articles saves up to 20 pages in one multipart request. Its manifest field holds a JSON array of {url, title, mediaType}, where title and mediaType are optional, and each page whose entry has a mediaType sends its bytes in a content-N file part, where N is the entry's index. It answers 200 with counts and a result for each page. It answers 422 with an error entity when the manifest is malformed, lists more than 20 pages, or the request is over 4.5 MB.

save-articles files every page into All and records each one as a page the reader chose, so send only pages a reader picked.

save-content saves a page or file you already hold, so Readplace keeps what the reader saw. It's a multipart request with url, content (the file), mediaType (text/html or application/pdf), an optional title, and captureTrigger. It files into All only, and answers 201 with the saved article, or 409 as save-article does.

Send captureTrigger=automatic with save-content for any capture no reader tapped. A capture sent without it counts as one the reader chose.

For a file over the content field's maxBytes, send size in bytes instead of content. The answer is an upload slot with an expiresAt and two actions:

  1. upload-content: PUT the file, exactly the size you declared, to its href, with the action's type as the Content-Type, before expiresAt. The href is a signed upload address, so it needs no token.
  2. save-uploaded-content: submit it with the values its fields carry.

A file saved through an upload slot counts as a capture the reader chose, whatever captureTrigger the save-content request sent, so use one only for a file a reader picked.

A refused save-content answers 422 with an error entity and a fallback save-article action that saves the link alone. The codes are invalid-save-content, capture-not-allowed, unsupported-media-type, content-too-large, original-unresolved, upload-not-found and not-a-pdf, which save-uploaded-content answers when the uploaded file isn't a PDF.

A 201 save answer, a 409, and the 402 and 403 refusals carry messages for the reader. Show each one as given, because its body is HTML. Every other refusal is an error entity with a code to key off and a plain-text message, except the 422 collection with a warning above, and the 406 and 429 under Errors.

Mark as read or unread

update-status has one field, status, whose value the server sets to read or unread, so send it as given. It answers 303 back to the collection, which you follow yourself, and it changes the article in every readlist that holds it. It answers 303 even when the article no longer exists, so re-read the collection to confirm.

Manage readlists

A readlist is a named list of the reader's articles. All holds every save, and the reader can create up to 15 named readlists besides it.

  • create-readlist, on every collection: a form with label. It answers 303 to the new readlist's collection, which is where you learn the new readlist's href.
  • rename-readlist, on a named readlist's collection: a form with label. It answers 303 to the renamed readlist's collection. A label another readlist already has gets a number added.
  • delete-readlist, on a named readlist's collection: a form with no fields. It answers 303 to All, and it takes nothing out of All.
  • add-to-readlist, on every article, including the one a save answers with: JSON with readlists, hrefs of named readlists from properties.readlists. All isn't a target: every article is already in All. Sending no href for a named readlist the reader owns answers 404 unknown-readlist, including when the only href is All's. It answers 303 to page 1 of the readlist and tab its href was built for: the listing the article came from, or All's To Read tab for the article a save answers with. Filing an article in a named readlist that already holds it succeeds.
  • remove-from-readlist, on an article listed in a named readlist: a form with no fields. It answers 303 to the first page of the same readlist and tab, and it takes nothing out of All.

Apart from the 402 and 403 under Errors, which carry messages, a refusal is an error entity with a code and a message:

  • 404 unknown-readlist: the readlist no longer exists, or add-to-readlist named none of the reader's named readlists.
  • 404 unknown-article: the article isn't in that readlist any more, for example because it was already removed.
  • 422 invalid-name: the label is empty or longer than 24 characters.
  • 422 reserved-name: create-readlist was sent the label All, in any letter case.
  • 422 name-taken: for create-readlist, the reader already has a readlist with that label. For rename-readlist, the numbered label would be longer than 24 characters.
  • 422 limit-reached: the reader already has 15 named readlists.

To drain a readlist, take each tab in turn. Open page 1, invoke remove-from-readlist on each article, follow the 303 back to page 1, and repeat until the tab is empty. Removing moves later articles onto page 1, so always start again from page 1 rather than following next.

Caching

  • Collections and Markdown documents answer Cache-Control: private, no-cache. Keep a copy if you like, but revalidate it before you reuse it.
  • The redirect from / says in its own Cache-Control how long you may reuse it.
  • An answer may carry an ETag and answer 304 to a matching If-None-Match. That isn't promised, so use it when it's there and don't depend on it.
  • Don't send X-Readplace-Client. It marks Readplace's own apps, and their listings are cached differently.

Errors

Key off the status code, and show any messages as given.

  • 401 on a Siren request: the token is missing, expired or revoked, and the body is a Siren error entity. WWW-Authenticate points to the protected resource metadata with resource_metadata, and adds error="invalid_token" when a token was sent. Refresh the token and try again.
  • 401 on a Markdown read: WWW-Authenticate: Bearer error="invalid_token", with no resource_metadata. Refresh and try again. To find the authorization server from scratch, start from a Siren request.
  • 303 to /login: the request has no Siren Accept header, so Readplace treats it as a browser.
  • 402: the reader's subscription isn't active. Saving is refused, and so are creating, renaming and deleting readlists and adding articles to them. Reading, listing, marking as read and removing from a readlist still work.
  • 403: the reader's account is locked. The same actions are refused.
  • 404: the article isn't the reader's, a readlist action names a readlist that no longer exists, or add-to-readlist names none of the reader's named readlists. All isn't an add-to-readlist target. A GET of a deleted readlist's href lists All instead.
  • 406: a save sent without the Siren Accept header by a client signed in with a browser session, such as one create-session made.
  • 409: the save was accepted and is still being resolved. Don't send it again.
  • 422: a refusal. The saving and readlists sections list its shapes.
  • 429: too many requests. A shared throttle covers every route, with no per-client quota, and /oauth/register and /oauth/token also limit each IP address. Back off and try again, after Retry-After when it's sent.
  • 500: something failed on Readplace's side. Try again later.

Limits

  • Up to 15 named readlists, besides All.
  • Readlist names up to 24 characters.
  • Up to 3 MB per file sent with save-content. A larger file goes through an upload slot.
  • Up to 500 MB per PDF and 28 MB per HTML page through an upload slot.
  • Up to 4.5 MB per save-content or save-articles request.
  • Up to 20 pages per save-articles request, each up to 4.4 MB.

Each action also states its limits in its fields, as maxItems, maxBytes and maxRequestBytes. Read them from the answer rather than hard-coding these numbers.

Not in the API

  • Deleting an article stays in the Readplace app. The API advertises no delete action, and remove-from-readlist takes nothing out of All.
  • No webhooks or feeds. Poll the collection to see what changed.
  • No full-text search. search narrows by status, order, page and URL only.
  • No page-size control. The server picks the page size.

Walkthrough: drain a readlist

A job that files links into a readlist and later works through them, end to end:

  1. Register once, with a loopback redirect URI on the port your job listens on.
  2. Send the reader to authorize with a PKCE challenge, catch the code on your redirect URI, and exchange it for tokens. Store both.
  3. Request / with the token and the Siren media type, and follow the 303 to the collection yourself.
  4. Invoke create-readlist with a label, once, and follow its 303. On the collection it lands on, the new readlist is the properties.readlists entry with the rel current. Keep its href.
  5. Save each link with save-article, sending that href in readlists.
  6. Later, follow the readlist's href. For each entry in its properties.tabs, open that tab's page 1. For each article, follow read with the Markdown media type, hand the document on, and invoke remove-from-readlist. Follow the 303 back to page 1, and repeat until the tab is empty.
  7. All still holds every article you saved.
  8. When a request answers 401, refresh the token, store the new pair, and send the request again.