---
title: Catalog
description: Read movie, TV, and people data in a response shape that matches TMDB's API field for field.
section: Catalog
order: 1
---

# Catalog

Read movie, TV show, and people metadata in the same response shape TMDB's own v3 API returns.

The catalog surface exists so a client already built against TMDB doesn't need a rewrite. You point the base URL at `https://flicklist.tv/api/v3`, swap the key, and the request and response parsing code you already have keeps working. Movie and TV detail pages, the popular/trending/discover lists, search, and people all mirror TMDB's shapes, including `movie_details` and `tv_details`.

> [!REQUIRED]
> Every catalog endpoint needs a credential. Pass `api_key` as a query parameter, TMDB-style, or send `Authorization: Bearer <token>`. See [Authentication](/dev/authentication).

> [!TIP]
> If your existing code reads an API key from an environment variable and calls `api.themoviedb.org/3`, changing those two values is often the whole migration.

## Endpoint families

Full parameters and response schemas for every endpoint below live in the [API reference](/dev/api). This page groups them so you know where to look first.

| Family | Method + Path | What it returns |
| --- | --- | --- |
| Details | `GET /movie/{tmdb_id}` | Movie detail, TMDB `movie_details` shape. |
| Details | `GET /tv/{tmdb_id}` | TV show detail, TMDB `tv_details` shape. |
| Details | `GET /tv/{tmdb_id}/season/{season_number}` | Season detail with its episodes. |
| Popular / now playing / upcoming / airing | `GET /movie/popular` | Movies ranked by all-time popularity. |
| Popular / now playing / upcoming / airing | `GET /movie/now_playing` | Movies currently in theaters. |
| Popular / now playing / upcoming / airing | `GET /movie/upcoming` | Movies not yet released, without a trending fallback when the list is short. |
| Popular / now playing / upcoming / airing | `GET /tv/popular` | TV shows ranked by all-time popularity. |
| Popular / now playing / upcoming / airing | `GET /tv/airing_today` | Shows with an episode airing today. |
| Popular / now playing / upcoming / airing | `GET /tv/on_the_air` | Shows currently mid-season. |
| Trending | `GET /trending/{media_type}/{window}` | Trending movies or shows. `window` is `day` or `week`; both currently return the same daily snapshot. |
| Trending | `GET /trending/person/{window}` | Trending people, currently an alias of `/person/popular`. |
| Discover | `GET /discover/movie` | Movies filtered by genre, watch provider, language, release date, and sort order. |
| Discover | `GET /discover/tv` | The same filters, applied to TV shows. |
| Search | `GET /search/multi` | Movies and shows matching a query, combined. |
| Search | `GET /search/movie` | Movies matching a query. |
| Search | `GET /search/tv` | Shows matching a query. |
| Find by external ID | `GET /find/{external_id}` | The catalog item for an IMDb ID, a TVDB ID, or a FlickList `fldb` ID, detected from the ID's prefix. |
| Recommendations | `GET /movie/{tmdb_id}/recommendations` | Movies similar to the given title, one unpaginated batch. |
| Recommendations | `GET /tv/{tmdb_id}/recommendations` | Shows similar to the given title, one unpaginated batch. |
| Collections / networks / people | `GET /collection/{collection_id}` | A movie collection (franchise) and its member movies. |
| Collections / networks / people | `GET /network/{network_id}` | A TV network's name. |
| Collections / networks / people | `GET /person/popular` | People ranked by popularity, filtered to non-adult credits. |

## Worked example: movie detail, then discover

Look up a single movie by its TMDB ID.

:::tabs
```bash
curl "https://flicklist.tv/api/v3/movie/550?api_key=$API_KEY"
```
```javascript
const res = await fetch(
  `https://flicklist.tv/api/v3/movie/550?api_key=${apiKey}`
);
const movie = await res.json();
```
```python
import requests
r = requests.get(
    "https://flicklist.tv/api/v3/movie/550",
    params={"api_key": api_key},
)
movie = r.json()
```
:::

You get back the same fields a TMDB client already knows how to parse.

```json
{
  "id": 550,
  "title": "Fight Club",
  "release_date": "1999-10-15",
  "genres": [{ "id": 18, "name": "Drama" }],
  "vote_average": 8.4
  // … remaining movie_details fields
}
```

Now filter for something new to watch with `/discover/movie`.

:::tabs
```bash
curl "https://flicklist.tv/api/v3/discover/movie?api_key=$API_KEY&with_genres=18&sort_by=vote_average.desc"
```
```javascript
const res = await fetch(
  `https://flicklist.tv/api/v3/discover/movie?api_key=${apiKey}&with_genres=18&sort_by=vote_average.desc`
);
const page = await res.json();
```
```python
r = requests.get(
    "https://flicklist.tv/api/v3/discover/movie",
    params={"api_key": api_key, "with_genres": "18", "sort_by": "vote_average.desc"},
)
page = r.json()
```
:::

```json
{
  "page": 1,
  "results": [
    { "id": 550, "title": "Fight Club", "vote_average": 8.4 }
    // …
  ],
  "total_pages": 42,
  "total_results": 823
}
```

`sort_by` recognizes TMDB-style keys. Anything starting with `vote_average` sorts by rating, anything containing `date` sorts by year, anything starting with `original_title` sorts by title. Anything else falls back to popularity. Swap `/discover/movie` for `/discover/tv` and the same filters apply to shows, with `first_air_date` in place of `release_date`.

For the rest of the discover filters (`with_watch_providers`, `primary_release_year`, `with_keywords`, and more) and every other endpoint's full parameter list, see the [API reference](/dev/api).