{"service":"bmdb","name":"Beet Movies Database API","status":"ok","version":"v1","start_here":"Pick a shelf below and call its example. Everything else is detail.","shelves":{"now_showing":{"what":"Released and still in its theatrical run window (opened within the last 45 days, in the requested market).","example":"/v1/movies?status=now_showing&country=IN&language=te","ordered_by":"Most recently opened first."},"upcoming":{"what":"Has a future release date in the requested market. Cancelled and postponed editions are excluded.","example":"/v1/movies?status=upcoming&country=IN&language=te","ordered_by":"Soonest next release first."},"all":{"what":"Every published film, including back catalog. Rarely what a consumer app wants.","example":"/v1/movies?country=IN","ordered_by":"Earliest release first."}},"narrowing_a_shelf":{"type":"theatrical, ott or tv. Cinemas and streaming are different screens; ask for one.","fields":"fields=list returns only what a poster grid binds — about a tenth of the bytes. fields=full is the default.","q":"Free-text search across titles, aliases and transliterations. Results carry the same fields as a shelf, so a result grid needs no follow-up calls.","paging":"limit (1-100) and offset. pagination.nextOffset is null when the shelf ends. A search pages through its best 100 matches, so its offset stays below 100.","example":"/v1/movies?status=now_showing&type=theatrical&fields=list&limit=20"},"reading_a_movie":{"title_and_synopsis":"Already resolved for the language you asked for. Do not pick from titles[] yourself.","which_date_to_show":"selectedRelease.release_date — the edition matching your country and language. firstReleaseDate and nextReleaseDate are convenience fields across the whole market.","how_certain_is_it":"selectedRelease.confidence_tier: 'confirmed' means the date is well corroborated; 'provisional' means it may still move. Render the difference.","why_it_is_certain":"selectedRelease.confidence_basis says how it earned that tier. 'corroboration' = two independent kinds of source agree. 'stability' = one source has held the same value across repeated checks over weeks. 'staff' and 'seed' are hand-entered. You rarely need this, but it is the honest answer to 'how do you know'.","how_it_is_known":"Every release carries verification: level (official, partner, corroborated, stable, staff, reported), the source classes behind it, and whether that evidence is stale or disputed. A postponed release stays listed with supersededBy naming the release that replaced it; it is never the next date. A cancelled release stays listed as cancelled, for its country only. A film's detail lists corrections[]: dates it published and then corrected.","when_we_last_checked":"selectedRelease.last_verified_at is when a source last re-observed this exact edition. Publication is a lease here: an edition nobody re-observes decays, and one its own source contradicts is withdrawn rather than served.","what_to_draw":"posterUrl is always safe to render — a real poster when we have one, the BMDB placeholder when we do not. poster stays null so you can tell them apart.","how_fresh_is_it":"freshness.stale says whether we are about to re-verify this record. You do not need to act on it; reading a stale film already queues the refresh."},"market":{"what":"country picks the release market; language picks the audio/presentation edition. Both change what a film looks like.","why_it_matters":"A Tamil original and its Telugu dub are the same film with different dates, runtimes and artwork.","defaults":"country=IN, language unset (returns the market's editions unfiltered)."},"endpoints":{"health":"/v1/health","pipelineHealth":"/v1/health/pipeline","movies":"/v1/movies","movie":"/v1/movies/{slug}","refresh":"/v1/movies/{slug}/refresh","contentReports":"/v1/content-reports","takedowns":"/v1/takedowns","beacon":"/v1/beacon","beetFeed":"/v1/integrations/beet/movies","artwork":"/v1/artwork/{assetId}.jpg","crawler":"/bot","reportForm":"/report.html","legal":"/legal"},"telling_us_we_are_wrong":{"how":"POST /v1/content-reports with the movie UUID, a category and 20-2000 characters, optionally the releaseId it is about. People can use the form at /report.html.","effect":"Files a private report and queues a re-verification, at most one per film every 6 hours. It never edits the catalog directly, and it closes itself once that re-verification runs. A report without an evidence URL that nothing reproduces closes after 7 days.","rights":"A report in category 'rights' is answered routed_legal and goes to a person; it never removes anything. To have artwork removed on receipt, file POST /v1/takedowns."},"counting_views":{"how":"POST /v1/beacon with {\"movieIds\": [uuid, ...], \"kind\": \"detail_view\"} from the reader's own device when a film is shown. kind is detail_view (the default), list_impression or search_hit. Send nothing else: no user, device or session identifier is accepted.","why":"GET answers are cached at the edge, and a cached answer is never counted, so counts from reads alone are a lower bound. A beacon is never cached, so each one is counted: once per film, per kind, per client every 10 minutes.","answer":"204 whether or not it was counted. Limited to 120 a minute per client IP."},"if_you_own_the_rights":{"how":"POST /v1/takedowns with scope, claimantName, claimantEmail, rightsBasis, statement, goodFaith, and either movieSlug or assetUrl.","effect":"Acts on receipt. The artwork stops being served before a person reviews the notice, and a person reviews it afterwards. Scope 'asset' removes one image, 'movie_artwork' all artwork for a film, 'movie' withdraws the record pending review.","note":"BMDB fetches artwork at its own direction and is the publisher, so this is a good-faith fast remedy, not an intermediary safe harbour."},"contract":"docs/openapi.yaml in the repository is the authority; it is enforced by contract tests in CI.","artwork":{"status":"licensed_only","what":"poster and backdrop are set only for artwork BMDB is licensed to publish; trailer is also set for an official YouTube trailer, which is embedded, never rehosted. Everything else is null, and posterUrl is the BMDB placeholder."}}