# Filmaffinity — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search FilmAffinity's film database by title, director, genre, year, and more. Retrieve detailed movie information including cast, crew, synopsis, ratings, and user reviews. Access top-rated lists, box office rankings, theatrical and streaming releases, and full filmographies for cast and crew members.

**Category:** Entertainment | **Website:** [filmaffinity.com/](https://filmaffinity.com/) | **Docs:** [parse.bot/marketplace/3d87e305-0e06-482a-9c71-a7d9748c1915/filmaffinity-com-api](https://parse.bot/marketplace/3d87e305-0e06-482a-9c71-a7d9748c1915/filmaffinity-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/filmaffinity/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Advanced search

Perform an advanced search with multiple filters including search type, year range, country, and genre. Supports searching by title or director name. Without a types filter, defaults to title search.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country` | string | No | Country code filter (e.g. 'US') |
| `from_year` | string | No | Filter from year (e.g. '2005') |
| `genre` | string | No | Genre code filter |
| `query` | string | Yes | Search keyword or phrase |
| `to_year` | string | No | Filter to year (e.g. '2015') |
| `types` | string | No | Comma-separated search types to filter by: 'title', 'director', or 'title,director' |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/filmaffinity/advanced-search \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"country":"<string>","from_year":"<string>","genre":"<string>","query":"<string>","to_year":"<string>","types":"<string>"}'
```

### Get box office

Get current US weekly box office rankings. Returns rank, title, genre, weeks in theaters, weekend gross, and total gross for each entry. Data is updated weekly.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/filmaffinity/get-box-office \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get movie credits

Retrieve the full cast and crew credits for a movie, organized by role category (director, screenwriter, cast, music, cinematography, producer). Each person entry includes name and profile URL.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `film_id` | string | Yes | The numeric film ID from FilmAffinity (e.g. '971380') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/filmaffinity/get-movie-credits \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"film_id":"<string>"}'
```

### Get movie details

Retrieve full details of a specific movie or TV show by its FilmAffinity film ID. Includes title, year, cast, director, synopsis, rating, votes, genre, and critics reviews. The film_id is obtainable from search_movies, get_top_films, or advanced_search results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `film_id` | string | Yes | The numeric film ID from FilmAffinity (e.g. '971380') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/filmaffinity/get-movie-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"film_id":"<string>"}'
```

### Get movie rating

Get the FilmAffinity rating, vote count, and vote distribution for a movie. The distribution object maps score values (1-10) to percentage strings showing vote breakdown.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `film_id` | string | Yes | The numeric film ID from FilmAffinity (e.g. '971380') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/filmaffinity/get-movie-rating \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"film_id":"<string>"}'
```

### Get movies by year

List top-rated movies released in a specific year. Returns films from FilmAffinity's top-rated list filtered to the given year, ordered by rating descending.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `year` | string | Yes | The year to filter by (e.g. '2023', '1972') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/filmaffinity/get-movies-by-year \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"year":"<string>"}'
```

### Get person filmography

Retrieve filmography for a specific person by searching their name on FilmAffinity and filtering by role. Returns the list of films the person participated in for the specified role. If the person is not found by name search, falls back to advanced search.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Person name to search for (e.g. 'Tom Hanks', 'Christopher Nolan') |
| `role` | string | No | Role filter for filmography |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/filmaffinity/get-person-filmography \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"<string>","role":"<string>"}'
```

### Get top films

Retrieve ranked lists of top-rated movies with optional filters for genre, country, year range, and streaming platform. Returns paginated results using offset. Each page contains up to 30 films.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country` | string | No | Country code filter |
| `from_offset` | integer | No | Starting offset for pagination |
| `from_year` | string | No | Filter from year (e.g. '2000') |
| `genre` | string | No | Genre code filter (e.g. 'TH' for thriller) |
| `list_type` | string | No | List type identifier (e.g. 'top_1000_fa') |
| `platform` | string | No | Streaming platform code filter |
| `to_year` | string | No | Filter to year (e.g. '2023') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/filmaffinity/get-top-films \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"country":"<string>","from_offset":"<integer>","from_year":"<string>","genre":"<string>","list_type":"<string>","platform":"<string>","to_year":"<string>"}'
```

### Get us releases

Get theatrical or streaming releases in the US. Lists recently released or upcoming movies for the specified platform type.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `media_type` | string | No | Type of release to retrieve |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/filmaffinity/get-us-releases \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"media_type":"<string>"}'
```

### Get user reviews

Retrieve user reviews for a movie. Reviews are sourced from the Spanish-language version of FilmAffinity where user reviews are available. Returns paginated results with review title, text, author, rating, date, and helpfulness.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `film_id` | string | Yes | The numeric film ID from FilmAffinity (e.g. '971380') |
| `page` | integer | No | Page number for pagination |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/filmaffinity/get-user-reviews \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"film_id":"<string>","page":"<integer>"}'
```

### Search movies

Full-text search for movies and TV shows by title. Returns a list of matching results with basic metadata (film_id, title, year, director, cast). Rating and votes are not populated in search results — use get_movie_details or get_movie_rating for those. Pagination is not supported; all matching results are returned in a single page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword or phrase (e.g. 'inception', 'the godfather') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/filmaffinity/search-movies \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.