moviemood API

Complete API Documentation

Everything you need to integrate MovieMood’s search, similarity, mood, and interaction services. All endpoints respond with JSON and are designed to stay in sync with the UI powering moviemood.lol.

Base URL

https://www.moviemood.lol

Authentication

UI login creates a session cookie via /auth/login. Protected endpoints redirect (HTTP 302) to /auth/login when you are not authenticated.

Content-Type

Send application/json for JSON POST requests. Most API endpoints return JSON; protected endpoints may redirect to HTML login when unauthenticated.

How requests work

All routes live under the base URL shown above. Movie data is loaded from JSONL files into an in-memory cache at startup. Error payloads include an error field with HTTP status (400 bad input, 404 missing, 500 server error).

Quick examples

curl "/similar/The%20Matrix?k=5"       # Similar movies
curl "/movie/The%20Matrix?year=1999"   # Movie details
curl "/from_mood?happy=0.8&tense=0.2"  # Mood recommendation

/api/user/interactions and /profile require login. Unauthenticated requests redirect (HTTP 302) to login.

Utility

GET /health

Simple readiness probe.

{"status": "ok"}

GET /autocomplete

/autocomplete?q=<term>&limit=8

Quick suggestions for the search box. Matches normalized titles instantly.

q (required)

Case-insensitive substring. <2 chars returns empty.

limit

Max results (default 8).

[{"title":"The Matrix","year":1999,"poster":"https://..."},{"title":"The Matrix Reloaded","year":2003,"poster":null}]

Similarity

GET /similar/<movie_name>

/similar/<movie_name>?k=5&year=<optional>

Finds similar movies via fuzzy title matching. Returns up to k recommendations.

Number of results (default 5).

year

Optional year to disambiguate.

Response shape

{"anchor":{"queried":"...","resolved_title":"...","resolved_year":2023,"details":{...}},
 "recommendations":[{"title":"...","similarity_percent":82.1,"rating_count":123456,...}],
 "count":5}

Logged-in users get watched movies filtered out and final_score reranking.

Page

GET /recommendations/<movie_name>

/recommendations/<movie_name>?sort=popular|gems&year=

HTML page showing up to 100 similar movies.

sort

popular (high ratings first) or gems (low ratings first).

year

Optional year disambiguation.

Mood

GET /from_mood

/from_mood?happy=0.5&energetic=0.5&tense=0.5&romantic=0.5&weird=0.5&k=5

Recommendations based on 5 mood sliders (0..1 range).

happy

0..1 (default 0.5)

energetic

0..1 (default 0.5)

tense

0..1 (default 0.5)

romantic

0..1 (default 0.5)

weird

0..1 (default 0.5)

1..50 (default 5)

{"sliders":{...},"k":10,"recommendations":[{"title":"...","mood_similarity_percent":"87%"}],"count":10}

Logged-in users get watched movies filtered out.

Catalog

GET /movie/<movie_name>

/movie/<movie_name>?year=<optional>

Returns the best matching movie object from the catalog using fuzzy matching.

year

Optional integer year to disambiguate titles.

curl "https://www.moviemood.lol/movie/Zelig"

Catalog

GET /random_movie

Returns a random movie object from the full dataset.

curl "https://www.moviemood.lol/random_movie"

Popular

Top Popular Movies

GET /top

Renders the Top 100 page (paginated, 100 per page).

/top

GET /top/page/<page>

Renders additional pages of the popularity list.

/top/page/2

GET /api/popular

/api/popular?page=1

Returns JSON results for the popularity list.

page

Page number (default 1). Each page contains 100 items.

{
  "page": 1,
  "results": [
    {
      "title": "Barbie",
      "year": 2023,
      "slug": "barbie-2023",
      "cover_image": "https://...",
      "rating_average": 3.7,
      "rating_count": 123456
    }
  ],
  "total": 39400
}

Slugs are the canonical keys used by the UI and database (typically title-year).

Discovery

GET /lucky

Returns a random “lucky” recommendation. If you are logged in, it samples from movies similar to your watched list and excludes watched items; otherwise it falls back to a random pick from a popularity-weighted pool.

curl "https://www.moviemood.lol/lucky"

{
  "title": "...",
  "year": 2014,
  "slug": "...",
  "genres": ["..."],
  "cast": ["..."],
  "countries": ["..."],
  "languages": ["..."],
  "cover_image": "https://..."
}

User data

GET /api/user/interactions

Returns current user's watched/rating data by slug. Requires login (302 redirect otherwise).

{"the-matrix-1999":{"watched":true,"rating":5},"barbie-2023":{"watched":true}}

User data

POST /api/user/interactions

Creates or updates watched/rated state. Requires login.

movie_slug (required)

Slug key (e.g. the-matrix-1999).

watched

true inserts; false removes.

rating

1..5 to set; null removes.

POST: {"movie_slug":"the-matrix-1999","watched":true,"rating":5}
Response: {"status":"ok","movie_slug":"the-matrix-1999"}

Auth

Authentication routes

GET/POST /auth/register

HTML form for creating a user.

/auth/register

GET/POST /auth/login

HTML form for logging in. Successful login sets a session cookie and redirects to /.

/auth/login

GET /auth/logout

Clears the session and redirects to /.

/auth/logout

If you’re driving the API from scripts, authenticate by logging in via the UI (browser) or by scripting the form POST and preserving cookies.

Pages

HTML pages

These routes render HTML templates for the web UI.

GET /

Main search page.

GET /mood

Mood slider page.

GET /docs

This documentation.

GET /top

Top popular movies.

GET /profile

Watched/rated history (login required).