Overview
The ReelRifter Public API gives third-party apps read access to your watchlist and watch history, plus a write endpoint for scrobbling watch events from browser extensions or self-hosted automations.
All requests are authenticated with a Personal Access Token you mint yourself. There's no OAuth flow and no client registration — generate a token, copy it once, and use it as a bearer header.
> Just want auto-scrobbling on Netflix / Disney+ / Prime Video / Max? You don't need to build anything. Install the official browser extension from /extension and paste a token — it does the rest.
Generating a Token
1. Go to Settings → Integrations → API Tokens. 2. Enter a label (e.g. Home Assistant, Netflix Scrobbler) and click Create. 3. Copy the raw token — it starts with rr_pat_. We only store the hash, so this is the only time it's shown. 4. Use it in the Authorization header on every request:
Authorization: Bearer rr_pat_xxxxxxxxxxxxxxxxxxxx
You can hold up to 20 active tokens. Revoke any token from the same screen — anything using it stops working immediately.
Base URL
https://reelrifter.com/api/public/v1
Endpoints
`GET /me`
Returns the identity of the token's owner. Useful for verifying a token works before doing anything else.
`GET /watchlist`
List items from your watchlist. Supports filters and cursor-based pagination.
Query parameters:
- •
status— one ofWANT_TO_WATCH,WATCHING,FINISHED,DROPPED,ON_HOLD - •
mediaType—TVorMOVIE - •
limit— 1-200 (default 50) - •
cursor—nextCursorvalue from a previous response
`GET /history`
Returns a unified timeline of finished watchlist items and individual watched episodes, sorted most-recent first. Supports limit (1-200).
`POST /scrobble`
Log a watch event. Identical to how Plex/Jellyfin webhooks update your watchlist — the server matches the title against TMDB, then advances your current episode (TV) or marks the title finished (movie).
Body fields:
- •
title(required) — show name or movie title - •
mediaType— optional, inferred from season/episode if omitted - •
season,episode— numbers; presence implies TV - •
year— disambiguates reboots - •
action—watched(default) orwatchingfor play-start events - •
source— free-form label for your own debugging
If TMDB can't match the title, the response is { "matched": false } with status 200 (rather than 4xx) so clients don't waste retries on titles that will never match.
Rate Limits
There are no published rate limits yet. Please be reasonable — under 60 requests per minute per token is the soft ceiling. We may add hard limits without notice if abuse appears.
Examples
curl
bash curl https://reelrifter.com/api/public/v1/watchlist?status=WATCHING \ -H "Authorization: Bearer rr_pat_xxxxxxxxxxxx"
Node / fetch
js const res = await fetch("https://reelrifter.com/api/public/v1/scrobble", { method: "POST", headers: { "Authorization": Bearer ${process.env.REELRIFTER_TOKEN}, "Content-Type": "application/json", }, body: JSON.stringify({ title: "Severance", season: 2, episode: 4 }), });
Security
- •Treat the raw token like a password — anyone with it can read your watchlist and write scrobble events.
- •Tokens are stored as SHA-256 hashes; we can't recover a lost token, only revoke + reissue.
- •Revoke tokens you no longer use. The token list shows last-used timestamps so you can spot unused ones.