Quick Start Guide¶
Get up and running with the OpenSkip API in minutes.
Basic Usage¶
The OpenSkip API is free and requires no authentication for reading data.
Query Timestamps¶
The most common use case - get intro/outro times for an episode:
Response:
{
"items": [
{
"intro_start": 0.0,
"intro_end": 45.5,
"outro_start": 3420.0,
"outro_end": 3480.0
}
],
"total": 1
}
That's it!¶
Use the intro_end value to know when to stop skipping, and outro_start to know when credits begin.
Integration Examples¶
Python¶
import requests
def get_skip_times(tvdb_id: int, season: int, episode: int) -> dict | None:
"""Get intro/outro timestamps for an episode."""
response = requests.get(
"https://api.openskip.io/api/v1/timestamps",
params={
"tvdb_id": tvdb_id,
"season": season,
"episode": episode
}
)
data = response.json()
if data["total"] > 0:
return data["items"][0]
return None
# Example usage
timestamps = get_skip_times(tvdb_id=81189, season=1, episode=1)
if timestamps:
print(f"Skip intro at {timestamps['intro_end']} seconds")
JavaScript¶
async function getSkipTimes(tvdbId, season, episode) {
const params = new URLSearchParams({
tvdb_id: tvdbId,
season: season,
episode: episode
});
const response = await fetch(
`https://api.openskip.io/api/v1/timestamps?${params}`
);
const data = await response.json();
return data.total > 0 ? data.items[0] : null;
}
// Example usage
const timestamps = await getSkipTimes(81189, 1, 1);
if (timestamps) {
console.log(`Skip intro at ${timestamps.intro_end} seconds`);
}
Shell (curl + jq)¶
#!/bin/bash
TVDB_ID=81189
SEASON=1
EPISODE=1
INTRO_END=$(curl -s "https://api.openskip.io/api/v1/timestamps?\
tvdb_id=$TVDB_ID&season=$SEASON&episode=$EPISODE" | jq '.items[0].intro_end')
echo "Skip intro at $INTRO_END seconds"
Common Patterns¶
Caching Responses¶
Timestamp data rarely changes. Cache responses to reduce API calls:
import requests
from functools import lru_cache
@lru_cache(maxsize=1000)
def get_skip_times_cached(tvdb_id: int, season: int, episode: int):
response = requests.get(
"https://api.openskip.io/api/v1/timestamps",
params={"tvdb_id": tvdb_id, "season": season, "episode": episode}
)
return response.json()
Duration Matching¶
Match timestamps to your specific file version:
def get_skip_times_for_file(tvdb_id, season, episode, file_duration_ms):
response = requests.get(
"https://api.openskip.io/api/v1/timestamps",
params={
"tvdb_id": tvdb_id,
"season": season,
"episode": episode,
"duration_ms": file_duration_ms,
"tolerance": 5000 # 5 second tolerance
}
)
return response.json()
Handling Missing Data¶
Not all episodes have timestamps. Always handle empty responses:
timestamps = get_skip_times(tvdb_id, season, episode)
if timestamps is None:
# No data available - disable skip functionality
print("No skip data available for this episode")
else:
# Use timestamps
if timestamps.get("intro_end"):
enable_skip_intro(timestamps["intro_end"])
Next Steps¶
Build a Plugin¶
Ready to build something? Check out the full guide.