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. The same operations reach its watch logs, each a date and a season and episode range (type 'watch_log'), and a person's recommendations and favorite or disliked series (type 'recommendation' and 'taste').

tv_series_findFindthrough vritto_find

Read TV Series: the library (query, status 'watching'), episodes watched in a period (type 'watch_log' with from/to), counts (view 'stats'), one person's links (personId), or one record by id.

Note: type 'watch_log' with from/to reads episodes watched in a period; view 'stats' counts them by year and month; personId reads one person's recommendations, shared watches and tastes. Record rows carry nextEpisode, the next one to watch.

Field	Type	Description
type	one of record, watch_log	Default 'record' (shows).
id	string	Just this record of the type.
view	one of list, stats	'stats': watches and episodes by year and month, and ratings.
query	string	Matches a saved show's title, overview, genres and tags.
status	one of want_to_watch, watching, watched, completed, dropped, on_hold
from	string	Watched on or after.
to	string	Watched on or before. ALWAYS pass from/to when the question concerns a period.
year	string	With view 'stats'.
mediaRecordId	string	One show's watch logs.
personId	string	A People ID: what they recommended, watched with the user, love or avoid.
detail	one of summary, full
limit	integer
cursor	string

Example input

{
  "status": "watching"
}

tv_series_addCreate or Updatethrough vritto_create or vritto_update

Add to TV Series: a show by TMDB providerId (or a record), watched episodes of a saved show (type 'watch_log': one run, or many with segments), or a person's recommendation or taste. An id there updates that record.

Note: Pass providerId from vritto_lookup (tv_catalog) to save with full details. type 'watch_log' logs episodes; for many at once send segments (runs of episodes, each with when it was watched) and the server reads air dates itself.

Field	Type	Description
type	one of record, watch_log, recommendation, taste	'record' (default) a show; 'watch_log' a sitting; 'recommendation'; 'taste' a person's favorite or disliked show.
providerId	string	A show's TMDB ID: saves it with full details.
status	one of want_to_watch, watching, watched, completed, dropped, on_hold	With providerId, for a new show.
mediaRecordId	string	A saved show to overwrite with record.
record	object	A whole show; it replaces what is stored.
record.providerRef*	object
record.title*	string
record.originalTitle	string
record.overview	string
record.firstAirDate	string
record.runtimeMinutes	number
record.genres	list of string
record.numberOfSeasons	integer
record.numberOfEpisodes	integer
record.currentSeason	integer
record.currentEpisode	integer
record.status	one of want_to_watch, watching, watched, completed, dropped, on_hold	Default watching; completed when finished.
record.rating	one of dislike, okay, like, love
record.journalNotes	string
record.recommendedByPersonIds	list of string	People who recommended it.
record.tags	list of string
watchLogId	string
log	object	With segments, only mediaRecordId (and a platform).
log.mediaRecordId*	string	The saved show's ID, from tv_series_find.
log.watchedOn	string	Omit for episodeAirDate or the first air date, marked as a default.
log.episodeAirDate	string
log.seasonFrom	integer
log.episodeFrom	integer
log.seasonTo	integer
log.episodeTo	integer
log.platform	string	Where, e.g. Netflix.
log.platformType	one of theater, streaming, television, other
log.platformService	string
log.platformCountry	one of US, IN
log.placeKey	string
log.locationLabel	string
log.watchedWithPersonIds	list of string	People the user watched with.
log.notes	string
log.rating	one of dislike, okay, like, love
segments	list of object	Many episodes at once: runs, each with when it was watched.
batchId	string	With segments: reuse to retry or re-date a batch.
recommendationId	string
recommendation	object
recommendation.mediaRecordId*	string
recommendation.personId*	string	The recommender's People ID.
recommendation.status	one of open, accepted, dismissed, watched
recommendation.note	string
personTasteId	string
personTaste	object
personTaste.personId*	string
personTaste.providerRef*	object
personTaste.taste*	one of favorite, dislike
personTaste.note	string

Example input

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

tv_series_changeUpdatethrough vritto_update

Change one TV Series record by id; sent fields merge. A show's status, rating (the user's own) or notes; a watch log's date, episodes or details.

Note: Sent fields merge into the stored record. A rating set on the show is the user's own. Progress follows the logs: log episodes rather than setting currentEpisode.

Field	Type	Description
type	one of record, watch_log	Default 'record' (a show).
id	string
record	object	A show's fields to change; the rest stay.
record.status	one of want_to_watch, watching, watched, completed, dropped, on_hold
record.rating	one of	The user's own rating; null clears it.
record.journalNotes	string
record.tags	list of string
record.recommendedByPersonIds	list of string
record.title	string
log	object	A watch log's fields to change.
log.mediaRecordId	string	The saved show's ID, from tv_series_find.
log.watchedOn	string	Omit for episodeAirDate or the first air date, marked as a default.
log.episodeAirDate	string
log.seasonFrom	integer
log.episodeFrom	integer
log.seasonTo	integer
log.episodeTo	integer
log.platform	string	Where, e.g. Netflix.
log.platformType	one of theater, streaming, television, other
log.platformService	string
log.platformCountry	one of US, IN
log.placeKey	string
log.locationLabel	string
log.watchedWithPersonIds	list of string	People the user watched with.
log.notes	string
log.rating	one of dislike, okay, like, love
watchLogId	string	Older name for id.

Example input

{
  "id": "tv_severance",
  "record": {
    "rating": "love"
  }
}

tv_series_removeDeletethrough vritto_delete

Remove one show with its watch logs, one watch log, or every log of one batch (batchId). Only for explicit removals.

Note: type 'watch_log' removes one log; batchId removes every log one multi-episode log wrote.

Field	Type	Description
type	one of record, watch_log	Default 'record' (a show).
id	string
batchId	string	Every log of one batch.
mediaRecordId	string	Older name for id.
watchLogId	string	Older name for id.

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_find 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 Catalogtv_catalog

TV Series`tv_series`

TV Catalog`tv_catalog`