trakt-tv_skill

Overview

This skill connects to the Trakt API to manage watchlists, collections, viewing history, ratings, and content discovery. It provides curl examples and guidance for authenticated and unauthenticated endpoints so you can script or automate Trakt actions. It expects Trakt API credentials and an OAuth access token configured in your environment.

How this skill works

The skill issues HTTP requests to Trakt endpoints using curl with required headers (trakt-api-version, trakt-api-key, Authorization). It supports adding/removing items from watchlist, marking history, adding to collection, posting ratings, searching, and fetching trending/popular/recommendations. Responses are handled by HTTP status codes; 200/201 indicate success, 401 indicates auth issues, 404 not found, and 429 rate limiting.

When to use it

• Add or remove movies and shows from your Trakt watchlist
• Mark items as watched or add viewing history records
• Add physical or digital items to your collection with media metadata
• Submit or retrieve ratings for movies, shows, or episodes
• Search Trakt for titles or fetch trending/popular recommendations
• Automate periodic backups or syncs of your Trakt data

Best practices

• Always include required headers: trakt-api-version: 2, trakt-api-key, and Authorization when needed
• Identify items by title+year or by Trakt/IMDB/TMDB IDs for accuracy
• Use POST requests with Content-Type: application/json for modifications and batch multiple items where possible
• Monitor status codes and refresh OAuth tokens on 401; respect 429 rate limits
• Use ?extended=full to retrieve richer metadata when needed

Example use cases

• Add a newly released movie to your watchlist via a scripted curl POST
• Mark an evening’s viewing as watched with a timestamped history entry
• Add Blu-ray purchases to your collection including media_type and resolution
• Rate a complete series or movie in bulk using a single ratings POST
• Fetch top 10 trending movies or personalized recommendations for a weekly digest