# FlickList Developer API

> FlickList v3 API documentation. TMDB-compatible catalog reads plus a Trakt-shaped sync and scrobble surface. Base URL: https://flicklist.tv/api/v3

Every documentation page below is also served as raw markdown at the same URL with .md appended (for example https://flicklist.tv/dev/quickstart.md).
OpenAPI 3.1 specification (source of truth for every endpoint): https://flicklist.tv/openapi/v3.yaml
Interactive endpoint reference: https://flicklist.tv/dev/api
Start here if you are an AI assistant: https://flicklist.tv/dev/guides/ai.md

## Getting started

- [Quickstart](https://flicklist.tv/dev/quickstart.md): Make your first authenticated API call in minutes, with an API key or the device-code flow.
- [Authentication](https://flicklist.tv/dev/authentication.md): Device-code flow, API keys, scopes, and token rotation.
## Core concepts

- [The ids object](https://flicklist.tv/dev/ids.md): How the ids block identifies media across FlickList and external sources, on both reads and writes.
- [Pagination](https://flicklist.tv/dev/pagination.md): How to page through list results using page and limit and the X-FlickList response headers.
- [Errors](https://flicklist.tv/dev/errors.md): The error response shape and what each HTTP status code means for your client.
- [Rate limits & fair use](https://flicklist.tv/dev/rate-limits.md): The published request ceiling per credential and how to stay under it.
## Scrobbling

- [Scrobbling](https://flicklist.tv/dev/scrobbling.md): Report playback in near real time and let FlickList mark things watched automatically.
## Your data

- [Watched shows & movies](https://flicklist.tv/dev/sync/watched.md): Read the full watched shows and movies collections for an account.
- [History](https://flicklist.tv/dev/sync/history.md): Read, add, and remove individual watch events for an account.
- [Playback progress](https://flicklist.tv/dev/sync/playback.md): Read, write, and delete resume points for in-progress playback.
- [Watchlist](https://flicklist.tv/dev/sync/watchlist.md): Read, add to, and remove from an account's watchlist.
- [Ratings](https://flicklist.tv/dev/sync/ratings.md): Read, add, and remove ratings for an account.
- [Favorites](https://flicklist.tv/dev/sync/favorites.md): Read, add, and remove favorites for an account.
- [Your lists](https://flicklist.tv/dev/sync/lists.md): Create, delete, and manage the items on a signed-in user's custom lists.
- [Public lists & discovery](https://flicklist.tv/dev/lists.md): Browse, search, and read any public list on FlickList without a personal credential.
- [Up Next, tracked shows & change detection](https://flicklist.tv/dev/sync/up-next.md): Read a user's computed Up Next queue, manage tracked shows, and poll for what changed.
- [Calendar](https://flicklist.tv/dev/calendar.md): Read the global airing schedule or a signed-in user's personalized calendar.
## Catalog

- [Catalog](https://flicklist.tv/dev/catalog.md): Read movie, TV, and people data in a response shape that matches TMDB's API field for field.
## Guides

- [Building a Kodi integration](https://flicklist.tv/dev/guides/kodi.md): Wire device-code login, scrobbling, and watched-state sync into a Kodi addon.
- [Building batch & collection tools](https://flicklist.tv/dev/guides/batch-tools.md): Build a metadata, list, or library-matching tool that reads across a whole catalog.
- [Quick scripts](https://flicklist.tv/dev/guides/scripts.md): Pull your own data out of FlickList with a personal API key.
- [For AI assistants](https://flicklist.tv/dev/guides/ai.md): A structured reference for a coding agent integrating the FlickList API.
## Reference & policies

- [Our commitments](https://flicklist.tv/dev/commitments.md): The promises this API is built on, in writing.
- [FAQ](https://flicklist.tv/dev/faq.md): Common questions from developers building on the FlickList API.
- [API changelog](https://flicklist.tv/dev/changelog.md): Additive changes to the v3 API and this documentation, newest first.
- [API terms](https://flicklist.tv/dev/terms.md): Terms for building against the FlickList API, covering fair use, branding, and credentials.