### Install dependencies and copy environment file Source: https://github.com/trakt/trakt-api/blob/master/projects/developer/README.md Run from projects/developer. Requires Bun 1.3.14 or later. Installs dependencies with frozen lockfile and copies the environment template. ```sh bun install --frozen-lockfile cp .env.example .env ``` -------------------------------- ### GET /shows/updates/:start_date Source: https://github.com/trakt/trakt-api Returns show updates since a given start date. Public endpoint. ```APIDOC ## GET /shows/updates/:start_date ### Description Returns show updates since a given start date. Public endpoint. ### Method GET ### Endpoint /shows/updates/:start_date ### Parameters #### Path Parameters - **start_date** (string) - Required - The start date for updates. ### Response #### Success Response (200) - **updated_at** (string) - Timestamp of update. - **show** (ShowResponse) - Show details. ``` -------------------------------- ### Guide article frontmatter and heading Source: https://github.com/trakt/trakt-api/blob/master/projects/developer/README.md Begin each article with an ISO timestamp and a level-one heading. Set updatedAt to the last content edit; missing or invalid timestamps omit the footer. ```markdown --- updatedAt: 2026-09-09T12:00:00.000Z --- # Article title Article content. ``` -------------------------------- ### traktApi initialization example Source: https://github.com/trakt/trakt-api Example from projects/playground/main.ts showing how to create a client with Environment.production_private and a client ID from the TRAKT_CLIENT_ID environment variable. ```TypeScript import { Environment, traktApi } from '@trakt/api'; const api = traktApi({ environment: Environment.production_private, apiKey: TRAKT_CLIENT_ID, }); ``` -------------------------------- ### Run local development server Source: https://github.com/trakt/trakt-api/blob/master/projects/developer/README.md Starts the SvelteKit dev server on localhost:5174. Requires PUBLIC_TRAKT_CLIENT_ID set in .env and the redirect URI registered exactly as http://localhost:5174/callback. ```sh bun run dev:local ``` -------------------------------- ### GET /shows/updates/id/:start_date Source: https://github.com/trakt/trakt-api Returns updated show IDs since a given start date. Public endpoint. ```APIDOC ## GET /shows/updates/id/:start_date ### Description Returns updated show IDs since a given start date. Public endpoint. ### Method GET ### Endpoint /shows/updates/id/:start_date ### Parameters #### Path Parameters - **start_date** (string) - Required - The start date for updates. ### Response #### Success Response (200) - **body** (number[]) - List of show IDs. ``` -------------------------------- ### Guide link to API operation Source: https://github.com/trakt/trakt-api/blob/master/projects/developer/README.md Use the operationId from the OpenAPI document for API operation links. The 'Copy operation link' menu creates this URL without request inputs. ```markdown [Exchange a token](/?section=reference&operation=postOauthToken) ``` -------------------------------- ### GET /shows/updates/:start_date Source: https://github.com/trakt/trakt-api Returns all shows updated since the given start date. Public endpoint. ```APIDOC ## GET /shows/updates/:start_date ### Description Returns all shows updated since the given start date. ### Method GET ### Endpoint /shows/updates/:start_date ### Authentication Public ### Response #### Success Response (200) ``` -------------------------------- ### GET /search/show Source: https://github.com/trakt/trakt-api/blob/master/projects/developer/src/lib/guides/search.md Performs a broader search for shows, including fuzzy matches and other relevant results. Use this endpoint to get a wider set of results beyond exact title matches. ```APIDOC ## [GET] /search/show ### Description Performs a broader search for shows, including fuzzy matches and other relevant results. Use this endpoint to get a wider set of results beyond exact title matches. ### Method GET ### Endpoint /search/show ### Parameters #### Query Parameters - **query** (string) - Required - The show title to search for. ### Response #### Success Response (200) Returns a list of search results. ### Request Example ```http GET /search/show?query=from ``` ``` -------------------------------- ### GET /search/show/exact Source: https://github.com/trakt/trakt-api/blob/master/projects/developer/src/lib/guides/search.md Performs an exact search for shows by title. Use this endpoint when the user is looking for a known show title to get strong title matches. ```APIDOC ## [GET] /search/show/exact ### Description Performs an exact search for shows by title. Use this endpoint when the user is looking for a known show title to get strong title matches. ### Method GET ### Endpoint /search/show/exact ### Parameters #### Query Parameters - **query** (string) - Required - The show title to search for. ### Response #### Success Response (200) Returns a list of search results. ### Request Example ```http GET /search/show/exact?query=from ``` ``` -------------------------------- ### GET /users/settings Source: https://github.com/trakt/trakt-api/blob/master/projects/developer/src/lib/guides/user-account-limits.md Retrieves user account settings including VIP status and account limits. Use this endpoint to read account limits instead of hardcoding them, as limits can vary by account and change over time. ```APIDOC ## [GET] /users/settings ### Description Retrieves user account settings including VIP status and account limits. Use this endpoint to read account limits instead of hardcoding them, as limits can vary by account and change over time. ### Method GET ### Endpoint /users/settings ### Response #### Success Response (200) - **user.vip** (boolean) - Indicates if the user is a VIP member. - **limits.list.count** (integer) - Maximum number of personal lists. - **limits.list.item_count** (integer) - Maximum items per personal list. - **limits.watchlist.item_count** (integer) - Maximum watchlist items. ### Error Handling - **420** - Account Limit Exceeded. The response can have an empty body and no limit headers. ``` -------------------------------- ### POST /scrobble/start Source: https://github.com/trakt/trakt-api Starts a scrobble when the video starts playing or is unpaused. Removes existing playback progress and the watching status auto-expires after the remaining runtime. Requires OAuth authentication. ```APIDOC ## POST /scrobble/start ### Description Starts a scrobble when the video starts playing or is unpaused. Removes existing playback progress and the watching status auto-expires after the remaining runtime. ### Method POST ### Endpoint /scrobble/start ### Parameters #### Request Body - **progress** (float) - Required - Progress between 0 and 100. - **movie** (object) - Optional - Movie object with `ids` (movieIdsRequestSchema). - **episode** (object) - Optional - Episode object with `ids` (episodeIdsRequestSchema). ### Response #### Success Response (201) - **MovieScrobbleResponse | EpisodeScrobbleResponse** - The scrobble response. ### Request Example ```json { "progress": 0, "movie": { "ids": { "trakt": 157 } } } ``` ### Response Example ```json { "action": "start" } ``` ``` -------------------------------- ### POST /scrobble/start Source: https://github.com/trakt/trakt-api Starts a scrobble. Requires OAuth authentication. ```APIDOC ## POST /scrobble/start ### Description Starts a scrobble. ### Method POST ### Endpoint /scrobble/start ### Authentication OAuth ### Response #### Success Response (201) ``` -------------------------------- ### GET /calendars/:target/dvd/:start_date/:days Source: https://github.com/trakt/trakt-api Retrieves a calendar of DVD releases for a given target, start date, and number of days. This endpoint provides DVD calendar data. ```APIDOC ## GET /calendars/:target/dvd/:start_date/:days ### Description Retrieves a calendar of DVD releases for a given target, start date, and number of days. This endpoint provides DVD calendar data. ### Method GET ### Endpoint /calendars/:target/dvd/:start_date/:days ### Parameters #### Path Parameters - **target** (string) - Required - The target for the calendar (e.g., my, user). - **start_date** (string) - Required - The start date for the calendar. - **days** (integer) - Required - The number of days to include. ### Response #### Success Response (200) ``` -------------------------------- ### GET /calendars/:target/media/:start_date/:days Source: https://github.com/trakt/trakt-api Retrieves a calendar of media releases for a given target, start date, and number of days. This endpoint provides media calendar data. ```APIDOC ## GET /calendars/:target/media/:start_date/:days ### Description Retrieves a calendar of media releases for a given target, start date, and number of days. This endpoint provides media calendar data. ### Method GET ### Endpoint /calendars/:target/media/:start_date/:days ### Parameters #### Path Parameters - **target** (string) - Required - The target for the calendar (e.g., my, user). - **start_date** (string) - Required - The start date for the calendar. - **days** (integer) - Required - The number of days to include. ### Response #### Success Response (200) ``` -------------------------------- ### GET /sync/collection/minimal/shows Source: https://github.com/trakt/trakt-api Retrieves minimal show collection data. ```APIDOC ## GET /sync/collection/minimal/shows ### Description Retrieves minimal show collection data. ### Method GET ### Endpoint `/sync/collection/minimal/shows` ### Authentication OAuth required. ### Response #### Success Response (200) - List of minimal show collection data. ``` -------------------------------- ### GET /recommendations/shows/ Source: https://github.com/trakt/trakt-api Returns show recommendations. Requires OAuth authentication. ```APIDOC ## GET /recommendations/shows/ ### Description Returns show recommendations. ### Method GET ### Endpoint /recommendations/shows/ ### Authentication OAuth ### Response #### Success Response (200) ``` -------------------------------- ### GET /smart-lists/templates Source: https://github.com/trakt/trakt-api Retrieves available smart list templates. ```APIDOC ## GET /smart-lists/templates ### Description Retrieves available smart list templates. ### Method GET ### Endpoint `/smart-lists/templates` ### Response #### Success Response (200) - List of smart list templates. ``` -------------------------------- ### GET /shows/popular Source: https://github.com/trakt/trakt-api Returns popular shows. Public endpoint. ```APIDOC ## GET /shows/popular ### Description Returns popular shows. Public endpoint. ### Method GET ### Endpoint /shows/popular ### Response #### Success Response (200) - **body** (ShowResponse[]) - List of popular shows. ``` -------------------------------- ### GET /sync/collection/media Source: https://github.com/trakt/trakt-api Retrieves the user's media collection. ```APIDOC ## GET /sync/collection/media ### Description Retrieves the user's media collection. ### Method GET ### Endpoint `/sync/collection/media` ### Authentication OAuth required. ### Response #### Success Response (200) - List of collected media items. ``` -------------------------------- ### GET /sync/progress/up_next Source: https://github.com/trakt/trakt-api Retrieves the next episodes to watch for the user. ```APIDOC ## GET /sync/progress/up_next ### Description Retrieves the next episodes to watch for the user. ### Method GET ### Endpoint `/sync/progress/up_next` ### Authentication OAuth required. ### Response #### Success Response (200) - List of next episodes. ``` -------------------------------- ### GET /watchnow/sources Source: https://github.com/trakt/trakt-api Retrieves all watch now sources. This route is limited-access. ```APIDOC ## GET /watchnow/sources ### Description Retrieves all watch now sources. ### Method GET ### Endpoint /watchnow/sources ### Response #### Success Response (200) - **WatchNowSourcesResponse[]** - Array of watch now sources. ``` -------------------------------- ### GET /search/movie/exact Source: https://github.com/trakt/trakt-api/blob/master/projects/developer/src/lib/guides/search.md Performs an exact search for movies by title. Use this endpoint when the user is looking for a known movie title to get strong title matches. ```APIDOC ## [GET] /search/movie/exact ### Description Performs an exact search for movies by title. Use this endpoint when the user is looking for a known movie title to get strong title matches. ### Method GET ### Endpoint /search/movie/exact ### Parameters #### Query Parameters - **query** (string) - Required - The movie title to search for. ### Response #### Success Response (200) Returns a list of search results. ### Request Example ```http GET /search/movie/exact?query=weapons ``` ``` -------------------------------- ### GET /shows/:id/studios Source: https://github.com/trakt/trakt-api Returns studios for a show. Public endpoint. ```APIDOC ## GET /shows/:id/studios ### Description Returns studios for a show. ### Method GET ### Endpoint /shows/:id/studios ### Authentication Public ### Response #### Success Response (200) ``` -------------------------------- ### GET /users/:list_id/smart-lists/ Source: https://github.com/trakt/trakt-api Retrieve a smart list definition. ```APIDOC ## GET /users/:list_id/smart-lists/ ### Description Retrieve a smart list definition. ### Method GET ### Endpoint /users/:list_id/smart-lists/ ### Parameters #### Path Parameters - **list_id** (string) - Required - List ID ### Response #### Success Response (200) - **SmartListDefinitionResponse** - Smart list definition ``` -------------------------------- ### Using traktApiFactory with staging environment Source: https://github.com/trakt/trakt-api Example of creating a client with traktApiFactory, explicitly setting environment to Environment.staging. Shows error handling for network failures. ```TypeScript // Factory form — explicit environment required import { traktApiFactory, Environment } from '@trakt/api'; const client = traktApiFactory({ environment: Environment.staging, apiKey: '', }); try { const res = await client.shows.trending({}); console.log(res.status, res.body); } catch (error) { console.error('network failure', error); } ``` -------------------------------- ### GET /search/movie Source: https://github.com/trakt/trakt-api/blob/master/projects/developer/src/lib/guides/search.md Performs a broader search for movies, including fuzzy matches and other relevant results. Use this endpoint to get a wider set of results beyond exact title matches. ```APIDOC ## [GET] /search/movie ### Description Performs a broader search for movies, including fuzzy matches and other relevant results. Use this endpoint to get a wider set of results beyond exact title matches. ### Method GET ### Endpoint /search/movie ### Parameters #### Query Parameters - **query** (string) - Required - The movie title to search for. ### Response #### Success Response (200) Returns a list of search results. ### Request Example ```http GET /search/movie?query=weapons ``` ``` -------------------------------- ### Usage example for lists client Source: https://github.com/trakt/trakt-api Shows how to use the lists client to fetch popular lists, list items, and like a list. Requires an API key. ```TypeScript import { traktApi } from '@trakt/api'; const client = traktApi({ apiKey: '' }); // Popular lists today const popular = await client.lists.popular({ query: { page: 1, limit: 10 } }); if (popular.status === 200) { for (const list of popular.body) console.log(list.name, list.item_count); } // Movie items of a list, sorted const items = await client.lists.items.movie({ params: { id: '8213844' }, query: { sort_by: 'released', sort_how: 'asc', extended: 'full' }, }); // Like a list (204) — one like per user const liked = await client.lists.like({ params: { id: '8213844' }, body: undefined }); console.log(liked.status === 204); ``` -------------------------------- ### GET /people/updates/:start_date Source: https://github.com/trakt/trakt-api Returns all people updated since the given start date. Public endpoint. ```APIDOC ## GET /people/updates/:start_date ### Description Returns all people updated since the given start date. ### Method GET ### Endpoint /people/updates/:start_date ### Authentication Public ### Response #### Success Response (200) ``` -------------------------------- ### Usage example for traktApi client Source: https://github.com/trakt/trakt-api Shows how to instantiate the client and call trending, smart list templates, and genres endpoints. ```TypeScript import { traktApi } from '@trakt/api'; const client = traktApi({ apiKey: '' }); // Combined media feed const feed = await client.media.trending({ query: { genres: 'drama', page: 1 } }); // Official smart list templates const templates = await client.smart_lists.templates({ query: { extended: 'images' } }); // Genres with subgenres const genres = await client.genres.list({ params: { type: 'movies' }, query: { extended: 'subgenres' } }); ``` -------------------------------- ### GET /users/:list_id/lists/ Source: https://github.com/trakt/trakt-api Retrieve a specific list summary. ```APIDOC ## GET /users/:list_id/lists/ ### Description Retrieve a specific list summary. ### Method GET ### Endpoint /users/:list_id/lists/ ### Parameters #### Path Parameters - **list_id** (string) - Required - List ID ### Response #### Success Response (200) - **ListResponse** - The list summary ``` -------------------------------- ### contents.md sidebar group and entry Source: https://github.com/trakt/trakt-api/blob/master/projects/developer/README.md Use level-two headings for groups and Markdown list links for entries in contents.md. ```markdown ## Start here - [Introduction](/docs/getting-started) - [Authentication](/docs/authentication-oauth) ``` -------------------------------- ### GET /shows/updates/id/:start_date Source: https://github.com/trakt/trakt-api Returns all show IDs updated since the given start date. Public endpoint. ```APIDOC ## GET /shows/updates/id/:start_date ### Description Returns all show IDs updated since the given start date. ### Method GET ### Endpoint /shows/updates/id/:start_date ### Authentication Public ### Response #### Success Response (200) ``` -------------------------------- ### Usage examples for sync endpoints Source: https://github.com/trakt/trakt-api Shows how to use the sync client: adding a movie to the watchlist (expects 201), adding history with a back-dated watch, fetching up-next items sorted by recently-aired, and dropping a playback item (expects 204, 404 for invalid id). ```TypeScript import { traktApi } from '@trakt/api'; const client = traktApi({ apiKey: '' }); // Add a movie to the watchlist const added = await client.sync.watchlist.add({ body: { movies: [{ ids: { trakt: 157 } }] }, }); if (added.status === 201) { console.log('added:', added.body.added.movies); } // Add history with a back-dated watch const hist = await client.sync.history.add({ body: { episodes: [{ ids: { trakt: 234 }, watched_at: '2025-01-01T20:00:00.000Z' }], }, }); // Up next, sorted const upNext = await client.sync.progress.upNext.standard({ query: { sort_by: 'recently-aired', extended: 'full', include_stats: true }, }); for (const item of upNext.body) { console.log(item.show?.title, item.next_episode?.title); } // Drop a playback item; 404 when the id is invalid const dropped = await client.sync.progress.drop.movie({ params: { id: '123' } }); if (dropped.status === 204) console.log('removed'); ``` -------------------------------- ### GET /sync/playback Source: https://github.com/trakt/trakt-api Retrieves the user's playback progress for all items. ```APIDOC ## GET /sync/playback ### Description Retrieves the user's playback progress for all items. ### Method GET ### Endpoint `/sync/playback` ### Authentication OAuth required. ### Response #### Success Response (200) - List of items with playback progress. ``` -------------------------------- ### GET /people/updates/id/:start_date Source: https://github.com/trakt/trakt-api Returns all people IDs updated since the given start date. Public endpoint. ```APIDOC ## GET /people/updates/id/:start_date ### Description Returns all people IDs updated since the given start date. ### Method GET ### Endpoint /people/updates/id/:start_date ### Authentication Public ### Response #### Success Response (200) ``` -------------------------------- ### Install @trakt/api with Deno Source: https://github.com/trakt/trakt-api/blob/master/projects/api/README.md Adds the @trakt/api package from JSR using Deno. ```sh deno add jsr:@trakt/api ``` -------------------------------- ### GET /users/syncs Source: https://github.com/trakt/trakt-api Lists all data syncs for the authenticated user. First-party only. ```APIDOC ## GET /users/syncs ### Description Lists all data syncs for the authenticated user. ### Method GET ### Endpoint /users/syncs ### Response #### Success Response (200) - **SyncResponse[]** - Array of sync responses. ``` -------------------------------- ### Run validation checks Source: https://github.com/trakt/trakt-api/blob/master/projects/developer/README.md Run all validation commands from the project directory. Biome skips .svelte files, so Prettier with prettier-plugin-svelte formats them; run `bun run format:svelte` to apply. `check` validates TypeScript and Svelte components, `test` runs Vitest, and `build` regenerates the OpenAPI document and produces the static site in `build/`. ```sh bun run format:check bun run lint bun run format:svelte:check bun run check bun run test bun run build ``` -------------------------------- ### GET /movies/updates/:start_date Source: https://github.com/trakt/trakt-api Retrieves movie updates since a given start date. This endpoint is publicly accessible. ```APIDOC ## GET /movies/updates/:start_date ### Description Retrieves movie updates since a given start date. ### Method GET ### Endpoint /movies/updates/:start_date ### Parameters #### Path Parameters - **start_date** (string) - Required - The start date (e.g., YYYY-MM-DD). ### Response #### Success Response (200) - **array** - List of objects with `updated_at` and `movie` (MovieResponse). ``` -------------------------------- ### Trakt API shows usage example Source: https://github.com/trakt/trakt-api Demonstrates using the traktApi client to fetch show summary, next episode, episode stats, and reset progress. Requires a client ID as apiKey. Handles 204 for finished shows, 200 for stats, and 201 for successful reset. ```TypeScript import { traktApi } from '@trakt/api'; const client = traktApi({ apiKey: '' }); // Show + next episode const show = await client.shows.summary({ params: { id: 'game-of-thrones' }, query: { extended: 'full' } }); const next = await client.shows.nextEpisode({ params: { id: 'game-of-thrones' } }); if (next.status === 204) console.log('show finished'); // Episode stats const epStats = await client.shows.episode.stats({ params: { id: 'game-of-thrones', season: 1, episode: 1 }, }); if (epStats.status === 200) console.log(epStats.body); // Guarded progress reset for VIP clients const reset = await client.shows.progress.reset({ params: { id: 'game-of-thrones' }, body: { reset_at: '2025-01-01T00:00:00.000Z' }, }); if (reset.status === 201) console.log('progress reset'); ``` -------------------------------- ### GET /movies/updates/id/:start_date Source: https://github.com/trakt/trakt-api Retrieves the IDs of movies updated since a given start date. This endpoint is publicly accessible. ```APIDOC ## GET /movies/updates/id/:start_date ### Description Retrieves the IDs of movies updated since a given start date. ### Method GET ### Endpoint /movies/updates/id/:start_date ### Parameters #### Path Parameters - **start_date** (string) - Required - The start date (e.g., YYYY-MM-DD). ### Response #### Success Response (200) - **number[]** - List of Trakt IDs. ``` -------------------------------- ### Client usage example for notes.create, update, delete Source: https://github.com/trakt/trakt-api Shows how to create a note on a movie, then update and delete it using the client. Requires an API key. The create call returns status 201 and the note id; delete returns 204. ```TypeScript import { traktApi } from '@trakt/api'; const client = traktApi({ apiKey: '' }); // Add a note to a movie const created = await client.notes.create({ body: { item: { ids: { trakt: 157 } }, notes: 'Rewatch before the sequel.', spoiler: false, }, }); if (created.status === 201) console.log('note id:', created.body.id); // Update and delete const updated = await client.notes.update({ params: { id: String(created.body.id) }, body: { notes: 'Actually skip it.', spoiler: true }, }); const removed = await client.notes.delete({ params: { id: String(created.body.id) } }); console.log(removed.status === 204); ``` -------------------------------- ### GET /people/updates/id/:start_date Source: https://github.com/trakt/trakt-api Retrieves a list of person IDs that have been updated since the given start date. The response is an array of numeric IDs. ```APIDOC ## GET /people/updates/id/:start_date ### Description Retrieves a list of person IDs that have been updated since the given start date. The response is an array of numeric IDs. ### Method GET ### Endpoint /people/updates/id/:start_date ### Parameters #### Path Parameters - **start_date** (string) - Required - The start date for the updates. ### Response #### Success Response (200) - **number[]** - An array of person IDs. ``` -------------------------------- ### GET Source: https://github.com/trakt/trakt-api/blob/master/projects/developer/src/lib/guides/verbs.md Select one or more items. Success returns a 200 status code. ```APIDOC ## GET ### Description Select one or more items. Success returns `200` status code. ### Method GET ### Response #### Success Response (200) Success returns `200` status code. ``` -------------------------------- ### GET /people/updates/:start_date Source: https://github.com/trakt/trakt-api Retrieves a list of people that have been updated since the given start date. The response contains the updated_at timestamp and the person object for each update. ```APIDOC ## GET /people/updates/:start_date ### Description Retrieves a list of people that have been updated since the given start date. The response contains the updated_at timestamp and the person object for each update. ### Method GET ### Endpoint /people/updates/:start_date ### Parameters #### Path Parameters - **start_date** (string) - Required - The start date for the updates. ### Response #### Success Response (200) - **updated_at** (string) - The timestamp of the update. - **person** (PersonResponse) - The person object. ``` -------------------------------- ### GET /watchnow/sources Source: https://github.com/trakt/trakt-api Retrieves available watchnow sources. Requires limited authentication. ```APIDOC ## [GET] /watchnow/sources ### Description Retrieves available watchnow sources. Requires limited authentication. ### Method GET ### Endpoint /watchnow/sources ### Response #### Success Response (200) - No response body details provided in source. ``` -------------------------------- ### traktApi(options): TraktApi Source: https://github.com/trakt/trakt-api Creates a fully typed client bound to the given environment and credentials. It is a thin wrapper over traktApiFactory that defaults environment to Environment.production. ```APIDOC ## `traktApi(options): TraktApi` ### Description Creates a fully typed client bound to the given environment and credentials. It is a thin wrapper over `traktApiFactory` that defaults `environment` to `Environment.production`. ### Method Function call ### Endpoint `traktApi(options)` ### Parameters #### Options - **environment** (Environment) - Optional - The environment to use. Defaults to `Environment.production`. - **apiKey** (string) - Required - The Trakt API client ID. - **fetch** (typeof fetch) - Optional - Custom fetch implementation. - **cancellable** (boolean) - Optional - Whether the request is cancellable. - **cancellationId** (string) - Optional - Cancellation identifier. ### Returns `TraktApi` — the typed ts-rest client for `traktContract` (i.e. `InitClientReturn`). Every contract route becomes a method callable as `client..(({ params?, query?, body?, headers? }))` that resolves to `{ status, body, headers }`. ### Request Example ```ts import { traktApi, Environment } from '@trakt/api'; const client = traktApi({ apiKey: '' }); const res = await client.movies.summary({ params: { id: 'tron-legacy-2010' } }); if (res.status === 200) { console.log(res.body.title); // res.body is MovieResponse } ``` ``` -------------------------------- ### GET /movies/updates/:start_date Source: https://github.com/trakt/trakt-api Retrieves movie updates since a given start date. This endpoint is publicly accessible and returns a 200 status code. ```APIDOC ## GET /movies/updates/:start_date ### Description Retrieves movie updates since a given start date. ### Method GET ### Endpoint /movies/updates/:start_date ### Parameters #### Path Parameters - **start_date** (string) - Required - The start date for updates. ### Response #### Success Response (200) No response schema provided. ``` -------------------------------- ### GET /movies/updates/id/:start_date Source: https://github.com/trakt/trakt-api Retrieves movie update IDs since a given start date. This endpoint is publicly accessible and returns a 200 status code. ```APIDOC ## GET /movies/updates/id/:start_date ### Description Retrieves movie update IDs since a given start date. ### Method GET ### Endpoint /movies/updates/id/:start_date ### Parameters #### Path Parameters - **start_date** (string) - Required - The start date for updates. ### Response #### Success Response (200) No response schema provided. ``` -------------------------------- ### Regenerate share cards with bun run generate:share-cards Source: https://github.com/trakt/trakt-api/blob/master/projects/developer/README.md Run after a design change to regenerate the Open Graph cards. Requires oxipng, pngquant, and optionally CHROME_PATH if Chrome is not at the default macOS location. Output is committed, so only run when the design changes. ```sh bun run generate:share-cards ``` -------------------------------- ### traktApi / traktApiFactory Source: https://github.com/trakt/trakt-api Constructs a Trakt API client. The factory requires an environment and API key; the convenience wrapper defaults to the production environment. ```APIDOC ## traktApi / traktApiFactory ### Description Constructs a Trakt API client. The factory requires an environment and API key; the convenience wrapper defaults to the production environment. ### Parameters #### Options - **environment** (Environment | `https://${string}` | `http://localhost:${string}` | 'http://localhost') - Required (in factory), Optional (in wrapper) - API base URL. Any `https://` host or `http://localhost` works; `Environment` offers the four official targets. - **apiKey** (string) - Required - Trakt client id from your trakt.tv API application. Sent as the `trakt-api-key` header. - **fetch** (typeof fetch) - Optional - Custom fetch implementation used for every request. - **cancellable** (boolean) - Optional - When truthy, in-flight requests are tracked per `cancellationId` and aborted when a newer request with the same id starts. - **cancellationId** (string) - Optional - Key used by the cancellation map. ### Response Returns a client instance with methods for all contract domains. ``` -------------------------------- ### GET /calendars/releases/hot/finales/:start_date/:days Source: https://github.com/trakt/trakt-api Retrieves a calendar of hot finales for a given start date and number of days. This endpoint provides hot finale calendar data. ```APIDOC ## GET /calendars/releases/hot/finales/:start_date/:days ### Description Retrieves a calendar of hot finales for a given start date and number of days. This endpoint provides hot finale calendar data. ### Method GET ### Endpoint /calendars/releases/hot/finales/:start_date/:days ### Parameters #### Path Parameters - **start_date** (string) - Required - The start date for the calendar. - **days** (integer) - Required - The number of days to include. ### Response #### Success Response (200) ``` -------------------------------- ### GET /calendars/releases/hot/premieres/:start_date/:days Source: https://github.com/trakt/trakt-api Retrieves a calendar of hot premieres for a given start date and number of days. This endpoint provides hot premiere calendar data. ```APIDOC ## GET /calendars/releases/hot/premieres/:start_date/:days ### Description Retrieves a calendar of hot premieres for a given start date and number of days. This endpoint provides hot premiere calendar data. ### Method GET ### Endpoint /calendars/releases/hot/premieres/:start_date/:days ### Parameters #### Path Parameters - **start_date** (string) - Required - The start date for the calendar. - **days** (integer) - Required - The number of days to include. ### Response #### Success Response (200) ``` -------------------------------- ### Usage example for calendars.shows and calendars.releasesHot Source: https://github.com/trakt/trakt-api Shows how to call the calendars endpoints using the traktApi client. The first call retrieves the authenticated user's calendar for the next 7 days with full extended info. The second retrieves global hot releases for 30 days, filtered to movies and grouped by day. ```TypeScript import { traktApi } from '@trakt/api'; const client = traktApi({ apiKey: '' }); // My calendar for the next 7 days const my = await client.calendars.shows({ params: { target: 'my', start_date: '2025-06-01', days: 7 }, query: { extended: 'full' }, }); // Global hot releases const hot = await client.calendars.releasesHot({ params: { start_date: '2025-06-01', days: 30 }, query: { type: 'movie', group: 'day' }, }); ``` -------------------------------- ### GET /calendars/releases/hot/:start_date/:days Source: https://github.com/trakt/trakt-api Retrieves a calendar of hot releases for a given start date and number of days. This endpoint provides hot release calendar data. ```APIDOC ## GET /calendars/releases/hot/:start_date/:days ### Description Retrieves a calendar of hot releases for a given start date and number of days. This endpoint provides hot release calendar data. ### Method GET ### Endpoint /calendars/releases/hot/:start_date/:days ### Parameters #### Path Parameters - **start_date** (string) - Required - The start date for the calendar. - **days** (integer) - Required - The number of days to include. ### Response #### Success Response (200) ``` -------------------------------- ### Client usage example Source: https://github.com/trakt/trakt-api Shows how to use the search contract client: text search across movies and shows, IMDb lookup, and contributing to global trending searches. Requires an API key. ```TypeScript import { traktApi } from '@trakt/api'; const client = traktApi({ apiKey: '' }); // Text search across movies and shows const res = await client.search.query({ params: { type: 'movie,show' }, query: { query: 'tron', extended: 'full', page: 1, limit: 10 }, }); for (const hit of res.body) { if (hit.type === 'movie') console.log(hit.movie.title); if (hit.type === 'show') console.log(hit.show.title); } // IMDb lookup const lookup = await client.search.lookup({ params: { id_type: 'imdb', id: 'tt0084827' }, query: { type: 'movie' }, }); // Contribute to global trending searches const added = await client.search.recent.add({ body: { query: 'tron' }, }); ``` -------------------------------- ### GET /calendars/:target/movies/:start_date/:days Source: https://github.com/trakt/trakt-api Retrieves a calendar of movies for a given target, start date, and number of days. This endpoint provides movie calendar data. ```APIDOC ## GET /calendars/:target/movies/:start_date/:days ### Description Retrieves a calendar of movies for a given target, start date, and number of days. This endpoint provides movie calendar data. ### Method GET ### Endpoint /calendars/:target/movies/:start_date/:days ### Parameters #### Path Parameters - **target** (string) - Required - The target for the calendar (e.g., my, user). - **start_date** (string) - Required - The start date for the calendar. - **days** (integer) - Required - The number of days to include. ### Response #### Success Response (200) ``` -------------------------------- ### GET /calendars/:target/shows/:start_date/:days Source: https://github.com/trakt/trakt-api Retrieves a calendar of shows for a given target, start date, and number of days. This endpoint provides show calendar data. ```APIDOC ## GET /calendars/:target/shows/:start_date/:days ### Description Retrieves a calendar of shows for a given target, start date, and number of days. This endpoint provides show calendar data. ### Method GET ### Endpoint /calendars/:target/shows/:start_date/:days ### Parameters #### Path Parameters - **target** (string) - Required - The target for the calendar (e.g., my, user). - **start_date** (string) - Required - The start date for the calendar. - **days** (integer) - Required - The number of days to include. ### Response #### Success Response (200) ``` -------------------------------- ### Usage example for people endpoints Source: https://github.com/trakt/trakt-api Shows how to call people.summary and people.shows with the traktApi client, including query parameters and response handling. ```TypeScript import { traktApi } from '@trakt/api'; const client = traktApi({ apiKey: '' }); // Person summary with social ids const person = await client.people.summary({ params: { id: 'bryan-cranston' }, query: { extended: 'full', language: 'en' }, }); if (person.status === 200) { console.log(person.body.name, person.body.ids.slug); } // Credits const credits = await client.people.shows({ params: { id: 'bryan-cranston' }, query: { extended: 'full' }, }); if (credits.status === 200) { for (const role of credits.body.cast ?? []) { console.log(role.show.title, role.characters); } } ``` -------------------------------- ### GET /sync/playback Source: https://github.com/trakt/trakt-api Retrieves the user's playback progress for all media. Supports start_at and end_at parameters. ```APIDOC ## GET /sync/playback ### Description Retrieves the user's playback progress for all media. Supports start_at and end_at parameters. ### Method GET ### Endpoint /sync/playback ### Parameters #### Query Parameters - **start_at** (string) - Optional - Start timestamp. - **end_at** (string) - Optional - End timestamp. ### Response #### Success Response (200) - **PlaybackResponse[]** - Array of playback items. ``` -------------------------------- ### GET /calendars/:target/streaming/:start_date/:days Source: https://github.com/trakt/trakt-api Retrieves a calendar of streaming releases for a given target, start date, and number of days. This endpoint provides streaming calendar data. ```APIDOC ## GET /calendars/:target/streaming/:start_date/:days ### Description Retrieves a calendar of streaming releases for a given target, start date, and number of days. This endpoint provides streaming calendar data. ### Method GET ### Endpoint /calendars/:target/streaming/:start_date/:days ### Parameters #### Path Parameters - **target** (string) - Required - The target for the calendar (e.g., my, user). - **start_date** (string) - Required - The start date for the calendar. - **days** (integer) - Required - The number of days to include. ### Response #### Success Response (200) ``` -------------------------------- ### GET /calendars/:target/shows/finales/:start_date/:days Source: https://github.com/trakt/trakt-api Retrieves a calendar of show finales for a given target, start date, and number of days. This endpoint provides finale calendar data. ```APIDOC ## GET /calendars/:target/shows/finales/:start_date/:days ### Description Retrieves a calendar of show finales for a given target, start date, and number of days. This endpoint provides finale calendar data. ### Method GET ### Endpoint /calendars/:target/shows/finales/:start_date/:days ### Parameters #### Path Parameters - **target** (string) - Required - The target for the calendar (e.g., my, user). - **start_date** (string) - Required - The start date for the calendar. - **days** (integer) - Required - The number of days to include. ### Response #### Success Response (200) ``` -------------------------------- ### Usage example for comments client Source: https://github.com/trakt/trakt-api Shows how to post a comment, list trending comments, and handle an error when editing someone else's comment (returns 401). ```TypeScript import { traktApi } from '@trakt/api'; const client = traktApi({ apiKey: '' }); // Post a comment on a movie const posted = await client.comments.post({ body: { item: { ids: { trakt: 157 } }, comment: 'A masterpiece of the 80s.', spoiler: false, }, }); if (posted.status === 201) console.log('comment id:', posted.body.id); // List trending comments const trending = await client.comments.trending({ params: { comment_type: 'all', type: 'all' }, query: { include_replies: false, page: 1, limit: 10 }, }); // Error path: editing someone else's comment returns 401 const edit = await client.comments.edit({ params: { id: 123 }, body: { comment: 'updated text' }, }); if (edit.status === 401) console.log('not the author'); ``` -------------------------------- ### Using traktApi to fetch movie summary Source: https://github.com/trakt/trakt-api Example of creating a client with traktApi and calling the movies.summary endpoint. The response body is typed as MovieResponse when status is 200. ```TypeScript import { traktApi, Environment } from '@trakt/api'; const client = traktApi({ apiKey: '' }); const res = await client.movies.summary({ params: { id: 'tron-legacy-2010' } }); if (res.status === 200) { console.log(res.body.title); // res.body is MovieResponse } ``` -------------------------------- ### GET /calendars/:target/shows/premieres/:start_date/:days Source: https://github.com/trakt/trakt-api Retrieves a calendar of show premieres for a given target, start date, and number of days. This endpoint provides premiere calendar data. ```APIDOC ## GET /calendars/:target/shows/premieres/:start_date/:days ### Description Retrieves a calendar of show premieres for a given target, start date, and number of days. This endpoint provides premiere calendar data. ### Method GET ### Endpoint /calendars/:target/shows/premieres/:start_date/:days ### Parameters #### Path Parameters - **target** (string) - Required - The target for the calendar (e.g., my, user). - **start_date** (string) - Required - The start date for the calendar. - **days** (integer) - Required - The number of days to include. ### Response #### Success Response (200) ``` -------------------------------- ### GET /calendars/releases/hot/new/:start_date/:days Source: https://github.com/trakt/trakt-api Retrieves a calendar of new hot releases for a given start date and number of days. This endpoint provides new hot release calendar data. ```APIDOC ## GET /calendars/releases/hot/new/:start_date/:days ### Description Retrieves a calendar of new hot releases for a given start date and number of days. This endpoint provides new hot release calendar data. ### Method GET ### Endpoint /calendars/releases/hot/new/:start_date/:days ### Parameters #### Path Parameters - **start_date** (string) - Required - The start date for the calendar. - **days** (integer) - Required - The number of days to include. ### Response #### Success Response (200) ``` -------------------------------- ### TraktApiOptions type definition Source: https://github.com/trakt/trakt-api Defines the constructor options for traktApi and traktApiFactory. environment is required in traktApiFactory but optional in traktApi, defaulting to Environment.production. apiKey is sent as the trakt-api-key header. ```TypeScript export type TraktApiOptions = { environment: | Environment | `https://${string}` | `http://localhost:${string}` | 'http://localhost'; apiKey: string; fetch?: typeof fetch; cancellable?: boolean; cancellationId?: string; }; ``` -------------------------------- ### Base request headers Source: https://github.com/trakt/trakt-api Base headers set on every client request. Not configurable per request via options. ```TypeScript baseHeaders: { 'Content-Type': 'application/json', 'trakt-api-version': '2', 'trakt-api-key': apiKey, } ```