TheIntroDB

https://theintrodb.org/docs
Admin
TheIntroDB is a crowdsourced database API that provides skip timestamps for movie and TV episode...
Tokens:5,211
Snippets:79
Trust Score:2
Update:3 months ago
Show doc for...
Tokens:
Raw
### 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"
}
```
Tokens:
Raw