Core concepts .md

The ids object

Every Trakt-shaped object on the v3 API carries an ids block that ties the item to FlickList's own catalog and to the external databases your client already tracks.

{
  "title": "Breaking Bad",
  "year": 2008,
  "ids": {
    "fldb": "flt_9f2c8a1b",
    "slug": "breaking-bad",
    "tmdb": 1396,
    "imdb": "tt0903747",
    "tvdb": 81189,
    "anilist": null
  }
}

fldb is FlickList's own permanent public ID. It never gets reassigned, even when two catalog rows are merged into one, so it's the one identifier you can store and trust long term. Every other key is best-effort: tmdb is the primary external ID FlickList resolves against, imdb is a reliable backup when no TMDB match exists, and tvdb and anilist are nullable extras that fill in for titles those sources cover.

Using ids as input#

Write endpoints across Sync and Scrobble accept an ids block to identify the item you're acting on. You don't need every key, only enough to resolve to one catalog row:

{ "ids": { "tmdb": 1396 }, "media_type": "show" }

When an item carries more than one key, FlickList resolves in a fixed order: fldb first, then tmdb, then imdb, then tvdb. The first key present wins and the rest are ignored for that item. fldb resolves on its own since its prefix self-describes the item; every other key needs media_type on the same request, because a movie and an unrelated show adaptation can otherwise share the same external ID.

media_type accepts "tv" as a synonym of "show" on writes, so you don't need to translate your own internal vocabulary before sending a request.

Bulk write endpoints accept up to 1000 items per request. An item that doesn't resolve to any catalog row (an empty ids block, an unrecognized media_type, or no matching external id) isn't a request failure. It comes back in a not_found array so you can tell which items to look at, while every resolvable item in the same batch still succeeds:

{
  "added": 3,
  "not_found": [
    { "ids": { "tmdb": 999999999 }, "media_type": "show" }
  ]
}

Keys#

Key	Type	Presence	Notes
`fldb`	string	Always present	FlickList's permanent public ID (`flm_`/`flt_` prefix). Survives catalog merges, never reassigned.
`slug`	string or null	Read responses only	FlickList's URL slug for the title, when one exists.
`tmdb`	integer or null	Best-effort	Primary external ID FlickList resolves against.
`imdb`	string or null	Best-effort	Backup identifier when no TMDB match exists.
`tvdb`	integer or null	Best-effort, nullable	Present when FlickList has cross-linked the title to TVDB.
`anilist`	integer or null	Best-effort, nullable	Present when FlickList has cross-linked the title to AniList.

New keys can appear in this block at any time as FlickList adds sources. Treat any key not in this table the same way you treat a null value: ignore it and move on.