Mantra Movie API - Documentation

Authentication

All API endpoints require authentication via a Bearer token in the Authorization header.

Include your API key in every request:

Authorization: Bearer YOUR_API_KEY

Getting an API Key

WhatsApp +254743032398 Telegram @midknight_mantra

Example Request

// Using fetch (JavaScript)
fetch("https://movieapi.jabez.co.ke/api/v1/trending", {
  headers: {
    "Authorization": "Bearer Mantra_movieapi_your_key_here"
  }
})

# Using curl
curl -H "Authorization: Bearer Mantra_movieapi_your_key_here" \
  https://movieapi.jabez.co.ke/api/v1/trending

# Python
import requests

headers = {"Authorization": "Bearer Mantra_movieapi_your_key_here"}
response = requests.get("https://movieapi.jabez.co.ke/api/v1/trending", headers=headers)
data = response.json()

Rate Limits & Usage

To ensure fair usage, the API enforces rate limits and daily quotas.

Per-Minute Rate Limit

30 requests

Rolling 60-second window

Daily Quota

Varies per key

Default: 100/day, resets at midnight UTC

Key Expiration

Configurable

Keys can have optional expiry dates

CORS

Enabled

All origins allowed for browser apps

Rate Limit Headers

Every API response includes these headers:

Header	Description
X-RateLimit-Limit	Max requests per minute (30)
X-RateLimit-Remaining	Remaining requests in current window
X-RateLimit-Reset	Unix timestamp when the window resets

Base URL

All endpoints are relative to: https://movieapi.jabez.co.ke

Response Format

All successful responses follow this format:

{
  "status": 200,
  "success": true,
  "results": { ... }
}

GET /api/v1/homepage

Get homepage data including banners, featured movie sections, and platform lists.

Parameters

No parameters required.

Example Response

{
  "status": 200,
  "success": true,
  "results": {
    "operatingList": [
      {
        "type": "BANNER",
        "banner": {
          "items": [
            {
              "id": "...",
              "title": "Movie Title",
              "subjectId": "123456",
              "image": { "url": "https://..." }
            }
          ]
        }
      },
      {
        "type": "SUBJECTS_MOVIE",
        "title": "Trending Now",
        "subjects": [ ... ]
      }
    ],
    "platformList": [
      { "name": "Netflix" },
      { "name": "Disney" }
    ]
  }
}

GET /api/v1/search/:query

Search for movies and TV shows by title.

Parameters

Name	Type	Description
query	string required	Search term (URL path parameter)
page	number optional	Page number for pagination (default: 1)

Example Request

GET /api/v1/search/avatar?page=1

Example Response

{
  "status": 200,
  "success": true,
  "results": {
    "pager": {
      "hasMore": true,
      "nextPage": "2",
      "page": "1",
      "perPage": 24,
      "totalCount": 72
    },
    "items": [
      {
        "subjectId": "8906247916759695608",
        "title": "Avatar",
        "subjectType": 1,
        "genre": "Action,Adventure,Fantasy",
        ...
      }
    ]
  }
}

GET /api/v1/info/:id

Get detailed information about a specific movie or TV show.

Parameters

Name	Type	Description
id	string required	Subject ID of the movie or show

Subject Types

subjectType: 1 = Movie · subjectType: 2 = TV Series

Example Response

{
  "status": 200,
  "success": true,
  "results": {
    "subject": {
      "subjectId": "8906247916759695608",
      "subjectType": 1,
      "title": "Avatar",
      "description": "A paraplegic Marine...",
      "releaseDate": "2009-12-18",
      "duration": 9720,
      "genre": "Action,Adventure,Fantasy",
      "cover": { "url": "https://..." },
      "countryName": "United States",
      "imdbRatingValue": "7.9",
      "imdbRatingCount": 1400000,
      "hasResource": true,
      "trailer": { ... },
      "staffList": [ ... ]
    },
    "episodeList": []
  }
}

GET /api/v1/sources/:id

Get streaming and download links for a movie or TV episode in multiple qualities.

Parameters

Name	Type	Description
id	string required	Subject ID of the movie or show
season	number optional	Season number (for TV shows only)
episode	number optional	Episode number (for TV shows only)

Example Request (Movie)

GET /api/v1/sources/8906247916759695608

Example Request (TV Episode)

GET /api/v1/sources/123456?season=1&episode=3

Example Response

{
  "status": 200,
  "success": true,
  "results": [
    {
      "id": "1223777318477397960",
      "quality": "360p",
      "download_url": "https://...",
      "stream_url": "https://...",
      "size": "251658240",
      "format": "mp4"
    },
    {
      "quality": "720p",
      ...
    },
    {
      "quality": "1080p",
      ...
    }
  ]
}

GET /health

Check if the API is online and get basic stats. No authentication required.

Example Response

{
  "status": 200,
  "success": true,
  "uptime": 3600.5,
  "timestamp": "2026-02-22T12:00:00.000Z",
  "stats": {
    "totalKeys": 12,
    "activeKeys": 10,
    "totalRequests": 5432,
    "requestsToday": 234
  }
}

Error Handling

Error responses follow this format:

{
  "status": 401,
  "success": false,
  "error": "Missing or invalid Authorization header"
}

Status Codes

200Success

400Bad Request

401Unauthorized (missing/invalid API key)

403Forbidden (revoked/expired API key)

429Too Many Requests (rate limit or daily limit)

502Upstream API error

500Internal server error