# Search and movie details

Use `GET /movies` to find catalog records, then `GET /movies/{movie}` for a film's full details. Search results are paginated and contain compact movie records.

## Match an external identifier

```sh
curl --get "$ATM_API_BASE_URL/movies" \
  --header "Authorization: Bearer $ATM_API_KEY" \
  --data-urlencode 'imdb_id=tt1375666'
```

Use `tmdb_id` for a numeric TMDB ID. Both filters return the normal list envelope, including an empty list when no match exists. Use the returned ATM `id` or `slug` in subsequent detail, content, and recommendation paths. Do not pass an IMDb ID as the `{movie}` path value.

## Combine filters

Filters narrow the same result set. This example finds dramas released from 2000 through 2020 with both a summary and an ending explanation:

```sh
curl --get "$ATM_API_BASE_URL/movies" \
  --header "Authorization: Bearer $ATM_API_KEY" \
  --data-urlencode 'genre=Drama' \
  --data-urlencode 'year_from=2000' \
  --data-urlencode 'year_to=2020' \
  --data-urlencode 'has=summary,ending' \
  --data-urlencode 'sort=-year' \
  --data-urlencode 'limit=20'
```

| Filter                                              | Behavior                                                                          |
| --------------------------------------------------- | --------------------------------------------------------------------------------- |
| `q`                                                 | Matches part of the title, ignoring case.                                         |
| `genre`, `language`                                 | Genre name and original language, such as `Drama` and `en`.                       |
| `year_from`, `year_to`                              | Inclusive release-year range.                                                     |
| `release_from`, `release_to`                        | Inclusive release-date range in `YYYY-MM-DD` format.                              |
| `person_id`, `company_id`                           | Movies associated with an ATM person or company ID.                               |
| `has`                                               | Requires every comma-separated content section.                                   |
| `tone`, `mood`, `pacing`, `intensity`, `complexity` | Filters on the movie's viewing profile. Use the accepted values in the reference. |

Sorting supports `id`, `title`, `release_date`, `-release_date`, `year`, and `-year`. A leading minus sign reverses date or year order. The default is `id`.

Use one value per parameter. Unknown or repeated parameters return `400`; use `has=summary,ending`, not repeated `has` parameters. See [Pagination](/pagination) to continue a search.

## Retrieve details

```http
GET /movies/{movie}
```

Replace `{movie}` with a returned ID or slug. The response's `data` object includes:

- Title, release information, runtime, genres, images, and external IDs.
- Cast and directors, including person IDs for navigating to filmographies.
- Company, ratings, box office, source links, and after-credits information where known.
- `available_content`, listing the sections available through the content endpoints.

There is no `include` parameter. Use [content endpoints](/movie-content) for explanations and [extras endpoints](/related-resources) for related lists.

## Interpret missing and source-specific values

A `null` field means the value is unknown or unavailable. Empty arrays mean there are no returned entries. Do not turn either into a zero rating or a negative factual claim.

Ratings are source-native strings and do not share one scale. Keep the source label alongside a score. Runtime is display text, not a guaranteed number of minutes. `after_credits: "unknown"` does not mean a movie has no after-credits scene, and cast order does not indicate billing order.

**Reference:** [Movies](/api/movies)