GoodWatch

Your share lists from Lists, including unlisted lists, newest updated first. Each list has exactly five ranked titles and the share link produced by the site.

get_my_lists

Only your shows: Continue, Pick up, Waiting for episodes, Want to See, On hold and Dropped.

get_my_shows

Your real taste signal and strongest attributes; explains when there is not enough evidence.

get_taste

Your current pass, next episode and paged watches. Dates are unknown unless recorded.

get_show_progress

Log one movie or episode watch, an inclusive episode range (season, episode, episode_end), or a whole season (season, whole_season=true). Ranges use the catalog tracking season/episode numbers, mark only aired regular episodes missing in the current pass, never duplicate existing watches, and produce one receipt. Dates remain unknown unless explicitly supplied. Results report every added watch. Batch items are movies, episode ranges or whole seasons; whole-show status transitions are not supported by this tool. To change many titles at once, pass items instead of one title: up to 50 per call. Items are written independently and each reports done, already_set, not_found, ambiguous (with candidates; nothing written) or error, with a summary count and a batch_id; batch_id identifies the complete reversible batch. Full history (hundreds of titles or more) file import is available at: https://goodwatch.app/settings/imports For title actions, title_id takes precedence; title_name and year are ignored when an ID is supplied. Without title_id, title_name is required and year is optional. Replayed results describe the original action, not current state; a new read returns current state.

log_watch

Find more like a movie or show from GoodWatch’s own title-page fingerprint neighbors (up to 80 candidates), with each result’s GoodWatch taste match and posters. Ordered For you by default; for_you=false keeps similarity order. Similarity describes the source title, never your taste match. Searches everywhere and includes seen titles by default; exclude_seen=true applies Not seen yet before paging. Not interested and Dropped are always hidden. kind filters all/movie/show. Keep title and filters unchanged when paging. No paid descriptive search is used.

get_similar_titles

Set a score from 1 to 10, or clear it with null. Clearing a score is destructive. A movie rating can own one undated watch; show ratings never log episodes or change show status. For a show, season (and episode) score that aired season or episode instead of the whole show: kept apart from the show's score, they never change its score, taste or recommendations. Scoring an episode with no watch in any pass also logs one undated watch of it, which moves the show's status as logging it would; clearing that score removes that watch. A season score logs nothing. The result reports the previous score and exact watch changes. To change many titles at once, pass items instead of one title: up to 50 per call. Items are written independently and each reports done, already_set, not_found, ambiguous (with candidates; nothing written) or error, with a summary count and a batch_id; batch_id identifies the complete reversible batch. Full history (hundreds of titles or more) file import is available at: https://goodwatch.app/settings/imports For title actions, title_id takes precedence; title_name and year are ignored when an ID is supplied. Without title_id, title_name is required and year is optional. Replayed results describe the original action, not current state; a new read returns current state.

rate_title

Remove one watch record. Choose a watch_id, or omit it for the most recently logged individual watch of this title. Destructive: results identify the exact removed watch, date, pass and resulting marks; retrying the same action never removes a different watch. Or pass only batch_id (from a batch result) to take back the changes that batch call made, title by title, through the same undo the site uses, except a cleared season or episode score, or a write that wasn't confirmed, which it reports as not_undoable; a title changed again since keeps its newer value, and each title reports undone, partly_undone, already_undone, changed_since, not_undoable or error. A batch is undone once: undoing it again returns the first undo's result. For title actions, title_id takes precedence; title_name and year are ignored when an ID is supplied. Without title_id, title_name is required and year is optional. Replayed results describe the original action, not current state; a new read returns current state.

undo_watch

Search cast and crew by name. Returns canonical person_id values and GoodWatch person links.

search_people

Search movie and show names across the GoodWatch catalog, separate from your library. Name lookup by default; for descriptive queries, explicitly set ranked=true for an optional smarter match, ordered For you by default. Defaults to everywhere and includes seen titles. get_discover_filters describes every filter group, scales, presets, names and example calls. similar_to filters similar titles; more_like/less_like add temporary taste hints; people filters cast/crew; production_countries selects origins, streaming_country selects viewing availability, and rating_country selects age ratings independently. Use the shared Discover filters to narrow by type, genres, years, runtime, score, services, moods and more; filters accept catalog genre and provider IDs. Tag groups match any pick by default; match_all requires all picks in the named groups. Repeat filters with offset cursors; ranked cursors inherit their view. Except when paging with a ranked cursor, a missing, empty or whitespace-only query runs the native Discover path, filters and For you default; ranked is ignored and no smarter-match attempt is charged. exclude_seen=true returns only unseen results, filtered before pagination. Returns up to 40 results by default; limit bounds the page size. Different works can share a name and year: use runtime_minutes to distinguish them. Smarter matches allow 20 uncached attempts per member per UTC day, one in flight, normalized queries cached for 60 seconds and paging is free.

search_titles

Set or clear Not interested for an unseen, unrated title. Setting it removes an existing Wishlist entry and is destructive. Reports both marks before and after. To change many titles at once, pass items instead of one title: up to 50 per call. Items are written independently and each reports done, already_set, not_found, ambiguous (with candidates; nothing written) or error, with a summary count and a batch_id; batch_id identifies the complete reversible batch. Full history (hundreds of titles or more) file import is available at: https://goodwatch.app/settings/imports For title actions, title_id takes precedence; title_name and year are ignored when an ID is supplied. Without title_id, title_name is required and year is optional. Replayed results describe the original action, not current state; a new read returns current state.

set_not_interested

Add or remove a title from your Wishlist. Removal is destructive. Adding a Seen title means Want to rewatch and preserves watches. Reports previous membership and added-at time. To change many titles at once, pass items instead of one title: up to 50 per call. Items are written independently and each reports done, already_set, not_found, ambiguous (with candidates; nothing written) or error, with a summary count and a batch_id; batch_id identifies the complete reversible batch. Full history (hundreds of titles or more) file import is available at: https://goodwatch.app/settings/imports For title actions, title_id takes precedence; title_name and year are ignored when an ID is supplied. Without title_id, title_name is required and year is optional. Replayed results describe the original action, not current state; a new read returns current state.

set_want_to_see

Replace your saved country and streaming services. Country changes and removed services are destructive. Services accept exact names or numeric TMDB IDs; unknown/ambiguous names return choices without writing. Reports the full previous/new country and service IDs. For title actions, title_id takes precedence; title_name and year are ignored when an ID is supplied. Without title_id, title_name is required and year is optional. Replayed results describe the original action, not current state; a new read returns current state.

set_my_services

Apply a native show-status transition. Dropped and bulk Seen are destructive. Seen logs aired episodes with no dates. Watching from Seen starts a new pass while retaining earlier watches. Not started never erases watches. Reports previous/new status, pass and watch changes. To change many titles at once, pass items instead of one title: up to 50 per call. Items are written independently and each reports done, already_set, not_found, ambiguous (with candidates; nothing written) or error, with a summary count and a batch_id; batch_id identifies the complete reversible batch. Full history (hundreds of titles or more) file import is available at: https://goodwatch.app/settings/imports For title actions, title_id takes precedence; title_name and year are ignored when an ID is supplied. Without title_id, title_name is required and year is optional. Replayed results describe the original action, not current state; a new read returns current state.

set_show_status

Choose one thing to watch next, using your saved country and services: a next episode from a show you are watching, otherwise a Wishlist movie or show to start (or a suggestion if the Wishlist is empty). Returns one recommendation rather than the complete Wishlist.

get_tonight