Skip to content

Shows API

Endpoints for querying TV show information.

List Shows

GET /api/v1/shows

List all shows with optional filtering and pagination.

Query Parameters

Parameter Type Description
search string Search shows by title
tvdb_id integer Filter by TVDB ID
tmdb_id integer Filter by TMDB ID
page integer Page number (default: 1)
per_page integer Items per page (default: 20, max: 100)

Examples

curl "https://api.openskip.io/api/v1/shows?search=breaking"

curl "https://api.openskip.io/api/v1/shows?tvdb_id=81189"

curl "https://api.openskip.io/api/v1/shows?page=2&per_page=50"

Response

{
  "items": [
    {
      "id": 1,
      "tvdb_id": 81189,
      "tmdb_id": 1396,
      "imdb_id": "tt0903747",
      "title": "Breaking Bad",
      "year": 2008,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

Get Show

GET /api/v1/shows/{show_id}

Get details for a specific show.

Path Parameters

Parameter Type Description
show_id integer The show's database ID

Example

curl "https://api.openskip.io/api/v1/shows/1"

Response

{
  "id": 1,
  "tvdb_id": 81189,
  "tmdb_id": 1396,
  "imdb_id": "tt0903747",
  "title": "Breaking Bad",
  "year": 2008,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

List Show Episodes

GET /api/v1/shows/{show_id}/episodes

Get all episodes for a specific show.

Path Parameters

Parameter Type Description
show_id integer The show's database ID

Example

curl "https://api.openskip.io/api/v1/shows/1/episodes"

Response

{
  "items": [
    {
      "id": 1,
      "show_id": 1,
      "season": 1,
      "episode": 1,
      "title": "Pilot",
      "tvdb_episode_id": 349232,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": 2,
      "show_id": 1,
      "season": 1,
      "episode": 2,
      "title": "Cat's in the Bag...",
      "tvdb_episode_id": 349233,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 2
}

Get Specific Episode

GET /api/v1/shows/{show_id}/seasons/{season}/episodes/{episode}

Get a specific episode by show, season, and episode number.

Path Parameters

Parameter Type Description
show_id integer The show's database ID
season integer Season number
episode integer Episode number

Example

curl "https://api.openskip.io/api/v1/shows/1/seasons/1/episodes/1"

Response

{
  "id": 1,
  "show_id": 1,
  "season": 1,
  "episode": 1,
  "title": "Pilot",
  "tvdb_episode_id": 349232,
  "created_at": "2024-01-15T10:30:00Z"
}

Show Object

Field Type Description
id integer Database ID
tvdb_id integer TheTVDB.com ID
tmdb_id integer TheMovieDB.org ID
imdb_id string IMDB ID (e.g., "tt0903747")
title string Show title
year integer Year of first air date
created_at datetime When the record was created
updated_at datetime When the record was last updated

Episode Object

Field Type Description
id integer Database ID
show_id integer Parent show ID
season integer Season number
episode integer Episode number
title string Episode title
tvdb_episode_id integer TheTVDB.com episode ID
created_at datetime When the record was created