> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/providers/synchronization/adapter-anilist.md).

# Adapter: AniList

AniList sync is built for **anime watchlists and ratings**. It syncs AniList’s **Planning** list, supports AniList ratings, and tries to keep IDs usable elsewhere.

{% hint style="warning" %}
CrossWatch is optimized for **movies and shows**. Anime works well for common titles. Edge cases can still fail matching.
{% endhint %}

### What it supports

* Features: **Watchlist** and **Ratings**
* List used: **AniList “Planning”** (ANIME only, no manga)
* Watchlist writes: **add** and **remove**
* Ratings writes: **add / update** and **remove (clear)**
* Sync model: **present-state snapshot** for watchlists

### Prerequisite: connect AniList

Set up AniList in **Settings → Authentication** first. Use this guide: [AniList (Authentication provider)](/crosswatch/providers/authentication/auth-trackers/auth-anilist.md).

### How matching works (bridging)

Most providers prefer **IMDb/TMDb** IDs. AniList prefers **AniList/MAL** IDs.

CrossWatch tries these steps when it needs an AniList ID:

1. Use an existing `anilist` ID.
2. Else use **Anime ID Mapping** to bridge supported IDs.
3. Else use a `mal` ID and resolve it to AniList.
4. Else do a title search and require a strong match.

{% hint style="info" %}
Best results come from **Anime ID Mapping**.

Enable it in **Settings → Connections → Metadata / ID Mapping**.

Guide: [Anime ID Mapping](/crosswatch/providers/metadata-id-mapping/anime-id-mapping.md).

For pair-level **Watchlist** and **Ratings** controls, see [AniList pair options](/crosswatch/configure-pairs/anilist-pair-options.md).
{% endhint %}

### Limitations you should expect

* TMDb anime coverage is incomplete.
* Some titles will map wrong or not at all.
* Unmappable items can cause duplicates across providers.

### Snapshot model (why it behaves “all-or-nothing”)

AniList watchlist is treated as a full snapshot:

* No watermarks.
* No `date_from`.
* Each run re-reads the full Planning list.

### Shadow state (stability across runs)

CrossWatch keeps a local mapping file to avoid re-guessing every run:

`/config/.cw_state/anilist_watchlist_shadow.json`

It is used to:

* reuse stable mappings
* avoid retrying known no-match titles
* keep multi-provider sync paths stable

<details>

<summary>What gets stored in the shadow file</summary>

* AniList IDs, optional MAL IDs
* AniList list entry IDs
* source IDs from the originating provider
* ignored markers and ignore reasons (for “not anime / no match”)

</details>

### Rate limits and token lifecycle

* Run **daily** for normal usage.
* Avoid rapid re-runs while debugging.
* AniList tokens are valid for **1 year**.
* AniList has no refresh token flow in CrossWatch.
* Reconnect yearly in **Authentication** to get a new token.

### Best practices

* Enable **Anime ID Mapping** for AniList pairs.
* Use **separate pairs** for anime vs movies/shows.
* Whitelist libraries to keep non-anime out of the pair.
* Start one-way. Validate matches. Then go bidirectional.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.crosswatch.app/crosswatch/providers/synchronization/adapter-anilist.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.