TV Series

Fields marked * are required. Updates keep every field they are not given. An AI app can ask vritto_describe for the same details, filtered to what its connection may use.

TV Series`tv_series`

A series in the user's library, with progress and rating.

tv_series_queryTvSeriesPersonLinksFindthrough vritto_find

Read TV series linked to one Vritto People record: what they recommended, watch logs shared with them, and their favorite/dislike taste records.

Field	Type	Description
personId*	string	Vritto People record ID.
detail	one of summary, full	Row shape for linked records and watch logs: "summary" (default, compact) or "full" (every field incl. notes).
limit	integer	Maximum linked records per bucket (default 100).

tv_series_queryTvSeriesRecordsFindthrough vritto_find

Search the user's saved TV library by text and/or watch status (e.g. status "watching" for currently-watching questions). Use this to resolve mediaRecordId values before watch-log or record writes.

Field	Type	Description
query	string	Case-insensitive text matched against title, overview, genres, and tags.
status	one of want_to_watch, watching, watched, completed, dropped, on_hold	Filter by watch status.
detail	one of summary, full	Row shape: "summary" (default, id/title/status/rating/year) or "full" (every field incl. journal notes and overview).
limit	integer	Maximum records (default 50 in summary mode).
cursor	string	Pagination cursor from a previous nextCursor.

tv_series_queryTvSeriesStatsFindthrough vritto_find

Summarize the TV library: totals, watch-log counts by year and month, and rating distribution. Prefer this for how-much-TV-watched questions.

Field	Type	Description
year	string	Optional four-digit year filter for the by-year breakdown.

tv_series_upsertTvSeriesRecordCreate or Updatethrough vritto_create or vritto_update

Save a TV series to the library. Prefer passing providerId alone to import full TMDB metadata (existing status/rating/notes/tags are preserved); pass record only for manual or full-record writes, which replace stored fields.

Note: Pass providerId from vritto_lookup (tv_catalog) to save with full details. A record body replaces stored fields.

Field	Type	Description
providerId	string	TMDB TV series ID, pass this alone to import/save with TMDB metadata.
status	one of want_to_watch, watching, watched, completed, dropped, on_hold	Initial watch status for a provider-only quick-save (providerId without record); only applied when creating, an existing record's status wins. Ignored when record is passed.
mediaRecordId	string	Existing saved record ID to overwrite; defaults to a provider-derived ID.
record	object	Full TV series record body. The write replaces the stored record, so include every field to keep.
record.providerRef*	object	Provider reference identifying the series.
record.title*	string	Series title.
record.originalTitle	string
record.overview	string
record.firstAirDate	string	YYYY-MM-DD first air date; also a default watch-date fallback.
record.runtimeMinutes	number	Typical episode runtime.
record.genres	list of string
record.numberOfSeasons	integer
record.numberOfEpisodes	integer
record.currentSeason	integer	Season the user is currently on.
record.currentEpisode	integer	Episode the user is currently on.
record.status	one of want_to_watch, watching, watched, completed, dropped, on_hold	Watch status; defaults to "watching". Use "completed" for finished series and "watching" for in-progress ones.
record.rating	one of dislike, okay, like, love	Rating on Vritto's four-point scale.
record.journalNotes	string	Owner journal notes.
record.recommendedByPersonIds	list of string	Vritto People record IDs who recommended this series.
record.tags	list of string	List names/tags.

Example input

{
  "providerId": "95396",
  "status": "watching"
}

tv_series_deleteTvSeriesRecordDeletethrough vritto_delete

Remove one saved TV series plus all of its watch logs and recommendations. Only for explicit removals.

Field	Type	Description
mediaRecordId*	string	Saved TV series record ID to delete.

TV Watch Log`tv_watch_log`

A watched season or episode range.

tv_series_queryTvSeriesWatchLogsFindthrough vritto_find

