API Documentation

MediaCanon provides a free, open JSON API for movie and TV metadata. No API keys. No rate limits. Just data.

Base URL

https://mediacanon.org/api

All endpoints return JSON. The API is read-only.

Data Schemas

Title

Base metadata for any movie or show.

{
  "id": number,
  "type": "movie" | "show",
  "display_name": string,
  "year": number | null,
  "imdb_id": string | null,
  "image_url": string | null,
  "created_at": datetime,
  "updated_at": datetime
}

Movie

A movie with embedded title metadata.

{
  "id": number,
  "title_id": number,
  "title": Title
}

Show

A TV show with embedded title metadata and seasons.

{
  "id": number,
  "title_id": number,
  "title": Title,
  "seasons": Season[]
}

Season

A season of a TV show.

{
  "id": number,
  "show_id": number,
  "season": number,
  "episodes": Episode[]
}

Episode

An episode of a TV show season.

{
  "id": number,
  "season_id": number,
  "episode": number,
  "display_name": string | null
}

Titles

Search across all movies and shows.

GET /api/titles

List titles with optional search and type filter. Returns up to 100 results.

Param	Type	Description
`q`	string	Search by display name (case-insensitive partial match)
`type`	string	Filter by type: `movie` or `show`

Response: Title[]

GET /api/titles?q=breaking&type=show

GET /api/titles/:id

Get a specific title by ID.

Response: Title

Movies

GET /api/movies/:id

Get a movie by ID, including full title metadata.

Response: Movie

GET /api/movies/12345

{
  "id": 12345,
  "title_id": 67890,
  "title": {
    "id": 67890,
    "type": "movie",
    "display_name": "The Matrix",
    "year": 1999,
    "imdb_id": "tt0133093",
    "image_url": null,
    "created_at": "2026-01-26T12:00:00Z",
    "updated_at": "2026-01-26T12:00:00Z"
  }
}

Shows

GET /api/shows/:id

Get a show by ID, including all seasons and episodes.

Response: Show (with nested seasons and episodes)

GET /api/shows/47214

{
  "id": 47214,
  "title_id": 123456,
  "title": {
    "display_name": "Breaking Bad",
    "year": 2008,
    "imdb_id": "tt0903747"
  },
  "seasons": [
    {
      "id": 341534,
      "show_id": 47214,
      "season": 1,
      "episodes": [
        {"id": 1001, "season_id": 341534, "episode": 1, "display_name": "Pilot"},
        {"id": 1002, "season_id": 341534, "episode": 2, "display_name": "Cat's in the Bag..."}
      ]
    },
    {
      "id": 341535,
      "show_id": 47214,
      "season": 2,
      "episodes": [...]
    }
  ]
}

GET /api/shows/:id/seasons

Get all seasons for a show (without episodes).

Response: Season[]

Seasons

GET /api/seasons/:id

Get a season by ID, including all episodes.

Response: Season (with nested episodes)

GET /api/seasons/:id/episodes

Get all episodes in a season.

Response: Episode[]

Episodes

GET /api/episodes/:id

Get a specific episode by ID.

Response: Episode

GET /api/episodes/341534

{
  "id": 341534,
  "season_id": 12345,
  "episode": 1,
  "display_name": "Pilot"
}

Usage Examples

cURL

curl https://mediacanon.org/api/titles?q=matrix
curl https://mediacanon.org/api/shows/47214
curl https://mediacanon.org/api/movies/12345

JavaScript

const res = await fetch('https://mediacanon.org/api/titles?q=breaking');
const titles = await res.json();
console.log(titles);

Python

import requests
titles = requests.get('https://mediacanon.org/api/titles?q=breaking').json()
print(titles)

Data Stats

~892,000 movies
~362,000 TV shows
~7.5 million episodes

Data sourced from IMDb datasets, updated periodically.

Rate Limits

None. Be reasonable.