Reading
Instapaper articles, reading progress, and highlights, with semantic search across everything you have saved.
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) |
The 0.75 threshold accounts for article footers, author bios, and related links that you don't typically scroll through.
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).
Year in review
GET /reading/year/:year returns a reading summary for a single year, including counts, top domains, and highlights.
From Claude
You can also explore your reading history from Claude. Set up the MCP server, then the reading tools are yours. Ask what you have been reading, or to find an article you saved about a topic.