Guides .md

Building batch & collection tools

Build a tool that reads metadata, lists, or library matches for many titles at once, the way a media-server metadata agent or a collection manager does.

1. Create an API key with the read scope#

A batch tool that only reads catalog data, lists, and sync state needs the read scope, not write. See Authentication for how the key attaches to a request.

2. Pull catalog metadata for the titles you already matched#

Once your tool has a TMDB ID for a title (from your own matching step or from a library's existing metadata), pull its full record from the catalog.

curl "https://flicklist.tv/api/v3/movie/550?api_key=$API_KEY"

const res = await fetch(
  `https://flicklist.tv/api/v3/movie/550?api_key=${apiKey}`
);
const movie = await res.json();

import requests
r = requests.get(
    "https://flicklist.tv/api/v3/movie/550",
    params={"api_key": api_key},
)
movie = r.json()

See Catalog for the rest of the read endpoints, including discover and search for titles you haven't matched yet.

3. Resolve mixed external IDs to one identifier#

Most libraries mix ID types. Some items only have an IMDb ID, others only a TVDB ID. Use find to resolve any of them to a FlickList catalog record before you do anything else with the title.

curl "https://flicklist.tv/api/v3/find/tt0111161?api_key=$API_KEY&external_source=imdb_id"

const res = await fetch(
  `https://flicklist.tv/api/v3/find/tt0111161?api_key=${apiKey}&external_source=imdb_id`
);
const result = await res.json();

r = requests.get(
    "https://flicklist.tv/api/v3/find/tt0111161",
    params={"api_key": api_key, "external_source": "imdb_id"},
)
result = r.json()

If you're writing data back later (marking things watched, rating them), the same mixed-ID problem shows up in reverse. The ids object covers the precedence FlickList uses when a write request carries more than one ID for the same item.

4. Read public and community lists#

List reads don't require a credential when the list is public. Browse the community list surface, or pull a specific list's items, without an API key at all.

curl "https://flicklist.tv/api/v3/lists/community"

const res = await fetch('https://flicklist.tv/api/v3/lists/community');
const lists = await res.json();

r = requests.get("https://flicklist.tv/api/v3/lists/community")
lists = r.json()

See Lists for search, tags, a user's public lists, and fetching one list's items.

5. Walk pagination all the way through#

Catalog endpoints paginate in the response body, TMDB style: every page carries page, total_pages, and total_results, so read total_pages from the first response and loop. (List and history endpoints paginate through X-FlickList-* response headers instead; Pagination has the full split.)

curl "https://flicklist.tv/api/v3/discover/movie?api_key=$API_KEY&page=1"

const res = await fetch(
  `https://flicklist.tv/api/v3/discover/movie?api_key=${apiKey}&page=1`
);
const { total_pages: totalPages } = await res.json();

r = requests.get(
    "https://flicklist.tv/api/v3/discover/movie",
    params={"api_key": api_key, "page": 1},
)
total_pages = r.json()["total_pages"]

page = 1
while page <= total_pages:
    r = requests.get(
        "https://flicklist.tv/api/v3/discover/movie",
        params={"api_key": api_key, "page": page},
    )
    process(r.json()["results"])
    page += 1

See Pagination for the full set of headers and both query parameters.

6. Follow batch etiquette#

A tool that syncs on a schedule should poll GET /sync/last_activities first and only re-fetch the collections whose timestamps actually moved. Re-walking every list and every collection on every run wastes your rate budget on data that hasn't changed.