List TV watch logs (title, date, season/episode range, platform, rating), newest first. Supports a watched-date range, ALWAYS pass from/to when the question concerns a period (a year, a month, 'recently'). Rows are compact summaries; pass detail 'full' only when the user needs full log notes.

Field	Type	Description
mediaRecordId	string	Limit logs to one saved TV series record.
from	string	Only logs watched ON or AFTER this YYYY-MM-DD date.
to	string	Only logs watched ON or BEFORE this YYYY-MM-DD date.
detail	one of summary, full	Row shape: "summary" (default, title/date/platform/rating + notes preview) or "full" (every field incl. complete notes).
limit	integer	Maximum logs (default 100 in summary mode).
cursor	string	Pagination cursor from a previous nextCursor.

tv_series_addTvSeriesWatchLogCreatethrough vritto_create

Log a watched season/episode range for a saved series; the record's status moves to watching (completed records stay completed). Omit watchedOn to accept the air-date default.

Field	Type	Description
watchLogId	string	Explicit watch log ID; reusing the same ID makes retries idempotent. Defaults to a random ID.
log*	object	Watch log fields. TV logs cover season/episode ranges, not individual episodes.
log.mediaRecordId*	string	Saved TV series record ID; resolve it with tv_series_queryTvSeriesRecords first.
log.watchedOn	string	YYYY-MM-DD watch date. Omit to default to episodeAirDate (when given) or the series first air date, marked as defaulted so the user can edit it later.
log.episodeAirDate	string	YYYY-MM-DD air date of the watched episode; used as the default watch date when watchedOn is omitted.
log.seasonFrom	integer	Starting season of the watched range.
log.episodeFrom	integer	Starting episode of the watched range.
log.seasonTo	integer	Ending season of the watched range; must not be before seasonFrom.
log.episodeTo	integer	Ending episode of the watched range.
log.platform	string	Where it was watched, e.g. Netflix or Hulu.
log.platformType	one of theater, streaming, television, other	Platform type; defaults to "theater".
log.platformService	string	Streaming service name when platformType is streaming.
log.platformCountry	one of US, IN	Country whose catalog the platform was watched in; omit when unknown.
log.placeKey	string	Places key where it was watched: google:<placeId> or manual:<uuid>, from the Places module.
log.locationLabel	string	Free-text location label.
log.watchedWithPersonIds	list of string	Vritto People record IDs the user watched with; must reference active People records.
log.notes	string	Journal notes for this watch.
log.rating	one of dislike, okay, like, love	Rating on Vritto's four-point scale.

Example input

{
  "log": {
    "mediaRecordId": "tv_severance",
    "watchedOn": "2026-09-25",
    "seasonFrom": 2,
    "episodeFrom": 1,
    "seasonTo": 2,
    "episodeTo": 3,
    "platformType": "streaming"
  }
}

tv_series_updateTvSeriesWatchLogUpdatethrough vritto_update

Rewrite an existing TV watch log. The log body replaces the stored fields, so include mediaRecordId and every field to keep.

Note: The log body replaces the stored fields; read the log first and send every field to keep.

Field	Type	Description
watchLogId*	string	Existing watch log ID.
log*	object	Watch log fields. TV logs cover season/episode ranges, not individual episodes.
log.mediaRecordId*	string	Saved TV series record ID; resolve it with tv_series_queryTvSeriesRecords first.
log.watchedOn	string	YYYY-MM-DD watch date. Omit to default to episodeAirDate (when given) or the series first air date, marked as defaulted so the user can edit it later.
log.episodeAirDate	string	YYYY-MM-DD air date of the watched episode; used as the default watch date when watchedOn is omitted.
log.seasonFrom	integer	Starting season of the watched range.
log.episodeFrom	integer	Starting episode of the watched range.
log.seasonTo	integer	Ending season of the watched range; must not be before seasonFrom.
log.episodeTo	integer	Ending episode of the watched range.
log.platform	string	Where it was watched, e.g. Netflix or Hulu.
log.platformType	one of theater, streaming, television, other	Platform type; defaults to "theater".
log.platformService	string	Streaming service name when platformType is streaming.
log.platformCountry	one of US, IN	Country whose catalog the platform was watched in; omit when unknown.
log.placeKey	string	Places key where it was watched: google:<placeId> or manual:<uuid>, from the Places module.
log.locationLabel	string	Free-text location label.
log.watchedWithPersonIds	list of string	Vritto People record IDs the user watched with; must reference active People records.
log.notes	string	Journal notes for this watch.
log.rating	one of dislike, okay, like, love	Rating on Vritto's four-point scale.

