Endpoints

Browse & discovery

Paginated browsing with the website's filters, plus curated discovery shortcuts.

GET/api/v1/catalog

The catalog, filtered and paginated.

The workhorse: browse by media type, genre, year or year range, sorted the way the website sorts, 24 titles per page.

Parameter	In	Required	Description
media_type	query	no	movie \| series
genre	query	no	Exact genre name — enumerate them via /api/v1/genres.
year	query	no	Exact release year.
year_from / year_to	query	no	Release year range (1870–2100).
sort	query	no	top-rated (default) \| newest \| most-viewed
available	query	no	1 = only titles deliverable in the 𝕏TV library.
page	query	no	1-based page number.

$curl -H "Authorization: Bearer xtvdb_YOUR_KEY" \

"https://xtvdb.com/api/v1/catalog?media_type=series&genre=Drama&sort=top-rated&page=1"

Returns { data: Title[], meta: { page, page_size, total, total_pages } }

GET/api/v1/trending

What the network is actually watching.

Most-viewed titles across the 𝕏TV network, library titles only.

Parameter	In	Required	Description
media_type	query	no	movie \| series
limit	query	no	1–50, default 20.

$curl -H "Authorization: Bearer xtvdb_YOUR_KEY" \

"https://xtvdb.com/api/v1/trending?media_type=movie&limit=10"

Returns { data: Title[] }

GET/api/v1/new

Freshly added to the 𝕏TV library.

Titles in the order they became deliverable (available_since), newest first. The feed to watch if you announce new arrivals.

Parameter	In	Required	Description
media_type	query	no	movie \| series
page	query	no	1-based page number.

$curl -H "Authorization: Bearer xtvdb_YOUR_KEY" \

"https://xtvdb.com/api/v1/new?media_type=series"

Returns { data: Title[], meta: { page, page_size, total, total_pages } }

GET/api/v1/random

One random title.

The shortest path to “what should I watch tonight”. Never cached.

Parameter	In	Required	Description
available	query	no	1 = only 𝕏TV library titles.

$curl -H "Authorization: Bearer xtvdb_YOUR_KEY" \

"https://xtvdb.com/api/v1/random?available=1"

Returns { data: Title }

GET/api/v1/genres

Every genre present in the catalog.

Feed the values into /api/v1/catalog?genre=…

$curl -H "Authorization: Bearer xtvdb_YOUR_KEY" \

"https://xtvdb.com/api/v1/genres"

Returns { data: string[] }