Skip to main content

Documentation Index

Fetch the complete documentation index at: https://rocks.docs.rive.wtf/llms.txt

Use this file to discover all available pages before exploring further.

Every API key is tied to one IP. To apply for a key, DM southctrl on Discord.
Use the endpoint path below, replace the required params, and send Authorization: Bearer YOUR_API_KEY.

​
Most Used Endpoints

Get by Title

Look up one movie or show by title

Search

Search across many results

IMDb ID

Fetch a title by IMDb ID

Season

Get season episode data
Use search when the title may have multiple matches.

​
Get by Title

Get detailed information about a movie or TV show by title.

​
Endpoint

GET /api/omdb/title

​
Query Parameters

​
title
string
required
Movie or TV show title.
​
year
integer
Release year (optional, for better accuracy).
​
plot
string
default:"short"
Plot length. Options: short, full.
​
type
string
Media type. Options: movie, series, episode.

​
Example Request

cURL (Movie)
curl -X GET "https://rocks.rive.wtf/api/omdb/title?title=The%20Matrix&year=1999&plot=short" \
  -H "Authorization: Bearer YOUR_API_KEY"
cURL (Series)
curl -X GET "https://rocks.rive.wtf/api/omdb/title?title=Breaking%20Bad&type=series" \
  -H "Authorization: Bearer YOUR_API_KEY"
JavaScript
const response = await fetch('https://rocks.rive.wtf/api/omdb/title?title=Matrix&year=1999&plot=short', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);
Python
import requests

headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {
    'title': 'Matrix',
    'year': 1999,
    'plot': 'short'
}

response = requests.get(
    'https://rocks.rive.wtf/api/omdb/title',
    headers=headers,
    params=params
)

print(response.json())

​
Example Response

{
  "Title": "Matrix",
  "Year": "1999",
  "Rated": "R",
  "Released": "31 Mar 1999",
  "Runtime": "136 min",
  "Genre": "Action, Sci-Fi",
  "Director": "Lana Wachowski, Lilly Wachowski",
  "Writer": "Lilly Wachowski, Lana Wachowski",
  "Actors": "Keanu Reeves, Laurence Fishburne, Carrie-Anne Moss",
  "Plot": "When a beautiful stranger leads computer hacker Neo to a forbidding underworld, he discovers the shocking truth--the life he knows is the elaborate deception of an evil cyber-intelligence.",
  "Language": "English",
  "Country": "United States, Australia",
  "Awards": "Won 4 Oscars. 42 wins & 52 nominations total",
  "Poster": "https://m.media-amazon.com/images/M/MV5BN2NmN2VhMTQtMDNiOS00NDlhLTliMjgtODE2ZTY0ODQyNDRhXkEyXkFqcGc@._V1_SX300.jpg",
  "Ratings": [
    {
      "Source": "Internet Movie Database",
      "Value": "8.7/10"
    },
    {
      "Source": "Rotten Tomatoes",
      "Value": "83%"
    },
    {
      "Source": "Metacritic",
      "Value": "73/100"
    }
  ],
  "Metascore": "73",
  "imdbRating": "8.7",
  "imdbVotes": "2,217,731",
  "imdbID": "tt0133093",
  "Type": "movie",
  "DVD": "N/A",
  "BoxOffice": "$177,559,005",
  "Production": "N/A",
  "Website": "N/A",
  "Response": "True"
}

​
Get by IMDb ID

Get detailed information using an IMDb ID.

​
Endpoint

GET /api/omdb/id

​
Query Parameters

​
id
string
required
IMDb ID (e.g., tt0111161).
​
plot
string
default:"short"
Plot length. Options: short, full.

​
Example Request

cURL
curl -X GET "https://rocks.rive.wtf/api/omdb/id?id=tt0111161&plot=full" \
  -H "Authorization: Bearer YOUR_API_KEY"
JavaScript
const response = await fetch('https://rocks.rive.wtf/api/omdb/id?id=tt0111161&plot=full', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);
Python
import requests

headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {
    'id': 'tt0111161',
    'plot': 'full'
}

response = requests.get(
    'https://rocks.rive.wtf/api/omdb/id',
    headers=headers,
    params=params
)

print(response.json())

​
Example Response

