SkipDBSkipDB
Sign in

API documentation

Base URL: https://api.skipdb.tv. Reading is open and rate-limited (120 req/min). Writing requires a logged-in session or an API key (30 req/min). All timestamps are returned in both _ms and _sec. Data is licensed ODbL 1.0 unless you have explicit permission.

GET/api/segments

Fetch the best segments for a movie or episode. Query params: imdb_id (required), season, episode, type (intro | recap | outro | preview), and duration (stream length in seconds — pass this for the best results).

When duration is supplied, SkipDB returns the best-matching version and shifts timestamps for streams that differ by up to 15s — assuming an extra/missing logo or scene at the start. Passing seconds (not ms) also maximises CDN cache hit rates since encoding variations won't produce different URLs.

Each segment value is either the best result or null (no data yet). confidence is 0–1 based on how many submissions agree plus community votes. The match field indicates how well the result fits the requested duration: exact, shifted (timestamps adjusted for a stream with a slightly different intro/logo), agnostic (no duration was submitted so no comparison was possible), or out-of-range (the best available data is from a stream whose length differs too much to shift reliably — treat this as an uncertain match and reflect that in your UI).

intro_length_estimate_msis the median intro length for the season (when 80% of episodes agree within 15 s). When no intro segment exists for an episode, use this to offer a “skip ~Xs” button that advances playback by that amount (minus a few seconds to give the user time to click the button after the intro starts) rather than jumping to a specific timestamp.

curl "https://api.skipdb.tv/api/segments?imdb_id=tt0903747&season=1&episode=1&duration=2820"

{
  "imdb_id": "tt0903747", "season": 1, "episode": 1,
  "segments": {
    "intro": {
      "start_ms": 61000, "end_ms": 91000,
      "start_sec": 61,   "end_sec": 91,
      "match": "exact", "adjusted": false, "offset_ms": 0,
      "confidence": 0.93
    },
    "recap":   null,
    "outro":   { "start_ms": 2760000, "end_ms": 2820000, "match": "shifted", ... },
    "preview": { "start_ms": 2700000, "end_ms": 2760000, "match": "out-of-range", ... }
  },
  "intro_length_estimate_ms": 30000
}
POST/api/segments

Submit a segment. Auth via Authorization: Bearer skdb_… or X-API-Key (or a session cookie). Times accept *_ms (numbers) or *_sec (seconds or clock strings). Submitting implies agreement to publish under ODbL 1.0 (see terms).

curl -X POST https://api.skipdb.tv/api/segments \
  -H "Authorization: Bearer skdb_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "imdb_id": "tt0903747",
    "season": 1, "episode": 1,
    "segment_type": "intro",
    "start_ms": 61000, "end_ms": 91000,
    "duration_ms": 2820000
  }'

{ "id": 42, "status": "approved", "auto_approved": true,
  "reasons": ["matches an existing approved segment (consensus)"] }
POST/api/segments/{id}/vote

Vote a segment { "value": 1 } (good) or -1 (bad), or 0 to clear. Requires auth.

GET/api/titles/search?q=

Search by name or IMDb id. Returns TMDB matches (if configured) plus titles already in the database.

GET/api/titles/{imdbId}

Title metadata with the season/episode list and a per-episode coverage matrix.

GET/api/dump

The full open data dump of every approved segment — no user data. Licensed ODbL 1.0. This is the guarantee that the data stays free.

POST/api/keys

Generate or reset your API key (returns the plaintext once). GET returns the active key prefix; DELETE revokes it. Session only.