Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.discovr.media/llms.txt

Use this file to discover all available pages before exploring further.

Adds a media item to the history list for a specific profile. Duplicates: Unlike other lists, the history list allows duplicate entries. Each call to this endpoint creates a new history entry, even if the same media was watched before. TV Shows: For TV shows, season is required and episode is optional. When episode is omitted, the entry represents a “Default for Episode” item that applies to all episodes in the season where episode.air_date < historyItem.updatedAt. This allows updating multiple episodes with a single history entry. Frontend clients should treat entries without episode as applying to all episodes in the season whose air date is less than the history item’s updatedAt timestamp. The matching logic is a client-side concern and not exposed by the API. Overriding Season Defaults: When an episode has an explicit history entry (with episode specified), it takes precedence over any season default entries. This allows clients to override season-level completions for individual episodes. For example, to unmark an episode that was completed via a season default, create an explicit episode entry with progress < 80% (which will not be marked as completed). Explicit episode entries always override season defaults when determining completion status and progress for that specific episode. Updated At: You can optionally provide an updatedAt timestamp. If not provided, the current time will be used. Progress: You can optionally provide a progress value (0-100) to track playback progress.

​
Parameters

NameTypeRequiredDescription
mediaIdstringYesThe media ID with prefix (MV_TMDBID for movies, TV_TMDBID for TV shows)
updatedAtstring (date-time)NoISO 8601 timestamp indicating when the history entry was last updated
progressnumberNoPlayback progress percentage (0-100)
seasonintegerNoSeason number (required for TV shows)
episodeintegerNoEpisode number (optional for TV shows). When omitted, creates a “Default for Episode” entry that applies to all episodes in the season where episode.air_date < historyItem.updatedAt. This allows updating multiple episodes with a single history entry. Overriding Season Defaults: When provided, creates an explicit episode entry that takes precedence over any season default entries. To unmark an episode completed via season default, create an explicit entry with progress < 80% (which will not be marked as completed).
importedstringNoSource of import (e.g., “trakt”) if this item was imported

​
Returns

SuccessMessage — Item added successfully 
{
  "message": "string",
  "added": "string",
  "removed": "string"
}

​
Example

import { DiscovrClient } from "discovr";
import type { AddHistoryPayload, SuccessMessage } from "discovr";

const discovr = new DiscovrClient("your-client-id", {
  basePath: "https://api.discovr.media",
});

// After sign-in and profile selection …
const response: SuccessMessage = await discovr.addHistoryItem("TV_TMDBID1396", { updatedAt: "2023-01-15T00:00:00.000Z", progress: 45.5, season: 1, episode: 5, imported: "trakt" });
console.log(response);