FlickFlick
FlickAPIBeta

Flick API · Beta

API Reference

Read your own Flick data — profile, reviews, watchlist, lists — and write reviews to your own account, over plain JSON. Every endpoint below has a built-in Try it console — paste a key once and send live requests right from the docs.

This API is in beta.

Endpoints, response shapes, limits, and policies can and will change without notice while we iterate — pin nothing, handle errors defensively, and expect breaking changes. Feedback, feature requests, and bug reports: Discord.

Stored only in this browser tab and sent only to http://localhost:8080. No key yet? Create one.

Introduction

The Flick API is scoped to yourdata: an API key acts on behalf of the account that created it. There is no OAuth and no access to other users' accounts — keys read and write the key owner's data only.

All endpoints live under https://flickmovies.com/api/beta and accept and return JSON.

OpenAPI is the industry-standard format for describing a REST API in a single machine-readable file — every path, parameter, and response shape. We publish ours at /api/beta/openapi.json. Point a tool at it to generate a typed client in your language (openapi-generator, Speakeasy, etc.), import it into Postman or Insomnia, or feed it to an AI assistant — no hand-copying of endpoints. The OpenAPI link in the top nav opens /api/beta/docs, a Swagger UI rendered from that same schema where you can browse and try endpoints against the live server. (For most things, the inline Try it consoles below are quicker.)

API access requires a Flick Pro subscription. By using the API you agree to the API Terms of Service.

Base URL
https://flickmovies.com/api/beta

Authentication

Create an API key on the API keys page — sign in with the same email or phone you use in the Flick app. Keys look like flick_sk_… and the full key is shown once, at creation; store it somewhere safe.

Pass the key on every request, either as a bearer token or an X-API-Key header. You can hold up to 5 active keys and revoke any of them at any time from the same page — revocation takes effect within about 30 seconds.

Keys are personal and non-transferable. Don't embed them in client-side code or public repos — anyone with your key can read and write your Flick data. If a key leaks, revoke it immediately.

Either header works
curl https://flickmovies.com/api/beta/me \
  -H "Authorization: Bearer flick_sk_YOUR_KEY"

# or
curl https://flickmovies.com/api/beta/me \
  -H "X-API-Key: flick_sk_YOUR_KEY"

Rate limits

Default limits are 60 requests/minute and 5,000 requests/day per key (subject to change during beta — reach out on Discord if you need more). Daily windows reset at UTC midnight.

Exceeding a limit returns 429 with a Retry-After header (seconds). Back off and retry after that long.

X-RateLimit-LimitRequests allowed per minute
X-RateLimit-RemainingRemaining in the current minute window
X-RateLimit-ResetUnix time when the minute window resets
X-RateLimit-Limit-DayRequests allowed per day (UTC days)
X-RateLimit-Remaining-DayRemaining in the current UTC day
Retry-AfterOn 429 only — seconds to wait before retrying
On every response
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 41
X-RateLimit-Reset: 1781200560
X-RateLimit-Limit-Day: 5000
X-RateLimit-Remaining-Day: 4817
429 · rate_limited
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded for the minute window. Retry after 12 seconds."
  }
}

Errors

Every error — auth, validation, rate limiting, server faults — uses the same envelope: an error object with a stable machine-readable code and a human-readable message. Match on the code, not the message.

400invalid_requestMalformed body or query params
401invalid_api_keyMissing, malformed, or unknown key
401api_key_revokedKey was revoked
403pro_requiredAccount no longer has Pro
404not_foundResource doesn't exist or isn't yours
404media_not_foundNo such title on TMDB
429rate_limitedRate limit exceeded — back off per Retry-After
500internal_errorSomething broke on our side
503api_disabledAPI temporarily disabled (check Discord)
Error envelope
{
  "error": {
    "code": "media_not_found",
    "message": "No movie found on TMDB for tmdb_id 999999999."
  }
}

Pagination & media

List endpoints paginate with ?page=1&limit=50 (limit max 100) and return a { data, page, limit, total, has_more } envelope. Pagination style may change to cursors before GA.

Titles are identified by their TMDB id plus a media_type of movie, tv, tv_season, or tv_episode. For seasons and episodes, pass the show's TMDB id along with season_number (and episode_number for episodes).

Everywhere a title appears in a response it uses the same media object. The season_number, episode_number, and show_title fields are present only for seasons and episodes.

