> 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/settings/synchronization/trackers/floppy.md).

# Floppy

Floppy adapter notes for syncing watchlist, ratings, history, and progress.

Floppy adapter lets CW synchronize with a Floppy server. It supports watchlist, ratings, history, and progress.

{% hint style="info" %}
Connect Floppy first. Use [Floppy (Authentication provider)](https://wiki.crosswatch.app/crosswatch/settings/connections/trackers/floppy.md).
{% endhint %}

{% hint style="info" %}
CW throttles Floppy requests to reduce server load. Defaults are `20` GET requests per second and `20` POST requests per second. See [Provider rate limiting](https://wiki.crosswatch.app/crosswatch/advanced-and-api/rate-limiting-and-retries.md) to tune them.
{% endhint %}

Floppy is normally self-hosted. It has no fixed synchronization schedule requirement. Very frequent runs can still add unnecessary load.

### What CrossWatch can sync

| Feature    | Read | Write | Notes                                                                 |
| ---------- | ---- | ----- | --------------------------------------------------------------------- |
| Watchlist  | Yes  | Yes   | Movies and shows in the configured Watchlist list. Requires TMDb IDs. |
| History    | Yes  | Yes   | Movies and episodes.                                                  |
| Ratings    | Yes  | Yes   | Movies, shows, seasons and episodes. Requires TMDb IDs.               |
| Progress   | Yes  | Yes   | Resume positions for movies and episodes.                             |
| Playlists  | Yes  | Yes   | Actions depend on ownership; no public-list link import.              |
| Collection | Yes  | Yes   | Movies, shows, seasons and episodes. Requires TMDb IDs.               |

**Read** brings data into CrossWatch; **Write** sends changes to this provider. Enable only features supported by both sides. Collection pairs are one-way only.

Floppy support is experimental. Start with a one-way pair and a Dry run. Matching requires TMDb IDs; episodes also need the show ID and episode numbers.

Connect the provider first: [Floppy setup](https://wiki.crosswatch.app/crosswatch/settings/connections/trackers/floppy.md).

### Watchlist behavior

* **Read:** reads movies and shows from the configured Floppy list.
* **Write:** adds or removes movies and shows.
* Default list name: `Watchlist`.
* CW finds the configured list by name.
* If the list is missing, CW creates it when adding an item.
* Items without a TMDb ID cannot synchronize.

The watchlist uses a standard Floppy custom list. It can also be a playlist endpoint when ownership is established.

### Playlist behavior

Your own lists support reading, creation, rename, deletion, item changes, and ordering. CrossWatch supports movies, shows, seasons, and episodes through TMDb identifiers.

The configured `watchlist_name` list is a built-in endpoint when ownership is established. You can change its items, but cannot rename or delete it.

Collaborated lists allow item additions and removals. They do not allow rename, delete, or reorder actions. If ownership cannot be established, owner-only actions remain unavailable.

Floppy does not support public-list resolution or add-by-link. Do not use Watchlist rules and playlist mappings to manage the same underlying list.

See [Playlists](https://wiki.crosswatch.app/crosswatch/main-dashboard/navigation/playlists.md) for setup guidance.

### Collection behavior

Floppy can be a Collection source or target. Collection sync is one-way only.

The first run creates a baseline. Later runs process changes since that baseline.

### Ratings behavior

* **Read:** reads ratings for movies, shows, seasons, and episodes.
* **Write:** upserts or removes ratings.
* Rating scale: `0–10`.
* Values above `10`, through `100`, are converted to the `0–10` scale.
* CW can create the media entry before applying a rating.
* A rating of zero clears the rating.

### History behavior

* **Read:** reads completed movies and watched episodes.
* **Write:** marks movies or episodes as watched.
* **Remove:** removes movie or episode watched state.
* Movie history uses the movie TMDb ID.
* Episode history uses the show TMDb ID, season number, and episode number.

Show-level and season-level history are not supported. Movie writes mark the item completed. Episode writes create a watch event when needed.

### Progress behavior

* **Read:** reads movie and episode resume positions.
* **Write:** synchronizes movie and episode resume positions.
* Progress requires a usable movie or episode identity.

Show-level and season-level progress are not supported.

### Pagination

CW reads Floppy results in pages of up to `200` items. Each request sequence has an internal limit of `1000` pages.

This is a CW safety boundary. It is not a confirmed Floppy account or storage limit.

### Settings (advanced)

#### Server URL

Example: `http://floppy:8000`

The server must be reachable from the CW container or host.

#### API token

Create the token in Floppy under **Settings → Advanced**.

#### Verify SSL

Default: disabled

Enable this when Floppy uses HTTPS with a certificate that needs validation.

#### Timeout

Default: `12` seconds

#### Watchlist name

Default: `Watchlist`

Controls the Floppy custom list used for watchlist synchronization.

#### GET rate

Default: `20` requests per second

#### POST rate

Default: `20` requests per second

### Limitations

* **Experimental:** Floppy is new and its API can still change.
* Sync speed depends on where and how you run Floppy. Large imports can take time.
* Large history backfills can be slow. Floppy handles watched records one item at a time.
* Watchlist supports movies and shows only.
* Ratings support movies, shows, seasons, and episodes.
* History supports movies and individual episodes only.
* Progress supports movies and individual episodes only.
* TMDb matching is required. Items without a TMDb ID remain unresolved.

### Custom status mapping

Each status sync reads your whole Floppy library. Large libraries can take longer, even when little has changed. The pair editor shows this restriction under **Configure mappings**.

For per-pair status rules, enable History and **Status mapping**, then configure **Providers → Status mapping**. See [Status mapping](https://wiki.crosswatch.app/crosswatch/settings/configure-pairs/provider-settings/status-mapping.md) for supported movie/show destinations, defaults, and restrictions. Planned stays managed by Watchlist.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://wiki.crosswatch.app/crosswatch/settings/synchronization/trackers/floppy.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
