Overview
The Reading domain tracks articles and reading activity from Instapaper, including reading progress, starred items, and highlighted passages. Bookmarks and highlights sync a few times a day. Each sync transfers only new or changed items, and deletions from Instapaper propagate through. Reading status is derived from progress data. Browse every endpoint in the API reference.Reading status
Status is derived from Instapaper folder and reading progress:| Status | Meaning |
|---|---|
unread | Saved but never opened (progress = 0) |
reading | Started but not finished (0 < progress < 0.75) |
finished | Read most of the article (progress >= 0.75) |
skipped | Archived without reading (progress = 0, archived) |
abandoned | Started but gave up (progress > 0, archived) |
Highlights
Highlighted passages are stored with their position and timestamp. The highlights endpoints return each highlight with parent-article context (title, author, domain, URL), useful for building a highlights collection or a daily-quote feature. Highlights are independently searchable via/v1/search.
Semantic search
Reading supports meaning-based retrieval, not just keyword matching:- Search by meaning:
GET /v1/search?mode=semantic&domain=reading(ormode=hybridto blend keyword and semantic). Each result is scored by relevance. - Related articles:
GET /v1/reading/articles/:id/relatedfor “what else did I read like this?”
Article metadata
Each article includes metadata extracted during sync:- Title, description: from Instapaper.
- Author, site name: from the article’s OG meta tags.
- Domain: parsed from the URL (for example,
wired.com,theatlantic.com). - Word count, estimated read time: computed from the article’s processed text.
- Thumbnail: from the article’s
og:image, served via the image pipeline.
Filtering
Articles can be filtered by:status: unread, reading, finished, skipped, abandoned.domain: source domain (for example,wired.com,theatlantic.com).tag: Instapaper tags.starred: true/false.- Standard date filters (
date,from,to).