Paginated envelope
{
  "data": [ … ],
  "page": 1,
  "limit": 50,
  "total": 412,
  "has_more": true
}
Media object
{
  "tmdb_id": "1396",
  "type": "tv_episode",
  "title": "Pilot",
  "year": 2008,
  "poster_url": "https://image.tmdb.org/t/p/w500/…",
  "season_number": 1,
  "episode_number": 1,
  "show_title": "Breaking Bad"
}

Profile

Get your profile

GET/api/beta/me

The profile of the account that owns the API key.

curl https://flickmovies.com/api/beta/me \
  -H "Authorization: Bearer flick_sk_YOUR_KEY"
Response · 200
{
  "id": "abc123",
  "username": "moviebuff",
  "display_name": "Movie Buff",
  "bio": "Watching everything.",
  "profile_picture_url": "https://…",
  "is_pro": true
}

Update your profile

PATCH/api/beta/me

Update your own display name and bio.

Only the fields you send change; omitted fields are left as-is.

Body parameters

display_namestring· max 120 chars

Your display name.

biostring· max 2,000 chars

Your profile bio.

curl -X PATCH https://flickmovies.com/api/beta/me \
  -H "Authorization: Bearer flick_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Movie Buff",
    "bio": "Watching everything."
  }'
Response · 200
{
  "id": "abc123",
  "username": "moviebuff",
  "display_name": "Movie Buff",
  "bio": "Watching everything.",
  "profile_picture_url": "https://…",
  "is_pro": true
}

List users you follow

GET/api/beta/me/following

The users you follow, most recently followed first. Each user_id here is exactly what watched_with accepts (you can also pass the @username).

This is the discovery endpoint for co-watcher tagging: list who you follow, then pass their user_id (or @username) to watched_with on a review write.

Query parameters

pageinteger· default 1

Page number, 1-indexed.

limitinteger· default 50, max 100· default 50

Items per page.

curl "https://flickmovies.com/api/beta/me/following?page=1&limit=2" \
  -H "Authorization: Bearer flick_sk_YOUR_KEY"
Response · 200
{
  "data": [
    {
      "user_id": "uid_friend",
      "username": "alice",
      "display_name": "Alice",
      "profile_picture_url": "https://…",
      "is_pro": true,
      "followed_at": "2026-06-01T00:00:00+00:00"
    }
  ],
  "page": 1,
  "limit": 2,
  "total": 37,
  "has_more": true
}

Media

Resolve a title to a TMDB id

GET/api/beta/resolve

Best-effort lookup from loose metadata you already have — a title, optionally a year and type — to the TMDB id and media_type the rest of the API expects.

Handy before a review write: most catalogs and spreadsheets carry a title and year, not a TMDB id. Resolve once, then POST to /me/reviews with the result.

This is a fuzzy match, not an authority. match is the strongest candidate (or null when nothing plausible turns up); candidates holds up to five ranked alternatives. Each carries a score (0–1) and a confidence of high, medium, or low — verify before trusting a low.

Only movie and tv are resolvable here. For a specific season or episode, resolve the show, then pass season_number / episode_number to the review endpoints.

Query parameters

titlestringrequired· 1–200 chars

The title to search for.

yearinteger

Release (or first-air) year. Narrows same-named titles.

media_typestring

Narrow to movie or tv. Omit to search both.

curl "https://flickmovies.com/api/beta/resolve?title=The%20Matrix&year=1999&media_type=movie" \
  -H "Authorization: Bearer flick_sk_YOUR_KEY"
Response · 200
{
  "query": { "title": "The Matrix", "year": 1999, "media_type": "movie" },
  "match": {
    "tmdb_id": "603",
    "media_type": "movie",
    "title": "The Matrix",
    "year": 1999,
    "poster_url": "https://image.tmdb.org/t/p/w500/…",
    "score": 0.97,
    "confidence": "high"
  },
  "candidates": [
    {
      "tmdb_id": "603",
      "media_type": "movie",
      "title": "The Matrix",
      "year": 1999,
      "poster_url": "https://image.tmdb.org/t/p/w500/…",
      "score": 0.97,
      "confidence": "high"
    }
  ]
}
No confident match
curl "https://flickmovies.com/api/beta/resolve?title=asdkjfhqwoeiu" \
  -H "Authorization: Bearer flick_sk_YOUR_KEY"

