Letterboxd target

Letterboxd is a movie-only target. Shows are filtered before mapping and do not appear as unmatched. It supports watchlist, half-star ratings, Watched state, append-only dated diary history, and ordered custom lists.

Authorization and HTTP policy

Letterboxd currently supports only hosted OAuth through https://auth.brokerr.net with content:modify and oauth:refresh scopes. After connection, Brokerr loads the member LID, username, avatar, and profile URL.

The access token is refreshed automatically through a rotating opaque gateway refresh handle. The default handle lifetime is 90 days; reconnect when the handle expires or is revoked.

The default target policy is one request per second, three attempts, and a one-second initial backoff. Diary POST is not blindly retried after a timeout. The tester exposes Test connection and Search films.

Mapping

Mapping order is:

1. manual profile override or direct Letterboxd LID;
2. TMDB ID;
3. IMDb ID.

Automatic title guessing is deliberately disabled. An item without a trusted identifier remains unmatched. Film snapshots are read in batches of up to 100 IDs.

Watchlist

Source choices are Native Plex watchlist, All unwatched library items, or both.

• Protect target watchlist keeps target-only entries instead of removing them.
• Do not re-add previously watched films applies to the derived All unwatched portion. If Plex history or Letterboxd Watched/diary proves an earlier viewing, Brokerr preserves current target membership rather than re-adding the film. Explicit Plex watchlist membership remains authoritative.
• Remove watched films from watchlist removes a completed Plex film after Watched, diary, and rating writes, even when protection would otherwise keep it.

Letterboxd rating or diary mutations can affect Watched/watchlist state. The runtime therefore performs Watched/diary first, rating second, and final watchlist reconciliation last.

Ratings

Letterboxd uses 0.5–5 in half-star steps with exact Decimal conversion and ROUND_HALF_UP. Removing a Plex rating removes the Letterboxd rating by default. Writing a rating may mark a film Watched.

• Only fill missing ratings writes only if Letterboxd has no rating.
• Keep target when source is empty preserves a remote rating when Plex is empty.

Revert restores the exact previous rating and then reconciles watchlist state.

Watched status

The disabled-by-default Watched status feature marks completed or historically viewed Plex films Watched without creating a dated diary row. It never marks a film Unwatched. If Diary history is also enabled, diary owns the Watched side effect so only one provider mutation is sent.

Diary history

The disabled-by-default Diary history feature appends exact Plex playback dates and implies Watched. It can make the first full run much longer.

Rules:

• only movies with exact completed playback dates create diary rows;
• multiple plays of one movie on one local calendar day collapse into one row;
• timestamps use the global Brokerr timezone;
• the chronological first known viewing has rewatch=false, later viewings use rewatch=true;
• existing same-film/same-day Letterboxd rows are treated as satisfied;
• normal sync never edits or deletes remote diary rows;
• if Plex proves Watched but has no exact date, Brokerr marks Watched only;
• missing dates are never invented to fill a higher viewCount.

Plex can expose the same timestamp after a user manually marks a film Watched. It cannot always prove that the film was actually played, so weak timestamps may create false diary entries. The UI displays this warning.

Bulk Watched detection

Bulk detection is enabled by default. With the default Films allowed in the time window = 3 and Bulk detection window = 15 minutes, four or more different films receiving weak Watched timestamps on one local day are treated as a bulk manual marking. Brokerr marks them Watched but suppresses their diary dates.

Real Plex playback sessions are not suppressed. Run cards receive a Bulk Watched detected badge; source diagnostics show count/window and details list suppressed dates and event IDs outside the target mutation payload.

Plex recorded history

Enable the Plex source feature Synchronize recorded history to merge exact playback activity retained by the connected Plex account. Enable Sync watched media missing from libraries to include account titles absent from the selected server libraries. See Plex recorded history.

Idempotence and Revert

Before POST, Letterboxd is checked again for the film/date. After an ambiguous response, a bounded reconciliation read decides whether the own entry was created, a pre-existing entry satisfied it, or the result remains ambiguous.

Brokerr stores the returned log-entry ID. Revert deletes only an entry proven to have been created by that operation. It never deletes a pre-existing or ambiguously owned diary entry. Diary entries are reverted before restoring Watched/rating, and watchlist is restored last.

Custom lists

Letterboxd supports Exact mirror, Mirror membership, and Add only, including independent order updates. Brokerr stores the stable list LID for provider I/O and the member/list slug URL returned by Letterboxd for browser links.

New lists are private and unranked. Sync changes title, membership, and order as configured but preserves descriptions, tags, comments, item notes, and later manual privacy metadata.