> ## Documentation Index
> Fetch the complete documentation index at: https://api.simkl.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Lists

> How to access user-curated Custom Lists from simkl.com/lists/ — and what to use today while the V2 Beta API ships.

**Custom Lists are user-curated collections of titles** — themed groupings like *"Best 90s sci-fi"*, *"Watched with my kids"*, or *"Recommended by Anna"* — created by users in the simkl.com web UI at [simkl.com/lists/](https://simkl.com/lists/).

They are **distinct from the [five-status Watchlist](/conventions/list-statuses)** (`watching`, `plantowatch`, `hold`, `dropped`, `completed`) that the API has always exposed. A title can be on the user's Watchlist with a status AND on one or more Custom Lists at the same time, independently.

<Warning>
  **Custom Lists are not yet available via the API.** They're served by **Simkl V2 Beta**, an in-development backend that isn't publicly callable yet. There is no public endpoint to read, create, or modify Custom Lists, and no firm ETA.

  Until V2 Beta ships, use the existing **Watchlist sync** endpoints (below) for everything library-related. We'll announce Custom Lists on the [changelog](/changelog) and in the [Discord](https://discord.gg/MJsWNE4) `#api` channel the moment they're callable.
</Warning>

## What to use today

For "fetch the user's library" use cases, the Watchlist sync endpoints already cover what most apps need — every movie / show / anime the user has tracked, with status, ratings, watched-episode counts, last-watched timestamps, and rewatch sessions.

<CardGroup cols={2}>
  <Card title="GET /sync/all-items" icon="list" href="/api-reference/simkl/get-all-items">
    Full library snapshot. See the [Sync guide](/guides/sync) for two-phase fetch and `date_from` semantics.
  </Card>

  <Card title="POST /sync/add-to-list" icon="circle-plus" href="/api-reference/simkl/add-to-list">
    Move items between the five Watchlist statuses.
  </Card>

  <Card title="GET /sync/activities" icon="clock-rotate-left" href="/api-reference/simkl/get-activities">
    Per-bucket timestamps for cheap "is there anything new?" polling.
  </Card>

  <Card title="POST /sync/history" icon="circle-check" href="/api-reference/simkl/add-to-history">
    Record watch events — single episode, whole season, or whole show.
  </Card>
</CardGroup>

These give you the same library data Simkl shows at `simkl.com/<user>/` — organized by status bucket rather than by user-defined list, but the underlying items are the same.

## When V2 Beta ships

When Custom Lists become available via the public API, we'll publish endpoints to:

* **List** the user's Custom Lists with metadata (name, description, public/private, item count).
* **Read** a specific Custom List's items.
* **Create**, **update**, and **delete** Custom Lists.
* **Add** and **remove** items within a Custom List.
* Read **public** Custom Lists by user or list slug — the same lists currently visible in the web UI at `simkl.com/<user>/lists/<list-slug>`.

The Watchlist sync endpoints will continue to work unchanged — Custom Lists are a new layer on top, not a replacement.

## Common questions

<AccordionGroup>
  <Accordion title="Why are simkl.com/lists/ pages public but I can't fetch them?">
    The web UI calls internal endpoints that are part of Simkl's V2 Beta backend. They aren't documented or stable, and they're tied to Simkl's own session cookies rather than OAuth tokens. **Don't scrape them** — they'll break under you without notice, and we may rate-limit or block clients that hit them. Wait for the public API.
  </Accordion>

  <Accordion title="Can I store list-like grouping using existing endpoints?">
    Not on the Simkl side. The only grouping primitive the public API exposes today is the five-status Watchlist. If your app needs custom grouping right now, store the grouping client-side (your own DB keyed by Simkl ID) and overlay it on top of `/sync/all-items` data. When the Custom Lists API ships, you'll be able to migrate that data into real Simkl Custom Lists.
  </Accordion>

  <Accordion title="Will my Watchlist data carry over when Custom Lists ship?">
    Yes. The Watchlist endpoints (`/sync/all-items`, `/sync/add-to-list`, `/sync/history`, …) will continue to work unchanged. Custom Lists are a separate, additive concept — a title can be on the user's Watchlist with a status (e.g. `completed`) AND on one or more Custom Lists at the same time, independently.
  </Accordion>

  <Accordion title="Can I follow another user's Custom List?">
    Public Custom Lists are viewable in the web UI at `simkl.com/<user>/lists/<list-slug>`, but there's no API for them yet. Public-list read access is planned to ship alongside the rest of the Custom Lists API.
  </Accordion>

  <Accordion title="Will Custom Lists count against my rate limit?">
    Once shipped, yes — they'll use the same rate-limit pool as the other `/sync/*` endpoints. Plan your polling accordingly: a Custom-Lists-heavy app should batch reads where possible and use `/sync/activities` (or its eventual Custom-Lists equivalent) to detect change rather than polling list contents on a fixed cadence.
  </Accordion>
</AccordionGroup>

## Reference

<CardGroup cols={2}>
  <Card title="Sync guide" icon="arrows-rotate" href="/guides/sync">
    Two-phase model, `date_from` semantics, deletion reconciliation.
  </Card>

  <Card title="Watchlist statuses" icon="list-check" href="/conventions/list-statuses">
    The five status values, per-type rules, and the legacy `notinteresting` → `dropped` rename.
  </Card>

  <Card title="Mark as watched" icon="circle-check" href="/guides/mark-as-watched">
    Simple "the user finished this" recipes.
  </Card>

  <Card title="Rewatches" icon="rotate" href="/guides/rewatches">
    Separate sessions for items the user already finished.
  </Card>
</CardGroup>