{"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.","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'.","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","movies":"/v1/movies","movie":"/v1/movies/{slug}","refresh":"/v1/movies/{slug}/refresh","contentReports":"/v1/content-reports","takedowns":"/v1/takedowns"},"telling_us_we_are_wrong":{"how":"POST /v1/content-reports with the movie UUID, a category and 20-2000 characters.","effect":"Files a private report and immediately queues a re-verification. It never edits the catalog directly, and it closes itself once that re-verification runs."},"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":{"enabled":true,"status":"approved","attribution":"This product uses the TMDB API but is not endorsed or certified by TMDB."}}