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.

movies_queryMoviePersonLinksFindthrough vritto_find

Read movies 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).

movies_queryMovieRecordsFindthrough vritto_find

Search the user's saved movie library by text and/or watch status. 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.

movies_queryMovieStatsFindthrough vritto_find

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

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

movies_upsertMovieRecordCreate or Updatethrough vritto_create or vritto_update

Save a movie 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 (movie_catalog) to save with full details. A record body replaces stored fields.

Field	Type	Description
providerId	string	TMDB movie 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 movie record body. The write replaces the stored record, so include every field to keep.
record.providerRef*	object	Provider reference identifying the movie.
record.title*	string	Movie title.
record.originalTitle	string
record.overview	string
record.releaseDate	string	YYYY-MM-DD theatrical release date; also the default first-watch date.
record.runtimeMinutes	number
record.genres	list of string
record.status	one of want_to_watch, watching, watched, completed, dropped, on_hold	Watch status; defaults to "want_to_watch".
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 movie.
record.tags	list of string	List names/tags.

Example input

{
  "providerId": "693134",
  "status": "want_to_watch"
}

movies_deleteMovieRecordDeletethrough vritto_delete

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

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

Movie Watch Log`movie_watch_log`

One viewing of a saved movie.

movies_queryMovieWatchLogsFindthrough vritto_find

List movie watch logs (title, date, 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 movie 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.

movies_addMovieWatchLogCreatethrough vritto_create

Log a watch of a saved movie and mark the record watched. Use this to mark movies as watched after resolving the mediaRecordId; omit watchedOn when the release-date default is acceptable.

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.
log.mediaRecordId*	string	Saved movie record ID; resolve it with movies_queryMovieRecords first.
log.watchedOn	string	YYYY-MM-DD watch date. Omit to default to the TMDB release date, marked as defaulted so the user can edit it later.
log.platform	string	Where it was watched, e.g. Netflix or AMC.
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": "movie_dune2",
    "watchedOn": "2026-09-25",
    "platformType": "theater",
    "rating": "love"
  }
}

movies_updateMovieWatchLogUpdatethrough vritto_update

Rewrite an existing movie 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.
log.mediaRecordId*	string	Saved movie record ID; resolve it with movies_queryMovieRecords first.
log.watchedOn	string	YYYY-MM-DD watch date. Omit to default to the TMDB release date, marked as defaulted so the user can edit it later.
log.platform	string	Where it was watched, e.g. Netflix or AMC.
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.

movies_deleteMovieWatchLogDeletethrough vritto_delete

Delete one movie 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.

Movie Recommendation`movie_recommendation`

A person's recommendation of a saved movie.

movies_upsertMovieRecommendationCreate or Updatethrough vritto_create or vritto_update

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

Field	Type	Description
recommendationId	string	Existing recommendation ID; defaults to a movie+person derived ID.
recommendation*	object
recommendation.mediaRecordId*	string	Saved movie 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 Movie Taste`movie_taste`

A person's favorite or disliked movie.

movies_upsertMoviePersonTasteCreate or Updatethrough vritto_create or vritto_update

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

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

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_queryMovieRecords 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 Watch Logmovie_watch_log

Movie Recommendationmovie_recommendation

Person's Movie Tastemovie_taste

Movie Catalogmovie_catalog

Movie`movie`

Movie Watch Log`movie_watch_log`

Movie Recommendation`movie_recommendation`

Person's Movie Taste`movie_taste`

Movie Catalog`movie_catalog`