API reference

Quick start

No signup needed to try it — you get 2 requests per IP per day without a token. Hit Try It! below.

GET

Need more than 2 a day? Request a token — an admin reviews it and issues one. Already have an account? Check your quota and usage.

Authentication

Send your token as a Bearer header on every request. Paste it into the Credentials box above and every sample on this page updates to use it.

GET /api/actresses?limit=1

Keep your token server-side. It is a bearer credential — anyone holding it spends your quota. Never ship it in client-side JavaScript or a NEXT_PUBLIC_* variable. See React / Next.js for the proxy pattern.

A ?token= query parameter also works but is discouraged: it leaks into browser history, server logs and referrer headers.

Limits & quotas

Tier	How to use it	Limit	On breach
Free	No `Authorization` header	2 requests per IP per day	`429` Free limit reached
Token	`Authorization: Bearer …`	A monthly quota and a per-second rate limit, both set per account by the admin	`403` quota spent · `429` too fast
Unlimited	Same header, if the admin flagged your account unlimited	Neither limit applies	—

Monthly quotas reset at midnight on the 1st. The per-second bucket refills every second. Call /api/usage any time to see exactly where you stand — it doesn't cost you a request.

Get all FILM actresses

category=film restricts to cinema. Sorted by TMDB popularity by default.

GET

What you read back: data[] — each with name, tmdbId, profileImageUrl, filmographyCount. Page with ?page=2.

Get all TV actresses

Same endpoint, category=tv. Note TV entries often have fewer images on TMDB.

GET

What you read back: Identical shape to the film list.

Get SOUTH INDIAN actresses

Telugu, Tamil, Malayalam and Kannada leads. This list is curated to actresses born 1978 or later, so it skews current rather than historical.

GET

What you read back: Identical shape to the film list.

Get BHOJPURI actresses

Bhojpuri cinema leads, also curated to actresses born 1978 or later. TMDB coverage of this industry is thinner, so expect smaller filmographies.

GET

What you read back: Identical shape to the film list.

List actresses alphabetically

sort accepts popularity, name, or recent (last synced).

GET

What you read back: limit maxes out at 100 — page through for more.

Get one actress's movies and TV shows

The list endpoint omits filmography to stay small. Fetch the actress by id to get it. Each entry has mediaType "movie" or "tv" — filter client-side to separate them.

GET

What you read back: data.filmography[] — newest first. Each has title, releaseYear, character, rating, genres, posterUrl, and fullCast (top 15 billed).

const res = await fetch(BASE + '/api/actresses/53975', { headers });
const { data } = await res.json();

const movies = data.filmography.filter(f => f.mediaType === 'movie');
const shows  = data.filmography.filter(f => f.mediaType === 'tv');

console.log(data.name, '-', movies.length, 'films,', shows.length, 'shows');

Search by name (autocomplete)

Partial, case-insensitive. Also matches alternate spellings and known-for titles.

GET

What you read back: Same list shape. Use the returned _id to fetch the full record.

Get the cast of a film or show

Use the tmdbId from a filmography entry, and pass its mediaType as ?type=.

GET

What you read back: data.fullCast[] — top 15 billed, each with name, character and profileImageUrl. appearsIn[] lists actresses in this database credited on it.

Get an actress's images

gallery[] comes back on the detail endpoint. url is w500-sized; originalUrl is full resolution. Hotlink them — do not re-host.

GET

What you read back: data.gallery[] — filePath, url, originalUrl, width, height, voteAverage, source (profile or tagged).

Check how much quota you have left

Does not itself consume quota, and still answers after a 403.

GET

What you read back: quota.remaining, quota.resetsOn, and analysis.outlook (healthy | approaching-limit | on-track-to-exceed | exhausted).

GET `/api/actresses`

List actresses

Paginated list of stored actresses. Heavy fields (biography, gallery, filmography) are omitted here — use the detail endpoint for those.