Reviews

List your reviews

GET/api/beta/me/reviews

Your reviews. Defaults to newest first; every filter below is optional and they combine (AND).

source is app (logged in the app), import (Letterboxd/CSV import), or api (created via this API).

is_log is true for a plain watch log — no rating, no review text, no photos; the row only records that you watched (e.g. a quick episode mark in the app). Anything carrying an opinion is is_log: false.

watch_context ("how you watched") is an object or null; watched_with is a list of user ids.

Pass tmdb_id together with media_type to fetch your review(s) of one specific title.

Query parameters

media_typestring

Filter to one type: movie, tv, tv_season, or tv_episode.

tmdb_idstring

Only your review(s) of this title. Requires media_type.

tagstring

Only reviews carrying this exact tag.

min_ratingnumber

Lowest rating to include.

max_ratingnumber

Highest rating to include.

ratedboolean

true = only rated reviews; false = only unrated (text-only reviews and watch logs). Omit for both.

sortstring

Sort field: created_at (default), watched_date, or rating.

orderstring

desc (default) or asc.

pageinteger· default 1

Page number, 1-indexed.

limitinteger· default 50, max 100· default 50

Items per page.

curl "https://flickmovies.com/api/beta/me/reviews?page=1&limit=2" \
  -H "Authorization: Bearer flick_sk_YOUR_KEY"
Response · 200
{
  "data": [
    {
      "id": "5f0c4f7a-…",
      "media": {
        "tmdb_id": "603",
        "type": "movie",
        "title": "The Matrix",
        "year": 1999,
        "poster_url": "https://image.tmdb.org/t/p/w500/…"
      },
      "rating": 9.2,
      "review": "Still holds up.",
      "watched_date": "2026-06-01T00:00:00+00:00",
      "created_at": "2026-06-02T18:21:09.123456+00:00",
      "tags": ["sci-fi"],
      "watch_context": { "source": "theater", "format": "IMAX" },
      "watched_with": ["uid_friend"],
      "source": "app",
      "is_log": false
    }
  ],
  "page": 1,
  "limit": 2,
  "total": 412,
  "has_more": true
}

Get one of your reviews

GET/api/beta/me/reviews/{review_id}

Fetch a single review you own by id.

Path parameters

review_idstringrequired

The review id (from GET /me/reviews).

Endpoint errors

404not_foundThe review doesn't exist or isn't yours
curl https://flickmovies.com/api/beta/me/reviews/5f0c4f7a-%E2%80%A6 \
  -H "Authorization: Bearer flick_sk_YOUR_KEY"
Response · 200
{
  "id": "5f0c4f7a-…",
  "media": { "tmdb_id": "603", "type": "movie", "title": "The Matrix", "year": 1999, "poster_url": "https://…" },
  "rating": 9.2,
  "review": "Still holds up.",
  "watched_date": "2026-06-01T00:00:00+00:00",
  "created_at": "2026-06-02T18:21:09+00:00",
  "tags": ["sci-fi"],
  "watch_context": { "source": "theater", "format": "IMAX" },
  "watched_with": [],
  "source": "api",
  "is_log": false
}

Create a review

POST/api/beta/me/reviews

Add one review to your account.

Re-POSTing an identical review (same title, rating, text, watched date) is deduplicated and returns 200 with deduplicated: true instead of creating a copy.

Reviews created via the API are tagged source: "api" and show up in the app like imported reviews. Rewatch numbering and rating-tier ordering normalize the next time you edit in the app — a known beta limitation.

Body parameters

tmdb_idstringrequired

The TMDB id of the title. For seasons and episodes, pass the show’s TMDB id.

media_typeenumrequired

What kind of title this is.

movietvtv_seasontv_episode
season_numberintegerrequired if media_type is tv_season or tv_episode

Season being reviewed.

episode_numberintegerrequired if media_type is tv_episode

Episode being reviewed.

ratingnumber· 0–10

Your rating. Omit for an unrated log.

reviewstring· max 10,000 chars

Review text.

watched_datedate· YYYY-MM-DD

When you watched it. Not in the future.

tagsarray of strings· max 20 tags, 64 chars each

Tags to attach.

watched_witharray of strings· max 50

People you watched with. Each entry is a user id (from GET /me/following) or an @username. Each must be someone you follow — unknown entries are rejected.