tv_series_deleteTvSeriesWatchLogDeletethrough vritto_delete

Delete one TV watch log and refresh the record's watch count and last-watched date. Only for explicit removals.

Field	Type	Description
watchLogId*	string	Watch log ID to delete.

TV Recommendation`tv_recommendation`

A person's recommendation of a saved series.

tv_series_upsertTvSeriesRecommendationCreate or Updatethrough vritto_create or vritto_update

Record that a Vritto person recommended a saved TV series, and track the recommendation's status. Also links the person on the series record.

Field	Type	Description
recommendationId	string	Existing recommendation ID; defaults to a series+person derived ID.
recommendation*	object
recommendation.mediaRecordId*	string	Saved TV series record ID.
recommendation.personId*	string	Vritto People record ID of the recommender.
recommendation.status	one of open, accepted, dismissed, watched	Recommendation status; defaults to "open".
recommendation.note	string	Why they recommended it.

Person's TV Taste`tv_taste`

A person's favorite or disliked series.

tv_series_upsertTvSeriesPersonTasteCreate or Updatethrough vritto_create or vritto_update

Record a Vritto person's favorite/dislike taste for a TV series identified by provider reference (the series does not need to be saved).

Field	Type	Description
personTasteId	string	Existing taste record ID; defaults to a person+series derived ID.
personTaste*	object
personTaste.personId*	string	Vritto People record ID.
personTaste.providerRef*	object	Provider reference identifying the series.
personTaste.taste*	one of favorite, dislike	Whether the person loves or avoids it.
personTaste.note	string

TV Catalog`tv_catalog`

TMDB reference data for series and seasons.

tv_series_discoverTvSeriesLook Upthrough vritto_lookup

Browse TMDB TV discovery lists (popular, airing today, on the air, top rated) when the user wants suggestions rather than a title search.

Field	Type	Description
category	one of popular, airing_today, on_the_air, top_rated	Discovery list; defaults to "popular".
page	integer	TMDB result page, starting at 1.

tv_series_getTvSeriesDetailsLook Upthrough vritto_lookup

Fetch full TMDB details (overview, seasons, episodes, genres, cast/crew) for one TV series by TMDB ID.

Field	Type	Description
providerId*	string	TMDB TV series ID (numeric string).

tv_series_getTvSeriesSeasonDetailsLook Upthrough vritto_lookup

Fetch TMDB details for one season of a TV series: episode list with names, numbers, and air dates. Use this to resolve an episodeAirDate before logging a watch.

Field	Type	Description
providerId*	string	TMDB TV series ID (numeric string).
seasonNumber*	integer	Season number (0 is usually specials).

tv_series_searchTvSeriesLook Upthrough vritto_lookup

Search TMDB for TV series by title; an empty query returns popular series. Returns provider metadata, not the user's saved library: use tv_series_queryTvSeriesRecords for saved series.

Field	Type	Description
query	string	Search text. Omit to return popular series.
page	integer	TMDB result page, starting at 1.

TV Series

TV Seriestv_series

TV Watch Logtv_watch_log

TV Recommendationtv_recommendation

Person's TV Tastetv_taste

TV Catalogtv_catalog

TV Series`tv_series`

TV Watch Log`tv_watch_log`

TV Recommendation`tv_recommendation`

Person's TV Taste`tv_taste`

TV Catalog`tv_catalog`