Search Movies

This API allows developers to build full-scale movie catalogues. It retrieves rich metadata, cover images, torrent distributions, and more based on advanced search queries.

Note

• This endpoint utilizes a 12-hour edge cache.
• In some rare cases involving brand-new uploads, torrents may not be immediately available in the array.

Endpoint

POST /api/v1/movies/search

Request Parameters

The following parameters are accepted in the request body:

Field	Type	Required	Description	Example
query	string	Optional	Search query / Movie title.	"Inception"
page	integer	Optional	Page number for pagination.	1
limit	integer	Optional	Results per page (Max 50, Default 10).	10
genre	string	Optional	Genre filter (e.g., Action, Drama, Sci-Fi).	"Action"
sort_by	string	Optional	Sort by: title, year, rating, peers, seeds, download_count, like_count, date_added.	"rating"
min_rating	number	Optional	Minimum IMDb rating (0-9).	7.5

Request Examples

cURL

curl -X POST https://heavstal.com.ng/api/v1/movies/search \
-H "Content-Type: application/json" \
-H "x-api-key: <YOUR_API_KEY>" \
-d '{"query": "Inception", "limit": 1}'

JavaScript (Fetch)

const response = await fetch('https://heavstal.com.ng/api/v1/movies/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '<YOUR_API_KEY>'
  },
  body: JSON.stringify({
    query: "Inception",
    limit: 1
  })
});

const res = await response.json();
console.log(res.data.movies);

Heavstal SDK

import { movies } from '@heavstal/api';

// Search movies with filters
const results = await movies.search({
  query: "Inception",
  min_rating: 8.0
});

console.log(`Found ${results.count} results!`);

Python

import requests

url = "https://heavstal.com.ng/api/v1/movies/search"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "<YOUR_API_KEY>"
}
payload = {
    "query": "Inception",
    "limit": 1
}

response = requests.post(url, headers=headers, json=payload)
print(response.json()["data"]["movies"])

Response Examples

Success Response

{
  "status": "success",
  "creator": "HEAVSTAL TECH",
  "cached": true,
  "cache_ttl": 43190,
  "data": {
    "count": 1,
    "total": 1,
    "page": 1,
    "movies": [
      {
        "id": 1,
        "title": "Inception",
        "description": "A thief who steals corporate secrets through the use of dream-sharing technology...",
        "year": 2010,
        "rating": 8.8,
        "genres": ["Action", "Adventure", "Sci-Fi"],
        "poster": "https://yts.gg/assets/images/movies/inception_2010/large-cover.jpg",
        "torrents": [
          {
            "quality": "1080p",
            "type": "web",
            "size": "2.1 GB",
            "seeds": 1250,
            "peers": 340,
            "url": "https://yts.gg/torrent/download/..."
          }
        ]
      }
    ]
  }
}

Error Response

{
  "status": "error",
  "error": "No movies found matching your query."
}