Public API

SubKong Subtitle API

Access subtitles from multiple sources through a single simple API. Search by IMDb ID and language, optionally filter TV series by season and episode, and receive direct download endpoints.

IMDbthe_maidthe_manUser Subtitles

Endpoint

The main subtitle endpoint is:

Example

GET /api/v1/subtitles

The endpoint accepts query parameters to identify the title and filter the returned subtitles.

Parameters

imdb_idstringrequired

IMDb identifier of the movie or TV series. Example: tt22084616

languagestringrequired

Language of the requested subtitles. Example: English

seasoninteger

TV season number. Use this only for TV series.

episodeinteger

TV episode number. Requires a season parameter.

Basic Request

To retrieve English subtitles for Spider-Man: Brand New Day, send a GET request with its IMDb ID and language.

Example

GET /api/v1/subtitles?imdb_id=tt22084616&language=English

The API searches all enabled subtitle sources and combines the results into one response.

Movies

Movies only require the IMDb ID and language. Season and episode parameters should not be supplied.

Example

GET /api/v1/subtitles?imdb_id=tt22084616&language=English

The response may contain subtitles from the_maid, the_man, and registered users.

TV Series

TV subtitles support both season and episode filtering. For example, Game of Thrones uses IMDb ID tt0944947.

All episodes in a season

Example

GET /api/v1/subtitles?imdb_id=tt0944947&language=English&season=1

Specific episode

Example

GET /api/v1/subtitles?imdb_id=tt0944947&language=English&season=1&episode=3

Note: An episode cannot be requested without specifying its season.

Subtitle Sources

The API combines subtitles from multiple providers into one unified response.

the_maid

Subtitles provided by the OpenSubtitles database.

the_man

Subtitles provided by the SubDL database.

user

Subtitles uploaded by SubKong users.

Response

A successful request returns a JSON object containing the request information and an array of subtitles. Results can come from the_maid, the_man, or user uploads.

Example

{
  "success": true,
  "imdb_id": "tt0944947",
  "language": "english",
  "season": 1,
  "episode": 3,
  "count": 3,
  "subtitles": [
    {
      "source": "user",
      "language": "English",
      "name": "Game.of.Thrones.S01E03.1080p",
      "MovieReleaseName": "Game.of.Thrones.S01E03.1080p",
      "season": 1,
      "episode": 3,
      "format": "srt",
      "SubFormat": "srt",
      "downloads": 12,
      "username": "example_user",
      "user_id": 6,
      "donation_url": null,
      "uploaded_at": "2026-08-27T10:00:00.000Z",
      "download": "/api/v1/download/user/6"
    },
    {
      "source": "the_man",
      "language": "English",
      "name": "Game.of.Thrones.S01E03.1080p",
      "MovieReleaseName": "Game.of.Thrones.S01E03.1080p",
      "season": 1,
      "episode": 3,
      "format": "srt",
      "SubFormat": "srt",
      "tmdb_id": "1399",
      "imdb_id": "tt0944947",
      "download": "/api/v1/download/the_man/TOKEN"
    },
    {
      "source": "the_maid",
      "language": "English",
      "name": "Game.of.Thrones.S01E03.1080p",
      "MovieReleaseName": "Game.of.Thrones.S01E03.1080p",
      "season": 1,
      "episode": 3,
      "format": "srt",
      "SubFormat": "srt",
      "ISO639": "en",
      "MovieYear": 2011,
      "MovieKind": "tv",
      "imdb_id": "tt0944947",
      "download": "/api/v1/download/the_maid/TOKEN"
    }
  ]
}

Downloading Subtitles

Every subtitle returned by the API contains a dedicated download endpoint.

Example

GET /api/v1/download/the_man/TOKEN

The download path depends on the subtitle source. the_man and the_maid use secure download tokens, while user subtitles use their subtitle ID.

Source	Download endpoint
the_man	`/api/v1/download/the_man/:token`
the_maid	`/api/v1/download/the_maid/:token`
user	`/api/v1/download/user/:id`

JavaScript Example

Example using the browser Fetch API:

Example

const response = await fetch(
  "/api/v1/subtitles?imdb_id=tt0944947&language=English&season=1&episode=3"
);

const data = await response.json();

console.log(data.subtitles);

Each item contains a download URL that can be opened directly in the browser.

Python Example

Example

import requests

url = "https://subkong.com/api/v1/subtitles"

params = {
    "imdb_id": "tt0944947",
    "language": "English",
    "season": 1,
    "episode": 3
}

response = requests.get(
    url,
    params=params
)

data = response.json()

for subtitle in data["subtitles"]:
    print(subtitle["name"])
    print(subtitle["source"])
    print(subtitle["download"])

cURL Example

Example

curl "https://subkong.com/api/v1/subtitles?imdb_id=tt22084616&language=English"

Errors

The API returns an appropriate HTTP status code together with a JSON error message.

400Invalid or missing parameters

405HTTP method is not supported

500Internal server or database error

Example

{
  "success": false,
  "error": "Invalid IMDb id"
}

API Flow

1. Send an IMDb ID and language.

2. Optionally provide season and episode for TV.

3. The API searches the available subtitle databases, including the_maid, the_man, and user subtitles.

4. Results are normalized into a single format.

5. Each subtitle receives its own download endpoint.