watch_contextobject

How you watched it. A sparse object — send only what you know. Keys: source (theater/home/onTheGo), cinema_type, format, theater, auditorium, showtime, seat, medium (streaming/physical/broadcast/download), service, edition, channel, place, device.

Endpoint errors

404media_not_foundThe tmdb_id / media_type combination doesn’t exist on TMDB
curl -X POST https://flickmovies.com/api/beta/me/reviews \
  -H "Authorization: Bearer flick_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tmdb_id": "603",
    "media_type": "movie",
    "rating": 9,
    "review": "Whoa.",
    "watched_date": "2026-06-01"
  }'
Response · 201
{
  "created": true,
  "deduplicated": false,
  "review": {
    "id": "5f0c4f7a-…",
    "media": {
      "tmdb_id": "603",
      "type": "movie",
      "title": "The Matrix",
      "year": 1999,
      "poster_url": "https://image.tmdb.org/t/p/w500/…"
    },
    "rating": 9,
    "review": "Whoa.",
    "watched_date": "2026-06-01",
    "created_at": "2026-06-10T18:21:09+00:00",
    "tags": [],
    "source": "api",
    "is_log": false
  }
}
Review a TV season
curl -X POST https://flickmovies.com/api/beta/me/reviews \
  -H "Authorization: Bearer flick_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tmdb_id": "1396",
    "media_type": "tv_season",
    "season_number": 1,
    "rating": 9.5
  }'
Review a TV episode
curl -X POST https://flickmovies.com/api/beta/me/reviews \
  -H "Authorization: Bearer flick_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tmdb_id": "1396",
    "media_type": "tv_episode",
    "season_number": 1,
    "episode_number": 1,
    "rating": 9
  }'

Create reviews in batch

POST/api/beta/me/reviews/batch

Add up to 50 reviews in one request.

Items are processed independently; the response reports per-item outcomes in input order.

Duplicates — against your existing reviews or within the batch — are skipped and counted in deduplicated_count.

There is no all-or-nothing rollback: check each item’s created / error instead of the HTTP status.

Body parameters

reviewsarray of objectsrequired· 1–50 items

The reviews to create.

each item

tmdb_idstringrequired

The TMDB id of the title. For seasons and episodes, pass the show’s TMDB id.

media_typeenumrequired

What kind of title this is.

movietvtv_seasontv_episode
season_numberintegerrequired if media_type is tv_season or tv_episode

Season being reviewed.

episode_numberintegerrequired if media_type is tv_episode

Episode being reviewed.

ratingnumber· 0–10

Your rating. Omit for an unrated log.

reviewstring· max 10,000 chars

Review text.

watched_datedate· YYYY-MM-DD

When you watched it. Not in the future.

tagsarray of strings· max 20 tags, 64 chars each

Tags to attach.

watched_witharray of strings· max 50

People you watched with. Each entry is a user id (from GET /me/following) or an @username. Each must be someone you follow — unknown entries are rejected.

watch_contextobject

How you watched it. A sparse object — send only what you know. Keys: source (theater/home/onTheGo), cinema_type, format, theater, auditorium, showtime, seat, medium (streaming/physical/broadcast/download), service, edition, channel, place, device.

Endpoint errors

404media_not_foundReported per item in results[].error, not as a top-level status
curl -X POST https://flickmovies.com/api/beta/me/reviews/batch \
  -H "Authorization: Bearer flick_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reviews": [
      {
        "tmdb_id": "550",
        "media_type": "movie",
        "rating": 8
      },
      {
        "tmdb_id": "1396",
        "media_type": "tv",
        "rating": 10,
        "review": "Peak TV."
      }
    ]
  }'
Response · 200
{
  "created_count": 2,
  "deduplicated_count": 0,
  "failed_count": 0,
  "results": [
    { "index": 0, "created": true, "deduplicated": false, "review_id": "…", "error": null },
    { "index": 1, "created": true, "deduplicated": false, "review_id": "…", "error": null }
  ]
}

Update a review

PATCH/api/beta/me/reviews/{review_id}

Update one of your reviews. The title is immutable.

Only the fields you send change. Send an explicit null to clear rating, tags, watch_context, or watched_with.

Editing a rating renormalizes the rating-tier ordering automatically.

Path parameters

review_idstringrequired

The review id to update.

