Your lists, in your app

1. Get a key

In Flixby, open Settings → Apps & API, name the key after your app and choose what it may do. Flixby shows the key once; copy it somewhere safe. It looks like fbx_ followed by 32 letters and numbers. Revoke it there any time and it stops working at once.

Send it with every request:

curl https://flixby.app/api/v1/lists \
  -H "Authorization: Bearer fbx_your_key_here"

Treat a key like a password: keep it on your server or device, not in a public web page or a public repository.

Try it

Check the key works (shows its name and permissions):

curl https://flixby.app/api/v1 -H "Authorization: Bearer fbx_your_key"

Make a list, then add films to it (use the list id from the first answer):

curl -X POST https://flixby.app/api/v1/lists \
  -H "Authorization: Bearer fbx_your_key" -H "Content-Type: application/json" \
  -d '{"name": "Date night", "films": [603, 550]}'

curl -X POST https://flixby.app/api/v1/lists/k3v9x2mq7a1b/films \
  -H "Authorization: Bearer fbx_your_key" -H "Content-Type: application/json" \
  -d '{"films": [13, 680], "position": 0}'

2. Permissions

• lists:read see your lists and the films on them (every key has this)
• lists:write create, rename, reorder and delete lists; add or remove films
• lists:publish put lists on your profile wall or take them off (lists stay private unless published)

Call GET /api/v1 to see which permissions a key has. More areas (Saved, Tonight, Watched, ratings) will get their own permissions later; existing ones won’t change.

3. Films and shows

Films are identified by their TMDB movie id (for example 603 is The Matrix). Flixby lists can hold TV shows too: a show’s id is 900000000 plus its TMDB TV id (Breaking Bad, TMDB TV 1396, is 900001396). Send shows that way when you add them. When you read a list, films keeps these ids in list order, and movies and shows give the plain TMDB movie and TV ids separately. The API returns ids only; look up titles and posters with TMDB’s own API under their terms. New films and shows must exist at TMDB, and up to 100 can be added per request.

4. Lists

A list looks like this:

{
  "id": "k3v9x2mq7a1b",
  "name": "Date night",
  "filmCount": 3,
  "films": [603, 550, 900001396],
  "movies": [603, 550],
  "shows": [1396],
  "published": false,
  "publishedAt": null,
  "createdAt": "2026-10-22T09:00:00.000Z",
  "updatedAt": "2026-10-22T09:30:00.000Z",
  "version": "9f2c1a7b0e4d6c3a"
}

Names are 1 to 60 characters and unique (ignoring capitals); “Saved for later” is taken by Flixby. You can have up to 100 lists of up to 5,000 films. A film is on a list at most once.

5. List links for Radarr and Sonarr

Apps such as Radarr and Sonarr read a list from a plain web address and can’t send a key. For them, switch on List links in Settings → Apps & API. Every list, plus Saved and Tonight, then gets two private links:

https://flixby.app/feeds/<secret>/<list id | saved | tonight>/radarr
https://flixby.app/feeds/<secret>/<list id | saved | tonight>/sonarr

• /radarr gives the list’s films as [{"id": 603}, …] (TMDB movie ids). In Radarr: Settings → Lists → + → Custom Lists, paste it as the List URL.
• /sonarr gives its TV shows as [{"tvdbId": 81189, "tmdbId": 1396, "imdbId": "tt0903747"}, …]. In Sonarr: Settings → Import Lists → + → Custom List, paste it as the List URL.

The secret is the same for all your links and only lets someone read lists, never change them; it is not your API key. Reset links makes a new secret and the old links stop working at once. Radarr checks lists every 12 hours and Sonarr every 6, so new films arrive automatically but not instantly. With a key, GET /api/v1/lists includes each list’s links (and Saved and Tonight’s) while List links are on.

6. Keeping in sync

1. Call GET /api/v1/lists and keep the syncToken and each list’s version.
2. Later, send If-None-Match: "<syncToken>". A 304 means nothing changed. Otherwise compare versions: fetch lists whose version changed, add new ones, and drop ids that are gone (deleted in Flixby).
3. When you change a list, send If-Match: "<version>". If someone changed it in Flixby since you read it, you get 412 with the current version instead of overwriting their change. Read it again, merge, and retry.

Every change answers with the updated list and its new version (also in the ETag header). Changes show up in the Flixby app the next time it syncs (when it’s opened or brought back to the front).

7. Limits and errors

Each key can make 60 requests a minute and 2,000 a day (the day resets at midnight UTC). Over that you get 429 with a Retry-After header in seconds.

Errors are JSON with a plain sentence and a code to check in your app:

{"error": "There’s no list with that id.", "code": "list_not_found"}

• 400 something in the request is wrong (invalid_name, invalid_films, invalid_json…)
• 401 missing_key or invalid_key · 403 missing_scope
• 404 list_not_found, film_not_on_list
• 409 name_taken; busy (another device saved at the same moment: retry); no_profile (open Flixby once first)
• 412 version_mismatch · 422 unknown_films (with the ids), too_many_new_films, list_full, too_many_lists
• 429 rate_limited · 503 try again shortly

The API answers browsers from any website (CORS), but because a key can change your lists, only use it in apps you trust.

Rules

Use the API for your own account, or with the clear permission of the person whose key it is. Don’t share keys, try to get around the limits, or use the API to send spam. Flixby can revoke keys that break these rules or the terms of service. The privacy policy explains what a connected app can see. Questions or ideas: flixby.admin@gmail.com.