Episodes API¶

Episodes are accessed through the Shows API. This page provides additional details about episode data.

Accessing Episodes¶

Episodes are accessed via their parent show:

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

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

See Shows API for full documentation.

Episode Object¶

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

Field	Type	Description
`id`	integer	Database ID (use for timestamp queries)
`show_id`	integer	Parent show's database ID
`season`	integer	Season number (0 for specials)
`episode`	integer	Episode number within season
`title`	string	Episode title (may be null)
`tvdb_episode_id`	integer	TheTVDB.com episode ID
`created_at`	datetime	When the record was created

Querying Timestamps by Episode¶

Once you have an episode ID, you can query its timestamps:

curl "https://api.openskip.io/api/v1/timestamps?episode_id=1"

Or query directly by show identifiers:

curl "https://api.openskip.io/api/v1/timestamps?tvdb_id=81189&season=1&episode=1"

See Timestamps API for more details.

Season Numbering¶

Season	Description
0	Specials (behind-the-scenes, extras)
1+	Regular seasons

Episode numbers reset within each season and start at 1.

Finding the Right Episode¶

Using TVDB ID (Recommended)¶

If your media player has TVDB metadata:

# Get the show first
curl "https://api.openskip.io/api/v1/shows?tvdb_id=81189"

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

Direct Timestamp Query¶

Or skip the episode lookup entirely and query timestamps directly:

curl "https://api.openskip.io/api/v1/timestamps?tvdb_id=81189&season=1&episode=1"