Body parameters

ratingnumber· 0–10

New rating.

reviewstring· max 10,000 chars

New review text.

watched_datedate· YYYY-MM-DD

When you watched it.

tagsarray of strings· max 20 tags

Replacement tag list.

watched_witharray of strings· max 50

Replacement co-watchers — user ids or @usernames, each someone you follow.

watch_contextobject

How you watched it. A sparse object — send only what you know. Keys: source (theater/home/onTheGo), cinema_type, format, theater, auditorium, showtime, seat, medium (streaming/physical/broadcast/download), service, edition, channel, place, device.

Endpoint errors

404not_foundThe review doesn't exist or isn't yours
curl -X PATCH https://flickmovies.com/api/beta/me/reviews/5f0c4f7a-%E2%80%A6 \
  -H "Authorization: Bearer flick_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": 8.5,
    "tags": [
      "rewatch"
    ]
  }'
Response · 200
{
  "id": "5f0c4f7a-…",
  "media": { "tmdb_id": "603", "type": "movie", "title": "The Matrix", "year": 1999, "poster_url": "https://…" },
  "rating": 8.5,
  "review": "Still holds up.",
  "watched_date": "2026-06-01T00:00:00+00:00",
  "created_at": "2026-06-02T18:21:09+00:00",
  "tags": ["rewatch"],
  "watch_context": null,
  "watched_with": [],
  "source": "api",
  "is_log": false
}

Delete a review

DELETE/api/beta/me/reviews/{review_id}

Permanently delete one of your reviews.

Path parameters

review_idstringrequired

The review id to delete.

Endpoint errors

404not_foundThe review doesn't exist or isn't yours
curl -X DELETE https://flickmovies.com/api/beta/me/reviews/5f0c4f7a-%E2%80%A6 \
  -H "Authorization: Bearer flick_sk_YOUR_KEY"
Response · 200
{ "deleted": true }

Add/remove tags across reviews

POST/api/beta/me/reviews/bulk/tags

Add and/or remove tags across many of your reviews at once.

Provide add, remove, or both. Reviews that aren’t yours are skipped silently.

rows_added / rows_removed count the reviews each operation actually changed.

Body parameters

review_idsarray of stringsrequired· 1–100 ids

The review ids to edit.

addarray of strings

Tags to add.

removearray of strings

Tags to remove.

curl -X POST https://flickmovies.com/api/beta/me/reviews/bulk/tags \
  -H "Authorization: Bearer flick_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "review_ids": [
      "5f0c4f7a-…",
      "7a1b…"
    ],
    "add": [
      "rewatch"
    ],
    "remove": [
      "todo"
    ]
  }'
Response · 200
{ "review_ids": 2, "rows_added": 2, "rows_removed": 1 }

Add/remove co-watchers across reviews

POST/api/beta/me/reviews/bulk/watched-with

Add and/or remove "watched with" co-watchers across many reviews.

Entries in add and remove are user ids or @usernames. Everyone in add must be someone you follow — unknown entries reject the request. remove is not follow-gated (you can untag anyone).

Body parameters

review_idsarray of stringsrequired· 1–100 ids

The review ids to edit.

addarray of strings

Co-watchers to add — user ids or @usernames you follow.

removearray of strings

Co-watchers to remove — user ids or @usernames.

curl -X POST https://flickmovies.com/api/beta/me/reviews/bulk/watched-with \
  -H "Authorization: Bearer flick_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "review_ids": [
      "5f0c4f7a-…"
    ],
    "add": [
      "uid_friend"
    ]
  }'
Response · 200
{ "review_ids": 1, "rows_added": 1, "rows_removed": 0 }

Set watch context across reviews

POST/api/beta/me/reviews/bulk/watch-context

Overwrite "how you watched" on many reviews at once.

Send watch_context: null to clear it on all targeted reviews.

Body parameters

review_idsarray of stringsrequired· 1–100 ids

The review ids to edit.

watch_contextobject

How you watched it. A sparse object — send only what you know. Keys: source (theater/home/onTheGo), cinema_type, format, theater, auditorium, showtime, seat, medium (streaming/physical/broadcast/download), service, edition, channel, place, device.

curl -X POST https://flickmovies.com/api/beta/me/reviews/bulk/watch-context \
  -H "Authorization: Bearer flick_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "review_ids": [
      "5f0c4f7a-…"
    ],
    "watch_context": {
      "source": "home",
      "medium": "streaming",
      "service": "Netflix"
    }
  }'