Free tier or token Works with no token (capped per IP per day) or with an Authorization header (higher monthly quota and per-second rate limit).

Query Params

category string optional Defaults to all

Filter by industry. One value only — an actress is filed under exactly one. Accepts: film | tv | bhojpuri | south

page integer optional Defaults to 1

Page number. Accepts: >= 1

limit integer optional Defaults to 20

Results per page. Values above 100 are clamped. Accepts: 1 - 100

sort string optional Defaults to popularity

Ordering. "recent" sorts by last sync time. Accepts: popularity | name | recent

Request

GET

Response `200`

{
  "data": [
    {
      "_id": "6650f1a2c3d4e5f6a7b8c9d0",
      "name": "Deepika Padukone",
      "tmdbId": 53975,
      "category": "film",
      "popularity": 2.42,
      "profileImageUrl": "https://image.tmdb.org/t/p/w500/rzvv.jpg",
      "profileImageAvailable": true,
      "knownFor": [
        "Padmaavat",
        "Piku"
      ],
      "dateOfBirth": "1986-01-05",
      "placeOfBirth": "Copenhagen, Denmark",
      "careerStartYear": 2006,
      "careerLatestYear": 2025,
      "filmographyCount": 40,
      "lastSyncedAt": "2026-08-01T14:12:44.019Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 2,
    "total": 314,
    "totalPages": 157,
    "hasNext": true,
    "hasPrev": false
  },
  "filters": {
    "category": "film",
    "sort": "popularity"
  }
}

GET `/api/actresses/search`

Search actresses by name

Case-insensitive partial match against name, alternate spellings (TMDB also_known_as) and known-for titles. Returns an empty result set when q is blank.

Free tier or token Works with no token (capped per IP per day) or with an Authorization header (higher monthly quota and per-second rate limit).

Query Params

q string required Defaults to —

Search term. Partial names work. Accepts: any text

category string optional Defaults to all

Restrict to one industry. Accepts: film | tv | bhojpuri | south

page integer optional Defaults to 1

Page number. Accepts: >= 1

limit integer optional Defaults to 20

Results per page. Accepts: 1 - 100

Request

GET

Response `200`

{
  "query": "alia",
  "data": [
    {
      "_id": "6650f1a2c3d4e5f6a7b8c9d1",
      "name": "Alia Bhatt",
      "category": "film",
      "filmographyCount": 40
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

GET `/api/actresses/:id`

Get one actress in full

Complete record: biography, gallery, and full filmography with per-title cast. Filmography is sorted newest first; gallery is ordered by TMDB vote average. Every optional field ships with a companion *Available boolean.

Free tier or token Works with no token (capped per IP per day) or with an Authorization header (higher monthly quota and per-second rate limit).

Path Params

id string required Defaults to —

Accepts either identifier. Accepts: Mongo _id or TMDB person id

Request

GET

Response `200`

{
  "data": {
    "name": "Deepika Padukone",
    "tmdbId": 53975,
    "category": "film",
    "bio": "Deepika Padukone is an Indian actress…",
    "bioAvailable": true,
    "dateOfBirth": "1986-01-05",
    "dateOfBirthAvailable": true,
    "placeOfBirth": "Copenhagen, Denmark",
    "placeOfBirthAvailable": true,
    "nationality": "Denmark",
    "nationalityAvailable": true,
    "education": [],
    "educationAvailable": false,
    "isAlive": true,
    "gallery": [
      {
        "filePath": "/rzvv.jpg",
        "url": "https://image.tmdb.org/t/p/w500/rzvv.jpg",
        "originalUrl": "https://image.tmdb.org/t/p/original/rzvv.jpg",
        "width": 500,
        "height": 750,
        "voteAverage": 7.19,
        "source": "profile"
      }
    ],
    "filmography": [
      {
        "tmdbId": 447365,
        "mediaType": "movie",
        "title": "Padmaavat",
        "releaseYear": 2018,
        "character": "Rani Padmavati",
        "characterAvailable": true,
        "rating": 7.1,
        "voteCount": 412,
        "genres": [
          "Drama",
          "History"
        ],
        "overview": "Rani Padmavati, married to Maharawal Ratan Singh…",
        "overviewAvailable": true,
        "fullCast": [
          {
            "name": "Ranveer Singh",
            "character": "Sultan Alauddin Khilji",
            "order": 0,
            "profileImageUrl": "…"
          }
        ],
        "boxOfficeCollection": null,
        "boxOfficeAvailable": false
      }
    ],
    "filmographyCount": 40
  }
}

Errors

404

{
  "error": "Actress not found",
  "id": "999999"
}

GET `/api/titles/:tmdbId`

Get a movie or TV title

Served from the local store when any synced actress is credited on the title, otherwise fetched live from TMDB. The "source" field tells you which. "appearsIn" lists stored actresses credited on it.

Free tier or token Works with no token (capped per IP per day) or with an Authorization header (higher monthly quota and per-second rate limit).

Path Params

tmdbId integer required Defaults to —

The title id on TMDB. Accepts: TMDB movie or TV id

Query Params

type string optional Defaults to movie

Which TMDB namespace to look in. Wrong value gives a 404. Accepts: movie | tv

Request

GET

Response `200`

{
  "source": "database",
  "data": {
    "tmdbId": 447365,
    "mediaType": "movie",
    "title": "Padmaavat",
    "releaseYear": 2018,
    "rating": 7.1,
    "genres": [
      "Drama",
      "History"
    ],
    "fullCast": [
      {
        "name": "Ranveer Singh",
        "character": "Sultan Alauddin Khilji",
        "order": 0
      }
    ],
    "boxOfficeAvailable": false
  },
  "appearsIn": [
    {
      "name": "Deepika Padukone",
      "tmdbId": 53975,
      "character": "Rani Padmavati"
    }
  ]
}

Errors

404

{
  "error": "Title not found",
  "tmdbId": "999999",
  "type": "movie"
}

POST `/api/access-request`

Request an API token

Creates a pending request for an admin to review. No token is issued here — an admin approves it and sends you the token. Submitting twice with the same email returns 409.

Free / no token Works without any credentials, but capped per IP per day.

Body Params application/json

email string required

Valid email address. One request per email.

name string required

Your name. Minimum 2 characters.

reason string required

What you are building. Minimum 10 characters.

Request

POST /api/access-request

Response `200`

{
  "message": "Access request received and is pending admin review",
  "requestId": "6650f9b1c3d4e5f6a7b8c9d1",
  "status": "pending",
  "note": "Your token will be issued by an admin once approved."
}

Errors

400

{
  "error": "Validation failed",
  "details": [
    "A valid email is required"
  ]
}

409

{
  "error": "A request for this email is already pending review"
}

GET `/api/usage`

Check your quota and usage

Full report for the token you send: remaining quota, reset date, burn rate, and a projection of where you will land by month end. This endpoint does NOT consume quota, and keeps answering even after you have been cut off with a 403 — so you can always see when your quota resets.

Token required Send your API token. Does not count against your quota.

Request

GET

Response `200`

{
  "account": {
    "email": "you@example.com",
    "name": "Your Name",
    "status": "approved",
    "tokenIssuedAt": "2026-08-01T10:00:00.000Z",
    "memberSince": "2026-07-28T09:15:00.000Z"
  },
  "quota": {
    "unlimited": false,
    "monthlyLimit": 5000,
    "usedThisMonth": 1284,
    "remaining": 3716,
    "percentUsed": 25.7,
    "resetsOn": "2026-09-01T00:00:00.000Z",
    "daysUntilReset": 31
  },
  "rateLimit": {
    "unlimited": false,
    "requestsPerSecond": 5
  },
  "analysis": {
    "outlook": "healthy",
    "daysElapsedThisWindow": 1,
    "averageRequestsPerDay": 1284,
    "projectedUsageAtMonthEnd": 41088,
    "daysUntilExhaustedAtCurrentRate": 2,
    "lastRequestAt": "2026-08-01T14:22:10.441Z"
  }
}

Errors

401

{
  "error": "Missing API token",
  "action": "Send it as: Authorization: Bearer <token>"
}

POST `/api/usage/check`

Look up quota by email

Check an account's status and remaining quota using the email it was registered with — useful when you have misplaced your token, or want to see whether your request has been approved yet. Never returns the token itself. Also accepts GET /api/usage/check?email=you@example.com.

Free / no token Works without any credentials, but capped per IP per day.

Body Params application/json

email string required

The email you submitted on the access request.

Request

POST /api/usage/check

Response `200`

{
  "account": {
    "email": "you@example.com",
    "name": "Your Name",
    "status": "approved"
  },
  "quota": {
    "unlimited": false,
    "monthlyLimit": 5000,
    "usedThisMonth": 1284,
    "remaining": 3716,
    "percentUsed": 25.7,
    "resetsOn": "2026-09-01T00:00:00.000Z",
    "daysUntilReset": 31
  },
  "rateLimit": {
    "unlimited": false,
    "requestsPerSecond": 5
  },
  "analysis": {
    "outlook": "healthy",
    "averageRequestsPerDay": 1284,
    "projectedUsageAtMonthEnd": 41088
  }
}

Errors

400

{
  "error": "A valid email is required",
  "field": "email"
}

404

{
  "error": "No access request found for that email",
  "action": "Submit POST /api/access-request to apply for a token"
}

GET `/api`

Service metadata

Endpoint index, free-tier limit and attribution. Never rate limited.

Free / no token Works without any credentials, but capped per IP per day.

Request

GET

Response `200`

{
  "name": "bolly-cast-api",
  "endpoints": {
    "GET /api/actresses": "category=film|tv|bhojpuri|south&page=&limit=&sort="
  }
}

GET `/api/health`

Health check

Liveness probe. Never rate limited.

Free / no token Works without any credentials, but capped per IP per day.

Request

GET

Response `200`

{
  "status": "ok",
  "uptime": 1423.8
}

Response headers

Every gated response reports where you stand, so you can back off before you get blocked.

Header	Meaning
`X-RateLimit-Tier`	free, token, or unlimited
`X-RateLimit-Limit`	Requests allowed — per day (free) or per second (token)
`X-RateLimit-Remaining`	How many remain in the current window
`X-Quota-Limit`	Your monthly request allowance
`X-Quota-Used`	Requests used this month
`X-Quota-Remaining`	Monthly requests left
`X-Quota-Resets-On`	ISO timestamp of the next monthly reset
`Retry-After`	Seconds to wait, present on 429 responses

Error codes

400 Request body failed validation (access request only).

{
  "error": "Validation failed",
  "details": [
    "reason must be at least 10 characters"
  ]
}

401 Token missing, malformed, expired, or superseded by a newer one.

{
  "error": "Invalid or expired API token"
}

403 Monthly quota used up. Resets on the 1st of next month.

{
  "error": "Monthly quota exceeded",
  "monthlyLimit": 1000,
  "usedThisMonth": 1000,
  "resetsOn": "2026-09-01T00:00:00.000Z"
}

404 No such actress, title or endpoint.

{
  "error": "Actress not found"
}

409 An access request for that email already exists.

{
  "error": "A request for this email is already pending review"
}

429 Free daily limit reached, or per-second rate limit exceeded with a token.

{
  "error": "Free limit reached",
  "action": "Submit POST /api/access-request to get a token"
}

React / Next.js

Next.js server component — recommended

// app/actresses/page.tsx
async function getActresses() {
  const res = await fetch(`${process.env.BOLLY_API_URL}/api/actresses?category=film&limit=24`, {
    headers: { Authorization: `Bearer ${process.env.BOLLY_API_TOKEN}` },
    next: { revalidate: 3600 },   // cache an hour — kind to your monthly quota
  });
  if (!res.ok) throw new Error(`API ${res.status}`);
  return res.json();
}

export default async function Page() {
  const { data } = await getActresses();
  return <ul>{data.map((a) => <li key={a._id}>{a.name}</li>)}</ul>;
}

Next.js route handler as a proxy

Lets client components query without ever seeing the token.

// app/api/actresses/route.ts
export async function GET(req: Request) {
  const qs = new URL(req.url).searchParams.toString();
  const upstream = await fetch(`${process.env.BOLLY_API_URL}/api/actresses?${qs}`, {
    headers: { Authorization: `Bearer ${process.env.BOLLY_API_TOKEN}` },
  });
  return new Response(await upstream.text(), {
    status: upstream.status,
    headers: { 'Content-Type': 'application/json' },
  });
}

React with axios

import axios from 'axios';

const bolly = axios.create({ baseURL: '/api' });  // your own proxy, not this host

bolly.interceptors.response.use(null, (error) => {
  const { status, data, headers } = error.response ?? {};
  if (status === 429) throw new Error(`Rate limited — retry in ${headers['retry-after']}s`);
  if (status === 403) throw new Error(`Quota exhausted, resets ${data.resetsOn}`);
  throw error;
});

Handling missing data

Branch on the *Available flag rather than truthiness, so an empty string is never mistaken for a fact:

<dd>{actress.placeOfBirthAvailable ? actress.placeOfBirth : <em>Not available</em>}</dd>

Data integrity

Every value comes from TMDB. Nothing is generated, inferred, scraped or guessed.
Fields TMDB does not provide come back as null (or []) with a companion *Available: false flag — never a placeholder, never a substitute.
education is always empty: TMDB publishes no education data, and no other source is consulted.
boxOfficeCollection is entered manually with a cited source, or left null. Never estimated.
Only living people are stored. Anyone with a TMDB deathday is skipped and logged.
Images are TMDB CDN URLs plus metadata — no binary is downloaded or re-hosted. Coverage is uneven; many television actresses have one image or none.
There are no appearance, body or physical-attribute fields anywhere in the schema.

This product uses the TMDB API but is not endorsed or certified by TMDB. Keep that attribution in anything you build on this data.

Machine-readable version of this page: GET /api/docs

Quick start

Authentication

Limits & quotas

How do I…

Get all FILM actresses

Get all TV actresses

Get SOUTH INDIAN actresses

Get BHOJPURI actresses

List actresses alphabetically

Get one actress's movies and TV shows

Search by name (autocomplete)

Get the cast of a film or show

Get an actress's images

Check how much quota you have left

API reference

GET /api/actresses

Query Params

Request

Response 200

GET /api/actresses/search

Query Params

Request

Response 200

GET /api/actresses/:id

Path Params

Request

Response 200

Errors

GET /api/titles/:tmdbId

Path Params

Query Params

Request

Response 200

Errors

POST /api/access-request

Body Params application/json

Request

Response 200

Errors

GET /api/usage

Request

Response 200

Errors

POST /api/usage/check

Body Params application/json

Request

Response 200

Errors

GET /api

Request

Response 200

GET /api/health

Request

Response 200

Response headers

Error codes

React / Next.js

Next.js server component — recommended

Next.js route handler as a proxy

React with axios

Handling missing data

Data integrity

GET `/api/actresses`

Response `200`

GET `/api/actresses/search`

Response `200`

GET `/api/actresses/:id`

Response `200`

GET `/api/titles/:tmdbId`

Response `200`

POST `/api/access-request`

Response `200`

GET `/api/usage`

Response `200`

POST `/api/usage/check`

Response `200`

GET `/api`

Response `200`

GET `/api/health`

Response `200`