Recommendations

Use GET /movies/{movie}/recommendations to find related films. Choose a ranked list of similar movies or explore recommendations grouped into themed threads.

Similar movies

The default mode is similar:

Code
curl --get "$ATM_API_BASE_URL/movies/$ATM_MOVIE_ID/recommendations" \
  --header "Authorization: Bearer $ATM_API_KEY" \
  --data-urlencode 'mode=similar' \
  --data-urlencode 'limit=10'

Each result is a movie record with rank and score. Preserve the returned ordering when displaying recommendations. A score is recommendation metadata, not a critic rating or a percentage match.

You can narrow results with genre, year_from, and year_to. Keep these filters when following a pagination cursor.

Explore themed threads

Code
curl --get "$ATM_API_BASE_URL/movies/$ATM_MOVIE_ID/recommendations" \
  --header "Authorization: Bearer $ATM_API_KEY" \
  --data-urlencode 'mode=threads' \
  --data-urlencode 'limit=10'

Each thread contains an id, title, description, type, strength, and a movies page. Use the title and description to explain the connection to your reader. The embedded movie list is a preview of up to five movies.

Open one thread

Set ATM_THREAD_ID to an ID returned for this movie, then request its movies directly:

Code
curl --get "$ATM_API_BASE_URL/movies/$ATM_MOVIE_ID/recommendations" \
  --header "Authorization: Bearer $ATM_API_KEY" \
  --data-urlencode 'mode=threads' \
  --data-urlencode "thread_id=$ATM_THREAD_ID" \
  --data-urlencode 'limit=20'

This returns a paginated list of movies for the selected thread. Follow that response's next_cursor on the same URL with mode=threads and the same thread_id. A thread ID must belong to the movie in the path; otherwise the request returns 404.

Handle an empty recommendation list

Not every movie has recommendations or threads. A successful empty list means there are no matching results. Offer another search or a collection in your interface rather than treating it as an API failure.

Next: Pagination →