Response · 200
{ "review_ids": 1, "rows_updated": 1 }

List your tags

GET/api/beta/me/tags

Your distinct review tags with usage counts, most-used first.

curl https://flickmovies.com/api/beta/me/tags \
  -H "Authorization: Bearer flick_sk_YOUR_KEY"
Response · 200
{
  "data": [
    { "tag": "rewatch", "count": 42 },
    { "tag": "sci-fi", "count": 17 }
  ]
}

Watchlist

List your watchlist

GET/api/beta/me/watchlist

Your watchlist, most recently added first.

Query parameters

pageinteger· default 1

Page number, 1-indexed.

limitinteger· default 50, max 100· default 50

Items per page.

curl https://flickmovies.com/api/beta/me/watchlist \
  -H "Authorization: Bearer flick_sk_YOUR_KEY"
Response · 200
{
  "data": [
    {
      "media": {
        "tmdb_id": "693134",
        "type": "movie",
        "title": "Dune: Part Two",
        "year": 2024,
        "poster_url": "https://image.tmdb.org/t/p/w500/…"
      },
      "added_at": "2026-05-30T02:11:00+00:00"
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 23,
  "has_more": false
}

Add to your watchlist

POST/api/beta/me/watchlist

Add a title to your watchlist.

Re-adding a title already on your watchlist is a no-op.

Body parameters

tmdb_idstringrequired

The TMDB id.

media_typeenumrequired

What kind of title.

movietvtv_seasontv_episode
season_numberintegerrequired if media_type is tv_season or tv_episode

Season.

episode_numberintegerrequired if media_type is tv_episode

Episode.

Endpoint errors

404media_not_foundNo such title on TMDB
curl -X POST https://flickmovies.com/api/beta/me/watchlist \
  -H "Authorization: Bearer flick_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tmdb_id": "693134",
    "media_type": "movie"
  }'
Response · 201
{ "added": true }

Add to your watchlist in bulk

POST/api/beta/me/watchlist/batch

Add up to 50 titles to your watchlist in one request.

Items are processed independently — check each added / error in results.

Body parameters

itemsarray of objectsrequired· 1–50 items

The titles to add.

each item

tmdb_idstringrequired

The TMDB id.

media_typeenumrequired

What kind of title.

movietvtv_seasontv_episode
season_numberintegerrequired if media_type is tv_season or tv_episode

Season.

episode_numberintegerrequired if media_type is tv_episode

Episode.

curl -X POST https://flickmovies.com/api/beta/me/watchlist/batch \
  -H "Authorization: Bearer flick_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "tmdb_id": "693134",
        "media_type": "movie"
      },
      {
        "tmdb_id": "1396",
        "media_type": "tv"
      }
    ]
  }'
Response · 200
{
  "added_count": 2,
  "failed_count": 0,
  "results": [
    { "index": 0, "added": true, "error": null },
    { "index": 1, "added": true, "error": null }
  ]
}

Remove from your watchlist

DELETE/api/beta/me/watchlist/{tmdb_id}

Remove a title from your watchlist.

Path parameters

tmdb_idstringrequired

The TMDB id to remove.

Query parameters

media_typeenumrequired

The media type (tmdb_id alone is ambiguous across movie/tv).

movietvtv_seasontv_episode
season_numberinteger

Season (for tv_season / tv_episode).

episode_numberinteger

Episode (for tv_episode).

Endpoint errors

404not_foundThat title isn't on your watchlist
404media_not_foundNo such title on TMDB
curl -X DELETE "https://flickmovies.com/api/beta/me/watchlist/693134?media_type=movie" \
  -H "Authorization: Bearer flick_sk_YOUR_KEY"
Response · 200
{ "removed": true }

Lists

List your lists

GET/api/beta/me/lists

Custom lists you own. The built-in watchlist is excluded — use /me/watchlist for that.

curl https://flickmovies.com/api/beta/me/lists \
  -H "Authorization: Bearer flick_sk_YOUR_KEY"
Response · 200
{
  "data": [
    {
      "id": "list_abc",
      "title": "Best of the 90s",
      "description": "",
      "is_ranked": true,
      "num_media": 25,
      "created_at": "2026-01-12T09:00:00+00:00",
      "updated_at": "2026-06-01T17:30:00+00:00"
    }
  ]
}

