Readwise API

Connect to Readwise APIs to fetch and analyze reading activity.

Overview

Fetch saved articles, highlights, and identify most-highlighted content from user's Readwise account for any date range. Uses Readwise v2 Highlights API and v3 Reader API.

Default behavior: Last 7 days (when no date flags specified)

Prerequisites

API Token: Set READWISE_API_TOKEN environment variable

• Get token: https://readwise.io/access_token

• export READWISE_API_TOKEN="your_token_here"

Dependencies: Installed via pnpm (auto on first use)

• chalk (terminal colors)

• ora (spinners)

• TypeScript support

Date Range Options

All commands support flexible date ranges via flags:

Preset Shortcuts

• --today : Midnight today → now

• --yesterday : Yesterday (full day)

• --last-week : Last 7 days (default when no flags specified)

• --last-month : Last 30 days

Custom Ranges

• --from YYYY-MM-DD : Start date (inclusive)

• --to YYYY-MM-DD : End date (inclusive)

• Can use together: --from 2025-01-01 --to 2025-01-07

Examples

Today only

pnpm tsx scripts/fetch-todays-activity.ts articles --today

Yesterday

pnpm tsx scripts/fetch-todays-activity.ts highlights --yesterday

Custom range

pnpm tsx scripts/fetch-todays-activity.ts all --from 2025-01-01 --to 2025-01-07

Default (no flags) = last 7 days

pnpm tsx scripts/fetch-todays-activity.ts all

Note: Reader API doesn't support end dates natively. Articles filtered client-side for accurate date ranges.

Core Capabilities

Default: Comprehensive Activity Summary

Command:

pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts all [date-flags]

Output: Four-section analysis w/ insights-first approach:

🧠 Key Learnings

• Top 5 insights extracted from highlight content

• Domain-tagged bullets (emoji + category: insight)

• Reading context paragraph (pattern + domain mix)

📈 Activity Timeline

• Daily breakdown w/ visual bars (unicode blocks)

• Peak days identified

• Reading pattern analysis (consistent/burst/weekend/weekday)

📂 By Category

• Domain grouping w/ visual bars + percentages

• Auto-inferred from content (Architecture, Performance, Psychology, etc.)

• Top 2 focus areas highlighted

📊 Stats Dashboard

• Articles saved, highlights created

• Unique sources, avg/day

• Top source by highlight count

When to use: User asks "Show my Readwise activity", "What have I been learning?", "My reading summary"

Individual Modes

1. Key Learnings Only

Command:

pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts learnings [date-flags]

Output: Insights + context only (no timeline/stats)

When to use: User wants just the learnings/insights

2. Activity Timeline Only

Command:

pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts timeline [date-flags]

Output: Daily activity visualization + peaks + pattern

When to use: User asks "When am I most active?" or "Show my reading schedule"

3. Category Breakdown Only

Command:

pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts categories [date-flags]

Output: Domain distribution w/ visual bars

When to use: User asks "What topics am I focusing on?" or "My reading categories"

4. Stats Dashboard Only

Command:

pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts dashboard [date-flags]

Output: Stats summary box

When to use: User wants quick metrics only

Legacy Modes (Still Available)

Articles

Command: pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts articles [date-flags]

Output: List of saved articles w/ categories, titles, authors, URLs

Highlights

Command: pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts highlights [date-flags]

Output: All highlights grouped by source, showing text + notes

Top Highlighted

Command: pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts top-highlighted [N] [date-flags]

Output: Top N sources ranked by highlight count

Usage Examples

Example 1: "What have I been learning on Readwise this week?"

pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts all

Returns comprehensive analysis: insights, timeline, categories, stats (default = last 7 days)

Example 2: "Show my key insights from today"

pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts learnings --today

Returns top 5 insights extracted from today's highlights + reading context

Example 3: "When am I most active on Readwise?"

pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts timeline --last-month

Returns daily activity visualization for last 30 days w/ peak identification

Example 4: "What topics am I focusing on?"

pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts categories

Returns domain distribution w/ visual bars (default = last 7 days)

Example 5: "Show Readwise stats from Jan 1-7"

pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts dashboard --from 2025-01-01 --to 2025-01-07

Returns metrics dashboard for custom date range

Error Handling

Missing API token: Clear error with link to get token

Rate limits: Automatic 3s delays between paginated requests (20 req/min limit)

Network errors: Graceful failure with error messages via spinner

Empty results: Friendly "no activity yet" messages

API Details

Rate Limits: 20 requests/minute per access token

• Script auto-throttles with 3s delays between requests

• Pagination handled automatically

Date Filtering:

• Presets: today, yesterday, last-week (7d), last-month (30d)

• Custom ranges via --from/--to flags (ISO 8601: YYYY-MM-DD)

• Default: last 7 days

• Timezone: Local (dates converted to UTC for API)

Reader API Limitation:

• Supports only start date (updatedAfter ), no end date

• End date filtering done client-side after fetch

• May fetch extra data that gets filtered locally

Pagination: Automatically follows next URLs (v2) and pageCursor (v3)

Implementation

API Client: scripts/readwise-client.ts

• Pure functions, typed errors

• Handles pagination and rate limiting

• Returns ApiResult<T> with success/error

Analysis: scripts/analyze-highlights.ts

• Daily grouping + peak detection

• Domain inference (14 categories: Architecture, Performance, Psychology, etc.)

• NLP-style insight extraction (sentence scoring, clustering, ranking)

• Pattern analysis (consistent/burst/weekend/weekday reader)

• Pure functions, immutable transformations

CLI: scripts/fetch-todays-activity.ts

• Human-readable terminal output w/ unicode visual bars

• Colored text via chalk, spinners via ora

• Eight modes: learnings, timeline, categories, dashboard, articles, highlights, top-highlighted, all

• Default order: insights → timeline → categories → stats

Tests: scripts/tests/analyze-highlights.test.ts

• Comprehensive coverage (52 tests)

• Edge cases: empty data, date boundaries, pattern detection

References

Detailed API documentation: references/api_reference.md

• Endpoint details

• Authentication

• Rate limits

• Request/response formats

• Example code