API documentation

Fetch the best segment of each type for a movie or episode, adjusted for the requester's stream duration when given.

match reference: exact (stream duration matched within 2s), shifted (within 15s, timestamps adjusted for an assumed extra/missing logo or scene at the start), agnostic (no duration supplied, so no comparison was possible), out-of-range (closest available data differs too much to shift reliably — treat as an uncertain match in your UI).

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,
      "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
}

Submit a segment. Submitting implies agreement to publish under ODbL 1.0 + reciprocity (see terms). Resubmitting the same episode/type/duration within 24h edits your existing submission instead of creating a duplicate.

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)"],
  "message": "Submission accepted and published.",
  "license": "ODbL 1.0 + Service Provider Reciprocity ..." }

status is one of approved, pending, rejected, or (on a 409) already_approved.

Edit a submission's times. Re-runs review, so a previously auto-approved segment can drop back to pending if the new values no longer qualify.

{ "id": 42, "status": "pending", "auto_approved": false,
  "reasons": [...], "message": "Submission updated and sent back to review." }

Delete a submission.

{ "id": 42, "deleted": true }

Vote a segment up or down. Requires a real, ownable identity — an anonymous key (below) can't vote — and you can't vote on your own submission.

{ "segment_id": 42, "your_vote": 1,
  "votes": { "up": 6, "down": 1, "score": 5 } }

Search by name or IMDb id. Proxies TMDB (when configured) and always also checks titles already in the database.

curl "https://api.skipdb.tv/api/titles/search?q=Breaking%20Bad"

Title metadata with the season/episode list and a per-episode coverage matrix (which segment types have data).

The full open data dump of every approved segment — no user data. Licensed ODbL 1.0 + reciprocity. This is the guarantee that the data stays free. Cached for an hour; may 302-redirect to a static mirror.

Generate or reset your API key. GET returns the active key's prefix (not the secret); POST returns the plaintext key once and revokes any previous key; DELETErevokes it. Not available via API key — you can't bootstrap key management from a key.

// POST response (201)
{ "key": "skdb_live_...", "prefix": "skdb_live_ab12",
  "message": "Here is your API key. ..." }

Get an API key without signing up. Creates a blank, login-less user behind the scenes and returns its key (plaintext, once) — there's no account to recover it from, so save it immediately. Rate-limited per IP (5/hour). DELETE with the same key (via Authorization or X-API-Key) revokes it.

Anonymous keys can submit, edit, and delete their own segments the same as a full account — the one thing they can't do is vote on other people's submissions, since voting feeds reputation and abuse resistance that depend on a real, ownable identity.

// POST response (201)
{ "key": "skdb_live_...", "prefix": "skdb_live_cd34",
  "message": "Here is your anonymous API key. ..." }