Repository navigation
TheIntroDB API: v2/v3 are being retired — 10-minute path to v4 #3264
Description
Hi - I maintain TheIntroDB, the community database behind the intro/recap/credits timestamps.
Short version: v1 is already gone, and v2 and v3 are now deprecated. They still answer GET /media, but they're frozen - no fixes, no new fields - and they're being removed. v4 is the only surface under active development, so anything built on v2/v3 is on borrowed time.
I scanned GitHub for API consumers and this project is one of them:
app/src/main/java/com/lagradost/cloudstream3/utils/videoskip/TheIntroDBSkip.kt- callshttps://api.theintrodb.org/v2/media
So the change lands on you. Nothing is on fire today, but the clock is running.
What actually changes
- base URL
v2->v4 - responses are keyed by
tvdb_id; thetmdb_idfield is gone from the body - segment shapes (
intro/recap/credits/preview,start_ms/end_ms) are unchanged POST /submitonly exists on v4 - if you submit on v2/v3 it already 404s- if your season/episode numbers come from Jellyfin/Plex/Emby display order, v4 takes
mapping=default|official|dvd|alternate|absolute|regionaland converts them. That is the one v4 feature worth adopting even if you only read.
Links
- API docs: https://theintrodb.org/docs
- OpenAPI spec (source of truth): https://theintrodb.org/openapi.yaml
- v3 -> v4 migration guide: https://github.com/TheIntroDB/theintrodb-npm/blob/main/docs/migration-v3-to-v4.md
- npm client:
npm i theintrodb@4
If you'd rather hand it to an agent, paste this into Claude Code / Codex / Cursor / whatever you use:
Update this repository to use TheIntroDB API v4. The v2/v3 endpoints it currently
calls are deprecated and will be shut down.
Reference material:
- OpenAPI spec (authoritative): https://theintrodb.org/openapi.yaml
- v3 -> v4 migration guide: https://github.com/TheIntroDB/theintrodb-npm/blob/main/docs/migration-v3-to-v4.md
- API docs: https://theintrodb.org/docs
- npm client v4: https://www.npmjs.com/package/theintrodb
Steps:
1. Find every call site hitting api.theintrodb.org - any hardcoded /v1, /v2 or /v3
path, base-URL constants, config files, and the `theintrodb` npm dependency.
2. Move them to /v4. v1 is removed (404). v2 and v3 only ever served GET /media;
any submit/flag/vote call must move to POST /v4/submit.
3. Update response handling: v4 bodies are keyed by tvdb_id and no longer carry
tmdb_id. Segment arrays keep their existing shape (start_ms/end_ms).
4. Where season/episode numbers come from a media server's display order rather
than TVDB's default order, pass mapping= (default|official|dvd|alternate|
absolute|regional) so reads and submissions resolve to the right episode.
5. If the repo uses the npm package: upgrade to theintrodb@4 and adapt to
getMedia() returning a discriminated union on kind ('media' | 'versions' |
'episodes'), MediaRecord.tmdbId -> tvdbId, and /submit returning
{ ok, submissions }.
6. Keep the diff minimal: no refactors, no unrelated dependency bumps, no
formatting churn.
7. Run the repo's tests and linters, and add a URL assertion test for /v4 if the
repo already tests this integration.
8. Report every file changed and open a PR titled "Update TheIntroDB API
integration to v4", including test results.
If the spec and the migration guide disagree, follow the OpenAPI spec. Do not
invent endpoints - everything v4 serves is in the spec.
If something in the migration doc doesn't match what you're seeing, reply here and I'll fix the doc rather than have you guess at it. Same if you're stuck on the mapping part - that's the piece most clients get wrong.
Activity
fire-light42 commentedon Oct 17, 2026
Thank you for the notification! This is more than sufficient to migrate it 👍
Update theintrodb to v4