IntroDBIntroDB

Docs / Reference

API reference

Read segment timestamps anonymously and submit new ones with a session or API key.

Base URL

All endpoints are served from a single origin. Reads are public and need no key.

Base URL
https://api.introdb.app

Authentication

  • Read segments

    Auth: None

    How: Anonymous, rate limited

  • Submit (web / app session)

    Auth: Clerk JWT

    How: Authorization: Bearer <token>

  • Submit (integrations)

    Auth: API key

    How: X-API-Key: idb_…

API keys are created from Account settings.

GET/segments

Every live segment for one episode or movie in a single call. Missing segments are null. This is the endpoint new integrations should use.

no_intro, no_recap and no_outro are true when the community confirmed the episode has none of that segment, so a null there means "nothing to skip" rather than "not timed yet".

Query parameters
imdb_idstringrequired
IMDb id, e.g. tt0903747.
seasoninteger
Season number. Required for TV.
episodeinteger
Episode number. Required for TV.
is_movieboolean
Set true for movies and omit season/episode.
Request
curl "https://api.introdb.app/segments?imdb_id=tt0903747&season=1&episode=1"
Response · 200
{
  "imdb_id": "tt0903747",
  "media_type": "tv",
  "is_movie": false,
  "season": 1,
  "episode": 1,
  "intro": {
    "start_sec": 2.5,
    "end_sec": 58,
    "start_ms": 2500,
    "end_ms": 58000,
    "confidence": 0.92,
    "submission_count": 14,
    "updated_at": "2026-09-12T21:03:17.409Z"
  },
  "recap": null,
  "outro": null,
  "post_credits": null,
  "no_intro": false,
  "no_recap": true,
  "no_outro": false
}
GET/intro

Intro only, for older clients. Same query as /segments for TV, returns the intro fields at the top level, or 404 when there is no live intro.

Request
curl "https://api.introdb.app/intro?imdb_id=tt0903747&season=1&episode=1"
GET/outro

Shortcut for a movie's end credits. Takes just imdb_id.

Request
curl "https://api.introdb.app/outro?imdb_id=tt0371746"
POST/segments/submitClerk JWT

Submit timestamps as a signed-in user. Clean matches go live immediately; outliers move into review.

Body
imdb_idstringrequired
IMDb id of the show or movie.
segment_typestringrequired
intro, recap, outro or post-credits.
start_secnumber | stringrequired
Segment start. See time formats.
end_secnumber | stringrequired
Segment end. See time formats.
seasoninteger
Required for TV.
episodeinteger
Required for TV.
is_movieboolean
Set true for movies.
TV intro
POST /segments/submit
Authorization: Bearer <clerk_token>
Content-Type: application/json

{
  "imdb_id": "tt0903747",
  "segment_type": "intro",
  "season": 1,
  "episode": 1,
  "start_sec": "00:00:02",
  "end_sec": "00:00:58"
}
Movie end credits
POST /segments/submit
Authorization: Bearer <clerk_token>
Content-Type: application/json

{
  "imdb_id": "tt0371746",
  "is_movie": true,
  "segment_type": "outro",
  "start_sec": "1:59:00",
  "end_sec": "2:06:00"
}
POST/submitAPI key

Same body as above, authenticated with an API key instead of a session. Built for players and scripts.

Recap via API key
POST /submit
X-API-Key: idb_...
Content-Type: application/json

{
  "imdb_id": "tt0903747",
  "segment_type": "recap",
  "season": 1,
  "episode": 2,
  "start_sec": 30,
  "end_sec": 135
}

Time formats

start_sec and end_sec accept plain seconds (150, 2.5) or clock strings (2:30, 1:02:30).

  • Intro

    Min: 5s

    Max: 180s (300s for Arabic titles)

  • Recap

    Min: 5s

    Max: 480s

  • Outro / end credits

    Min: 5s

    Max: 900s

  • Post-credits

    Min: 5s

    Max: 600s

Errors & limits

Errors return JSON with an error message. Bad query params are 400, missing data is 404, and rate-limited requests are 429 with limit and reset_at.

Interactive reference

The full OpenAPI spec with try-it-out lives at api.introdb.app.