{"openapi":"3.0.0","info":{"title":"MCUAPI Documentation","description":"This is an API with information about MCU Movies, TV Shows, Characters, and Timeline across the Marvel Multiverse. Supports content from Marvel Studios, FOX X-Men Universe, Sony, and other Marvel properties.","version":"3.0.0","contact":{"name":"Marcelo Augusto","email":"mrclgst10@gmail.com"}},"servers":[{"url":"https://mcuapi.up.railway.app","description":"Production"},{"url":"http://localhost:3333","description":"Local development"}],"paths":{"/health":{"get":{"tags":["Health"],"summary":"Service health check","description":"Reports API and database status. Returns 503 when the database is unreachable.","responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"503":{"description":"Database is unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/docs/openapi.json":{"get":{"tags":["Health"],"summary":"Raw OpenAPI spec","description":"Returns this OpenAPI document as raw JSON, for tooling and agents that need a fetchable spec URL instead of the rendered Swagger UI at /docs.","responses":{"200":{"description":"OpenAPI 3.0 document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/movies":{"get":{"tags":["Movies"],"summary":"List all movies","description":"List all movies","parameters":[{"name":"page","in":"query","description":"Page number for pagination","required":false,"schema":{"type":"integer","example":"1"}},{"name":"limit","in":"query","description":"Limit of items to return. Defaults to 10; values above 100 are capped at 100.","required":false,"schema":{"type":"integer","default":10,"minimum":1,"maximum":100,"example":10}},{"name":"columns","in":"query","description":"Comma-separated movie properties to be returned. Unknown properties are ignored","required":false,"schema":{"type":"string","example":"title,release_date,phase"}},{"name":"order","in":"query","description":"Order by column and sorting type (ASC, DESC). Multiple clauses can be separated by semicolons; unknown columns are ignored","required":false,"schema":{"type":"string","example":"chronology,DESC;title,ASC"}},{"name":"filter","in":"query","description":"Filter by column=value. Multiple clauses can be separated by semicolons; unknown columns are ignored","required":false,"schema":{"type":"string","example":"title=Iron;phase=1"}},{"name":"studio","in":"query","description":"Filter by production studio (e.g., Marvel Studios, FOX, Sony)","required":false,"schema":{"type":"string","example":"FOX"}},{"name":"continuity","in":"query","description":"Filter by continuity/universe (e.g., MCU, FOX X-Men Universe)","required":false,"schema":{"type":"string","example":"MCU"}},{"name":"multiverse_designation","in":"query","description":"Filter by multiverse Earth designation (e.g., Earth-616, Earth-838)","required":false,"schema":{"type":"string","example":"Earth-616"}},{"name":"is_mcu","in":"query","description":"Filter for MCU content only","required":false,"schema":{"type":"boolean","example":true}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Movie"}},"total":{"type":"integer","description":"Total of movies"},"page":{"type":"integer","description":"Current page (1 when not paginated)","example":1},"limit":{"type":"integer","description":"Items per page (present only when the limit query param is used)","example":10},"_links":{"allOf":[{"$ref":"#/components/schemas/ResourceLinks"}],"description":"Collection links: self, first, last, and prev/next when applicable. All original query params are preserved."}}}}}},"500":{"description":"Internal Server Error"}}}},"/api/v1/movies/{movie_id}":{"get":{"tags":["Movies"],"summary":"List a movie","description":"List a movie by ID","parameters":[{"name":"movie_id","in":"path","description":"Movie ID","required":true,"type":"integer","example":1}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Movie"}}}},"404":{"description":"Movie not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":"string","statusCode":"integer","message":"string"},"example":{"status":"Error","statusCode":404,"message":"Movie not found"}}}}},"500":{"description":"Internal Server Error"}}}},"/api/v1/tvshows":{"get":{"tags":["TV Shows"],"summary":"List all tv shows","description":"List all tv shows","parameters":[{"name":"page","in":"query","description":"Page number for pagination","required":false,"schema":{"type":"integer","example":"1"}},{"name":"limit","in":"query","description":"Limit of items to return. Defaults to 10; values above 100 are capped at 100.","required":false,"schema":{"type":"integer","default":10,"minimum":1,"maximum":100,"example":10}},{"name":"columns","in":"query","description":"Comma-separated TV show properties to be returned. Unknown properties are ignored","required":false,"schema":{"type":"string","example":"title,release_date,phase"}},{"name":"order","in":"query","description":"Order by column and sorting type (ASC, DESC). Multiple clauses can be separated by semicolons; unknown columns are ignored","required":false,"schema":{"type":"string","example":"release_date,DESC;title,ASC"}},{"name":"filter","in":"query","description":"Filter by column=value. Multiple clauses can be separated by semicolons; unknown columns are ignored","required":false,"schema":{"type":"string","example":"title=Wanda;phase=4"}},{"name":"studio","in":"query","description":"Filter by production studio (e.g., Marvel Studios, FOX, Sony)","required":false,"schema":{"type":"string","example":"Marvel Studios"}},{"name":"continuity","in":"query","description":"Filter by continuity/universe (e.g., MCU, FOX X-Men Universe)","required":false,"schema":{"type":"string","example":"MCU"}},{"name":"multiverse_designation","in":"query","description":"Filter by multiverse Earth designation (e.g., Earth-616, Earth-838)","required":false,"schema":{"type":"string","example":"Earth-616"}},{"name":"is_mcu","in":"query","description":"Filter for MCU content only","required":false,"schema":{"type":"boolean","example":true}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TVShow"}},"total":{"type":"integer","description":"Total of tv shows"},"page":{"type":"integer","description":"Current page (1 when not paginated)","example":1},"limit":{"type":"integer","description":"Items per page (present only when the limit query param is used)","example":10},"_links":{"allOf":[{"$ref":"#/components/schemas/ResourceLinks"}],"description":"Collection links: self, first, last, and prev/next when applicable. All original query params are preserved."}}}}}},"500":{"description":"Internal Server Error"}}}},"/api/v1/tvshows/{tvshow_id}":{"get":{"tags":["TV Shows"],"summary":"List a tv show","description":"List a tv show by ID","parameters":[{"name":"tvshow_id","in":"path","description":"TV Show ID","required":true,"type":"integer","example":1}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/TVShow"}}}},"404":{"description":"TV Show not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":"string","statusCode":"integer","message":"string"},"example":{"status":"Error","statusCode":404,"message":"Movie not found"}}}}},"500":{"description":"Internal Server Error"}}}},"/api/v1/characters":{"get":{"tags":["Characters"],"summary":"List all characters","description":"List all characters across the multiverse","parameters":[{"name":"page","in":"query","description":"Page number for pagination","required":false,"schema":{"type":"integer","example":"1"}},{"name":"limit","in":"query","description":"Limit of items to return. Defaults to 10; values above 100 are capped at 100.","required":false,"schema":{"type":"integer","default":10,"minimum":1,"maximum":100,"example":10}},{"name":"columns","in":"query","description":"Comma-separated character properties to be returned. Unknown properties are ignored","required":false,"schema":{"type":"string","example":"name,alias,continuity"}},{"name":"order","in":"query","description":"Order by column and sorting type (ASC, DESC). Multiple clauses can be separated by semicolons; unknown columns are ignored","required":false,"schema":{"type":"string","example":"name,ASC;continuity,DESC"}},{"name":"filter","in":"query","description":"Filter by column=value. Multiple clauses can be separated by semicolons; unknown columns are ignored","required":false,"schema":{"type":"string","example":"name=Iron Man;continuity=MCU"}},{"name":"continuity","in":"query","description":"Filter by continuity/universe (e.g., MCU, FOX X-Men Universe)","required":false,"schema":{"type":"string","example":"MCU"}},{"name":"multiverse_designation","in":"query","description":"Filter by multiverse Earth designation (e.g., Earth-616, Earth-838)","required":false,"schema":{"type":"string","example":"Earth-616"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Character"}},"total":{"type":"integer","description":"Total of characters"},"page":{"type":"integer","description":"Current page (1 when not paginated)","example":1},"limit":{"type":"integer","description":"Items per page (present only when the limit query param is used)","example":10},"_links":{"allOf":[{"$ref":"#/components/schemas/ResourceLinks"}],"description":"Collection links: self, first, last, and prev/next when applicable. All original query params are preserved."}}}}}},"500":{"description":"Internal Server Error"}}}},"/api/v1/characters/{character_id}":{"get":{"tags":["Characters"],"summary":"Get a character","description":"Get a character by ID","parameters":[{"name":"character_id","in":"path","description":"Character ID","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Character"}}}},"404":{"description":"Character not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Character not found"}}}}}},"500":{"description":"Internal Server Error"}}}},"/api/v1/characters/movie/{movie_id}":{"get":{"tags":["Characters"],"summary":"Get characters in a movie","description":"Get all characters that appear in a specific movie","parameters":[{"name":"movie_id","in":"path","description":"Movie ID","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Character"},{"type":"object","properties":{"role_type":{"type":"string","description":"Character's role in the movie (main, supporting, cameo)","example":"main"}}}]}}}}},"500":{"description":"Internal Server Error"}}}},"/api/v1/characters/tvshow/{tvshow_id}":{"get":{"tags":["Characters"],"summary":"Get characters in a TV show","description":"Get all characters that appear in a specific TV show","parameters":[{"name":"tvshow_id","in":"path","description":"TV Show ID","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Character"},{"type":"object","properties":{"role_type":{"type":"string","description":"Character's role in the TV show (main, supporting, cameo)","example":"main"}}}]}}}}},"500":{"description":"Internal Server Error"}}}},"/api/v1/people":{"get":{"tags":["People"],"summary":"List all people","description":"List all people (actors and directors) normalized out of the played_by/directed_by fields on characters, movies, and TV shows","parameters":[{"name":"page","in":"query","description":"Page number for pagination","required":false,"schema":{"type":"integer","example":"1"}},{"name":"limit","in":"query","description":"Limit of items to return. Defaults to 10; values above 100 are capped at 100.","required":false,"schema":{"type":"integer","default":10,"minimum":1,"maximum":100,"example":10}},{"name":"columns","in":"query","description":"Comma-separated person properties to be returned. Unknown properties are ignored","required":false,"schema":{"type":"string","example":"name"}},{"name":"order","in":"query","description":"Order by column and sorting type (ASC, DESC). Multiple clauses can be separated by semicolons; unknown columns are ignored","required":false,"schema":{"type":"string","example":"name,ASC"}},{"name":"filter","in":"query","description":"Filter by column=value. Multiple clauses can be separated by semicolons; unknown columns are ignored","required":false,"schema":{"type":"string","example":"name=Robert Downey Jr."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Person"}},"total":{"type":"integer","description":"Total of people"},"page":{"type":"integer","description":"Current page (1 when not paginated)","example":1},"limit":{"type":"integer","description":"Items per page (present only when the limit query param is used)","example":10},"_links":{"allOf":[{"$ref":"#/components/schemas/ResourceLinks"}],"description":"Collection links: self, first, last, and prev/next when applicable. All original query params are preserved."}}}}}},"500":{"description":"Internal Server Error"}}}},"/api/v1/people/{person_id}":{"get":{"tags":["People"],"summary":"Get a person","description":"Get a person by ID","parameters":[{"name":"person_id","in":"path","description":"Person ID","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Person"}}}},"404":{"description":"Person not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Person not found"}}}}}},"500":{"description":"Internal Server Error"}}}},"/api/v1/people/{person_id}/characters":{"get":{"tags":["People"],"summary":"Get characters played by a person","description":"Get every character a person has played, in the order they appear in the character's played_by field","parameters":[{"name":"person_id","in":"path","description":"Person ID","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Character"},{"type":"object","properties":{"recast_order":{"type":"integer","description":"Position preserved from the character's played_by sequence; 1 is first-listed","example":1}}}]}}}}},"404":{"description":"Person not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Person not found"}}}}}},"500":{"description":"Internal Server Error"}}}},"/api/v1/people/{person_id}/titles":{"get":{"tags":["People"],"summary":"Get titles directed by a person","description":"Get every movie and TV show a person directed, merged and sorted by release date","parameters":[{"name":"person_id","in":"path","description":"Person ID","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"allOf":[{"anyOf":[{"$ref":"#/components/schemas/Movie"},{"$ref":"#/components/schemas/TVShow"}]},{"type":"object","properties":{"type":{"type":"string","enum":["movie","tvshow"],"description":"Content type","example":"movie"},"role":{"type":"string","description":"Person's role for this title","example":"director"}}}]}}}}},"404":{"description":"Person not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Person not found"}}}}}},"500":{"description":"Internal Server Error"}}}},"/api/v1/post-credit-scenes":{"get":{"tags":["PostCreditScenes"],"summary":"List all post-credit scenes","description":"List structured post- and mid-credits scenes across movies and TV shows","parameters":[{"name":"page","in":"query","description":"Page number for pagination","required":false,"schema":{"type":"integer","example":"1"}},{"name":"limit","in":"query","description":"Limit of items to return. Defaults to 10; values above 100 are capped at 100.","required":false,"schema":{"type":"integer","default":10,"minimum":1,"maximum":100,"example":10}},{"name":"columns","in":"query","description":"Comma-separated post-credit scene properties to be returned. Unknown properties are ignored","required":false,"schema":{"type":"string","example":"description"}},{"name":"order","in":"query","description":"Order by column and sorting type (ASC, DESC). Multiple clauses can be separated by semicolons; unknown columns are ignored","required":false,"schema":{"type":"string","example":"movie_id,ASC"}},{"name":"filter","in":"query","description":"Filter by column=value. Multiple clauses can be separated by semicolons; unknown columns are ignored","required":false,"schema":{"type":"string","example":"movie_id=1"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PostCreditScene"}},"total":{"type":"integer","description":"Total of post-credit scenes"},"page":{"type":"integer","description":"Current page (1 when not paginated)","example":1},"limit":{"type":"integer","description":"Items per page (present only when the limit query param is used)","example":10},"_links":{"allOf":[{"$ref":"#/components/schemas/ResourceLinks"}],"description":"Collection links: self, first, last, and prev/next when applicable. All original query params are preserved."}}}}}},"500":{"description":"Internal Server Error"}}}},"/api/v1/post-credit-scenes/{post_credit_scene_id}":{"get":{"tags":["PostCreditScenes"],"summary":"Get a post-credit scene","description":"Get a post-credit scene by ID","parameters":[{"name":"post_credit_scene_id","in":"path","description":"Post-credit scene ID","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostCreditScene"}}}},"404":{"description":"Post-credit scene not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Post-credit scene not found"}}}}}},"500":{"description":"Internal Server Error"}}}},"/api/v1/post-credit-scenes/movie/{movie_id}":{"get":{"tags":["PostCreditScenes"],"summary":"Get post-credit scenes for a movie","description":"Get every post- and mid-credits scene belonging to a movie","parameters":[{"name":"movie_id","in":"path","description":"Movie ID","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PostCreditScene"}}}}},"500":{"description":"Internal Server Error"}}}},"/api/v1/post-credit-scenes/tvshow/{tvshow_id}":{"get":{"tags":["PostCreditScenes"],"summary":"Get post-credit scenes for a TV show","description":"Get every post- and mid-credits scene belonging to a TV show","parameters":[{"name":"tvshow_id","in":"path","description":"TV show ID","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PostCreditScene"}}}}},"500":{"description":"Internal Server Error"}}}},"/api/v1/timeline":{"get":{"tags":["Timeline"],"summary":"Get timeline across universes","description":"Get chronological timeline of movies and TV shows across different universes","parameters":[{"name":"multiverse","in":"query","description":"Filter by specific multiverse designation (e.g., Earth-616, Earth-838)","required":false,"schema":{"type":"string","example":"Earth-616"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TimelineContinuity"}}}}},"500":{"description":"Internal Server Error"}}}},"/api/v1/characters/{character_id}/movies":{"get":{"tags":["Characters"],"summary":"Get movies a character appears in","description":"Get all movies a specific character appears in, with the role type of each appearance","parameters":[{"name":"character_id","in":"path","description":"Character ID","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Movie"},{"type":"object","properties":{"role_type":{"type":"string","description":"Character's role in the movie (main, supporting, cameo)","example":"main"}}}]}}}}},"404":{"description":"Character not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"statusCode":{"type":"integer"},"message":{"type":"string"}},"example":{"status":"Error","statusCode":404,"message":"Character not found"}}}}},"500":{"description":"Internal Server Error"}}}},"/api/v1/upcoming":{"get":{"tags":["Upcoming"],"summary":"List upcoming releases","description":"Titles whose release_date is strictly in the future, movies and TV shows merged into one list sorted by release_date ascending. Titles with no announced release_date (e.g. Blade, Ghost Rider, Your Friendly Neighborhood Spider-Man) are excluded — they remain reachable via /movies and /tvshows.","parameters":[{"name":"page","in":"query","description":"Page number for pagination","required":false,"schema":{"type":"integer","example":"1"}},{"name":"limit","in":"query","description":"Limit of items to return. Defaults to 10; values above 100 are capped at 100.","required":false,"schema":{"type":"integer","default":10,"minimum":1,"maximum":100,"example":10}},{"name":"type","in":"query","description":"Filter by content type","required":false,"schema":{"type":"string","enum":["movie","tvshow"],"example":"tvshow"}},{"name":"continuity","in":"query","description":"Filter by continuity/universe (e.g., MCU, FOX X-Men Universe)","required":false,"schema":{"type":"string","example":"MCU"}},{"name":"multiverse_designation","in":"query","description":"Filter by multiverse Earth designation (e.g., Earth-616, Earth-838)","required":false,"schema":{"type":"string","example":"Earth-616"}},{"name":"is_mcu","in":"query","description":"Filter for MCU content only","required":false,"schema":{"type":"boolean","example":true}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UpcomingItem"}},"total":{"type":"integer","description":"Total of upcoming titles matching the filters"},"page":{"type":"integer","description":"Current page (1 when not paginated)","example":1},"limit":{"type":"integer","description":"Items per page (present only when the limit query param is used)","example":10},"_links":{"allOf":[{"$ref":"#/components/schemas/ResourceLinks"}],"description":"Collection links: self, first, last, and prev/next when applicable. All original query params are preserved."}}}}}},"500":{"description":"Internal Server Error"}}}},"/api/v1/stats":{"get":{"tags":["Stats"],"summary":"Get dataset-wide counts","description":"Aggregate counts of the catalogue: movies, tvshows, characters, people, titles (movies + tvshows), continuities and designations. continuities is the distinct count over movies + tvshows only. designations is the distinct count over movies + tvshows + characters — Earth-838 exists only on characters (the Doctor Strange in the Multiverse of Madness Illuminati), so titles alone would undercount it.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Stats"}}}},"500":{"description":"Internal Server Error"}}}},"/api/v1/characters/{character_id}/tvshows":{"get":{"tags":["Characters"],"summary":"Get TV shows a character appears in","description":"Get all TV shows a specific character appears in, with the role type of each appearance","parameters":[{"name":"character_id","in":"path","description":"Character ID","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/TVShow"},{"type":"object","properties":{"role_type":{"type":"string","description":"Character's role in the tv show (main, supporting, cameo)","example":"main"}}}]}}}}},"404":{"description":"Character not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"statusCode":{"type":"integer"},"message":{"type":"string"}},"example":{"status":"Error","statusCode":404,"message":"Character not found"}}}}},"500":{"description":"Internal Server Error"}}}}},"components":{"schemas":{"Health":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"],"example":"ok"},"version":{"type":"string","nullable":true,"example":"3.0.0"},"uptime":{"type":"integer","description":"Process uptime in seconds","example":3600},"database":{"type":"string","enum":["up","down"],"example":"up"}}},"Movie":{"type":"object","properties":{"id":{"type":"integer","description":"Movie ID"},"title":{"type":"string","description":"Movie title"},"release_date":{"type":"string","description":"Movie release date"},"box_office":{"type":"integer","description":"Movie box office as a decimal"},"duration":{"type":"integer","description":"Movie duration in minutes"},"overview":{"type":"string","description":"Movie description"},"cover_url":{"type":"string","description":"Movie url image"},"trailer_url":{"type":"string","description":"YouTube movie trailer URL"},"directed_by":{"type":"string","description":"Name of who directed the movie"},"phase":{"type":"integer","description":"Phase to which the movie belongs"},"saga":{"type":"string","description":"Saga to which the movie belongs"},"chronology":{"type":"integer","description":"Position of the movie in chronological order"},"post_credit_scenes":{"type":"integer","description":"Number of post-credit scenes in the movie"},"imdb_id":{"type":"string","description":"IMDB ID"},"studio":{"type":"string","description":"Production studio (e.g., Marvel Studios, FOX, Sony)","example":"Marvel Studios"},"continuity":{"type":"string","description":"Story/branding group (e.g., MCU, FOX X-Men Universe)","example":"MCU"},"multiverse_designation":{"type":"string","description":"Multiverse Earth designation (e.g., Earth-616, Earth-838)","example":"Earth-616"},"is_mcu":{"type":"boolean","description":"Whether the movie is part of the official MCU","example":true},"type":{"type":"string","description":"Content type","example":"movie"},"timeline_chronology_order":{"type":"integer","description":"Chronological order within the universe","example":1},"updated_at":{"type":"string","format":"date-time","description":"Timestamp of the last update to the movie record"},"_links":{"$ref":"#/components/schemas/ResourceLinks"}}},"TVShow":{"type":"object","properties":{"id":{"type":"integer","description":"TV Show ID"},"title":{"type":"string","description":"TV Show title"},"release_date":{"type":"string","description":"TV Show release date"},"last_aired_date":{"type":"string","description":"TV Show last episode date"},"season":{"type":"integer","description":"TV Show's season number"},"number_episodes":{"type":"integer","description":"Number of episodes of the tv show"},"overview":{"type":"string","description":"TV Show description"},"cover_url":{"type":"string","description":"TV Show url image"},"trailer_url":{"type":"string","description":"TV Show url trailer"},"directed_by":{"type":"string","description":"Name of who directed the tv show"},"phase":{"type":"integer","description":"Phase to which the tv show belongs"},"saga":{"type":"string","description":"Saga to which the tv show belongs"},"chronology":{"type":"integer","description":"Position of the tv show in chronological order"},"post_credit_scenes":{"type":"integer","description":"Number of post-credit scenes in the tv show"},"imdb_id":{"type":"string","description":"IMDB ID"},"studio":{"type":"string","description":"Production studio (e.g., Marvel Studios, FOX, Sony)","example":"Marvel Studios"},"continuity":{"type":"string","description":"Story/branding group (e.g., MCU, FOX X-Men Universe)","example":"MCU"},"multiverse_designation":{"type":"string","description":"Multiverse Earth designation (e.g., Earth-616, Earth-838)","example":"Earth-616"},"is_mcu":{"type":"boolean","description":"Whether the TV show is part of the official MCU","example":true},"type":{"type":"string","description":"Content type","example":"tvshow"},"timeline_chronology_order":{"type":"integer","description":"Chronological order within the universe","example":25},"updated_at":{"type":"string","format":"date-time","description":"Timestamp of the last update to the tv show record"},"_links":{"$ref":"#/components/schemas/ResourceLinks"}}},"Character":{"type":"object","properties":{"id":{"type":"integer","description":"Character ID"},"name":{"type":"string","description":"Character's real name","example":"Tony Stark"},"alias":{"type":"string","description":"Character's superhero/villain alias","example":"Iron Man"},"description":{"type":"string","description":"Character description"},"image_url":{"type":"string","description":"Character image URL"},"played_by":{"type":"string","description":"Actor name(s); recast characters list all, comma-separated","example":"Edward Norton, Mark Ruffalo"},"continuity":{"type":"string","description":"Story/branding group (e.g., MCU, FOX X-Men Universe)","example":"MCU"},"multiverse_designation":{"type":"string","description":"Multiverse Earth designation (e.g., Earth-616, Earth-838)","example":"Earth-616"},"variant_of":{"type":"integer","description":"ID of the character this is a variant of","example":1},"first_appearance_movie_id":{"type":"integer","description":"ID of the movie where the character first appears"},"first_appearance_tvshow_id":{"type":"integer","description":"ID of the TV show where the character first appears"},"created_at":{"type":"string","format":"date-time","description":"When the character was created in the database"},"updated_at":{"type":"string","format":"date-time","description":"When the character was last updated"},"_links":{"$ref":"#/components/schemas/ResourceLinks"}}},"Person":{"type":"object","properties":{"id":{"type":"integer","description":"Person ID"},"name":{"type":"string","description":"Person's real name","example":"Robert Downey Jr."},"created_at":{"type":"string","format":"date-time","description":"When the person was created in the database"},"updated_at":{"type":"string","format":"date-time","description":"When the person was last updated"},"_links":{"$ref":"#/components/schemas/ResourceLinks"}}},"PostCreditScene":{"type":"object","properties":{"id":{"type":"integer","description":"Post-credit scene ID"},"movie_id":{"type":"integer","description":"ID of the movie this scene appears in (mutually exclusive with tvshow_id)","nullable":true},"tvshow_id":{"type":"integer","description":"ID of the TV show this scene appears in (mutually exclusive with movie_id)","nullable":true},"description":{"type":"string","description":"What happens in the scene","example":"Nick Fury approaches Tony Stark to discuss the Avengers Initiative."},"teases_movie_id":{"type":"integer","description":"ID of the movie this scene teases, if any (mutually exclusive with teases_tvshow_id)","nullable":true},"teases_tvshow_id":{"type":"integer","description":"ID of the TV show this scene teases, if any (mutually exclusive with teases_movie_id)","nullable":true},"is_stinger":{"type":"boolean","description":"true = mid-credits scene, false = final post-credits scene","example":false},"created_at":{"type":"string","format":"date-time","description":"When the scene was created in the database"},"updated_at":{"type":"string","format":"date-time","description":"When the scene was last updated"},"_links":{"$ref":"#/components/schemas/ResourceLinks"}}},"TimelineContinuity":{"type":"object","properties":{"continuity":{"type":"string","description":"Story/branding group (e.g., MCU, FOX X-Men Universe)","example":"MCU"},"multiverse_designation":{"type":"string","description":"Multiverse Earth designation (e.g., Earth-616, Earth-838)","example":"Earth-616"},"entries":{"type":"array","items":{"$ref":"#/components/schemas/TimelineEntry"},"description":"Chronologically ordered list of movies and TV shows"}}},"TimelineEntry":{"type":"object","properties":{"id":{"type":"integer","description":"Movie or TV show ID"},"title":{"type":"string","description":"Movie or TV show title","example":"Iron Man"},"chronology_order":{"type":"integer","description":"Chronological order within the universe","example":1},"type":{"type":"string","description":"Content type (movie or tvshow)","example":"movie"},"_links":{"$ref":"#/components/schemas/ResourceLinks"}}},"UpcomingItem":{"type":"object","properties":{"id":{"type":"integer","description":"Movie or TV show ID"},"type":{"type":"string","enum":["movie","tvshow"],"description":"Content type","example":"tvshow"},"title":{"type":"string","description":"Movie or TV show title","example":"VisionQuest"},"release_date":{"type":"string","format":"date","description":"Release date"},"overview":{"type":"string","description":"Synopsis","nullable":true},"cover_url":{"type":"string","description":"Cover image URL","nullable":true},"continuity":{"type":"string","description":"Story/branding group (e.g., MCU, FOX X-Men Universe)","example":"MCU"},"multiverse_designation":{"type":"string","description":"Multiverse Earth designation (e.g., Earth-616, Earth-838)","example":"Earth-616"},"is_mcu":{"type":"boolean","description":"Whether the title is part of the official MCU","example":true},"phase":{"type":"integer","description":"Phase to which the title belongs"},"saga":{"type":"string","description":"Saga to which the title belongs"},"_links":{"$ref":"#/components/schemas/ResourceLinks"}}},"Stats":{"type":"object","properties":{"movies":{"type":"integer","description":"Total number of movies","example":74},"tvshows":{"type":"integer","description":"Total number of TV shows","example":56},"characters":{"type":"integer","description":"Total number of characters","example":302},"people":{"type":"integer","description":"Total number of people","example":372},"titles":{"type":"integer","description":"movies + tvshows","example":130},"continuities":{"type":"integer","description":"Distinct non-null continuity values across movies + tvshows only","example":10},"designations":{"type":"integer","description":"Distinct non-null multiverse_designation values across movies + tvshows + characters","example":5},"last_updated":{"type":"string","format":"date-time","nullable":true,"description":"Max updated_at across movies, tvshows and characters; null when all three tables are empty"},"_links":{"$ref":"#/components/schemas/ResourceLinks"}}},"Link":{"type":"object","properties":{"href":{"type":"string","example":"https://mcuapi.example.com/api/v1/movies/1"}}},"ResourceLinks":{"type":"object","description":"HAL-style hypermedia links. Each relation maps to a Link or an array of Links.","additionalProperties":{"oneOf":[{"$ref":"#/components/schemas/Link"},{"type":"array","items":{"$ref":"#/components/schemas/Link"}}]},"example":{"self":{"href":"https://mcuapi.example.com/api/v1/movies/1"},"characters":{"href":"https://mcuapi.example.com/api/v1/characters/movie/1"},"post_credit_scenes":{"href":"https://mcuapi.example.com/api/v1/post-credit-scenes/movie/1"}}}}}}