# Collections API > A collection groups the movies of one franchise, such as a trilogy or a long running series of films. GET /3/collection/{collection_id} returns its name, overview, artwork and a parts array of movies in release order. Movies point back to their collection through belongs_to_collection, so you can move in both directions. ## Endpoint `GET /3/collection/{collection_id}` ```bash curl "https://api.amodb.dev/3/collection/10?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` Response: ```json { "id": 10, "name": "Star Wars - Saga", "overview": "An epic space-opera theatrical film series, which depicts the adventures of various characters \"a long time ago in a galaxy far, far away….\"", "poster_path": "/6mHkagjziBPth2Mx0VpEercocm4.jpg", "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg", "parts": [ { "adult": false, "backdrop_path": "/jKquaxnCRelAbibZVMdTsUEnkKm.jpg", "genre_ids": [ 12, 28, 878 ], "id": 11, "original_language": "en", "original_title": "Star Wars", "overview": "Princess Leia is captured and held hostage by the evil Imperial forces in their effort to take over the galactic Empire. Venturesome Luke Skywalker and dashing captain Han Solo team together with the loveable robot duo R2-D2 and C-3PO to re...", "popularity": 70.481, "poster_path": "/fai0rspsNeJCS69wHNjOdWxcI7P.jpg", "release_date": "1977-05-25", "title": "Star Wars", "video": false, "vote_average": 8.207, "vote_count": 23028, "media_type": "movie" }, { "adult": false, "backdrop_path": "/k9pshruhCpJAdH9RaGJO6jaWQ4X.jpg", "genre_ids": [ 12, 28, 878 ], "id": 1891, "original_language": "en", "original_title": "The Empire Strikes Back", "overview": "The epic saga continues as Luke Skywalker, in hopes of defeating the evil Galactic Empire, learns the ways of the Jedi from aging master Yoda. But Darth Vader is more determined than ever to capture Luke. Meanwhile, rebel leader Princess Le...", "popularity": 29.9034, "poster_path": "/nNAeTmF4CtdSgMDplXTDPOpYzsX.jpg", "release_date": "1980-05-20", "title": "The Empire Strikes Back", "video": false, "vote_average": 8.393, "vote_count": 18993, "media_type": "movie" }, { "adult": false, "backdrop_path": "/ziECpBRIyclmBNaFSWlvCfsKbMD.jpg", "genre_ids": [ 12, 28, 878 ], "id": 1892, "original_language": "en", "original_title": "Return of the Jedi", "overview": "Luke Skywalker leads a mission to rescue his friend Han Solo from the clutches of Jabba the Hutt, the Emperor prepares to crush the Rebellion with a more powerful Death Star, and the Rebel fleet mounts a massive attack on the space station....", "popularity": 26.3255, "poster_path": "/jQYlydvHm3kUix1f8prMucrplhm.jpg", "release_date": "1983-05-25", "title": "Return of the Jedi", "video": false, "vote_average": 7.911, "vote_count": 17442, "media_type": "movie" } ] } ``` ## Get a collection `GET /3/collection/{collection_id}` returns one franchise: its name, an overview, a poster, a backdrop and the `parts` array. Each part is a movie summary with the fields you need for a card, so one call can draw a whole franchise shelf. The example loads collection 10, the Star Wars films, and prints its movies in release order. ```bash curl -s "https://api.amodb.dev/3/collection/10?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const url = 'https://api.amodb.dev/3/collection/10?language=en-US'; const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const collection = await res.json(); console.log(collection.name); for (const p of collection.parts) console.log(p.release_date || 'not dated', p.title); ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/collection/10", params={"language": "en-US"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() collection = r.json() print(collection["name"]) for p in collection["parts"]: print(p.get("release_date") or "not dated", p["title"]) ``` ```php true, CURLOPT_TIMEOUT => 10, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')], ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($status !== 200) { throw new RuntimeException("amodb returned $status"); } $collection = json_decode($body, true); echo $collection['name'], PHP_EOL; foreach ($collection['parts'] as $p) { echo $p['release_date'] ?: 'not dated', ' ', $p['title'], PHP_EOL; } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "time" ) type Collection struct { Name string `json:"name"` Parts []struct { Title string `json:"title"` ReleaseDate string `json:"release_date"` } `json:"parts"` } func main() { url := "https://api.amodb.dev/3/collection/10?language=en-US" req, _ := http.NewRequest("GET", url, nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY")) client := &http.Client{Timeout: 10 * time.Second} res, err := client.Do(req) if err != nil { panic(err) } defer res.Body.Close() if res.StatusCode != http.StatusOK { panic(res.Status) } var c Collection if err := json.NewDecoder(res.Body).Decode(&c); err != nil { panic(err) } fmt.Println(c.Name) for _, p := range c.Parts { date := p.ReleaseDate if date == "" { date = "not dated" } fmt.Println(date, p.Title) } } ``` ### Parameters | Parameter | In | Required | Description | | --------------- | ----- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `collection_id` | path | yes | Numeric collection id, for example `10`. | | `api_key` | query | one of two | Your key. Use this or the `Authorization: Bearer` header. | | `language` | query | no | One of the 14 served languages, for example `en-US` or `fr-FR`. Sets the language of each part's title and overview. Default `en-US`. | The collection's own `name` and `overview` come as stored and do not change with `language`. For some collections they are not in English. ### Response fields | Field | Type | Notes | | ---------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------ | | `id` | integer | Collection id. | | `name` | string | Franchise name. | | `overview` | string | Short description. Empty for some collections. | | `poster_path`, `backdrop_path` | string or null | Append to `https://img.amodb.dev/t/p/{size}`. See [images](https://amodb.dev/images-api/). | | `parts` | array | Movie summaries, oldest `release_date` first. | | `parts[].id` | integer | Movie id. Pass it to [movie details](https://amodb.dev/movies/). | | `parts[].title`, `parts[].original_title` | string | Localized and original title. | | `parts[].overview` | string | Localized synopsis. | | `parts[].release_date` | string | `YYYY-MM-DD`, or an empty string for a film without a date. Those parts come last. | | `parts[].media_type` | string | Always `movie` in a collection. | | `parts[].genre_ids` | array | Numeric ids. Names come from [genres](https://amodb.dev/genres/). | | `parts[].adult`, `parts[].video` | boolean | `adult` is always `false`, because adult titles are not served. | | `parts[].original_language` | string | Two letter language code. | | `parts[].popularity` | number | Popularity score. | | `parts[].poster_path`, `parts[].backdrop_path` | string or null | Artwork of the film. | | `parts[].vote_average`, `parts[].vote_count` | number, integer | Aggregate user score. | ### Example response Two of the nine parts are shown. ```json { "id": 10, "name": "Star Wars Collection", "overview": "An epic space-opera theatrical film series, which depicts the adventures of various cha...", "poster_path": "/pWVLFh4OuejTpUaDQbB1C4zoS2p.jpg", "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg", "parts": [ { "adult": false, "backdrop_path": "/zqkmTXzjkAgXmEWLRsY4UpTWCeo.jpg", "genre_ids": [12, 28, 878], "id": 11, "original_language": "en", "original_title": "Star Wars", "overview": "Princess Leia is captured and held hostage by the evil Imperial forces in their effort...", "popularity": 70.481, "poster_path": "/fai0rspsNeJCS69wHNjOdWxcI7P.jpg", "release_date": "1977-05-25", "title": "Star Wars", "video": false, "vote_average": 8.207, "vote_count": 23025, "media_type": "movie" }, { "adult": false, "backdrop_path": "/k9pshruhCpJAdH9RaGJO6jaWQ4X.jpg", "genre_ids": [12, 28, 878], "id": 1891, "original_language": "en", "original_title": "The Empire Strikes Back", "overview": "The epic saga continues as Luke Skywalker, in hopes of defeating the evil Galactic Empi...", "popularity": 29.9034, "poster_path": "/nNAeTmF4CtdSgMDplXTDPOpYzsX.jpg", "release_date": "1980-05-20", "title": "The Empire Strikes Back", "video": false, "vote_average": 8.393, "vote_count": 18990, "media_type": "movie" } ] } ``` Long strings are cut with `...` for this page. The real response holds the full text. ## Find the collection of a movie You rarely start from a collection id. You start from a movie, and the [movie details](https://amodb.dev/movies/) record tells you where it belongs. The `belongs_to_collection` field is an object with `id`, `name`, `poster_path` and `backdrop_path`. It is `null` for a movie that is not part of a franchise, such as movie 550. ```json { "id": 11, "title": "Star Wars", "belongs_to_collection": { "id": 10, "name": "Star Wars Collection", "poster_path": "/pWVLFh4OuejTpUaDQbB1C4zoS2p.jpg", "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg" } } ``` The sample below follows that link from a movie to its franchise in two requests. ```js const base = 'https://api.amodb.dev/3'; const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` }; async function getJson(path) { const res = await fetch(`${base}${path}`, { headers }); if (!res.ok) throw new Error(`${path} returned ${res.status}`); return res.json(); } const movie = await getJson('/movie/11'); if (movie.belongs_to_collection) { const collection = await getJson(`/collection/${movie.belongs_to_collection.id}`); console.log(movie.title, 'is one of', collection.parts.length, 'films in', collection.name); } ``` ## Artwork and search The poster and backdrop of a franchise are the `poster_path` and `backdrop_path` fields of the collection record. Build the file address from them as described on [images](https://amodb.dev/images-api/). amodb does not offer the `/collection/{collection_id}/images` and `/collection/{collection_id}/translations` paths, so a collection has no list of alternate posters and no per language rows. Part titles follow the `language` parameter instead, and [translations](https://amodb.dev/translations/) covers the paths that do return language rows. To find a collection by name, use `GET /3/search/collection?query=matrix`, described on [search](https://amodb.dev/search/). Each result has `id`, `name`, `overview`, `poster_path`, `backdrop_path`, `original_language`, `original_name` and `adult`. ## Errors | HTTP | status_code | When | | ---- | ----------- | --------------------------------------------------------------------------- | | 401 | 7 | The key is missing or wrong. | | 402 | 36 | The plan period has ended. | | 404 | 34 | No collection with that id, or an id that is not a number. | | 405 | 37 | You used a write method on a collection path. | | 429 | 25 | You went over your requests per minute. Wait for the `Retry-After` seconds. | See [errors](https://amodb.dev/errors/) for the full list and [rate limits](https://amodb.dev/rate-limits/) for plan limits. ## Practical notes - Collections group movies only. A movie holds at most one `belongs_to_collection` object, so one film maps to one franchise. - Parts arrive in release order. Films with an empty date come last, so label them as not dated yet. - The collection record is cached at the edge for 6 hours like other details, so a franchise page can reuse one response for that long. - A part carries summary fields only. Fetch runtime, credits and ratings per film through [movie details](https://amodb.dev/movies/) when the user opens it. - Use `parts[].id` as your key for a film, not its position in the franchise. Orders and dates get corrected over time. - Check that `name` is in your display language before you show it. Some collections carry a name in another language, and `language` does not change it. ## Questions and answers ### How do I know whether a movie belongs to a collection? Read belongs_to_collection on the movie details record. It is an object with id, name, poster_path and backdrop_path, or null when the movie stands alone. Use that id in the collection path. ### Are the parts returned in release order? Yes. The parts array comes oldest first by release_date. A film without a date has an empty release_date and is placed last, so label it as not dated yet. ### Do TV series have collections? No. Collections group movies. A series is described by its seasons and episodes, which are documented on the TV series and seasons and episodes pages. ### How do I search for a collection by name? Use the collection search path, for example /3/search/collection?query=matrix. It returns a paged list with id, name and artwork. Take the id and call the collection endpoint for the parts. ## Related pages - [Movie details API](https://amodb.dev/movies/): Movie details API with the same paths and JSON as TMDB v3. Get one movie by id, add credits, ratings and moods with append_to_response, in 14 languages. - [Search API](https://amodb.dev/search/): Search API with the same paths and JSON as TMDB v3. Find movies, TV shows, people, collections, companies and keywords by text, with year filters and paging. - [Images API and the TMDB image path](https://amodb.dev/images-api/): Build a TMDB image path: https://img.amodb.dev/t/p/{size}/{file}. List posters, backdrops and logos per title, then load them in 10 sizes with no key. - [Translations API](https://amodb.dev/translations/): Movie translations API with TMDB v3 paths: read every stored title, overview and tagline of a movie, series or episode in all its languages at once. - [TMDB discover API for movies and TV shows](https://amodb.dev/discover/): TMDB discover API with the same filters as TMDB v3. Discover movies and TV shows by genre, cast, company, keyword, year, rating, runtime and provider. - [Quickstart](https://amodb.dev/quickstart/): Make your first amodb call: get a key, request movie details in curl, JavaScript, Python, PHP or Go, then load the poster from img.amodb.dev. Under 2 minutes. Updated: 2026-10-18. Source: https://amodb.dev/collections/