List items in a list

GET/api/beta/me/lists/{list_id}/items

Items in one of your lists. Ranked lists come back in rank order.

Returns 404 not_found for lists you don’t own.

Path parameters

list_idstringrequired

A list id from GET /me/lists.

Query parameters

pageinteger· default 1

Page number, 1-indexed.

limitinteger· default 50, max 100· default 50

Items per page.

Endpoint errors

404not_foundThe list doesn’t exist or belongs to someone else
curl https://flickmovies.com/api/beta/me/lists/list_abc/items \
  -H "Authorization: Bearer flick_sk_YOUR_KEY"
Response · 200
{
  "data": [
    {
      "media": {
        "tmdb_id": "550",
        "type": "movie",
        "title": "Fight Club",
        "year": 1999,
        "poster_url": "https://image.tmdb.org/t/p/w500/…"
      },
      "rank": 1,
      "notes": "",
      "added_at": "2026-01-12T09:00:00+00:00"
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 25,
  "has_more": false
}

Create a list

POST/api/beta/me/lists

Create a new custom list.

Body parameters

titlestringrequired· 1–200 chars

List title.

descriptionstring· max 2,000 chars

List description.

is_rankedboolean· default false

Whether the list is ranked (ordered).

curl -X POST https://flickmovies.com/api/beta/me/lists \
  -H "Authorization: Bearer flick_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Best of the 90s",
    "is_ranked": true
  }'
Response · 201
{
  "id": "9b1c…",
  "title": "Best of the 90s",
  "description": "",
  "is_ranked": true,
  "num_media": 0,
  "created_at": "2026-06-14T18:00:00+00:00",
  "updated_at": "2026-06-14T18:00:00+00:00"
}

Update a list

PATCH/api/beta/me/lists/{list_id}

Rename a list, change its description, or toggle ranking.

Built-in lists (like the watchlist) can’t be edited.

Path parameters

list_idstringrequired

The list id.

Body parameters

titlestring· 1–200 chars

New title.

descriptionstring· max 2,000 chars

New description.

is_rankedboolean

Whether the list is ranked.

Endpoint errors

404not_foundThe list doesn't exist or isn't yours
curl -X PATCH https://flickmovies.com/api/beta/me/lists/9b1c%E2%80%A6 \
  -H "Authorization: Bearer flick_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Best of the 1990s"
  }'
Response · 200
{
  "id": "9b1c…",
  "title": "Best of the 1990s",
  "description": "",
  "is_ranked": true,
  "num_media": 25,
  "created_at": "2026-01-12T09:00:00+00:00",
  "updated_at": "2026-06-14T18:05:00+00:00"
}

Delete a list

DELETE/api/beta/me/lists/{list_id}

Permanently delete a custom list and its items.

Built-in lists (like the watchlist) can’t be deleted.

Path parameters

list_idstringrequired

The list id to delete.

Endpoint errors

404not_foundThe list doesn't exist or isn't yours
curl -X DELETE https://flickmovies.com/api/beta/me/lists/9b1c%E2%80%A6 \
  -H "Authorization: Bearer flick_sk_YOUR_KEY"
Response · 200
{ "deleted": true }

Add a title to a list

POST/api/beta/me/lists/{list_id}/items

Add a title to one of your lists.

Path parameters

list_idstringrequired

The list id.

Body parameters

tmdb_idstringrequired

The TMDB id.

media_typeenumrequired

What kind of title.

movietvtv_seasontv_episode
season_numberintegerrequired if media_type is tv_season or tv_episode

Season.

episode_numberintegerrequired if media_type is tv_episode

Episode.

notesstring· max 2,000 chars

Per-item notes.

positionenum· default end

Where to insert in a ranked list.

startend

Endpoint errors

404not_foundThe list doesn't exist or isn't yours
404media_not_foundNo such title on TMDB
curl -X POST https://flickmovies.com/api/beta/me/lists/9b1c%E2%80%A6/items \
  -H "Authorization: Bearer flick_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tmdb_id": "550",
    "media_type": "movie",
    "notes": "Top tier."
  }'
Response · 201
{ "added": true }

Add titles to a list in bulk

POST/api/beta/me/lists/{list_id}/items/batch

