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://localhostincluded), or plain http on127.0.0.1or[::1].http://localhostand custom schemes are refused with400 invalid_redirect_uri. redirect_urisholds 1 to 32 URIs of up to 2,048 characters each.client_nameis 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 benone. - The
201answer carries yourclient_id. Sending the same registration again returns the sameclient_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/registerand/oauth/tokenlimit how often one IP address can call them. Over the limit, they answer429with aRetry-Afterheader.
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
errorandreadplace_reason, with status400. A refused code exchange answers JSON witherroranderror_description. invalid_grantmeans 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_clientmeans no registration that allows refresh exists for yourclient_id: it expired, or it was registered without therefresh_tokengrant. Register again, leavinggrant_typesout.503withtemporarily_unavailablemeans 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
Acceptheader again. Some HTTP clients dropAuthorizationwhen they follow a redirect, and the API then answers401. - 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 relcurrent. 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 relcurrent. Thenextandprevlinks step one page at a time, and theselflink 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'sreadlistsfield.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 relcurrent. Follow an href to change the order.pageSize: presentation. The server picks the page size.appearance: presentation.warning: appears only on a422answer tosave-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:unreadorread.order:ascordesc.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, ornull.readTime:{value, label}, wherevalueis the minutes as a string andlabelis display text such as5 min read, ornullwhen Readplace has no word count for the article.sectionCount: present on a document with sections, such as a PDF: how many it has.status:unreadorread.isRead: the same fact asstatus, as a boolean.savedAt: an ISO 8601 UTC timestamp.readAt: an ISO 8601 UTC timestamp, ornulluntil the article is read.publishedOn: the date the source published the article, asYYYY-MM-DD, ornullwhen Readplace doesn't know it.needsBrowserCapture:truewhen the site blocked Readplace's fetch, so a capture from the reader's browser throughsave-contentwould get the article.contentState:available,processingorunavailable: 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";nullfor a saved link.durationSeconds: the length in seconds of an uploaded audio file the reader owns;nullotherwise.processing: present only while Readplace is still working on the article.labelis display text,estimateis an optional time left, andrefreshgives thehrefto fetch afterafterSecondsfor the article's next version. When the next version has noprocessing, the work has settled or Readplace has stopped waiting, and amessageswarning 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, asYYYY-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,failedornot-an-article.readplace_summary_status: while the content is processing or ready:pending,ready,failedorskipped.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, withmessagesto show and acollectionlink. Saving a link again answers201too, 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.422with an error entity whose code isinvalid-url: the URL is malformed.422with the collection and awarningof{code, message}: Readplace can't reach that URL, such as afile:link or a local address. That collection isn't scoped to a tab and isn't meant for paging.500withsave-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:
upload-content:PUTthe file, exactly the size you declared, to its href, with the action'stypeas theContent-Type, beforeexpiresAt. The href is a signed upload address, so it needs no token.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 withlabel. It answers303to 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 withlabel. It answers303to 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 answers303to All, and it takes nothing out of All.add-to-readlist, on every article, including the one a save answers with: JSON withreadlists, hrefs of named readlists fromproperties.readlists. All isn't a target: every article is already in All. Sending no href for a named readlist the reader owns answers404 unknown-readlist, including when the only href is All's. It answers303to 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 answers303to 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, oradd-to-readlistnamed 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-readlistwas sent the label All, in any letter case.422 name-taken: forcreate-readlist, the reader already has a readlist with that label. Forrename-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 ownCache-Controlhow long you may reuse it. - An answer may carry an
ETagand answer304to a matchingIf-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.
401on a Siren request: the token is missing, expired or revoked, and the body is a Siren error entity.WWW-Authenticatepoints to the protected resource metadata withresource_metadata, and addserror="invalid_token"when a token was sent. Refresh the token and try again.401on a Markdown read:WWW-Authenticate: Bearer error="invalid_token", with noresource_metadata. Refresh and try again. To find the authorization server from scratch, start from a Siren request.303to/login: the request has no SirenAcceptheader, 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, oradd-to-readlistnames none of the reader's named readlists. All isn't anadd-to-readlisttarget. AGETof a deleted readlist's href lists All instead.406: a save sent without the SirenAcceptheader by a client signed in with a browser session, such as onecreate-sessionmade.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/registerand/oauth/tokenalso limit each IP address. Back off and try again, afterRetry-Afterwhen 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-contentorsave-articlesrequest. - Up to 20 pages per
save-articlesrequest, 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-readlisttakes nothing out of All. - No webhooks or feeds. Poll the collection to see what changed.
- No full-text search.
searchnarrows 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:
- Register once, with a loopback redirect URI on the port your job listens on.
- Send the reader to authorize with a PKCE challenge, catch the code on your redirect URI, and exchange it for tokens. Store both.
- Request
/with the token and the Siren media type, and follow the303to the collection yourself. - Invoke
create-readlistwith a label, once, and follow its303. On the collection it lands on, the new readlist is theproperties.readlistsentry with the relcurrent. Keep its href. - Save each link with
save-article, sending that href inreadlists. - Later, follow the readlist's href. For each entry in its
properties.tabs, open that tab's page 1. For each article, followreadwith the Markdown media type, hand the document on, and invokeremove-from-readlist. Follow the303back to page 1, and repeat until the tab is empty. - All still holds every article you saved.
- When a request answers
401, refresh the token, store the new pair, and send the request again.