# Letterboxd API scraper — film details (rating, runtime, cast, crew, similar films), reviews, member profiles, diary, curated lists, and search from Letterboxd.com

> Full Letterboxd film detail by film slug or URL: title, year, directors, cast, genres, runtime, poster, IMDb/TMDb IDs, average rating, total ratings, watch count, like count, and list appearances.
> ReefAPI engine `letterboxd` · 11 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/letterboxd/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /letterboxd/v1/film — 1 credit
Full Letterboxd film detail by film slug or URL: title, year, directors, cast, genres, runtime, poster, IMDb/TMDb IDs, average rating, total ratings, watch count, like count, and list appearances.

**Parameters:**
- `film` (string, optional) — Letterboxd film slug, OR a full film URL (https://letterboxd.com/film/parasite-2019/) — the path is parsed to the slug.

**Returns:** film{} — title, year, directors, cast[], genres, runtime, poster, imdb_id/tmdb_id, avg_rating, rating_count, watch_count, like_count, list_count

**Example request body:**
```json
{
  "film": "parasite-2019"
}
```

### POST /letterboxd/v1/user — 1 credit
Public Letterboxd member profile and stats by username: display name, avatar, bio, film/list/follower counts, and the member's favourite films.

**Parameters:**
- `user` (string, required) — Letterboxd username (the handle in a profile URL), OR a profile URL.

**Returns:** profile{} — display_name, avatar, bio, films/lists/following/followers counts, favorite_films[]

**Example request body:**
```json
{
  "user": "dave"
}
```

### POST /letterboxd/v1/user_films — 1 credit
Paginated list of films a Letterboxd member has watched and rated, with their personal star rating for each.

**Parameters:**
- `user` (string, required) — Letterboxd username (the handle in a profile URL), OR a profile URL.
- `page` (integer, optional, default 1) — 1-based page number. Use meta.has_more to know when to stop; values < 1 clamp to 1.
- `per_page` (integer, optional) — Hint only — Letterboxd fixes the page size per view (films 72, reviews 12, diary/list 100); reported back in meta.per_page.

**Returns:** films[] (slug, name, url, user_rating); meta.page/per_page/has_more

**Example request body:**
```json
{
  "user": "dave"
}
```

### POST /letterboxd/v1/user_diary — 1 credit
Paginated diary entries for a Letterboxd member: film slug, name, watch date, and star rating for each viewing.

**Parameters:**
- `user` (string, required) — Letterboxd username (the handle in a profile URL), OR a profile URL.
- `page` (integer, optional, default 1) — 1-based page number. Use meta.has_more to know when to stop; values < 1 clamp to 1.
- `per_page` (integer, optional) — Hint only — Letterboxd fixes the page size per view (films 72, reviews 12, diary/list 100); reported back in meta.per_page.

**Returns:** entries[] (slug, name, watched_date, rating); meta.page/per_page/has_more

**Example request body:**
```json
{
  "user": "dave"
}
```

### POST /letterboxd/v1/list — 1 credit
A public Letterboxd curated film list: title, description, and the paginated film entries with user ratings.

**Parameters:**
- `user` (string, required) — Letterboxd username (the handle in a profile URL), OR a profile URL.
- `list` (string, required) — List slug (the segment after /list/ in a list URL).
- `page` (integer, optional, default 1) — 1-based page number. Use meta.has_more to know when to stop; values < 1 clamp to 1.
- `per_page` (integer, optional) — Hint only — Letterboxd fixes the page size per view (films 72, reviews 12, diary/list 100); reported back in meta.per_page.

**Returns:** username, slug, title, description, films[]; meta.page/per_page/has_more

### POST /letterboxd/v1/film_reviews — 1 credit
Paginated public reviews for a Letterboxd film: reviewer username, display name, star rating, review text, and like count.

**Parameters:**
- `film` (string, optional) — Letterboxd film slug, OR a full film URL (https://letterboxd.com/film/parasite-2019/) — the path is parsed to the slug.
- `page` (integer, optional, default 1) — 1-based page number. Use meta.has_more to know when to stop; values < 1 clamp to 1.
- `per_page` (integer, optional) — Hint only — Letterboxd fixes the page size per view (films 72, reviews 12, diary/list 100); reported back in meta.per_page.

**Returns:** reviews[] (username, display_name, rating, text, likes), film; meta.page/per_page/has_more

### POST /letterboxd/v1/browse — 1 credit
Browse Letterboxd films with optional genre / decade / year filters, ordered by popularity, rating, release date, or runtime (paginated): slug, name, URL, and average rating.

**Parameters:**
- `sort` (enum, optional, default "popular") — Ordering for the films browser. [one of: popular, rating, release, shortest, longest]
- `genre` (enum, optional) — Optional genre filter for the films browser (e.g. horror, science-fiction). Combine with sort to get e.g. highest-rated horror. [one of: action, adventure, animation, comedy, crime, documentary, drama, family, fantasy, history, horror, music, mystery, romance, science-fiction, thriller, tv-movie, war, western]
- `decade` (string, optional) — Optional decade filter, e.g. '1990s', '2010s'. Combine with sort and/or genre.
- `year` (integer, optional) — Optional release-year filter, e.g. 2019. Combine with sort and/or genre.
- `page` (integer, optional, default 1) — 1-based page number. Use meta.has_more to know when to stop; values < 1 clamp to 1.
- `per_page` (integer, optional) — Hint only — Letterboxd fixes the page size per view (films 72, reviews 12, diary/list 100); reported back in meta.per_page.

**Returns:** films[] (slug, name, url, avg_rating), sort, filters; meta.page/per_page/has_more

### POST /letterboxd/v1/film_similar — 1 credit
Films Letterboxd shows as similar/related to a given film: slug, name, URL — useful for recommendation and discovery off a single seed film.

**Parameters:**
- `film` (string, optional) — Letterboxd film slug, OR a full film URL (https://letterboxd.com/film/parasite-2019/) — the path is parsed to the slug.

**Returns:** similar_films[] (slug, name, url), film; meta.record_count

**Example request body:**
```json
{
  "film": "parasite-2019"
}
```

### POST /letterboxd/v1/lists_popular — 1 credit
Browse Letterboxd's most popular member-curated film lists for a time window (week/month/year/all): list title, owner username, list slug+URL, and a preview of the first films.

**Parameters:**
- `period` (enum, optional, default "week") — Time window for the popular-lists ranking. [one of: week, month, year, all]
- `page` (integer, optional, default 1) — 1-based page number. Use meta.has_more to know when to stop; values < 1 clamp to 1.
- `per_page` (integer, optional) — Hint only — Letterboxd fixes the page size per view (films 72, reviews 12, diary/list 100); reported back in meta.per_page.

**Returns:** lists[] (list_id, username, slug, title, url, preview_film_slugs[]), period; meta.page/per_page/has_more

### POST /letterboxd/v1/user_lists — 1 credit
The public film lists a Letterboxd member has created (paginated): list title, slug+URL, and a preview of the first films in each list.

**Parameters:**
- `user` (string, required) — Letterboxd username (the handle in a profile URL), OR a profile URL.
- `page` (integer, optional, default 1) — 1-based page number. Use meta.has_more to know when to stop; values < 1 clamp to 1.
- `per_page` (integer, optional) — Hint only — Letterboxd fixes the page size per view (films 72, reviews 12, diary/list 100); reported back in meta.per_page.

**Returns:** lists[] (list_id, username, slug, title, url, preview_film_slugs[]); meta.page/per_page/has_more

**Example request body:**
```json
{
  "user": "dave"
}
```

### POST /letterboxd/v1/search — 1 credit
Search Letterboxd for films, members, or curated lists by keyword — returns matching results with ratings and links.

**Parameters:**
- `query` (string, required) — Free-text search query.
- `type` (enum, optional, default "films") — Which catalog to search. [one of: films, members, lists]
- `page` (integer, optional, default 1) — 1-based page number. Use meta.has_more to know when to stop; values < 1 clamp to 1.
- `per_page` (integer, optional) — Hint only — Letterboxd fixes the page size per view (films 72, reviews 12, diary/list 100); reported back in meta.per_page.

**Returns:** films[] | members[] | lists[] (keyed by type), type, query; meta.page/per_page/has_more

## More
- Try it live, no code: https://reefapi.com/playground?engine=letterboxd
- Human docs page: https://reefapi.com/docs/letterboxd
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt