### Install TheIntroDB NPM package Source: https://theintrodb.org/docs Use this command to install the official typed API client package. ```bash npm install theintrodb ``` -------------------------------- ### Retrieve media timestamps via GET request Source: https://theintrodb.org/docs Examples of querying the /media endpoint for movies and TV episodes. ```http https://api.theintrodb.org/v3/media?tmdb_id=12345&duration_ms=7200000 ``` ```http https://api.theintrodb.org/v3/media?tmdb_id=67890&season=1&episode=1&duration_ms=2700000 ``` -------------------------------- ### Time Format Examples Source: https://theintrodb.org/docs Examples of supported time formats and null value handling for segment timestamps. ```json "start_sec": 30.5, "end_sec": 90.2 ``` ```json "start_ms": 30500, "end_ms": 90200 ``` ```json "start_sec": null, "end_sec": 45.0 ``` ```json "start_sec": null, "end_sec": null ``` -------------------------------- ### Submit Movie Intro Segment Source: https://theintrodb.org/docs Example request for submitting an intro segment for a movie using seconds. ```http POST https://api.theintrodb.org/v3/submit Authorization: Bearer YOUR_API_KEY Content-Type: application/json { "tmdb_id": 12345, "type": "movie", "segment": "intro", "start_sec": 30.5, "end_sec": 90.2, "imdb_id": "tt0111161", "video_duration_ms": 7200000 } ``` -------------------------------- ### Submit TV Credits Segment Source: https://theintrodb.org/docs Example request for submitting a credits segment for a TV episode. ```http POST https://api.theintrodb.org/v3/submit Authorization: Bearer YOUR_API_KEY Content-Type: application/json { "tmdb_id": 12345, "type": "tv", "season": "1", "episode": "1", "segment": "credits", "start_sec": 5400.0, "end_sec": null, "video_duration_ms": 2700000 } ``` -------------------------------- ### GET /media Source: https://theintrodb.org/docs Retrieve skip timestamps for a specific movie or TV episode using media identifiers. ```APIDOC ## GET /media ### Description Retrieve timestamps for a specific media item including intro, recap, credits, and preview segments. ### Method GET ### Endpoint https://api.theintrodb.org/v3/media ### Parameters #### Query Parameters - **tmdb_id** (integer) - Required (One of tmdb_id, imdb_id, or tvdb_id) - TMDB ID of the media item - **imdb_id** (string) - Required (One of tmdb_id, imdb_id, or tvdb_id) - IMDb ID of the media item - **tvdb_id** (integer) - Required (One of tmdb_id, imdb_id, or tvdb_id) - TVDB ID of the media item - **season** (integer) - Optional (TV only) - Season number (required for TV episodes) - **episode** (integer) - Optional (TV only) - Episode number (required for TV episodes) - **duration_ms** (integer) - Optional - Total video duration in milliseconds ### Response #### Success Response (200) - **tmdb_id** (integer) - TMDB ID of the media - **type** (string) - Media type (movie or tv) - **intro** (array) - List of intro timestamps - **recap** (array) - List of recap timestamps - **credits** (array) - List of credits timestamps - **preview** (array) - List of preview timestamps #### Response Example { "tmdb_id": 12345, "type": "movie", "intro": [ { "start_ms": null, "end_ms": 23000 } ], "recap": [ { "start_ms": 25000, "end_ms": 134000 } ], "credits": [ { "start_ms": 5801777, "end_ms": 6371111 }, { "start_ms": 6408000, "end_ms": null } ], "preview": [ { "start_ms": 1680000, "end_ms": 1740000 } ] } ``` -------------------------------- ### Handle 400 Bad Request Validation Error Source: https://theintrodb.org/docs Returned when input parameters fail validation, such as when segment end times are incorrectly configured relative to start times. ```json { "error": "end_sec must be greater than start_sec" } ``` -------------------------------- ### POST /submit Source: https://theintrodb.org/docs Submit segment timestamps for a media item. Requires an API key provided in the Authorization header. ```APIDOC ## POST /submit ### Description Submit segment timestamps for a media item. This endpoint requires authentication via an API key in the Authorization header. ### Method POST ### Endpoint https://api.theintrodb.org/v3/submit ### Parameters - **tmdb_id** (integer) - Required - TMDB ID of the media item (1-10,000,000) - **type** (string) - Required - Media type: "movie" or "tv" - **segment** (string) - Required - Segment type: "intro", "recap", "credits", or "preview" - **season** (string/number) - TV only - Season number (required for TV, null for movies) - **episode** (string/number) - TV only - Episode number (required for TV, null for movies) - **start_sec/end_sec** (number) - Optional - Time format in seconds with decimals - **start_ms/end_ms** (number) - Optional - Time format in milliseconds - **video_duration_ms** (integer) - Optional - Total video duration in milliseconds - **imdb_id** (string) - Optional - IMDB ID in format: tt followed by 7-8 digits ### Request Example { "tmdb_id": 12345, "type": "movie", "segment": "intro", "start_sec": 30.5, "end_sec": 90.2, "imdb_id": "tt0111161", "video_duration_ms": 7200000 } ### Response #### Success Response (200) - **ok** (boolean) - Status of the request - **submissions** (array) - List of submitted segments #### Response Example { "ok": true, "submissions": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "tmdbId": 12345, "type": "movie", "segment": "intro", "videoDurationMs": 7200000, "startMs": 30500, "endMs": 90200, "status": "pending", "weight": 1.0 } ] } ``` -------------------------------- ### Handle 401 Unauthorized Error Source: https://theintrodb.org/docs Returned when the request lacks valid authentication credentials. ```json { "error": "Unauthorized" } ``` -------------------------------- ### Error Handling Source: https://theintrodb.org/docs Standard error responses returned by the API when a request fails. ```APIDOC ## Error Handling ### 400 Bad Request Validation Error ```json { "error": "end_sec must be greater than start_sec" } ``` ### 401 Unauthorized Auth Error ```json { "error": "Unauthorized" } ``` ### 409 Conflict Duplicate Submission ```json { "error": "You have already submitted this exact segment for one or more episodes" } ``` ``` -------------------------------- ### Successful Submission Response Source: https://theintrodb.org/docs The JSON response returned upon a successful submission. ```json { "ok": true, "submissions": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "tmdbId": 12345, "type": "movie", "segment": "intro", "videoDurationMs": 7200000, "startMs": 30500, "endMs": 90200, "status": "pending", "weight": 1.0 } ] } ``` -------------------------------- ### Media timestamp response structure Source: https://theintrodb.org/docs The JSON response format for a successful media timestamp request. ```json { "tmdb_id": 12345, "type": "movie", "intro": [ { "start_ms": null, "end_ms": 23000 } ], "recap": [ { "start_ms": 25000, "end_ms": 134000 } ], "credits": [ { "start_ms": 5801777, "end_ms": 6371111 }, { "start_ms": 6408000, "end_ms": null } ], "preview": [ { "start_ms": 1680000, "end_ms": 1740000 } ] } ``` -------------------------------- ### Handle 409 Conflict Duplicate Submission Error Source: https://theintrodb.org/docs Returned when a submission is rejected because an identical segment has already been submitted for the specified episode. ```json { "error": "You have already submitted this exact segment for one or more episodes" } ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.