{
  "Title": "Shawshank Redemption",
  "Year": "1994",
  "Rated": "R",
  "Released": "14 Oct 1994",
  "Runtime": "142 min",
  "Genre": "Drama",
  "Director": "Frank Darabont",
  "Writer": "Stephen King, Frank Darabont",
  "Actors": "Tim Robbins, Morgan Freeman, Bob Gunton",
  "Plot": "Chronicles the experiences of a formerly successful banker as a prisoner in the gloomy jailhouse of Shawshank after being found guilty of a crime he did not commit. film portrays the man's unique way of dealing with his new, torturous life; along the way he befriends a number of fellow prisoners, most notably a wise long-term inmate named Red.",
  "Language": "English",
  "Country": "United States",
  "Awards": "Nominated for 7 Oscars. 21 wins & 42 nominations total",
  "Poster": "https://m.media-amazon.com/images/M/MV5BMDAyY2FhYjctNDc5OS00MDNlLThiMGUtY2UxYWVkNGY2ZjljXkEyXkFqcGc@._V1_SX300.jpg",
  "Ratings": [
    {
      "Source": "Internet Movie Database",
      "Value": "9.3/10"
    },
    {
      "Source": "Rotten Tomatoes",
      "Value": "89%"
    },
    {
      "Source": "Metacritic",
      "Value": "82/100"
    }
  ],
  "Metascore": "82",
  "imdbRating": "9.3",
  "imdbVotes": "3,136,948",
  "imdbID": "tt0111161",
  "Type": "movie",
  "DVD": "N/A",
  "BoxOffice": "$28,767,189",
  "Production": "N/A",
  "Website": "N/A",
  "Response": "True"
}
Search for movies and TV shows.

​
Endpoint

GET /api/omdb/search

​
Query Parameters

​
query
string
required
Search query.
​
page
integer
default:"1"
Page number for results.
​
year
integer
Filter by year.
​
type
string
Filter by type. Options: movie, series, episode.

​
Example Request

cURL
curl -X GET "https://rocks.rive.wtf/api/omdb/search?query=Batman&page=1" \
  -H "Authorization: Bearer YOUR_API_KEY"
cURL (With Filters)
curl -X GET "https://rocks.rive.wtf/api/omdb/search?query=Star%20Wars&year=1977&type=movie" \
  -H "Authorization: Bearer YOUR_API_KEY"
JavaScript
const response = await fetch('https://rocks.rive.wtf/api/omdb/search?query=Batman&page=1', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);
Python
import requests

headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {
    'query': 'Batman',
    'page': 1
}

response = requests.get(
    'https://rocks.rive.wtf/api/omdb/search',
    headers=headers,
    params=params
)

print(response.json())

​
Example Response

{
  "Search": [
    {
      "Title": "Batman Begins",
      "Year": "2005",
      "imdbID": "tt0372784",
      "Type": "movie",
      "Poster": "https://m.media-amazon.com/images/M/MV5BMzA2NDQzZDEtNDU5Ni00YTlkLTg2OWEtYmQwM2Y1YTBjMjFjXkEyXkFqcGc@._V1_SX300.jpg"
    },
    {
      "Title": "Batman",
      "Year": "2022",
      "imdbID": "tt1877830",
      "Type": "movie",
      "Poster": "https://m.media-amazon.com/images/M/MV5BMmU5NGJlMzAtMGNmOC00YjJjLTgyMzUtNjAyYmE4Njg5YWMyXkEyXkFqcGc@._V1_SX300.jpg"
    },
    {
      "Title": "Batman v Superman: Dawn of Justice",
      "Year": "2016",
      "imdbID": "tt2975590",
      "Type": "movie",
      "Poster": "https://m.media-amazon.com/images/M/MV5BZTJkYjdmYjYtOGMyNC00ZGU1LThkY2ItYTc1OTVlMmE2YWY1XkEyXkFqcGc@._V1_SX300.jpg"
    }
  ],
  "totalResults": "632",
  "Response": "True"
}

​
Get Season

Get information about a specific season of a TV series.

​
Endpoint

GET /api/omdb/season

​
Query Parameters

​
title
string
TV series title (use either title or id).
​
id
string
IMDb ID (use either title or id).
​
season
integer
required
Season number.

​
Example Request

cURL (By Title)
curl -X GET "https://rocks.rive.wtf/api/omdb/season?title=Breaking%20Bad&season=1" \
  -H "Authorization: Bearer YOUR_API_KEY"
cURL (By ID)
curl -X GET "https://rocks.rive.wtf/api/omdb/season?id=tt0903747&season=3" \
  -H "Authorization: Bearer YOUR_API_KEY"
JavaScript
const response = await fetch('https://rocks.rive.wtf/api/omdb/season?title=Breaking Bad&season=1', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);
Python
import requests

headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {
    'title': 'Breaking Bad',
    'season': 1
}

response = requests.get(
    'https://rocks.rive.wtf/api/omdb/season',
    headers=headers,
    params=params
)

print(response.json())

​
Example Response

{
  "Title": "Breaking Bad",
  "Season": "1",
  "totalSeasons": "5",
  "Episodes": [
    {
      "Title": "Pilot",
      "Released": "2008-01-20",
      "Episode": "1",
      "imdbRating": "9.0",
      "imdbID": "tt0959621"
    },
    {
      "Title": "Cat's in the Bag...",
      "Released": "2008-01-27",
      "Episode": "2",
      "imdbRating": "8.6",
      "imdbID": "tt1054724"
    },
    {
      "Title": "...And the Bag's in the River",
      "Released": "2008-02-10",
      "Episode": "3",
      "imdbRating": "8.7",
      "imdbID": "tt1054725"
    }
  ],
  "Response": "True"
}
Use the IMDb ID when possible for more accurate results, especially for titles with similar names.