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.

Updates an existing history item or creates a new one if it doesn’t exist (upsert operation). The item is identified by its media ID (DiscovrID with MV_ or TV_ prefix). This endpoint follows the same parameter structure as DELETE. Upsert Behavior:
  • If a matching history entry exists, it will be updated with the provided progress value.
  • If no matching entry exists, a new entry will be created with the provided progress.
  • This ensures only one entry exists per mediaId+season+episode combination (no duplicates).
TV Shows: For TV shows, season query parameter is required. episode is optional - when omitted, updates or creates the season default entry (entry without episode). When episode is provided, updates or creates an explicit episode entry. Overriding Season Defaults: To unmark an episode that was completed via a season default entry, use PATCH with progress: 0 (or any value < 80%). This creates an explicit episode entry that overrides the season default for that specific episode without affecting others. This is the preferred method for unmarking episodes. Movies: For movies, no additional parameters are needed. Progress: The progress value determines completion status. Values >= 80% are considered completed, values < 80% are not completed.

​
Parameters

NameTypeRequiredDescription
mediaIdstringYesThe DiscovrID (TV_<tmdbId> or MV_<tmdbId>) of the media item to update or create
seasonintegerNoSeason number (required for TV shows only, must be provided when mediaId starts with TV_)
episodeintegerNoEpisode number (optional for TV shows, only valid when mediaId starts with TV_). When omitted, updates or creates the season default entry.
progressnumberYesPlayback progress percentage (0-100). Values >= 80% are considered completed, values < 80% are not completed. Use progress: 0 to unmark an episode that was completed via season default.

​
Returns

SuccessMessage — History item updated or created successfully 
{
  "message": "string",
  "added": "string",
  "removed": "string"
}

​
Example

import { DiscovrClient } from "discovr";
import type { PatchHistoryPayload, 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.patchHistoryItem("TV_1396", 0, { season: 1, episode: 5 });
console.log(response);