Skip to main content
POST
/
profile
/
history
TypeScript
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_1396", { updatedAt: "2023-01-15T00:00:00.000Z", progress: 45.5, season: 1, episode: 5, imported: "trakt" });
console.log(response);
{
  "message": "Item added to history list successfully"
}

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.

Authorizations

​
Authorization
string
header
required

Bearer token authentication.

  • Identity-tier endpoints (/profiles, /auth/session-token, /auth/session) accept a long-lived refresh token (rt_<hex>).
  • Session-tier endpoints (/pages/*, /profile/*) accept a short-lived session JWT.

SDK clients use two typed API accessors (identityApi() with the refresh token vs sessionApi() with the session JWT) — see the SDK DiscovrAuth helper.

Format: Authorization: Bearer {token}

Body

application/json

A watch history entry to record. For TV shows, season is required; episode is optional.

​
mediaId
string
required

Full media ID — MV_<tmdbId> for movies, TV_<tmdbId> for TV shows (e.g., TV_1396)

Example:

"TV_1396"

​
updatedAt
string<date-time>

ISO 8601 timestamp indicating when the history entry was last updated

Example:

"2023-01-15T00:00:00.000Z"

​
progress
number

Playback progress percentage (0-100)

Required range: 0 <= x <= 100
Example:

45.5

​
season
integer

Season number (required for TV shows)

Required range: x >= 1
Example:

1

​
episode
integer

Episode 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).

Required range: x >= 1
Example:

5

​
imported
string

Source of import (e.g., "trakt") if this item was imported

Example:

"trakt"

Response

Item added successfully

Confirmation response with the action taken. For exclusive lists (liked/disliked/super_liked), also includes added (which list the item was added to) and optionally removed (which list it was removed from).

​
message
string
required

Success message

Example:

"Item added successfully"

​
added
string

The list type the item was added to (for exclusive lists)

Example:

"liked"

​
removed
string | null

The list type the item was removed from, if any (for exclusive lists)

Example:

"disliked"