# TrailerTube agent API v1

Public, read-only static JSON. No key is required. Start with [manifest.json](/api/v1/manifest.json).

## Search

Fetch the manifest, then its search.shards; each shard contains movies as arrays matching columns: [TMDB ID as a string, movie title, movie release date]. Filter titles case-insensitively in your client. These files index ordinary movies with a trailer not known to be unavailable; results may be incomplete. Do not send a search query parameter: this is static hosting.

## Details

For a numeric TMDB ID, calculate bucket = ID modulo details.shards and left-pad it to four digits. Fetch /data/catalog-{bucket}.json and /data/state-{bucket}.json, find the matching string id in both arrays, and merge them. The catalog entry includes movie metadata; the state entry contains trailer, duration, views, playable and regionRestriction. A missing state or trailer means no verified trailer is listed.

Construct a movie page as https://trailer.terryso.dev/watch/{id}, or a YouTube watch link as https://www.youtube.com/watch?v={trailer}. The YouTube video may be unavailable to some viewers despite the recorded playable status. Do not treat views as live: they are periodically refreshed.

## Snapshot consistency

Check generatedAt on the manifest and every search shard. Movie/state shards belong to the current /data/catalog.json snapshot; check its generatedAt matches the API manifest before and after reading. Retry if versions change during a deploy. The coverage.complete and coverage.auditGaps fields describe known collection limitations.

Genres and playlist metadata are available at /api/v1/genres.json and /api/v1/playlists.json. Movie release dates refer to the movie, not the trailer. Adult data is omitted from the agent search index.
