# Rotten Tomatoes — 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 for movies and TV shows, get detailed information like ratings and reviews, and browse curated collections to discover what to watch. Access comprehensive Rotten Tomatoes data including critic and audience scores, plot details, and user reviews all in one place.

**Category:** Entertainment | **Website:** [rottentomatoes.com/](https://rottentomatoes.com/) | **Docs:** [parse.bot/marketplace/edfd39ba-1041-4391-a924-24ec8a03491b/rottentomatoes-com-api](https://parse.bot/marketplace/edfd39ba-1041-4391-a924-24ec8a03491b/rottentomatoes-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/rotten-tomatoes/`
**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

### Browse movies

Browse movies by category and sort order. Returns a paginated list of movies with tomatometer ratings, release years, poster images, and URLs. Supports browsing movies currently in theaters or available at home. Paginates via cursor.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `after` | string | No | Pagination cursor from a previous response's endCursor. |
| `category` | string | No | Browse category: 'movies_at_home' or 'movies_in_theaters'. |
| `sort` | string | No | Sort order: 'popular' or 'newest'. |

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

### Get movie details

Retrieve full details for a movie by its slug. Returns structured schema.org metadata (cast, ratings, genre, director), an EMS ID for use with get_reviews, DTM analytics data, and streaming availability. The slug is the path segment from the Rotten Tomatoes movie URL (e.g. /m/the_dark_knight yields 'the_dark_knight').

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | Movie slug from the Rotten Tomatoes URL path (e.g. 'the_dark_knight', 'inception'). |

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

### Get reviews

Retrieve paginated critic or audience reviews for a movie or TV show. Requires the emsId obtained from get_movie_details or get_tv_show_details. Returns review text, critic information, score sentiment, and cursor-based pagination. Each page returns up to page_count reviews.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `after` | string | No | Pagination cursor from a previous response's endCursor. |
| `ems_id` | string | Yes | EMS ID of the movie or TV show (UUID format), obtained from get_movie_details or get_tv_show_details emsId field. |
| `item_type` | string | No | Content type: 'movies' or 'tv'. |
| `page_count` | integer | No | Number of reviews per page (max 20). |
| `review_type` | string | No | Review type: 'critic' or 'user'. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/rotten-tomatoes/get-reviews \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"after":"<string>","ems_id":"<string>","item_type":"<string>","page_count":"<integer>","review_type":"<string>"}'
```

### Get tv show details

Retrieve full details for a TV show by its slug. Returns structured schema.org metadata (cast, ratings, genre, seasons), an EMS ID for use with get_reviews, and DTM analytics data. The slug is the path segment from the Rotten Tomatoes TV URL (e.g. /tv/breaking_bad yields 'breaking_bad').

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | TV show slug from the Rotten Tomatoes URL path (e.g. 'breaking_bad', 'game_of_thrones'). |

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

### Search

Search for movies, TV shows, and people by keyword. Returns categorized results with titles, URLs, tomatometer scores, and release years where available. Results are not paginated; the site returns a fixed set of top matches per category.

**Estimated cost:** Metered

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

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/rotten-tomatoes/search \
  -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.