Add up to 50 titles to a list in one request.

Items are processed independently — check each added / error in results.

Path parameters

list_idstringrequired

The list id.

Body parameters

itemsarray of objectsrequired· 1–50 items

The titles to add.

each item

tmdb_idstringrequired

The TMDB id.

media_typeenumrequired

What kind of title.

movietvtv_seasontv_episode
season_numberintegerrequired if media_type is tv_season or tv_episode

Season.

episode_numberintegerrequired if media_type is tv_episode

Episode.

notesstring

Per-item notes.

Endpoint errors

404not_foundThe list doesn't exist or isn't yours
curl -X POST https://flickmovies.com/api/beta/me/lists/9b1c%E2%80%A6/items/batch \
  -H "Authorization: Bearer flick_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "tmdb_id": "550",
        "media_type": "movie"
      },
      {
        "tmdb_id": "603",
        "media_type": "movie"
      }
    ]
  }'
Response · 200
{
  "added_count": 2,
  "failed_count": 0,
  "results": [
    { "index": 0, "added": true, "error": null },
    { "index": 1, "added": true, "error": null }
  ]
}

Update a list item

PATCH/api/beta/me/lists/{list_id}/items/{tmdb_id}

Update an item’s notes or move it within a ranked list.

position is a 0-based target index used to reorder ranked lists.

Path parameters

list_idstringrequired

The list id.

tmdb_idstringrequired

The item’s TMDB id.

Query parameters

media_typeenumrequired

The item’s media type.

movietvtv_seasontv_episode
season_numberinteger

Season (for tv_season / tv_episode).

episode_numberinteger

Episode (for tv_episode).

Body parameters

notesstring· max 2,000 chars

New per-item notes.

positioninteger

0-based index to move the item to (ranked lists).

Endpoint errors

404not_foundThe list or item doesn't exist or isn't yours
404media_not_foundNo such title on TMDB
curl -X PATCH "https://flickmovies.com/api/beta/me/lists/9b1c%E2%80%A6/items/550?media_type=movie" \
  -H "Authorization: Bearer flick_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "position": 0
  }'
Response · 200
{ "updated": true }

Remove a title from a list

DELETE/api/beta/me/lists/{list_id}/items/{tmdb_id}

Remove a title from one of your lists.

Path parameters

list_idstringrequired

The list id.

tmdb_idstringrequired

The item’s TMDB id.

Query parameters

media_typeenumrequired

The item’s media type.

movietvtv_seasontv_episode
season_numberinteger

Season (for tv_season / tv_episode).

episode_numberinteger

Episode (for tv_episode).

Endpoint errors

404not_foundThe list or item doesn't exist or isn't yours
404media_not_foundNo such title on TMDB
curl -X DELETE "https://flickmovies.com/api/beta/me/lists/9b1c%E2%80%A6/items/550?media_type=movie" \
  -H "Authorization: Bearer flick_sk_YOUR_KEY"
Response · 200
{ "removed": true }

Watching

List shows you’re watching

GET/api/beta/me/watching

Shows with in-progress episode/season activity, most recent first.

Read-only in beta. episode_count / season_count are the logged episodes/seasons since your last reset.

curl https://flickmovies.com/api/beta/me/watching \
  -H "Authorization: Bearer flick_sk_YOUR_KEY"
Response · 200
{
  "data": [
    {
      "show": {
        "tmdb_id": "1396",
        "type": "tv",
        "title": "Breaking Bad",
        "poster_url": "https://image.tmdb.org/t/p/w500/…"
      },
      "last_watched_at": "2026-06-13T22:10:00+00:00",
      "last_reset_at": null,
      "manually_completed_at": null,
      "most_recent_review": { "s": 2, "e": 4, "kind": "episode", "created_at": "2026-06-13T22:10:00+00:00" },
      "episode_count": 12,
      "season_count": 0
    }
  ]
}

Changelog & support

  • 2026-07 — Review objects now include is_log: truefor plain watch logs (no rating, review text, or photos), so they're distinguishable from deliberate blank reviews. Additive — existing fields and the ratedfilter's behavior are unchanged.
  • 2026-06 — Initial beta: own-data reads (profile, reviews, watchlist, lists) and review writes (single + batch).

This beta exists to learn what you want to build. Feature requests, bug reports, and questions all go to our Discord or hello@flickmovies.com.