API
API Overview
Current API reference for the Movie Recommender server
The Movie Recommender server currently exposes nine active API surfaces:
- Recommendations (Cached) - Main recommendation endpoint used by the home page
- Recommendation Quota - Remaining daily recommendation budget for the signed-in user
- Auth Signup - Server-side account creation with hCaptcha token submission
- Watched Movies API - Read and update user watched movies in Supabase
- My List API - Read and update the user's saved TMDB IDs
- Movie Search - Search TMDB movies for the search page
- Popular Movies - Cached TMDB popular feed for anonymous browsing
- Movie Details - Fetch movie metadata with Supabase-backed caching
- TMDB Import (Admin) - Populate the Supabase
moviescorpus from TMDB exports
All APIs are served from the server under /api/.
Quick Reference
| API | Base URL | Auth | Notes |
|---|---|---|---|
| Recommendations (Cached) | /api/recommend | Bearer token (Supabase session) | AI client, cached for 7 days |
| Recommendation Quota | /api/recommend/quota | Bearer token (Supabase session) | Remaining per-user daily recommendation quota |
| Auth Signup | /api/auth/signup | None | Server-side signup with email, password, username, and captchaToken |
| Watched Movies | /api/watched | Bearer token (Supabase session) | Hydrated movie cards on reads |
| My List | /api/mylist | Bearer token (Supabase session) | Uses Supabase RPC helpers on writes |
| Movie Search | /api/movies/search | None | TMDB-backed search endpoint |
| Popular Movies | /api/movies/popular | None | Cached TMDB popular feed |
| Movie Details | /api/movies/:id | None | Supabase-backed detail cache |
| TMDB Import (Admin) | /api/admin/tmdb-import | x-admin-token header | Imports the TMDB corpus into Supabase |
Environment Variables
Required configuration for API functionality:
NUXT_TMDB_API_KEY=your_tmdb_api_key_here
NUXT_GOOGLE_API_KEY=your_google_ai_studio_key
NUXT_GOOGLE_MODELS=gemini-flash-lite-latest,gemini-2.5-flash-lite,gemini-2.0-flash-lite
NUXT_OPENROUTER_API_KEY=your_openrouter_api_key
NUXT_OPENROUTER_MODELS=google/gemini-2.5-flash-lite
NUXT_PUBLIC_SUPABASE_URL=your_supabase_url
NUXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
NUXT_SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
NUXT_PUBLIC_HCAPTCHA_SITE_KEY=your_hcaptcha_site_key
NUXT_HCAPTCHA_SECRET=your_hcaptcha_secret
ADMIN_API_TOKEN=your_admin_token
UPSTASH_REDIS_REST_URL=your_upstash_url_here
UPSTASH_REDIS_REST_TOKEN=your_upstash_key_here
Authentication
Public signup route:
/api/auth/signupacceptsemail,password,username, andcaptchaToken- Duplicate-email responses are intentional so the UI can send existing users back to login
Protected routes require a Supabase bearer token (Authorization: Bearer ...):
/api/recommend/api/recommend/quota/api/watched/api/mylist
Admin route requires x-admin-token:
/api/admin/tmdb-import
Rate Limiting
- TMDB-backed requests share a server-side quota enforced in
server/utils/tmdb/client.ts - Recommendation generation is limited per authenticated user
- Rate-limit headers are included on limited responses
Data Notes
moviesis the current Supabase source for imported titles and cached movie detailsuser_watched_moviesstores watched state as one row per user/movie pairuser_my_liststores saved TMDB IDs and is mutated through RPC functionsrecommendationscachestmdb_idsinstead of full recommendation objects
Next Steps
- See Recommendations (Cached) for
/api/recommend - See TMDB Integration for how the server reaches TMDB
- See Watched Movies API for watched list and My List reads/writes
- See Recommendation Generation for the AI flow used by
/api/recommend - See Movie Search for search endpoint behavior
- See Movie Details for metadata with caching
- See TMDB Import for admin import behavior
- See Backend Server for server architecture
- See Frontend Components for how the UI consumes these APIs