# Comingsoon — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://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.

> Find movie showtimes, theater locations, and box office rankings across Italy with access to detailed movie and theater information. Search now-playing films by city, compare showtimes at different cinemas, and discover what's trending at the Italian box office.

**Category:** Entertainment | **Website:** [comingsoon.it/](https://comingsoon.it/) | **Docs:** [parse.bot/marketplace/c19b3c0a-2469-4c20-bc38-6fa004599a6f/comingsoon-it-api](https://parse.bot/marketplace/c19b3c0a-2469-4c20-bc38-6fa004599a6f/comingsoon-it-api)

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

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/comingsoon/`
**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

### Get box office italy

Returns the current Italian box office rankings with movie details, weekend and total gross revenue, screen count, and weeks in release. Rankings are ordered by weekend performance.

**Estimated cost:** Metered

_No parameters required._

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

### Get cities list

Returns all Italian cities and provinces that have cinemas listed on ComingSoon.it. Each city includes its slug for use in other endpoints. Movie counts may be null.

**Estimated cost:** Metered

_No parameters required._

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

### Get movie details

Returns complete metadata for a specific movie from its schema.org JSON-LD structured data including cast, directors, description, rating, trailer URL, and extended metadata parsed from the page. Requires both movie_id and movie_slug from get_movies_now_playing or get_box_office_italy results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `movie_id` | string | Yes | Numeric movie ID from get_movies_now_playing or get_box_office_italy results (e.g. '68151'). |
| `movie_slug` | string | Yes | Movie URL slug from get_movies_now_playing or get_box_office_italy results (e.g. 'scary-movie'). |

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

### Get movies in city

Returns all movies currently showing in a given Italian city. The movie IDs returned are city-specific showtime IDs (idf), suitable for get_showtimes_for_movie_in_city.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city_slug` | string | Yes | City slug from get_cities_list results (e.g. 'roma', 'milano', 'torino'). |

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

### Get movies now playing

Returns a paginated list of movies currently in Italian cinemas. Sortable by number of theaters showing the film or by audience rating. Returns movie ID and slug suitable for get_movie_details.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination (1-based). |
| `sort` | string | No | Sort order for the listing. |

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

### Get showtimes for movie in city

Returns showtimes for a specific movie in a specific city. Lists theaters showing the movie with hall names and schedule/price details. The movie_id is the city-specific idf value from get_movies_in_city.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city_slug` | string | Yes | City slug (e.g. 'roma', 'milano'). |
| `movie_id` | string | Yes | City-specific movie ID (idf) from get_movies_in_city results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/comingsoon/get-showtimes-for-movie-in-city \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"city_slug":"<string>","movie_id":"<string>"}'
```

### Get theater details

Returns full details for a specific cinema theater including postal address, geo coordinates, aggregate rating, and films currently showing. Requires city_slug, theater_slug, and theater_id from get_theaters_in_city.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city_slug` | string | Yes | City slug (e.g. 'roma'). |
| `theater_id` | string | Yes | Theater ID from get_theaters_in_city results (e.g. '467'). |
| `theater_slug` | string | Yes | Theater URL slug from get_theaters_in_city results (e.g. 'adriano-multisala'). |

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

### Get theaters in city

Returns all cinema theaters in a given Italian city. Each theater includes an ID and slug for use with get_theater_details.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city_slug` | string | Yes | City slug from get_cities_list results (e.g. 'roma', 'milano'). |

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

## Next steps

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