{"openapi":"3.0.3","info":{"title":"InsFlix Microservice Backend API","version":"1.0.0","description":"Unified REST API microservice backend for InsFlix mobile app and admin clients. Powered by Next.js, Neon Serverless PostgreSQL, and Drizzle ORM.","contact":{"name":"InsFlix Engineering Team"}},"servers":[{"url":"/","description":"Current Environment Server"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Provide secret API key for write, update, and delete operations"},"CronKeyAuth":{"type":"apiKey","in":"header","name":"x-cron-key","description":"Provide secret CRON_KEY for periodic cron webhook operations (also accepts Authorization: Bearer <key> or ?key=<key>)"}},"schemas":{"CastMember":{"type":"object","properties":{"name":{"type":"string","example":"Cillian Murphy"},"role":{"type":"string","example":"Actor"},"character":{"type":"string","example":"J. Robert Oppenheimer"},"profileUrl":{"type":"string","format":"uri","example":"https://image.tmdb.org/t/p/w185/xyz.jpg"}},"required":["name"]},"Movie":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","example":"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"},"title":{"type":"string","example":"Oppenheimer"},"overview":{"type":"string","example":"The story of American scientist J. Robert Oppenheimer and his role in the development of the atomic bomb."},"videoUrl":{"type":"string","format":"uri","example":"https://cdn.example.com/videos/oppenheimer_master.mp4"},"fastUrl":{"type":"string","format":"uri","example":"https://stream.example.com/fast/oppenheimer.mp4"},"trailerUrl":{"type":"string","format":"uri","example":"https://www.youtube.com/watch?v=uYPbbksJxIg"},"quality":{"type":"string","example":"4K"},"mimeType":{"type":"string","example":"video/mp4"},"sizeBytes":{"type":"integer","example":4294967296},"seedrFileId":{"type":"integer","example":123456},"posterUrl":{"type":"string","format":"uri","example":"https://image.tmdb.org/t/p/w500/8Gxv8gSFCU0XGDykEGv7zR1n2ua.jpg"},"backdropUrl":{"type":"string","format":"uri","example":"https://image.tmdb.org/t/p/original/fm6KqXpk3M2HVveHwCrBSSBaO0V.jpg"},"screenshots":{"type":"array","items":{"type":"string"}},"images":{"type":"array","items":{"type":"object"}},"videos":{"type":"array","items":{"type":"object"}},"reviews":{"type":"array","items":{"type":"object"}},"releaseDate":{"type":"string","example":"2023-07-21"},"releaseYear":{"type":"integer","example":2023},"runtime":{"type":"integer","example":180},"genres":{"type":"string","example":"Biography, Drama, History"},"contentRating":{"type":"string","example":"R"},"language":{"type":"string","example":"en"},"country":{"type":"string","example":"United States"},"director":{"type":"string","example":"Christopher Nolan"},"writers":{"type":"string","example":"Christopher Nolan, Kai Bird"},"cast":{"type":"array","items":{"$ref":"#/components/schemas/CastMember"}},"imdbId":{"type":"string","example":"tt15398776"},"imdbRating":{"type":"number","example":8.9},"imdbVotes":{"type":"integer","example":750000},"imdbRank":{"type":"integer","example":40},"imdbType":{"type":"string","example":"movie"},"isFeatured":{"type":"boolean","example":true},"trendingScore":{"type":"number","example":98.5},"isActive":{"type":"boolean","example":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ApiResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"string"},"details":{"type":"object"},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}},"paths":{"/api/health":{"get":{"summary":"Health Check & Database Connectivity","description":"Returns health status and validates Neon serverless DB connectivity.","tags":["System"],"responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}}}}},"/api/data/{entity}":{"get":{"summary":"Common Entity List API","description":"Lists records from any database entity (e.g. movies) with search, filtering, and pagination.","tags":["Data Common Endpoints"],"parameters":[{"name":"entity","in":"path","required":true,"schema":{"type":"string","example":"movies"},"description":"Target entity name (e.g. movies)"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Search keyword (searches title)"},{"name":"genre","in":"query","schema":{"type":"string"},"description":"Filter by genre"},{"name":"year","in":"query","schema":{"type":"integer"},"description":"Filter by release year"},{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20},"description":"Items per page"},{"name":"sortBy","in":"query","schema":{"type":"string","default":"createdAt"},"description":"Sort column"},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}}],"responses":{"200":{"description":"Entity records retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"400":{"description":"Unrecognized entity"}}},"post":{"summary":"Common Entity Create API","description":"Creates a record in the specified entity table (e.g. movies). Automatically generates UUID. Requires x-api-key header.","tags":["Data Common Endpoints"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"entity","in":"path","required":true,"schema":{"type":"string","example":"movies"},"description":"Target entity name"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"201":{"description":"Record created successfully"},"400":{"description":"Invalid payload or entity"},"401":{"description":"Unauthorized"}}}},"/api/data/{entity}/{id}":{"get":{"summary":"Common Entity Get by UUID","description":"Fetches record by UUID from the specified entity (e.g. /api/data/movies/<uuid>).","tags":["Data Common Endpoints"],"parameters":[{"name":"entity","in":"path","required":true,"schema":{"type":"string","example":"movies"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"},"description":"Record UUID"}],"responses":{"200":{"description":"Record found"},"404":{"description":"Record not found"}}},"patch":{"summary":"Common Entity Update by UUID","description":"Updates record by UUID in the specified entity. Requires x-api-key header.","tags":["Data Common Endpoints"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"entity","in":"path","required":true,"schema":{"type":"string","example":"movies"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"},"description":"Record UUID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Record updated"},"401":{"description":"Unauthorized"},"404":{"description":"Record not found"}}},"delete":{"summary":"Common Entity Delete by UUID","description":"Deletes record by UUID from the specified entity. Requires x-api-key header.","tags":["Data Common Endpoints"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"entity","in":"path","required":true,"schema":{"type":"string","example":"movies"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"},"description":"Record UUID"}],"responses":{"200":{"description":"Record deleted"},"401":{"description":"Unauthorized"},"404":{"description":"Record not found"}}}},"/api/webhooks/tamilmv":{"get":{"summary":"Trigger 1TamilMV Movie Fetcher (GET)","description":"Scrapes latest forum movies from 1TamilMV and bulk inserts new movies into the database. Protected by CRON_KEY.","tags":["Webhooks / Cron"],"security":[{"CronKeyAuth":[]}],"parameters":[{"name":"key","in":"query","schema":{"type":"string"},"description":"Cron key query parameter alternative"},{"name":"pages","in":"query","schema":{"type":"integer","default":1},"description":"Max pages to scrape per forum"},{"name":"forum","in":"query","schema":{"type":"string"},"description":"Optional forum name or language filter"}],"responses":{"200":{"description":"Scrape finished successfully"},"401":{"description":"Unauthorized / invalid cron key"},"500":{"description":"Scraper execution error"}}},"post":{"summary":"Trigger 1TamilMV Movie Fetcher (POST)","description":"Scrapes latest forum movies from 1TamilMV and bulk inserts new movies into the database. Protected by CRON_KEY.","tags":["Webhooks / Cron"],"security":[{"CronKeyAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"pages":{"type":"integer","default":1},"forum":{"type":"string"}}}}}},"responses":{"200":{"description":"Scrape finished successfully"},"401":{"description":"Unauthorized / invalid cron key"},"500":{"description":"Scraper execution error"}}}},"/api/webhooks/imdb":{"get":{"summary":"Trigger IMDb Metadata Enrichment (GET)","description":"Enriches movies without IMDb data using IMDb GraphQL and suggestion APIs, saving high-confidence matches in chunks of 5. Protected by CRON_KEY.","tags":["Webhooks / Cron"],"security":[{"CronKeyAuth":[]}],"parameters":[{"name":"key","in":"query","schema":{"type":"string"},"description":"Cron key query parameter alternative"},{"name":"limit","in":"query","schema":{"type":"integer","default":25},"description":"Maximum movies to process"},{"name":"delay","in":"query","schema":{"type":"integer","default":3000},"description":"Delay in milliseconds between requests"},{"name":"force","in":"query","schema":{"type":"boolean","default":false},"description":"Force re-enrichment of already enriched movies"},{"name":"retryNotFound","in":"query","schema":{"type":"boolean","default":false},"description":"Retry movies previously marked as NOT_FOUND"}],"responses":{"200":{"description":"Enrichment finished successfully"},"401":{"description":"Unauthorized / invalid cron key"},"500":{"description":"Enrichment execution error"}}},"post":{"summary":"Trigger IMDb Metadata Enrichment (POST)","description":"Enriches movies without IMDb data using IMDb GraphQL and suggestion APIs, saving high-confidence matches in chunks of 5. Protected by CRON_KEY.","tags":["Webhooks / Cron"],"security":[{"CronKeyAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer","default":25},"delay":{"type":"integer","default":3000},"force":{"type":"boolean","default":false},"retryNotFound":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Enrichment finished successfully"},"401":{"description":"Unauthorized / invalid cron key"},"500":{"description":"Enrichment execution error"}}}}}}