Movies

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.

Movie`movie`

A movie in the user's library, with status and rating. The same operations reach its watch logs (type 'watch_log'), booked cinema showings (type 'showing', which become a watch after the show), and a person's recommendations and favorite or disliked movies (type 'recommendation' and 'taste').

movies_findFindthrough vritto_find

Read Movies: the library (query, status), watches in a period (type 'watch_log' with from/to), counts (view 'stats'), booked showings (type 'showing'), one person's links (personId), or one record by id.

Note: type 'watch_log' with from/to reads watches in a period; view 'stats' counts them by year and month; type 'showing' reads booked showings; personId reads one person's recommendations, shared watches and tastes.

Field	Type	Description
type	one of record, watch_log, showing	Default 'record' (films).
id	string	Just this record of the type.
view	one of list, stats	'stats': watches by year and month, and ratings.
query	string	Matches a saved film'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 film's watch logs or showings.
personId	string	A People ID: what they recommended, watched with the user, love or avoid.
scope	one of upcoming, to_rate, all	Showings to list.
detail	one of summary, full
limit	integer
cursor	string

Example input

{
  "status": "want_to_watch"
}

movies_addCreate or Updatethrough vritto_create or vritto_update

Add to Movies: a film by TMDB providerId (or a record), a watch of a saved film (type 'watch_log'), a booked showing (type 'showing'), or a person's recommendation or taste. An id there updates that record.

Note: Pass providerId from vritto_lookup (movie_catalog) to save with full details. type 'watch_log' logs a watch of a saved movie; type 'showing' books a cinema ticket, never a watch.

Field	Type	Description
type	one of record, watch_log, showing, recommendation, taste	'record' (default) a film; 'watch_log' a viewing; 'showing' a booked ticket, never a watch; 'recommendation'; 'taste' a person's favorite or disliked film.
providerId	string	A film'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 film.
mediaRecordId	string	A saved film to overwrite with record.
record	object	A whole film; it replaces what is stored.
record.providerRef*	object
record.title*	string
record.originalTitle	string
record.overview	string
record.releaseDate	string
record.runtimeMinutes	number
record.genres	list of string
record.status	one of want_to_watch, watching, watched, completed, dropped, on_hold	Default want_to_watch.
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
log.mediaRecordId*	string	The saved film's ID, from movies_find.
log.watchedOn	string	Omit for the release date, marked as a default.
log.platform	string	Where, e.g. Netflix or AMC.
log.platformType	one of theater, streaming, television, other	Default theater.
log.platformService	string
log.platformCountry	one of US, IN
log.placeKey	string	Places key of where it was watched.
log.locationLabel	string
log.watchedWithPersonIds	list of string	People the user watched with.
log.watchedWithNames	list of string	Companions not in People.
log.notes	string
log.rating	one of dislike, okay, like, love
showingId	string
showing	object
showing.mediaRecordId	string	The saved film (required to book).
showing.localDate	string
showing.localTime	string	HH:mm at the cinema.
showing.timeZone	string
showing.cinemaName	string
showing.cinemaAddress	string
showing.placeKey	string
showing.seats	list of string
showing.ticketCount	integer
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": "693134",
  "status": "want_to_watch"
}

movies_changeUpdatethrough vritto_update

Change one Movies record by id; sent fields merge. A film's status, rating (the user's own) or notes; a watch log's details; a showing's time, or its response to "How was it?".

Note: Sent fields merge into the stored record. A rating set on the movie is the user's own and wins over any watch's.

Field	Type	Description
type	one of record, watch_log, showing	Default 'record' (a film).
id	string
record	object	A film'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 film's ID, from movies_find.
log.watchedOn	string	Omit for the release date, marked as a default.
log.platform	string	Where, e.g. Netflix or AMC.
log.platformType	one of theater, streaming, television, other	Default theater.
log.platformService	string
log.platformCountry	one of US, IN
log.placeKey	string	Places key of where it was watched.
log.locationLabel	string
log.watchedWithPersonIds	list of string	People the user watched with.
log.watchedWithNames	list of string	Companions not in People.
log.notes	string
log.rating	one of dislike, okay, like, love
showing	object	A showing's new date, time or seats.
showing.mediaRecordId	string	The saved film (required to book).
showing.localDate	string
showing.localTime	string	HH:mm at the cinema.
showing.timeZone	string
showing.cinemaName	string
showing.cinemaAddress	string
showing.placeKey	string
showing.seats	list of string
showing.ticketCount	integer
response	one of rate, didnt_go, went, dismiss	The answer to "How was it?": rate, didnt_go (drops the watch, keeps the order), went (undoes didnt_go), dismiss.
rating	one of	With response 'rate'.
withPersonIds	list of string	With response 'rate': who came.
withNames	list of string	With response 'rate'.
watchLogId	string	Older name for id.
showingId	string	Older name for id.

Example input

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

movies_removeDeletethrough vritto_delete

Remove one film with its watch logs, one watch log, or one booked showing. Only for explicit removals.

Note: type 'watch_log' or 'showing' removes those instead; "I didn't go" is a movies_change of the showing.

Field	Type	Description
type	one of record, watch_log, showing	Default 'record' (a film).
id	string
mediaRecordId	string	Older name for id.
watchLogId	string	Older name for id.
showingId	string	Older name for id.

Movie Catalog`movie_catalog`

TMDB reference data, for saving a movie with full details.

movies_discoverMoviesLook Upthrough vritto_lookup

Browse TMDB movie discovery lists (popular, now playing, upcoming, top rated) when the user wants suggestions rather than a title search.

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

movies_getMovieDetailsLook Upthrough vritto_lookup

Fetch full TMDB details (overview, runtime, genres, cast/crew) for one movie by TMDB ID.

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

movies_searchMoviesLook Upthrough vritto_lookup

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

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

Movies

Moviemovie

Movie Catalogmovie_catalog

Movie`movie`

Movie Catalog`movie_catalog`