# Get an attended event Source: https://docs.rewind.rest/api-reference/attending/get-attended-event get /v1/attending/events/{id} Returns a single attended event with its venue, tickets, performers, and event_data. # Get a player you have watched play Source: https://docs.rewind.rest/api-reference/attending/get-attended-player get /v1/attending/players/{id} Returns the player bio with both photo variants when available, plus a list of every attended event in which they appeared along with that game's stat lines. # Attended games in a sports season Source: https://docs.rewind.rest/api-reference/attending/get-attended-season get /v1/attending/seasons/{league}/{season} Returns the games you attended (or hold tickets for) in a given league and season, with your win-loss record across them. # Aggregate attending stats Source: https://docs.rewind.rest/api-reference/attending/get-attending-stats get /v1/attending/stats Returns counts of attended events broken down by category, event_type, and year. Useful for top-line stats on the portfolio page. # List attended events Source: https://docs.rewind.rest/api-reference/attending/list-attended-events get /v1/attending/events Returns events you have tickets for, filterable by category, type, season, year, venue, team, and attendance status. Includes tickets for events you did not attend. # List players you have watched play Source: https://docs.rewind.rest/api-reference/attending/list-attended-players get /v1/attending/players Returns players who appeared in any event you attended, filterable by league, team, and name. Includes both photo variants when available. # List venues Source: https://docs.rewind.rest/api-reference/attending/list-venues get /v1/attending/venues Returns the venues catalog used by attended events. Includes city, state, country, lat/long, and capacity when known. # Year in review Source: https://docs.rewind.rest/api-reference/attending/year-in-review get /v1/attending/year/{year} Returns a year-in-review summary for attended events: totals, monthly breakdown, top venues, top concert performers, and the full event list. 404 when no attended events exist for the year. # Collection calendar Source: https://docs.rewind.rest/api-reference/collecting/collection-calendar get /v1/collecting/calendar Returns daily addition counts for a given year (vinyl and media combined). # Vinyl record detail Source: https://docs.rewind.rest/api-reference/collecting/collection-item-detail get /v1/collecting/vinyl/{id} Full detail for a single collection item including tracklist, country, and marketplace data. # Collection-listening cross-reference Source: https://docs.rewind.rest/api-reference/collecting/collection-listening-cross-reference get /v1/collecting/cross-reference Cross-references vinyl collection with Last.fm listening data showing play counts and match confidence. # Collection stats Source: https://docs.rewind.rest/api-reference/collecting/collection-statistics get /v1/collecting/stats Aggregate statistics for the vinyl collection. Supports optional date filtering to scope stats to items added within a time period. # Format breakdown Source: https://docs.rewind.rest/api-reference/collecting/format-breakdown get /v1/collecting/formats Count of collection items grouped by primary format (Vinyl, CD, Cassette, etc). # Genre breakdown Source: https://docs.rewind.rest/api-reference/collecting/genre-breakdown get /v1/collecting/genres Count of collection items grouped by genre. # List physical media collection Source: https://docs.rewind.rest/api-reference/collecting/list-physical-media-collection get /v1/collecting/media Paginated, filterable Trakt physical media collection (Blu-ray, DVD, etc) with movie metadata. # List vinyl collection Source: https://docs.rewind.rest/api-reference/collecting/list-vinyl-collection get /v1/collecting/vinyl Paginated, filterable, searchable Discogs vinyl collection with artist and image data. # Media format breakdown Source: https://docs.rewind.rest/api-reference/collecting/media-format-breakdown get /v1/collecting/media/formats Count of physical media items grouped by format type (bluray, dvd, etc). # Owned vs watched cross-reference Source: https://docs.rewind.rest/api-reference/collecting/owned-vs-watched-cross-reference get /v1/collecting/media/cross-reference Cross-references physical media collection with watch history showing watched/unwatched status. # Physical media item detail Source: https://docs.rewind.rest/api-reference/collecting/physical-media-item-detail get /v1/collecting/media/{id} Full detail for a single physical media item including movie metadata and watch history. # Physical media stats Source: https://docs.rewind.rest/api-reference/collecting/physical-media-statistics get /v1/collecting/media/stats Aggregate statistics for the physical media collection by format, resolution, HDR, genre, and decade. # Recent vinyl additions Source: https://docs.rewind.rest/api-reference/collecting/recent-additions get /v1/collecting/recent Most recently added items to the vinyl collection. Supports date filtering via date, from, and to params. # Recently added physical media Source: https://docs.rewind.rest/api-reference/collecting/recently-added-physical-media get /v1/collecting/media/recent Most recently added items to the physical media collection. Supports date filtering via date, from, and to params. # Top collected artists Source: https://docs.rewind.rest/api-reference/collecting/top-artists get /v1/collecting/artists Artists ranked by number of releases in the collection. # Wantlist Source: https://docs.rewind.rest/api-reference/collecting/wantlist get /v1/collecting/wantlist Paginated Discogs wantlist with sorting. # Cross-domain activity feed Source: https://docs.rewind.rest/api-reference/feed/cross-domain-activity-feed get /v1/feed Returns a cross-domain activity feed with cursor-based pagination. # On this day Source: https://docs.rewind.rest/api-reference/feed/on-this-day get /v1/feed/on-this-day Returns activity from a given calendar date across all years, grouped by year. # Single-domain activity feed Source: https://docs.rewind.rest/api-reference/feed/single-domain-activity-feed get /v1/feed/domain/{domain} Returns an activity feed filtered to a single domain with cursor-based pagination. # Get image by entity Source: https://docs.rewind.rest/api-reference/images/get-image-by-entity get /v1/images/{domain}/{entity_type}/{entity_id}/{size} Serve image via CDN redirect. Triggers the image pipeline on cache miss. Returns a 302 redirect to the CDN URL with metadata in response headers. # Album detail Source: https://docs.rewind.rest/api-reference/listening/album-detail get /v1/listening/albums/{id} Returns detailed information about an album including tracks. # Artist detail Source: https://docs.rewind.rest/api-reference/listening/artist-detail get /v1/listening/artists/{id} Returns detailed information about an artist including top albums and tracks. # Browse albums Source: https://docs.rewind.rest/api-reference/listening/browse-albums get /v1/listening/albums Returns paginated list of all albums. # Browse artists Source: https://docs.rewind.rest/api-reference/listening/browse-artists get /v1/listening/artists Returns paginated list of all artists. # Genre breakdown Source: https://docs.rewind.rest/api-reference/listening/genre-breakdown get /v1/listening/genres Returns a genre breakdown over time, grouped by period and designed for stacked bar charts. # Listening stats Source: https://docs.rewind.rest/api-reference/listening/listening-stats get /v1/listening/stats Returns listening statistics. Supports optional date filtering to scope stats to a time period. # Listening streaks Source: https://docs.rewind.rest/api-reference/listening/listening-streaks get /v1/listening/streaks Returns current and longest listening streaks. # Listening trends Source: https://docs.rewind.rest/api-reference/listening/listening-trends get /v1/listening/trends Returns monthly trend data for a given metric. # Now playing Source: https://docs.rewind.rest/api-reference/listening/now-playing get /v1/listening/now-playing Returns the currently playing or most recently scrobbled track from Last.fm. # Recent scrobbles Source: https://docs.rewind.rest/api-reference/listening/recent-scrobbles get /v1/listening/recent Returns the most recent scrobbles. Supports date filtering via date, from, and to params and page-based pagination. # Listening calendar Source: https://docs.rewind.rest/api-reference/listening/scrobble-calendar get /v1/listening/calendar Returns daily scrobble counts for a given year. # Listening history Source: https://docs.rewind.rest/api-reference/listening/scrobble-history get /v1/listening/history Returns paginated scrobble history with optional filters. # Top albums Source: https://docs.rewind.rest/api-reference/listening/top-albums get /v1/listening/top/albums Returns top albums for a given time period. Pass `include_sparklines=true` to attach a play-count time series per album (1month/3month/6month/12month/overall). # Top artists Source: https://docs.rewind.rest/api-reference/listening/top-artists get /v1/listening/top/artists Returns your top artists for a given time period. # Top tracks Source: https://docs.rewind.rest/api-reference/listening/top-tracks get /v1/listening/top/tracks Returns your top tracks for a given time period, optionally scoped to a single artist. # Year in review Source: https://docs.rewind.rest/api-reference/listening/year-in-review get /v1/listening/year/{year} Returns year-in-review listening data. Optionally pass ?month=N to scope to a single month. # Archived articles Source: https://docs.rewind.rest/api-reference/reading/archived-articles get /v1/reading/archive Returns finished articles, paginated. # Article detail Source: https://docs.rewind.rest/api-reference/reading/article-detail get /v1/reading/articles/{id} Returns a single article with its embedded highlights. # Currently reading Source: https://docs.rewind.rest/api-reference/reading/currently-reading get /v1/reading/currently-reading Returns articles currently being read (progress > 0 and < 0.75). # List articles Source: https://docs.rewind.rest/api-reference/reading/list-articles get /v1/reading/articles Returns a paginated list of articles, filterable by status, tag, domain, and starred. # List highlights Source: https://docs.rewind.rest/api-reference/reading/list-highlights get /v1/reading/highlights Returns all highlights newest first, with parent article context. # Random highlight Source: https://docs.rewind.rest/api-reference/reading/random-highlight get /v1/reading/highlights/random Returns a single random highlight with article context. # Reading calendar Source: https://docs.rewind.rest/api-reference/reading/reading-calendar get /v1/reading/calendar Returns daily counts of saved and finished articles for a given year. # Reading stats Source: https://docs.rewind.rest/api-reference/reading/reading-stats get /v1/reading/stats Returns aggregate reading statistics: total articles, finished count, currently reading, total highlights, word count, and average read time. # Reading streaks Source: https://docs.rewind.rest/api-reference/reading/reading-streaks get /v1/reading/streaks Returns current and longest reading streaks (consecutive days with a finished article). # Recent articles Source: https://docs.rewind.rest/api-reference/reading/recent-articles get /v1/reading/recent Returns recently saved or finished articles, ordered by most recent activity. # Tag breakdown Source: https://docs.rewind.rest/api-reference/reading/tag-breakdown get /v1/reading/tags Returns tags with article counts, sorted by count descending. # Top domains Source: https://docs.rewind.rest/api-reference/reading/top-domains get /v1/reading/domains Returns top source domains with article counts, sorted by count descending. # Year in review Source: https://docs.rewind.rest/api-reference/reading/year-in-review get /v1/reading/year/{year} Returns year-in-review reading data. # Activity calendar Source: https://docs.rewind.rest/api-reference/running/activity-calendar get /v1/running/calendar Returns daily activity heatmap data for a given year. # Activity detail Source: https://docs.rewind.rest/api-reference/running/activity-detail get /v1/running/activities/{id} Returns a single activity by Strava ID. # Activity splits Source: https://docs.rewind.rest/api-reference/running/activity-splits get /v1/running/activities/{id}/splits Returns per-mile splits for a specific activity. # All year summaries Source: https://docs.rewind.rest/api-reference/running/all-year-summaries get /v1/running/stats/years Returns running summaries for all years. # Cities Source: https://docs.rewind.rest/api-reference/running/cities get /v1/running/cities Returns cities where runs occurred with counts and distances. # Cumulative distance chart Source: https://docs.rewind.rest/api-reference/running/cumulative-distance-chart get /v1/running/charts/cumulative Returns year-over-year cumulative distance data for charting. # Eddington number Source: https://docs.rewind.rest/api-reference/running/eddington-number get /v1/running/eddington Returns the Eddington number and progress toward the next target. # Elevation chart Source: https://docs.rewind.rest/api-reference/running/elevation-chart get /v1/running/charts/elevation Returns elevation data with cumulative totals. # Gear list Source: https://docs.rewind.rest/api-reference/running/gear-list get /v1/running/gear Returns all gear/shoes with activity counts. # Running stats Source: https://docs.rewind.rest/api-reference/running/lifetime-running-statistics get /v1/running/stats Returns aggregate lifetime running statistics. # List activities Source: https://docs.rewind.rest/api-reference/running/list-activities get /v1/running/activities Returns a paginated, filterable list of running activities. # Pace trend chart Source: https://docs.rewind.rest/api-reference/running/pace-trend-chart get /v1/running/charts/pace-trend Returns pace over time with a rolling weighted average. # Personal records Source: https://docs.rewind.rest/api-reference/running/personal-records get /v1/running/prs Returns personal records for standard race distances. # Race activities Source: https://docs.rewind.rest/api-reference/running/race-activities get /v1/running/races Returns all race activities, optionally filtered by distance category. # Latest runs Source: https://docs.rewind.rest/api-reference/running/recent-activities get /v1/running/recent Returns the last N activities (default 10, max 50). Supports date filtering via date, from, and to params and page-based pagination. # Running streaks Source: https://docs.rewind.rest/api-reference/running/running-streaks get /v1/running/streaks Returns current and longest running streaks. # Single year summary Source: https://docs.rewind.rest/api-reference/running/single-year-summary get /v1/running/stats/years/{year} Returns running summary for a specific year. # Time of day chart Source: https://docs.rewind.rest/api-reference/running/time-of-day-chart get /v1/running/charts/time-of-day Returns run frequency by hour of day. # Year in review Source: https://docs.rewind.rest/api-reference/running/year-in-review get /v1/running/year/{year} Returns a year-in-review summary with monthly breakdown and top runs. # Cross-domain search Source: https://docs.rewind.rest/api-reference/search/cross-domain-search get /v1/search Full-text search across all data domains (listening, running, watching, collecting, reading). # Health check Source: https://docs.rewind.rest/api-reference/system/health-check get /v1/health Returns API health status and current timestamp. # Sync health status Source: https://docs.rewind.rest/api-reference/system/sync-health-status get /v1/health/sync Returns the latest sync status for each data domain, including last sync time, items synced, duration, and 24-hour error rate. # Decade stats Source: https://docs.rewind.rest/api-reference/watching/decade-stats get /v1/watching/stats/decades Returns decade breakdown for all watched movies. # Director stats Source: https://docs.rewind.rest/api-reference/watching/director-stats get /v1/watching/stats/directors Returns top directors by movie count. # Genre stats Source: https://docs.rewind.rest/api-reference/watching/genre-stats get /v1/watching/stats/genres Returns genre breakdown for all watched movies. # List movies Source: https://docs.rewind.rest/api-reference/watching/list-movies get /v1/watching/movies Returns paginated list of movies with optional filters. # List TV shows Source: https://docs.rewind.rest/api-reference/watching/list-tv-shows get /v1/watching/shows Returns paginated list of TV shows. # Movie detail Source: https://docs.rewind.rest/api-reference/watching/movie-detail get /v1/watching/movies/{id} Returns full details for a single movie including watch history. # Movie reviews Source: https://docs.rewind.rest/api-reference/watching/movie-reviews get /v1/watching/reviews Returns paginated list of movies with user reviews. # Rated movies Source: https://docs.rewind.rest/api-reference/watching/rated-movies get /v1/watching/ratings Returns paginated list of movies with user ratings. # Recent watches Source: https://docs.rewind.rest/api-reference/watching/recent-watches get /v1/watching/recent Returns most recently watched movies. Supports date filtering via date, from, and to params. # Season detail Source: https://docs.rewind.rest/api-reference/watching/season-detail get /v1/watching/shows/{id}/seasons/{season} Returns watched episodes for a specific season of a show. # Show detail Source: https://docs.rewind.rest/api-reference/watching/show-detail get /v1/watching/shows/{id} Returns full details for a single TV show including watched episodes. # Watch calendar Source: https://docs.rewind.rest/api-reference/watching/watch-calendar get /v1/watching/calendar Returns daily watch counts for a given year. # Watch stats Source: https://docs.rewind.rest/api-reference/watching/watch-stats get /v1/watching/stats Returns aggregate watching statistics. Supports optional date filtering to scope stats to a time period. # Watch trends Source: https://docs.rewind.rest/api-reference/watching/watch-trends get /v1/watching/trends Returns weekly or monthly watch counts. Supports date filtering via from/to params. # Year in review Source: https://docs.rewind.rest/api-reference/watching/year-in-review get /v1/watching/year/{year} Returns aggregate stats and top-rated movies for a specific year. # Webhooks Source: https://docs.rewind.rest/api-reference/webhooks/overview How Rewind receives inbound events from Strava and Plex to keep your data fresh in near real time. Rewind exposes two inbound webhook endpoints so Strava and Plex can push events the moment something happens, instead of waiting for the next cron sync. Finish a run on Strava or a movie on Plex, and the new activity lands in your archive within seconds. These are internal integration endpoints. Strava and Plex call them, not you. They take no API key and there is nothing to fetch from them by hand. You configure each one once as the operator, then they run unattended. ## How they work Every other Rewind route is something you call with a Bearer token. Webhooks invert that: an external service is the caller and Rewind is the receiver. Because Strava and Plex cannot present a Rewind API key, the auth middleware skips any path under `/v1/webhooks/`, and each endpoint verifies its own source instead. The two endpoints live at `/v1/webhooks/strava` and `/v1/webhooks/plex`. ## Strava Strava webhooks begin with a one-time handshake. When you register a subscription, Strava sends a `GET` to `/v1/webhooks/strava` with `hub.mode`, `hub.verify_token`, and `hub.challenge`. Rewind echoes the challenge back only when the mode is `subscribe` and the token matches `STRAVA_WEBHOOK_VERIFY_TOKEN`; otherwise it returns `400` and the subscription is not established. ```json theme={null} { "hub.challenge": "" } ``` Once the subscription is active, Strava `POST`s an event for each activity. Rewind acknowledges within Strava's roughly two-second window, dedupes retries, then processes asynchronously: a `create` or `update` syncs that activity, and a `delete` removes it. Events for other object types, such as `athlete`, are ignored. ## Plex Plex `POST`s a `multipart/form-data` payload to `/v1/webhooks/plex`. Rewind parses it, verifies it against `PLEX_WEBHOOK_SECRET` (returning `403` otherwise), and ingests only `media.scrobble` plays of movies or episodes from your own account, enriching the title with TMDB metadata and recomputing your watch stats. Everything else, other event types, other media, or plays from other users, is acknowledged with a `200` so Plex stops retrying. ## Configuration Both endpoints depend on operator-set environment variables, not on anything a reader supplies: | Variable | Endpoint | Purpose | | ----------------------------- | -------- | ----------------------------------------------------------- | | `STRAVA_WEBHOOK_VERIFY_TOKEN` | Strava | Matched against `hub.verify_token` during the handshake | | `PLEX_WEBHOOK_SECRET` | Plex | Verifies that an inbound Plex payload came from your server | To learn what happens once an event is ingested, see the [running](/domains/running) and [watching](/domains/watching) domain pages. # Authentication Source: https://docs.rewind.rest/authentication API keys and authorization ## API keys All endpoints (except `/v1/health` and webhooks) require a Bearer token. ```bash theme={null} curl -H "Authorization: Bearer rw_live_..." \ https://api.rewind.rest/v1/listening/recent ``` ## Key types | Key type | Prefix | Access | | --------- | -------------- | -------------------------------------------------------------------------- | | **Read** | `rw_live_...` | All GET endpoints | | **Admin** | `rw_admin_...` | All endpoints including sync triggers, data management, and key management | Read keys are safe to use in client-side applications. Admin keys should only be used server-side. ## Rate limiting Each API key gets 100 requests per 60-second sliding window. Every response carries the current state in headers, and exceeding the limit returns `429 Too Many Requests`. | Header | Meaning | | ----------------------- | ------------------------------------------------- | | `X-RateLimit-Limit` | Requests allowed per window | | `X-RateLimit-Remaining` | Requests left in the current window | | `X-RateLimit-Reset` | Unix timestamp (seconds) when the window resets | | `Retry-After` | Seconds to wait before retrying, sent only on 429 | ## Unauthorized responses If your key is missing or invalid: ```json theme={null} { "error": "Unauthorized", "status": 401 } ``` # Changelog Source: https://docs.rewind.rest/changelog API updates and new features. ## MCP server: tool titles and output schemas MCP tools are now clearer to read in the client and to consume programmatically. * **Display titles** — every tool, resource, and prompt shows a readable name in Claude Desktop and iOS, like "Now playing" or "Recent runs", instead of a raw identifier like `get_now_playing`. * **Output schemas** — schema-aware clients can render labeled fields from a tool's structured response; every tool now declares an `outputSchema`. * **`get_on_this_day` fix** — calling [`get_on_this_day`](/reference/mcp-tools/cross-domain#get_on_this_day) with no arguments returned an error; it now defaults to today. ## Reading domain: full Instapaper archive Reading endpoints now serve your full Instapaper archive instead of the live API's recent slice. Older articles are searchable and retrievable via [`get_article`](/reference/mcp-tools/reading#get_article). * [`GET /v1/reading/articles`](/api-reference/reading/list-articles) and [`GET /v1/reading/recent`](/api-reference/reading/recent-articles) accept `include_no_body=1` to include rows that exist but couldn't be body-extracted (paywalled sources). Default hides them. * Single-article responses include a `body_unavailable` flag for those placeholder rows so cards can render "read on source" instead of empty content. ## Single-entity cards Three interactive cards for MCP Apps clients (Claude Desktop + iOS) that render alongside Claude's text answer when you ask about one specific article, artist, or athlete. * **Article card** — `get_article` — hero image, title, byline, read time, top highlights, link out to source. * **Artist card** — `get_artist_details` — portrait, bio, total plays, all-time rank, yearly sparkline, top 5 tracks, top 3 albums, and similar artists scoped to your own scrobble history. * **Athlete card** — `get_attended_player` — headshot, team logo, position, current-season stats, your-attended summary across every game you've seen them play, recent appearances. MLB-only for live stats; other leagues surface appearance history. ## Listening * **Per-artist top tracks** — [`GET /v1/listening/top/tracks`](/api-reference/listening/top-tracks) accepts `artist_id` or `artist_name` to scope to a single artist. Combine with `period` for "what Olivia Rodrigo songs have I been listening to lately". * **Extended artist detail** — [`GET /v1/listening/artists/{id}`](/api-reference/listening/artist-detail) now carries bio, last-played timestamp, all-time rank, distinct tracks/albums counts, similar artists, and a yearly sparkline. ## Team logos and colors on attending responses Team metadata now ships inline on every attending endpoint that mentions a team — no follow-up call to render a logo or tint a card. * New `teams` reference table seeded from MLB Stats API (roster, division, home venue) and ESPN (brand colors). 30 MLB teams to start; NFL, NBA, MLS, and NCAA can be added on the same shape. * `event_data.home_team` and `event_data.away_team` on [`GET /v1/attending/events`](/api-reference/attending/list-attended-events) and [`GET /v1/attending/events/{id}`](/api-reference/attending/get-attended-event) now return a full team object with `logo_url`, `logo_dark_url`, `logo_light_url`, `primary_color`, `secondary_color`, `ui_tint_color`, `conference`, and `division`. * `primary_team` on [`GET /v1/attending/players`](/api-reference/attending/list-attended-players) and [`GET /v1/attending/players/{id}`](/api-reference/attending/get-attended-player) replaces the old `primary_team_id` field with the full team shape. * Per-game player appearances expose a `team` object instead of `team_id`, reflecting the in-game team — handles mid-season trades correctly without conflating with the player's current primary team. * Logos hot-link from `mlbstatic.com` SVG with on-light and on-dark cap variants; `` + `prefers-color-scheme` picks the right one in both Claude Desktop and iOS hosts. ## Attending domain New fifth domain for live events — sports games, concerts, theater. **193 events backfilled** from Google Calendar and Gmail across 2016–2026. * [`GET /v1/attending/events`](/api-reference/attending/list-attended-events) — list attended events with filters for category (`sports` / `music` / `arts`), `event_type`, `season`, `year`, `venue_id`, and `attended` (separates "I went" from "I bought tickets but didn't go"). * [`GET /v1/attending/events/{id}`](/api-reference/attending/get-attended-event) — single event with venue, multiple ticket rows, and league-specific `event_data` (scores, winning pitcher, my\_team\_won). * [`GET /v1/attending/seasons/{league}/{season}`](/api-reference/attending/get-attended-season) — attended games in a sports season with W/L record. Counts only games you actually attended, not the team's full record. * [`GET /v1/attending/venues`](/api-reference/attending/list-venues) — venue catalog with city, capacity, and lat/long. * [`GET /v1/attending/stats`](/api-reference/attending/get-attending-stats) — counts by category, `event_type`, and year. * **Seven Gmail parsers** — Ticketmaster, SeatGeek, Ticket Club, AXS, StubHub, VividSeats, and Eventbrite. Universal `schema.org/EventReservation` JSON-LD parser as a fallback. * **Sports enrichment** via MLB Stats API (baseball) and ESPN (NFL, NBA, WNBA, MLS, NCAAF, NCAAB) attaches scores and outcomes to past games. * **Cross-domain link** — concert performers can carry a `lastfm_artist_id` so a single artist row drives both your scrobble history and your concert attendance. * Daily incremental sync at 4:00 AM Pacific. See [Attending domain](/domains/attending). ## MCP server Interactive card UIs for reading and music, plus inline clickable links across list tools. * **Article list UI** for `get_recent_reads` via [MCP Apps](https://blog.modelcontextprotocol.io/posts/2026-01-26-mcp-apps/) — titles, authors, domains, read time, excerpts, and thumbnails. * **Cover grid** for `get_top_albums` and **portrait grid** for `get_top_artists` — both click through to Apple Music (or Last.fm when no match). * **Inline markdown links** in `search`, `semantic_search`, `find_similar_articles`, `get_recent_reads`, `get_top_artists`, `get_top_albums`, and `get_top_tracks` — clickable in every client. * **Author names** render correctly when a source article's `article:author` tag is URL-shaped. * `get_top_artists` accepts `include_sparklines` and forwards the new per-artist play-count series. ## Listening * **Sparklines on top artists** — pass `include_sparklines=true` to [`GET /v1/listening/top/artists`](/api-reference/listening/top-artists) to attach a zero-filled play-count series per artist. Supported for `1month`, `3month`, `6month`, and `12month`. See [Listening domain](/domains/listening#sparklines). * Album and artist artwork now resolves for ampersand-named artists like Matt & Kim, Simon & Garfunkel, and Hall & Oates. * Listening image placeholders auto-expire after 7 days, matching reading-domain behavior. ## Search * [`GET /v1/search`](/api-reference/search/cross-domain-search) results now include `image` URLs and thumbhashes for listening, watching, collecting, and reading hits. The field was previously always null in keyword mode. ## API discovery The OpenAPI 3.1 spec is reachable without auth at `https://api.rewind.rest/openapi.json` (redirects to the canonical `/v1/openapi.json`). Use it to generate clients, drive agent tools, or import into Postman or Insomnia. ## Reading * Reading articles now have thumbnails for most paywalled sources (NYT, Reuters, WSJ) via multi-tier OG extraction. * `description` now falls back to `og_description` when the editorial field is null. * `POST /v1/admin/reenrich-reading` gains a `mode` param: `failed` (default) or `missing-images`. * Reading image placeholders auto-expire after 7 days (previously permanent). ## MCP server * **Interactive poster grid** for `get_recent_watches` via [MCP Apps](https://blog.modelcontextprotocol.io/posts/2026-01-26-mcp-apps/) — renders inline in Claude Desktop, Claude web, VS Code GitHub Copilot, and Goose. * **Semantic and hybrid search** for reading via new `semantic_search` and `find_similar_articles` tools; `search` gains a `mode` param (`keyword` | `semantic` | `hybrid`). * **Full article text** via new `get_article(id)` tool — returns the Instapaper body, including paywalled NYT / WSJ / Atlantic. * **Instapaper deep-links** on every reading article: `instapaper_url` (paywall-free web archive) and `instapaper_app_url` (iOS app). * New prompts: `letterboxd-review-draft`, `training-report`, `film-diet`, and `find-article`. ## API * `GET /v1/search?mode=keyword|semantic|hybrid` — three ranking modes; semantic/hybrid are reading-only. * `GET /v1/reading/articles/{id}` — gains `content`, `instapaper_url`, `instapaper_app_url`. * `GET /v1/reading/articles/{id}/related?limit=5` — related articles via semantic similarity. * `GET /v1/reading/highlights/{id}` — highlight detail with parent-article context. * All `/recent` endpoints: `limit` cap raised from 20 to 50, new `page` param for offset pagination. ## MCP server New [MCP server](/mcp/overview) for connecting AI assistants to your Rewind data. Published as [`rewind-mcp-server`](https://www.npmjs.com/package/rewind-mcp-server) on npm. * 30 tools across all five domains: listening, running, watching, collecting, reading. * Cross-domain search, unified feed, and on-this-day. * Built-in prompt templates for weekly summaries, year-in-review, and period comparisons. * Works with Claude Desktop, Claude Code, Claude iOS/web, and any MCP-compatible client. * Local mode via `npx` or remote mode via `mcp.rewind.rest`. ## Reading domain: delta sync Instapaper sync now transfers only new or changed bookmarks and highlights each cycle, and deletions from Instapaper propagate through. `/health/sync` now includes the Reading domain. ## Reading domain New Reading domain powered by Instapaper. Track articles, reading progress, and highlights. * `GET /reading/articles` — browse and filter articles by status, domain, or tag. * `GET /reading/currently-reading` — articles in progress. * `GET /reading/highlights` — highlighted passages across all articles. * `GET /reading/highlights/random` — random highlight for a daily quote. * `GET /reading/stats` — reading statistics and streaks. * `GET /reading/year/{year}` — year in review. Articles include metadata extracted from OG tags: author, site name, word count, estimated read time, and thumbnail images. ## Public API documentation Launched interactive API documentation at [docs.rewind.rest](https://docs.rewind.rest) powered by Mintlify. Includes getting started guides, domain overviews, and a full API reference with response examples and an interactive playground. ## Apple Music enrichment Listening endpoints now include `apple_music_url` and `preview_url` fields on tracks, artists, and albums. Links go directly to the matching item on Apple Music. Preview URLs point to 30-second audio clips when available. ## Watching: reviews, ratings, and last watched * Movies endpoint now includes `last_watched_at` for sorting by when you last watched. * Reviews and ratings from Letterboxd are now exposed via `review`, `review_url`, and `user_rating` fields on watch history entries. ## Genres, on-this-day, and date filtering * New `GET /listening/genres` endpoint with genre breakdown over time. * Artists now tagged with genres from Last.fm (`genre` field on artist responses). * New `GET /feed/on-this-day` endpoint for what happened on this date in previous years. * Artist and album detail endpoints now include `first_scrobbled_at`. * All recent, stats, and feed endpoints now accept `date`, `from`, and `to` query parameters. * Album and artist artwork falls back to Deezer when Apple Music and iTunes don't have a match. ## Trakt physical media collection New physical media endpoints in the Collecting domain. Track your Blu-ray, DVD, and 4K UHD collection synced from Trakt, with cross-referencing against your Plex watch history. * `GET /collecting/media` — list physical media collection. * `GET /collecting/media/:id` — media item detail. * `GET /collecting/media/stats` — collection statistics by format. * `GET /collecting/media/cross-reference` — owned vs. watched comparison. ## Cross-domain features New endpoints that work across all data domains: * `GET /feed` — unified activity feed with cursor-based pagination. * `GET /feed/domain/:domain` — filter feed to a single domain. * `GET /search` — full-text search across listening, running, watching, and collecting. * `GET /health` — API health check. * `GET /health/sync` — sync status for all domains. # Attending Source: https://docs.rewind.rest/domains/attending Live events, tickets, and game attendance parsed from your calendar and inbox, with sports score enrichment. ## Overview The Attending domain tracks live events you bought tickets for: sports games, concerts, theater, and other one-off events. Events come from two sources: * **Google Calendar**: auto-extracts ticketing details from event descriptions when Google's parsers populate them. * **Gmail**: per-vendor parsers for the major ticket sellers, with a universal [EventReservation](https://schema.org/EventReservation) schema parser as a fallback for everything else. Events sync daily, with incremental Gmail and Calendar pulls. Browse every endpoint in the [API reference](/api-reference/attending/list-attended-events). ## Event categories Every event has a top-level `category` and a more specific `event_type`: | Category | Event types | | -------- | --------------------------------------------------------------------------------------- | | `sports` | `mlb_game`, `nfl_game`, `nba_game`, `wnba_game`, `mls_game`, `ncaaf_game`, `ncaab_game` | | `music` | `concert` | | `arts` | `theater`, `comedy`, `other` | ## Sports enrichment Sports events are enriched with team and score data: MLB from the MLB Stats API, and NFL, NBA, WNBA, MLS, NCAAF, and NCAAB from ESPN. Each event carries league-specific fields in `event_data`, such as final scores, the winning pitcher, and `my_team_won`. The full team object, with name, brand colors, and light and dark logo variants, is denormalized onto every event, player, and appearance, so you never need a second call to render a logo or tint. For MLB, box scores also resolve into per-player appearance lines on the players endpoints. W/L on the [seasons endpoint](/api-reference/attending/get-attended-season) counts only games you attended (`attended=1`), so a 6-game home season with one no-show reports 5-1, not the team's full 5-2. The exact `event_data` and team field shapes are in the [API reference](/api-reference/attending/get-attended-event). ## Filtering The events endpoint supports filtering by: * `category`: `sports`, `music`, or `arts`. * `event_type`: specific event type (e.g., `mlb_game`, `concert`). * `season` / `year`: sports season or calendar year. * `venue_id`: filter to a single venue. * `attended`: `1` for confirmed attendance, `0` for tickets bought but not used, omit for both. ## Year in review The [year in review endpoint](/api-reference/attending/year-in-review) returns a monthly breakdown of your attended events for a given year, plus top venues and top performers. ## From Claude You can also explore your attendance history from Claude. Set up the [MCP server](/mcp/overview), then the [attending tools](/reference/mcp-tools/attending) are yours. Ask which games you went to this season, or your team's attended record. # Collecting Source: https://docs.rewind.rest/domains/collecting Discogs vinyl and Trakt physical media in one place, cross-referenced with your listening and watching. ## Overview The Collecting domain tracks physical media from two sources. Your Discogs and Trakt collections sync weekly. * **Discogs**: vinyl and CD collection, wantlist, and marketplace data. * **Trakt**: physical media (Blu-ray, DVD, 4K) collection tracking. Browse every endpoint in the [API reference](/api-reference/collecting/list-vinyl-collection). ## Cross-referencing The cross-reference endpoints compare your physical collection with your digital activity: * **Vinyl cross-reference**: shows which records in your collection you've actually listened to (matched via Last.fm artist/album data). * **Media cross-reference**: shows which Blu-rays and DVDs you own that you've also watched on Plex. ## Images Album artwork is sourced from Discogs release images. Movie and show artwork for physical media comes from TMDB. See [Images](/domains/images) for the source and fallback details. ## From Claude You can also explore your collection from Claude. Set up the [MCP server](/mcp/overview), then the [collecting tools](/reference/mcp-tools/collecting) are yours. Ask what is in your collection, or which records you own but have never played. # Images Source: https://docs.rewind.rest/domains/images Image pipeline, CDN, and color extraction ## Overview Rewind has a unified image pipeline that handles artwork for all domains. Images are fetched from source APIs, stored in Cloudflare R2, and served through Cloudflare Images for on-the-fly transforms. ## CDN URLs All image responses include an `image` object: ```json theme={null} { "image": { "url": "https://cdn.rewind.rest/cdn-cgi/image/width=300,height=300,fit=cover,format=auto,quality=85/listening/albums/1566/original.jpg?v=1", "thumbhash": "NwgKBwDIl4d2h3h/hrZ4d2h0d4QHQ2oA", "dominant_color": "#d8d8d8", "accent_color": "#d8d8d8" } } ``` ## Image transforms Sized images use Cloudflare's `/cdn-cgi/image//` path. Transform options are comma-separated in the path; the `v` query parameter is only a cache buster. ```text theme={null} https://cdn.rewind.rest/cdn-cgi/image/width={w},height={h},fit=cover,format=auto,quality=85/{r2_key}?v={image_version} ``` The transform options are: | Parameter | Values | Description | | --------- | -------------------------------- | -------------------------------------------- | | `width` | pixels | Target width | | `height` | pixels | Target height | | `fit` | `cover`, `contain`, `scale-down` | Resize behavior | | `format` | `auto`, `webp`, `avif`, `jpeg` | Output format (`auto` picks best for client) | | `quality` | 1-100 | Compression quality | Original images omit the transform path: ```text theme={null} https://cdn.rewind.rest/{r2_key}?v={image_version} ``` ## ThumbHash Every image includes a `thumbhash`, a compact placeholder (20-30 bytes, base64-encoded) that can be decoded client-side into a blurry preview image. This enables instant placeholder rendering before the full image loads. See [thumbhash.io](https://evanw.github.io/thumbhash/) for decoder libraries. ## Color extraction Each image has two extracted colors: * **`dominant_color`**: the most common color in the image (hex). * **`accent_color`**: a secondary color that contrasts with the dominant color (hex). These are useful for dynamic UI theming (e.g., tinting a background based on album art). ## Image sources by domain | Domain | Primary source | Fallbacks | | ------------------- | ---------------- | ----------------- | | Listening (albums) | Apple Music | Deezer, iTunes | | Listening (artists) | Apple Music | Deezer, Fanart.tv | | Running | Strava map tiles | None | | Watching (movies) | TMDB | Fanart.tv, Plex | | Watching (shows) | TMDB | Fanart.tv, Plex | | Collecting (vinyl) | Discogs | None | | Collecting (media) | TMDB | None | # Listening Source: https://docs.rewind.rest/domains/listening Last.fm and Apple Music scrobble data, with top lists, streaks, and a year in review. ## Overview The Listening domain tracks your music history from Last.fm, enriched with Apple Music metadata. * **Last.fm:** scrobble history, top artists, albums, and tracks, and listening streaks. * **Apple Music:** artwork, preview URLs, and Apple Music links layered onto matched records. Scrobbles sync every few minutes. Browse every endpoint in the [API reference](/api-reference/listening/now-playing). ## Time periods Top list endpoints accept a `period` parameter: | Period | Description | | --------- | ------------- | | `7day` | Last 7 days | | `1month` | Last 30 days | | `3month` | Last 90 days | | `6month` | Last 180 days | | `12month` | Last 365 days | | `overall` | All time | ## Sparklines [GET /listening/top/artists](/api-reference/listening/top-artists) accepts `?include_sparklines=true` to attach a per-artist play-count time series, suitable for rendering an inline sparkline next to each item. | Period | Granularity | Points | | --------- | ----------- | ------ | | `1month` | day | 28 | | `3month` | week | 13 | | `6month` | week | 26 | | `12month` | week | 52 | `points` is ordered oldest to newest and zero-filled. The most recent bucket is partial (current week or current day in progress). Weekly buckets anchor on the Monday of the week. `7day` and `overall` omit the field; treat its absence as "no sparkline". ## Filtering * Audiobooks, podcasts, and holiday music are automatically filtered from all listening endpoints. * The filter system combines artist matching, album and track pattern matching, and Last.fm tag-based auto-detection. * Standard date filters (`date`, `from`, `to`). ## Year in review [GET /listening/year/:year](/api-reference/listening/year-in-review) returns year-in-review listening data for a single year. Optionally pass `?month=N` to scope the summary to a single month. ## Images Album and artist artwork is served through the shared image pipeline, with thumbhash placeholders and extracted dominant and accent colors. See [Images](/domains/images) for the source and fallback details. ## From Claude You can also explore your listening history from Claude. Set up the [MCP server](/mcp/overview), then the [listening tools](/reference/mcp-tools/listening) are yours. Ask for your top artists this month, or what you played on a given day. # Reading Source: https://docs.rewind.rest/domains/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](/api-reference/reading/recent-articles). ## 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` (or `mode=hybrid` to blend keyword and semantic). Each result is scored by relevance. * **Related articles**: `GET /v1/reading/articles/:id/related` for "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](/domains/images). ## 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](/api-reference/reading/year-in-review) 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](/mcp/overview), then the [reading tools](/reference/mcp-tools/reading) are yours. Ask what you have been reading, or to find an article you saved about a topic. # Running Source: https://docs.rewind.rest/domains/running Track running activities synced from Strava, including distance, pace, elevation, splits, gear, and personal records. ## Overview The Running domain tracks running activities from Strava, including distance, pace, elevation, splits, gear, and personal records. Activities sync daily, with new runs arriving in real time via Strava webhooks. Browse every endpoint in the [API reference](/api-reference/running/lifetime-running-statistics). ## Charts Several endpoints return chart-ready series for plotting: cumulative distance, pace trend, time-of-day distribution, and elevation gain over time. ## Filtering The activities endpoint supports filtering by: * `year`: filter to a specific year. * `type`: workout type (default, race, long\_run, etc.). * `city`: filter by city name. * `min_distance` / `max_distance`: distance range in miles. * `sort`: sort field (date, distance, pace, elevation). * `order`: asc or desc. * Standard date filters (`date`, `from`, `to`). ## Year in review For a per-year breakdown, use [GET /running/stats/years/:year](/api-reference/running/single-year-summary). It returns year-specific stats such as total runs, distance, elevation, and pace for the requested year. ## Images Running activities carry map artwork generated from Strava map tiles. See [Images](/domains/images) for the source and fallback details. ## From Claude You can also explore your running history from Claude. Set up the [MCP server](/mcp/overview), then the [running tools](/reference/mcp-tools/running) are yours. Ask how far you ran last month, or for a year-over-year pace trend. # Watching Source: https://docs.rewind.rest/domains/watching Movies and TV shows from Plex and Letterboxd, enriched with TMDB metadata. ## Overview The Watching domain tracks movies and TV shows from two sources: * **Plex**: real-time watch events via webhooks, plus a daily library scan. * **Letterboxd**: ratings, reviews, and watch history from the RSS feed, synced a few times a day. Both sources feed into a unified movie database enriched with TMDB metadata such as posters, ratings, genres, directors, and summaries. Browse every endpoint in the [API reference](/api-reference/watching/recent-watches). ## Filtering The movies endpoint supports filtering by: * `genre`: filter by genre name. * `decade`: filter by decade (e.g., `2020`). * `director`: filter by director name. * `year`: filter by release year. * `sort`: sort field (watched\_at, year, title, tmdb\_rating). * `order`: asc or desc. ## Year in review [GET /watching/year/:year](/api-reference/watching/year-in-review) returns a year summary including total movies watched, top-rated films, genre breakdown, and decade distribution. ## Images Movie posters and backdrops are sourced from TMDB, with fallbacks to Fanart.tv and Plex. See [Images](/domains/images) for the source and fallback details. ## From Claude You can also explore your watching history from Claude. Set up the [MCP server](/mcp/overview), then the [watching tools](/reference/mcp-tools/watching) are yours. Ask what you watched last month, or for your top-rated films of a given year. # Welcome to Rewind Source: https://docs.rewind.rest/introduction A personal archive of everything you listen to, run, watch, read, collect, and attend, served as one API you and Claude can query. Rewind is a personal archive of everything you listen to, run, watch, read, collect, and attend. It pulls the services that track your life into one API that you, and Claude, can query. Rewind answering questions about your listening and attendance history in Claude on iPhone ## What it tracks | Domain | Sources | What it tracks | | ------------------------------------- | ---------------------- | ---------------------------------------------------------- | | [**Listening**](/domains/listening) | Last.fm, Apple Music | Scrobbles, top artists/albums/tracks, streaks, stats | | [**Running**](/domains/running) | Strava | Activities, splits, gear, personal records, year summaries | | [**Watching**](/domains/watching) | Plex, Letterboxd | Movies, TV shows, watch history, ratings, reviews | | [**Collecting**](/domains/collecting) | Discogs, Trakt | Vinyl/CD collection, physical media, wantlist | | [**Reading**](/domains/reading) | Instapaper | Articles, reading progress, highlights, word count | | [**Attending**](/domains/attending) | Google Calendar, Gmail | Live events, tickets, sports games, concerts, venues | ## How to use it * **As a REST API**: every domain is served from `api.rewind.rest` with consistent pagination, date filters, and an image CDN. Start with the [quickstart](/quickstart). * **From Claude**: connect the [MCP server](/mcp/overview) and ask in natural language, like *"what was I listening to last March,"* *"how far did I run in 2025,"* or *"find that article I saved about urban design."* ## Who it's for Rewind is single-user by design: it serves one person's archive, read-only. Anyone, or any AI assistant, can explore that data through the API or the MCP server, but it is not multi-tenant. It exists to make one life's data queryable. Make your first authenticated API call in a few minutes. API keys, Bearer tokens, and the read-versus-admin scopes. Connect the MCP server and query your data in natural language. Every endpoint as a machine-readable schema for client generation. # Connect via local stdio Source: https://docs.rewind.rest/mcp/connect-local Run the Rewind MCP server as a local child process for Claude Desktop and Claude Code, communicating over stdin and stdout. Local mode runs the `rewind-mcp-server` package on your own machine. Your MCP client launches it as a child process with `npx`, and the two talk over stdin and stdout using JSON-RPC. Your API key stays in the client config file on your machine and is never sent anywhere except the Rewind API. This is the right choice for desktop clients you control: [Claude Desktop](#claude-desktop) and the [Claude Code CLI](#claude-code-cli). If you are on mobile, on the web, or want a hosted endpoint instead, use [remote connection](/mcp/connect-remote). ## Prerequisites You need two things before you connect: * **Node.js**: the server is published to npm as `rewind-mcp-server` and runs with `npx`, so most clients invoke `npx -y rewind-mcp-server` to download and run the latest version on demand. * **A [Rewind API key](/authentication)**: a read key (prefixed `rw_live_`) is enough, since the server only ever makes GET requests. ## Claude Desktop Add Rewind to your `mcpServers` config. Use a real key in place of the placeholder, then restart the app. ```json claude_desktop_config.json theme={null} { "mcpServers": { "rewind": { "command": "npx", "args": ["-y", "rewind-mcp-server"], "env": { "REWIND_API_KEY": "rw_live_..." } } } } ``` After saving, restart Claude Desktop so it picks up the new server. The client launches the process on startup and tears it down on exit. ## Claude Code CLI The fastest way to add Rewind in [Claude Code](https://docs.claude.com/en/docs/claude-code) is one command. Everything after `--` is the command the CLI runs to start the server. ```bash theme={null} claude mcp add rewind -- npx -y rewind-mcp-server ``` Set your key as an environment variable so the spawned process inherits it, or pass it inline with the `--env` flag: ```bash theme={null} claude mcp add rewind --env REWIND_API_KEY=rw_live_... -- npx -y rewind-mcp-server ``` ### Project config with .mcp.json To share the connection with everyone who works in a repository, commit a `.mcp.json` file to the project root instead. Claude Code reads it automatically when you open the project. ```json .mcp.json theme={null} { "mcpServers": { "rewind": { "command": "npx", "args": ["-y", "rewind-mcp-server"], "env": { "REWIND_API_KEY": "rw_live_..." } } } } ``` Treat `.mcp.json` like any other file that may contain secrets. If you commit it to a shared repository, reference an environment variable rather than pasting a live key, or keep the key in your shell environment and omit the `env` block. ## Environment variables The server reads its configuration from two environment variables. | Variable | Required | Default | Description | | ---------------- | -------- | ------------------------- | ----------------------------------------------------------------------- | | `REWIND_API_KEY` | Yes | none | Your Rewind API key. The server exits at startup if it is missing. | | `REWIND_API_URL` | No | `https://api.rewind.rest` | Base URL for the Rewind API. Override only for self-hosting or testing. | You almost never need to set `REWIND_API_URL`. Leave it unset to point at the production API. Set it only if you run your own Rewind instance. # Connect via the hosted server Source: https://docs.rewind.rest/mcp/connect-remote Connect a mobile or web MCP client to the hosted Rewind server at mcp.rewind.rest, using either a Bearer token or the GitHub sign-in flow. The hosted Rewind MCP server runs as a Cloudflare Worker at `https://mcp.rewind.rest/mcp`. Use it when your client cannot launch a local process: Claude on iOS, claude.ai, ChatGPT, and other clients that connect to a remote URL. If you are on a desktop that can run a child process, [connect over local stdio](/mcp/connect-local) instead. The MCP endpoint is always `https://mcp.rewind.rest/mcp`. How you authenticate depends on your client. Some clients let you paste a static Bearer token. Others speak full OAuth and walk you through a GitHub sign-in. Both paths reach the same server. ## Connect with a Bearer token If your client lets you add a remote MCP server with a custom authorization header, point it at the endpoint and pass your [Rewind API key](/authentication) as a Bearer token. ```json title="remote-mcp-config.json" theme={null} { "url": "https://mcp.rewind.rest/mcp", "headers": { "Authorization": "Bearer rw_live_..." } } ``` Use a read key. The server only exposes read tools, so an admin key buys you nothing here. See [authentication](/authentication) for how to mint a key. ## Connect with GitHub sign-in Clients that implement the full OAuth 2.1 handshake (claude.ai and Claude on iOS, for example) do not ask you for an API key. You add the server by URL, and the client redirects you through a consent flow. The Worker uses GitHub as the upstream identity provider and maps your GitHub account to a Rewind user behind the scenes. In your client's integrations or connectors settings, add a remote MCP server with the URL `https://mcp.rewind.rest/mcp`. Leave the authorization field blank if the client offers one; the OAuth flow supplies the token. The client opens the Rewind authorize page. It names the client requesting access and the scopes it is asking for. Review it, then choose to sign in with GitHub. GitHub prompts you to authorize the connection. After you approve, GitHub redirects back to the Worker, which looks up your GitHub account against the Rewind allowlist. On success the Worker issues an access token and refresh token to your client and redirects you back. The connection is now active and Rewind tools are available. ### The allowlist Rewind is a single-user personal archive, so the hosted server does not grant access to anyone with a GitHub account. The Worker keeps an allowlist that maps specific GitHub user IDs to Rewind users. If your GitHub account is not on it, the callback fails with a `403` and a message naming your GitHub login and ID, telling you to contact the Rewind admin to request access. To get added, send the admin the GitHub login and numeric user ID shown in that error. See [troubleshooting](/troubleshooting#claude-and-mcp) for how to resolve a `403` and other connection errors. ### Scopes The authorize request can ask for a broad `read` scope or for individual per-domain read scopes. The server advertises the full set: | Scope | Grants read access to | | ----------------- | --------------------- | | `read` | Every domain | | `read:listening` | Listening data | | `read:running` | Running data | | `read:watching` | Watching data | | `read:collecting` | Collecting data | | `read:reading` | Reading data | | `read:feed` | The cross-domain feed | Every scope is read-only. The server exposes no write or admin tools regardless of which scopes a client requests. ### Token lifetimes Once authorized, your client holds two tokens and refreshes the short-lived one as needed: | Token | Lifetime | | ------------- | -------- | | Access token | 1 hour | | Refresh token | 90 days | When the access token expires, the client exchanges the refresh token for a new one without prompting you. You re-run the GitHub sign-in only after the refresh token lapses or if access is revoked. The flow uses PKCE with S256 only. Plain PKCE is rejected, per the MCP specification, so a compliant client handles this automatically. ## Rate limit The hosted server caps requests at 120 per minute per client IP address. Exceed it and the server responds with `429 Too Many Requests` and a `Retry-After: 60` header. Back off for a minute and the window resets. Normal interactive use stays well under this ceiling; you mostly hit it with tight automated loops. # MCP Server Source: https://docs.rewind.rest/mcp/overview Connect AI assistants to your Rewind data using the Model Context Protocol. The Rewind MCP server gives AI assistants direct access to your personal data across every domain. Ask about your listening history, running stats, movie watches, vinyl collection, reading highlights, or events you have attended, all in natural language. It is built on the [Model Context Protocol](https://modelcontextprotocol.io/), an open standard from Anthropic, so it works with any MCP-compatible client such as Claude and ChatGPT. ## When to use it Reach for Rewind any time the conversation references your own history: things you read, listened to, watched, saved, bookmarked, ran, or collected. Rewind owns this data, so it answers from your archive instead of guessing or falling back to web search. Questions that route here include: * "What have I been listening to this week?" * "When was the last time I watched a Wes Anderson film?" * "What Beastie Boys records do I have on vinyl?" * "Find that article I saved about a former SNL writer." * "What happened on this day in previous years?" The server pulls live answers from the same [REST API](/openapi-spec) that powers Rewind, so what an assistant sees matches what your apps see. ## Tools by domain Rewind groups its tools by domain. Each page lists the tools an assistant can call, with parameters and example responses. Now playing, top artists, albums, and tracks, streaks, and stats. Recent runs, per-mile splits, personal records, streaks, and stats. Recent watches, browse by genre, decade, or director, and stats. Vinyl records, Blu-ray, 4K UHD, HD DVD, and collection stats. Articles, highlights, a random highlight, and stats. Sports games, concerts, theater, season records, and players you have watched. Full-text and semantic search, a unified feed, and on-this-day. Each card links to that domain's MCP tools. For background on the underlying data sources and their REST endpoints, see the [Domains guides](/domains/listening). ## Read-only by design The MCP server has read-only access to your data. It exposes browse, search, and stat tools only. No write or admin operations are reachable through it, so an assistant can read your archive but never change it. The server is also stateless. It holds no data between calls and caches nothing locally. ## Two ways to connect Pick the connection style that matches your client. Run the `rewind-mcp-server` package as a child process on your machine. Best for desktop clients and Claude Code, where your API key stays local. Connect to the hosted server at `https://mcp.rewind.rest/mcp`. Best for mobile and web clients that talk to a remote endpoint. Both modes serve the same tools, resources, and prompts. They differ only in where the server runs and how it is authenticated. # Resources and prompts Source: https://docs.rewind.rest/mcp/resources-and-prompts Pull full entity records into a conversation with @-mentionable resources, and kick off multi-step queries with the built-in prompt templates. Beyond tools, the Rewind MCP server exposes two things you can reference directly: entity resources you `@`-mention to load a full record, and prompt templates that orchestrate a whole multi-step query for you. Tools are how the model fetches data on its own; resources and prompts are how you hand it a starting point. ## Entity resources Every resource is addressed by a `rewind://` URI and returns the full detail record for one entity, fetched live from the API. Each maps to a specific endpoint, so the data matches what the corresponding [API reference](/openapi-spec) route returns. | Entity | URI | Source endpoint | | -------------- | ------------------------------- | --------------------------------------------------------- | | Movie | `rewind://movie/{id}` | `/v1/watching/movies/{id}` | | Show | `rewind://show/{id}` | `/v1/watching/shows/{id}` | | Album | `rewind://album/{id}` | `/v1/listening/albums/{id}` | | Artist | `rewind://artist/{id}` | `/v1/listening/artists/{id}` | | Vinyl | `rewind://vinyl/{id}` | `/v1/collecting/vinyl/{id}` | | Physical media | `rewind://physical-media/{id}` | `/v1/collecting/media/{id}` | | Article | `rewind://article/{id}` | `/v1/reading/articles/{id}` | | Highlight | `rewind://highlight/{id}` | `/v1/reading/highlights/{id}` | | Activity | `rewind://activity/{id}` | `/v1/running/activities/{id}` | | Sync status | `rewind://sync/status` | `/v1/health/sync` | | Year in review | `rewind://{domain}/year/{year}` | `/v1/{domain}/year/{year}` (listening, running, watching) | The `{id}` in each URI is the internal Rewind id, not a Last.fm, TMDB, or Discogs id. You usually get one from a tool result or a search hit rather than typing it by hand. ### Reference a resource with @-mention In a client that supports resource mentions (such as Claude Code), type `@rewind:` followed by the URI to pull the full record into the conversation: ```text theme={null} @rewind://artist/42 ``` That loads the complete artist detail (play count, genre, top albums, top tracks, image metadata, and Apple Music URL) so the model can reason over it directly, without spending a tool call to fetch it. ### From a search hit to a full record The [`search` tool](/reference/mcp-tools/cross-domain) returns `resource_link` blocks pointing at these URIs. That lets a client drill from a match straight into the full record: search surfaces the candidate, then the resource link resolves to the entity's `rewind://` URI for the complete detail. The article resource is the canonical way to read past an excerpt. `rewind://article/{id}` returns the full plain-text body, including for paywalled sources, so the model does not need to fall back to web search or fetch the original URL. ## Prompt templates Prompt templates are pre-written, multi-step instructions the model can run on your behalf. Each one knows which tools to call, in what order, and how to shape the result. Pick one from your client's prompt menu instead of describing the whole workflow yourself. | Prompt | Arguments | What it does | | ------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------- | | `weekly-summary` | none | Summarizes activity across all domains for the past week, organized by domain. | | `year-in-review` | `year` | Generates a comprehensive year-in-review across all domains for the given year. | | `compare-periods` | `domain`, `period1`, `period2` | Compares activity between two time periods for a single domain. | | `letterboxd-review-draft` | `title` (optional) | Drafts a Letterboxd-style review for a recently watched, rated-but-unreviewed film. | | `training-report` | `days` (optional, default 7) | Produces a coach-style running report for the last 7 to 14 days. | | `film-diet` | `period` (optional, default lifetime) | Paints a portrait of your film-watching taste: genre mix, decades, directors, rewatch rate. | | `find-article` | `description` | Recovers a half-remembered article via hybrid plus semantic search, then surfaces related pieces. | ### How a template runs A template seeds the conversation with a detailed instruction, then the model executes it using ordinary tools. The `training-report` prompt, for example, gathers recent runs, lifetime [running stats](/domains/running), streak state, and per-mile splits on the longest run, then structures a report with a volume headline, a pace trend, and one concrete suggestion for the week ahead. Templates with optional arguments fall back to sensible defaults: `training-report` covers 7 days when you do not pass `days`, `film-diet` reports on your lifetime when you do not pass `period`, and `letterboxd-review-draft` picks your most recent unreviewed watch when you do not pass a `title`. ### find-article and the article resource `find-article` is where prompts and resources work together. The template runs a [reading](/domains/reading) search, fetches the `rewind://article/{id}` resource for the top candidates to read each excerpt, and only claims a match after the excerpt actually supports your description. It is built to refuse to invent connecting facts: if nothing clearly matches, it presents the top few candidates and asks which one you meant. # Rich responses Source: https://docs.rewind.rest/mcp/rich-responses How Rewind MCP tools return images, links, structured data, and interactive cards beyond plain text. Rewind tools return more than a wall of text. Every response follows the MCP content model, so a single tool call can ship a text summary, cover art, links into source platforms, machine-readable JSON, and (in clients that support it) an interactive card. The model reasons over the same response your client renders. A typical response carries up to four kinds of payload: * A text block with a human-readable summary. * Image blocks for artwork, posters, and portraits. * Resource link blocks pointing at the canonical record or the source platform. * A `structuredContent` object with the exact numbers and fields. ## Image blocks Tools attach artwork as `image` content blocks. A detail tool returns the single poster, cover, or portrait for its entity; a list tool returns artwork for its top few items (five by default) and downscales them, so a long page stays well under the client's response-size budget. Any tool that returns images accepts an `include_images` parameter, defaulting to `true`. Set it to `false` for a compact, text-only response: ```text theme={null} get_top_albums(period: "12m", include_images: false) ``` See [Troubleshooting](/troubleshooting#claude-and-mcp) if responses feel too image-heavy in your client. ## Resource link blocks External platform URLs come back as `resource_link` content blocks: Letterboxd reviews, Strava activities, Discogs releases, Apple Music pages, original article URLs, and Last.fm pages. These let a client drill from a result straight into the source. Resource links arrive as `resource_link` blocks, which clients show in the tool-use accordion rather than inline. When the model lists items, it also renders each title as a markdown link from the URL fields in `structuredContent`, so the links reach you either way. The cross-domain [`search`](/api-reference/search/cross-domain-search) tool returns resource links pointing at `rewind://` entity URIs, so a match can drill into the full record. See [Resources and prompts](/mcp/resources-and-prompts) for how those URIs map to endpoints. ## Structured content Every tool also returns a `structuredContent` object: a JSON shape that mirrors the underlying [API response](/openapi-spec). This is where the exact numbers live. The model reads totals, counts, dates, ranks, and URLs from structured fields instead of re-parsing them out of the prose summary, which keeps numeric answers accurate. When you need precise figures (play counts, distances, ratings, streak lengths), they come from `structuredContent`, not the text block. ## Interactive cards Several tools advertise [MCP Apps](https://blog.modelcontextprotocol.io/posts/2026-01-26-mcp-apps/) UI resources. In a client that supports MCP Apps, these render as an inline interactive card that consumes the tool's `structuredContent`. In any other client, the same call returns the standard text, image, resource link, and structured response unchanged, so nothing breaks when cards are not supported. These tools render cards: | Tool | Card | | --------------------- | ---------------------------------------------------------------------------- | | `get_recent_watches` | Poster grid of recently watched movies | | `get_recent_reads` | Article card list of recently saved reads | | `get_article` | Single-article card: hero image, byline, meta strip, top highlights | | `get_artist_details` | Single-artist card: portrait, stats, yearly sparkline, top tracks and albums | | `get_top_tracks` | Top-tracks list with a flat and album-grouped view | | `get_top_albums` | Album cover grid | | `get_top_artists` | Artist portrait grid | | `get_attended_season` | Season grid: per-game score, attendance, weather, performers | | `get_attended_event` | Single-game card: linescore, notable performers, ticket info | | `get_attended_player` | Single-athlete card: headshot, season stats, recent appearances | These map to the [listening](/domains/listening), [watching](/domains/watching), [reading](/domains/reading), and [attending](/domains/attending) domains. Card support depends on the client, not the connection method: the hosted [remote server](/mcp/connect-remote) and the local [stdio server](/mcp/connect-local) both advertise the same UI resources. # OpenAPI Spec Source: https://docs.rewind.rest/openapi-spec Machine-readable schema for every Rewind endpoint The full Rewind API is published as an [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0) document -- the same schema that powers this site's [API Reference](/api-reference) tab, with every path, parameter, response, and example. ## Fetch the spec No auth required: ```bash theme={null} curl https://api.rewind.rest/v1/openapi.json ``` The shorter `https://api.rewind.rest/openapi.json` 301-redirects to the canonical `/v1/openapi.json` for tools that don't follow redirects. ## What it's for * **Generate clients.** Run [`openapi-generator`](https://openapi-generator.tech/) or your stack's preferred codegen against the URL to produce a typed SDK in any language. * **Drive agents.** Tools that consume OpenAPI -- function-calling LLMs, agent frameworks -- can ingest the spec and call any endpoint. * **Import into Postman / Insomnia / Bruno.** Use the URL as the import source; every endpoint and example is pre-loaded. * **Inspect contracts.** Browse the raw spec to see exact response shapes without clicking through the reference. # Quickstart Source: https://docs.rewind.rest/quickstart Make your first authenticated API call in a few minutes. Rewind is a hosted API, so there is nothing to install or run. With an API key you can make your first call in a couple of minutes. You need a Rewind API key (`rw_live_...`). See [Authentication](/authentication) to create one and for the read-versus-admin key types. The health endpoint needs no authentication, so it is the simplest way to confirm you can reach the API. ```bash theme={null} curl https://api.rewind.rest/v1/health ``` ```json theme={null} { "status": "ok", "timestamp": "2026-03-18T21:00:00.000Z" } ``` Every other endpoint takes your key as a Bearer token in the `Authorization` header. Fetch your most recent scrobbles: ```bash theme={null} curl -H "Authorization: Bearer rw_live_..." \ "https://api.rewind.rest/v1/listening/recent?limit=5" ``` ```json theme={null} { "data": [ { "track": { "id": 4296, "name": "Cherry" }, "artist": { "id": 551, "name": "Ratatat" }, "album": { "id": 1566, "name": "Ratatat" }, "scrobbled_at": "2026-03-18T01:14:04.000Z" } ] } ``` Every domain answers on the same `/v1//...` shape. Pull your lifetime running stats: ```bash theme={null} curl -H "Authorization: Bearer rw_live_..." \ https://api.rewind.rest/v1/running/stats ``` ```json theme={null} { "data": { "total_runs": 1350, "total_distance_mi": 6069.88, "avg_pace": "8:12/mi", "years_active": 17 } } ``` List endpoints return a `{ data, pagination }` envelope and accept `page` and `limit`. Most list and stats endpoints also accept `date`, `from`, and `to` filters. ```bash theme={null} curl -H "Authorization: Bearer rw_live_..." \ "https://api.rewind.rest/v1/listening/recent?from=2026-01-01&limit=10" ``` From here, browse the full [OpenAPI spec](/openapi-spec) to generate a client, or [use Rewind from Claude](/mcp/overview) through the MCP server. # Attending Source: https://docs.rewind.rest/reference/mcp-tools/attending MCP tools for the live events and games you have attended. ## `get_attended_event` Get a single attended event (sports game, concert, theater show) in full detail, including venue, tickets, and per-player stat lines for sports games. Event id. ## `get_attended_events` List events you bought tickets for: sports games, concerts, theater. 1 = only attended, 0 = only unattended (purchased but missed). Omit to return both. Top-level category filter. One of: `sports`, `music`, `arts`. Specific type, e.g. "mlb\_game", "concert", "ncaaf\_game". Items per page (max 100). Defaults to `20`. Page number, 1-indexed. Defaults to `1`. Sports season year (e.g. 2024). Case-insensitive substring match against either team name in event\_data. e.g. "mariners", "huskies", "storm". Returns games where this team was either home or away. Exact match on the league-native team id. e.g. 136 = Seattle Mariners (MLB), 264 = Washington Huskies (ESPN). Use when the natural-language `team` substring is ambiguous. Filter by venue id. Calendar year filter on event\_date. ## `get_attended_player` Detailed athlete card for an MLB / NFL / NCAAF / NBA player you've watched play in person. Player id. Include artwork/poster image content blocks in the response. Default true. Set false to keep responses small. Defaults to `true`. ## `get_attended_player_stats` Aggregate stats for one player across the games you attended. Player id (from get\_attended\_players or get\_attended\_player). Optional. Single-season slice. Omit for career across all attended games (recommended — see tool description). ## `get_attended_players` Search the list of players (MLB, NFL, NCAAF, NBA, etc.) you have watched play in person. Filter by league slug, e.g. "mlb", "nfl", "ncaaf". Items per page (max 50). Defaults to `10`. Case-insensitive substring match on full name. e.g. "julio", "kirby", "will smith". Page number, 1-indexed. Defaults to `1`. Filter by primary team id (league-native, e.g. 136 = Mariners in MLB). ## `get_attended_season` Get every game you attended (or hold tickets for) in a given league + season, with W/L record. league is a slug like "mlb", "nfl", "ncaaf", "nba", "wnba". League slug (lowercase): "mlb", "nfl", "nba", "wnba", "ncaaf", "ncaab", "mls". Season year (e.g. 2024 for the 2024 MLB season). ## `get_attending_stats` Aggregate counts of attended events broken down by category, event\_type, and year. This tool takes no parameters. ## `get_attending_year_in_review` Year-in-review summary for attended events: totals, monthly breakdown, top venues, top concert performers, and the full event list. Calendar year, e.g. 2024. # Collecting Source: https://docs.rewind.rest/reference/mcp-tools/collecting MCP tools for your Discogs vinyl and physical media collections. ## `get_collecting_stats` Get overall collection statistics including total items, format breakdown (vinyl, CD, cassette), unique artists, genre data, and year range. Optional: filter to a specific date (YYYY-MM-DD) Optional: start of date range (ISO 8601) Optional: end of date range (ISO 8601) ## `get_physical_media` Browse the physical media collection (Blu-ray, 4K UHD, HD DVD). Include artwork/poster image content blocks in the response. Default true. Set false to keep responses small. Defaults to `true`. Number of items to return Defaults to `10`. Optional: filter by format (bluray, uhd\_bluray, hddvd) One of: `bluray`, `uhd_bluray`, `hddvd`. Page number for pagination Defaults to `1`. Optional: search by title (e.g. 'Princess Bride', 'Kubrick') ## `get_physical_media_stats` Get statistics for the physical media collection including total items and breakdown by format (Blu-ray, 4K UHD, HD DVD). This tool takes no parameters. ## `get_vinyl_collection` Browse the vinyl record collection from Discogs. Optional: filter by artist name Optional: filter to a specific date (YYYY-MM-DD) Optional: filter by format (e.g. 'Vinyl', 'CD', 'Cassette') Optional: start of date range (ISO 8601) Optional: filter by genre Include artwork/poster image content blocks in the response. Default true. Set false to keep responses small. Defaults to `true`. Number of records to return Defaults to `10`. Optional: sort order (default: desc) One of: `asc`, `desc`. Page number for pagination Defaults to `1`. Optional: search by artist or album title (e.g. 'Beastie Boys', 'Dark Side') Optional: sort field (default: date\_added). Options: date\_added, title, year, artist Optional: end of date range (ISO 8601) # Cross-domain Source: https://docs.rewind.rest/reference/mcp-tools/cross-domain Search, feed, on-this-day, and health tools that span every domain. ## `get_feed` Get the unified activity feed across all domains. Optional: filter to a specific date (YYYY-MM-DD) Optional: filter feed to a single domain One of: `listening`, `running`, `watching`, `collecting`, `reading`. Optional: start of date range (ISO 8601) Number of feed items to return Defaults to `10`. Optional: end of date range (ISO 8601) ## `get_health` Check the health and sync status of the Rewind API. This tool takes no parameters. ## `get_on_this_day` Get historical 'on this day' items -- what happened on a given date in previous years across all domains. Optional: day (1-31). Defaults to current day. Optional: month (1-12). Defaults to current month. ## `search` Search across all domains (listening, running, watching, collecting, reading). Optional: filter results to a single domain One of: `listening`, `running`, `watching`, `collecting`, `reading`. Number of results to return Defaults to `10`. Ranking mode. keyword = FTS (default). semantic = cosine-similarity over article embeddings (reading only). hybrid = FTS + semantic via reciprocal rank fusion (reading only). One of: `keyword`, `semantic`, `hybrid`. Page number for pagination Defaults to `1`. Search query text ## `semantic_search` Semantic search over the reading domain using Voyage AI embeddings. Number of matches to return Defaults to `10`. Natural-language description of the article # Listening Source: https://docs.rewind.rest/reference/mcp-tools/listening MCP tools for your Last.fm and Apple Music listening history. ## `get_album_details` Get detailed information about a specific album by ID: artist, play count, track listing, cover art, and Apple Music link. Album ID Include artwork/poster image content blocks in the response. Default true. Set false to keep responses small. Defaults to `true`. ## `get_artist_details` Detailed listening profile for one artist: stats, rank, top tracks and albums, similar artists, and a yearly play sparkline. Artist ID Include artwork/poster image content blocks in the response. Default true. Set false to keep responses small. Defaults to `true`. ## `get_listening_genres` Get genre breakdown over time from Last.fm listening history, grouped by week/month/year. Optional: filter to a specific date (YYYY-MM-DD) Optional: start of date range (ISO 8601) Grouping period (default: month) One of: `week`, `month`, `year`. Defaults to `month`. Max genres to return -- rest grouped as "Other" (default 10) Defaults to `10`. Optional: end of date range (ISO 8601) ## `get_listening_stats` Get overall listening statistics from Last.fm including total scrobbles, unique artists, albums, tracks, and daily average. Optional: filter to a specific date (YYYY-MM-DD) Optional: start of date range (ISO 8601) Optional: end of date range (ISO 8601) ## `get_listening_streaks` Get listening streak data from Last.fm -- current consecutive days with scrobbles and the longest streak ever. This tool takes no parameters. ## `get_now_playing` Get the track currently playing (or most recently scrobbled) on Last.fm. Include artwork/poster image content blocks in the response. Default true. Set false to keep responses small. Defaults to `true`. ## `get_recent_listens` Get recently scrobbled tracks from Last.fm, with top-N album covers and Apple Music resource links. Optional: filter to a specific date (YYYY-MM-DD) Optional: start of date range (ISO 8601) Include artwork/poster image content blocks in the response. Default true. Set false to keep responses small. Defaults to `true`. Number of recent tracks to return (default 10, max 50) Defaults to `10`. Page number for pagination. Combine with limit to page through longer windows. Defaults to `1`. Optional: end of date range (ISO 8601) ## `get_top_albums` Get top listened-to albums from Last.fm for a given time period, with top-N covers and Apple Music links. Include artwork/poster image content blocks in the response. Default true. Set false to keep responses small. Defaults to `true`. Number of albums to return Defaults to `10`. Page number for pagination Defaults to `1`. Time period for rankings One of: `7day`, `1month`, `3month`, `6month`, `12month`, `overall`. Defaults to `1month`. ## `get_top_artists` Get top listened-to artists for a time window, with top-N artist images and Apple Music links. Optional: filter to a specific date (YYYY-MM-DD) Optional: start of date range (ISO 8601) Include artwork/poster image content blocks in the response. Default true. Set false to keep responses small. Defaults to `true`. When true (default), attach a `sparkline` (granularity + zero-filled play-count points) to each artist. Supported for period in \{7day, 1month, 3month, 6month, 12month}. Set false to keep responses small. Defaults to `true`. Number of artists to return Defaults to `10`. Page number for pagination Defaults to `1`. Rolling time period for rankings. Use for "lately"/"this week" style queries. Ignored when date/from/to is supplied. One of: `7day`, `1month`, `3month`, `6month`, `12month`, `overall`. Defaults to `1month`. Optional: end of date range (ISO 8601) ## `get_top_tracks` Top listened-to tracks for a time window, with top-N Apple Music links. Filter to a single artist. Stable id from get\_artist\_details or get\_top\_artists. Composes with period and date filters. Substring match against artist names (case-insensitive). Resolves to the highest-playcount match. Use only if no artist\_id is available; passing both is a 400. Optional: filter to a specific date (YYYY-MM-DD) Optional: start of date range (ISO 8601) Number of tracks to return Defaults to `10`. Page number for pagination Defaults to `1`. Rolling time period for rankings. Use for "lately"/"this week" style queries. Ignored when date/from/to is supplied. One of: `7day`, `1month`, `3month`, `6month`, `12month`, `overall`. Defaults to `1month`. Optional: end of date range (ISO 8601) # Reading Source: https://docs.rewind.rest/reference/mcp-tools/reading MCP tools for your Instapaper articles and highlights. ## `find_similar_articles` Find articles thematically similar to a given article by cosine similarity over Voyage AI embeddings. Internal Rewind article id (from an earlier search/recent result) Number of related articles to return Defaults to `5`. ## `get_article` Fetch one saved article by id, returning its full body, metadata, and highlights. Internal Rewind article id (from a get\_recent\_reads, search, semantic\_search, or find\_similar\_articles result) ## `get_random_highlight` Get a single random highlight from saved Instapaper articles. This tool takes no parameters. ## `get_reading_highlights` Get saved highlights from Instapaper articles. Number of highlights to return Defaults to `10`. Page number Defaults to `1`. ## `get_reading_stats` Get overall reading statistics from Instapaper including total articles, finished count, currently reading, highlights, and word count. This tool takes no parameters. ## `get_recent_reads` Get recently saved articles from Instapaper. Optional: filter to a specific date (YYYY-MM-DD) Optional: start of date range (ISO 8601) Include artwork/poster image content blocks in the response. Default true. Set false to keep responses small. Defaults to `true`. Number of recent articles to return (max 50) Defaults to `10`. Page number for pagination. Combine with limit to page through longer windows. Defaults to `1`. Optional: end of date range (ISO 8601) # Running Source: https://docs.rewind.rest/reference/mcp-tools/running MCP tools for your Strava running activities and stats. ## `get_activity_details` Get detailed information about a specific running activity by ID, including distance, pace, heart rate, elevation, calories, and a Strava resource link. Activity ID (from get\_recent\_runs or get\_personal\_records) ## `get_activity_splits` Get per-mile splits for a running activity. Activity ID (from get\_recent\_runs or get\_personal\_records) ## `get_personal_records` Get personal running records (PRs) from Strava -- fastest times at standard distances like mile, 5K, 10K, half marathon, marathon. This tool takes no parameters. ## `get_recent_runs` Get recent running activities from Strava. Optional: filter to a specific date (YYYY-MM-DD) Optional: start of date range (ISO 8601) Number of recent runs to return (max 50) Defaults to `10`. Page number for pagination. Combine with limit to page through longer windows. Defaults to `1`. Optional: end of date range (ISO 8601) ## `get_running_stats` Get overall running statistics from Strava including total runs, distance, elevation, duration, average pace, and Eddington number. This tool takes no parameters. ## `get_running_streaks` Get running streak data from Strava -- current consecutive days with runs and the longest streak ever. This tool takes no parameters. ## `get_running_years` Get per-year summary of running activity: total runs, distance, elevation, duration, average pace, longest run, and race count for every year on record. This tool takes no parameters. # Watching Source: https://docs.rewind.rest/reference/mcp-tools/watching MCP tools for your Plex and Letterboxd movie and TV history. ## `browse_movies` Browse the movie collection with filters for genre, decade, director, and year. Optional: filter by decade (e.g. '1990', '2000') Optional: filter by director name Optional: filter by genre (e.g. 'Horror', 'Comedy', 'Drama') Include artwork/poster image content blocks in the response. Default true. Set false to keep responses small. Defaults to `true`. Number of movies to return Defaults to `10`. Optional: sort order (default: desc) One of: `asc`, `desc`. Page number Defaults to `1`. Optional: sort by field (default: watched\_at). Options: watched\_at, title, year, rating Optional: filter by release year ## `get_movie_details` Get detailed information about a specific movie by ID, including director, genres, rating, summary, watch history, poster image, and Letterboxd review links for rated watches. Movie ID Include artwork/poster image content blocks in the response. Default true. Set false to keep responses small. Defaults to `true`. ## `get_recent_watches` Get recently watched movies and TV shows from Plex and Letterboxd. Optional: filter to a specific date (YYYY-MM-DD) Optional: start of date range (ISO 8601) Include artwork/poster image content blocks in the response. Default true. Set false to keep responses small. Defaults to `true`. Number of recent watches to return (max 50) Defaults to `10`. Page number for pagination (1-indexed). Combine with limit to page through longer windows like "last month". Defaults to `1`. Optional: end of date range (ISO 8601) ## `get_watching_decades` Get decade breakdown across all watched movies. This tool takes no parameters. ## `get_watching_directors` Get top directors by watched-movie count. Number of directors to return Defaults to `20`. ## `get_watching_genres` Get genre breakdown across all watched movies. This tool takes no parameters. ## `get_watching_stats` Get overall watching statistics including total movies, watch time, movies this year, top genre, top director, TV show counts, and episode counts. Optional: filter to a specific date (YYYY-MM-DD) Optional: start of date range (ISO 8601) Optional: end of date range (ISO 8601) # Troubleshooting Source: https://docs.rewind.rest/troubleshooting Diagnose authentication failures, rate limits, stale data, MCP setup, and image issues against the Rewind API. Most problems fall into a handful of buckets: a key the API does not accept, a window you have exhausted, a domain that has not synced recently, or an MCP client that has not picked up your configuration. Run the self-diagnostics first, then open the entry that matches what you see. ## Self-diagnostics first Two calls answer most questions. Run them before anything below: ```bash theme={null} curl https://api.rewind.rest/v1/health curl -H "Authorization: Bearer rw_live_..." \ https://api.rewind.rest/v1/health/sync ``` `/v1/health` confirms the API is reachable. `/v1/health/sync` reports each domain's `last_sync`, `status`, and `error_rate`, which separates a stale-data problem from an API outage (see [sync health](/api-reference/system/sync-health-status) for the full response). ## Requests and authentication A `401` means the request was not authenticated. Three distinct causes return the same status with a different `error` message: * **Malformed header.** The `Authorization` header is missing, or it does not begin with `Bearer rw_`. Check that the prefix is exactly `Bearer rw_`, not `bearer` or a bare token. * **Unknown or revoked key.** The prefix is correct but no active key matches it. A revoked key falls into this bucket once its cache entry expires. * **Expired key.** The key exists and is active, but its expiry has passed. This one returns `{"error":"Token expired","status":401}` so you can tell it apart from the other two. Auth lookups are cached in memory for about 60 seconds per Worker isolate, so a newly created or just-revoked key can take up to a minute to take effect. If a brand-new key returns `401`, wait a moment and retry before assuming it is wrong. On a remote MCP connection, a `401` means the request reached the server without a valid grant: re-run the [GitHub consent flow](/mcp/connect-remote), or re-check your Bearer token for token-based clients. The request authenticated successfully, but the key does not have the scope the endpoint requires. The common case is using a read key (`rw_live_...`) on an admin-only endpoint such as a sync trigger or key management. The fix is an admin key (`rw_admin_...`), not a new read key. See [Authentication](/authentication) for the scope each key type grants. You have exceeded the sliding 60-second window for your key. The response includes a `Retry-After` header (seconds to wait) plus the `X-RateLimit-*` headers; see [Authentication](/authentication) for the limit and what each header means. Back off until `Retry-After` passes, then retry. Heavy automated polling is the usual cause, so space out repeated calls. The window is tracked per Worker isolate, so counts reset when an isolate recycles and observed limits can be slightly more generous under load. The remote MCP server enforces its own per-minute limit the same way. ## Data freshness If a call succeeds but the data looks old or empty, the source sync is the place to look, not the API. Call `GET /v1/health/sync` and read the relevant domain: * `status` is `completed`, `failed`, or `never`. A value of `never` means that domain has not run a sync yet. * `error` is populated only when the latest run failed, and carries the failure message from the sync worker. * `error_rate` is the share of runs in the last 24 hours that failed, from `0.0` (all healthy) to `1.0` (all failing). * `last_sync` is the timestamp of the most recent run. Compare it against the domain's cron cadence to judge freshness. If a domain is stale and you hold an admin key, you can force a fresh sync through the admin sync endpoint. Read keys cannot trigger syncs and will get a `403`. Rewind answers from its last successful sync, not this exact moment, so a recent listen, run, or watch can be missing for a while. Ask the model to call `get_health` first: it returns overall API health plus a last-sync timestamp per domain, and a timestamp that is hours or days old explains the gap. The MCP server itself is stateless and caches nothing locally, so there is no local store to clear. When results look wrong, the cause is upstream sync timing, not a stale cache. The fix is the same as above: check `get_health`, then trigger a sync with an admin key if needed. ## Claude and MCP This is almost always configuration. Check these in order: * **`REWIND_API_KEY` is set.** The server reads your key from this environment variable; without it, every tool call fails authentication. A read key is sufficient, since the server is read-only. * **You restarted the client.** MCP configuration is read at startup. After editing the Claude Desktop JSON config, a `.mcp.json` file, or running `claude mcp add`, fully quit and reopen the client so it reloads the server definition. * **You are using the right transport.** Local clients run the server through `npx`; the hosted option connects to `https://mcp.rewind.rest/mcp`. Mixing the two in one entry will not connect. For the local stdio setup, see [Connect locally](/mcp/connect-local). For the hosted remote transport, see [Connect remotely](/mcp/connect-remote). A `403` from `https://mcp.rewind.rest/mcp` means your GitHub account authenticated successfully but is not on the access allowlist. The remote server maps each allowed GitHub user to a Rewind account, and any login outside that map is rejected after the consent step. Request access from the Rewind admin so your GitHub account can be added, then run the [GitHub consent flow](/mcp/connect-remote) again. A `401` here is different: it means there was no valid grant at all, so re-run the OAuth flow or re-check your Bearer token. Many tools return cover art, posters, and artist imagery as image content blocks, and list tools include the top few by default. If a response is larger than you want, or your client struggles to render the images, pass `include_images: false` to drop the image blocks and keep the text and structured data. See [Rich responses](/mcp/rich-responses) for the full content model. Some tools advertise [MCP Apps](https://blog.modelcontextprotocol.io/posts/2026-01-26-mcp-apps/) UI resources that render as inline cards, but whether you see one depends on your client. Clients that support MCP Apps draw the card; clients that do not still get the full response (text, images, resource links, and structured content), so nothing is lost. If you expected a card and got plain text plus images, your client does not support MCP Apps yet. See [Rich responses](/mcp/rich-responses) for which clients support them. Key handling depends on the connection mode: * **Local stdio.** Your `REWIND_API_KEY` stays on your machine in the client config. The server runs as a child process and talks to your client over stdin and stdout. * **Remote.** You authenticate through GitHub OAuth (or a Bearer token, for clients that take one), and the hosted Cloudflare Worker uses a server-side Rewind key on your behalf after your GitHub identity is matched to your account. In both modes the server has read-only access. No write or admin operations are exposed. ## Images and the CDN Each image type resolves through a source fallback chain: if the primary source has no art for an item, Rewind tries the next source before giving up. A blank or generic image usually means every source in the chain came up empty for that item, not that the CDN is down. Resize and format transforms are applied through query parameters on the `cdn.rewind.rest` URL. If a transform looks ignored, confirm you are hitting the CDN host and that the parameters are on the CDN URL, not the API URL. Image responses include a `thumbhash` alongside `dominant_color` and `accent_color`, meant to render as a blurred placeholder while the full image loads. A placeholder that never sharpens means the full-resolution fetch did not complete, so check the image URL. ## Error reference Every error response uses the same `{ "error", "status" }` envelope, where `status` matches the HTTP code. | Status | Meaning | Common cause | | ------ | ----------------- | ------------------------------------------------------------------------------------ | | `400` | Bad request | Malformed query parameter, invalid body, or unparseable input. | | `401` | Unauthorized | Missing or non-`Bearer rw_` header, unknown or revoked key, or expired key. | | `403` | Forbidden | Authenticated, but the key lacks the required scope (read key on an admin endpoint). | | `404` | Not found | The resource or route does not exist. | | `429` | Too Many Requests | Rate limit exceeded; honor the `Retry-After` header. | | `500` | Server error | Unexpected failure on the server. Retry, then report if it persists. | ## Still stuck If the self-diagnostics pass but the behavior is still wrong, open an issue at [github.com/pdugan20/rewind/issues](https://github.com/pdugan20/rewind/issues). Include the request URL, the response body, and the HTTP status code so the problem can be reproduced quickly.