Criterion APIcriterion.com ↗
Access the Criterion Collection catalog, Current magazine posts, Top 10 lists, and Closet Picks via 8 structured endpoints returning titles, synopses, and more.
What is the Criterion API?
The Criterion Collection API provides 8 endpoints covering the full film catalog, editorial content from Current magazine, Top 10 lists, and Closet Picks. Use get_film_detail to retrieve a film's synopsis, director, special features, runtime, aspect ratio, and spine number, or use get_all_films with filters like country, decade, director slug, and genre to paginate the catalog programmatically.
curl -X GET 'https://api.parse.bot/scraper/c4a7e815-f1b8-4725-b565-87cb4f23aa80/get_all_films?sort=spine_number&country=Japan' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace criterion-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Criterion Collection SDK — browse, search, and explore editorial content."""
from parse_apis.criterion_collection_api import Criterion, FilmSort, FilmNotFound
client = Criterion()
# Browse Japanese films sorted by spine number
for film in client.films.browse(country="Japan", sort=FilmSort.SPINE_NUMBER, limit=5):
print(film.spine, film.title, film.director, film.year)
# Search for a specific film and drill into details
result = client.films.search(query="Seven Samurai", limit=1).first()
if result:
print(result.title, result.director, result.url)
# Explore Top 10 lists and read picks from the first one
top_list = client.top10lists.list(limit=1).first()
if top_list:
detail = top_list.picks.get()
print(detail.author)
for pick in detail.picks:
print(pick)
# Browse editorial posts and read the full content of one
post = client.posts.list(limit=1).first()
if post:
full = post.detail.get()
print(full.title, full.content[:100])
# Handle a film not found error
try:
client.films.get(url="https://www.criterion.com/films/99999-nonexistent")
except FilmNotFound as exc:
print(f"Film not found: {exc.url}")
print("exercised: films.browse / films.search / films.get / top10lists.list / picks.get / posts.list / detail.get")
Browse the Criterion Collection catalog with various filters. Returns a list of films with spine number, title, director, country, and year. The full catalog contains ~1800 films returned in a single page.
| Param | Type | Description |
|---|---|---|
| sort | string | Sort order for results. |
| genre | string | Filter by genre slug. |
| query | string | Search query within catalog. |
| decade | string | Filter by decade (e.g., 1960s). |
| format | string | Filter by format. |
| country | string | Filter by country (e.g., Japan, France). |
| director | string | Filter by director slug. |
{
"type": "object",
"fields": {
"count": "integer total number of films returned",
"films": "array of film objects with spine, title, director, country, year, and url"
},
"sample": {
"data": {
"count": 1847,
"films": [
{
"url": "https://www.criterion.com/films/351-grand-illusion",
"year": "1937",
"spine": "1",
"title": "Grand Illusion",
"country": "France",
"director": "Jean Renoir"
},
{
"url": "https://www.criterion.com/films/165-seven-samurai",
"year": "1954",
"spine": "2",
"title": "Seven Samurai",
"country": "Japan",
"director": "Akira Kurosawa"
}
]
},
"status": "success"
}
}About the Criterion API
Film Catalog
get_all_films returns an array of film objects — each with spine, title, director, country, year, and url — and accepts optional parameters for sort (spine_number, title, year, director), genre, decade, country, director, format, and a free-text query. get_film_detail takes a full film URL and returns the complete record including synopsis, features (a list of special features on the release), and a details array covering country, year, runtime, format, aspect ratio, language, and spine number. search_films accepts a query string and returns matching films and box sets with title, director, and URL.
Editorial Content
get_current_posts retrieves posts from the Current magazine landing page or from a specific category slug such as 1-essays, 2-interviews, 3-features, or 8-top-10-lists. Each post object includes title, author, category, date, and url. get_current_post_detail fetches the full text content of an individual post given its URL.
Top 10 Lists and Closet Picks
get_top10_lists returns a paginated collection of Top 10 list objects with title, author, url, and id. Pass a specific list URL to get_top10_list_detail to get the picks array (film titles), the list title, and the author name. get_closet_picks takes no parameters and returns the full set of Closet Picks entries, each with a title and url.
The Criterion API is a managed, monitored endpoint for criterion.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when criterion.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official criterion.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a searchable Criterion spine-number index filtered by country or decade using
get_all_films - Populate a film detail page with synopsis, runtime, aspect ratio, and special features via
get_film_detail - Aggregate all film essays and interviews from Current magazine using
get_current_postswith category slugs - Extract curated film picks from critic Top 10 lists using
get_top10_list_detail - Monitor new Closet Picks video additions by polling
get_closet_picks - Build a recommendation tool that cross-references director or country filters from
get_all_filmswith editorial posts fromget_current_posts - Index the full text of Current magazine essays for search or NLP using
get_current_post_detail
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Criterion have an official developer API?+
What does `get_all_films` return, and how granular are the filters?+
get_all_films returns a films array where each entry includes spine (the Criterion spine number), title, director, country, year, and url. You can filter by genre slug, country (e.g., Japan, France), decade (e.g., 1960s), director slug, and format, and sort by spine_number, title, year, or director. The count field indicates how many results matched.Does `get_film_detail` include streaming availability or purchase pricing?+
get_film_detail covers synopsis, features, and a details array with runtime, aspect ratio, format, language, and spine number, but does not include streaming availability, retail pricing, or in-stock status. You can fork this API on Parse and revise it to add an endpoint targeting that data.Can I retrieve user reviews or ratings for Criterion films?+
Are there pagination controls on `get_current_posts` and `get_top10_lists`?+
limit integer parameter that caps how many items are returned. There is no explicit page or offset parameter in the current spec, so limit is the primary control over result set size.