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

# Floppy

{% tabs %}
{% tab title="End users" %}

<figure><img src="https://565675962-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3rh5THg1PdhVsBt3GALo%2Fuploads%2F2uFq3nDVq0YmwfCXsI2e%2Fimage.png?alt=media&amp;token=69884773-4093-4e1d-82e3-1af43205cb2b" alt=""><figcaption></figcaption></figure>

Connect a Floppy server to synchronize supported activity with CrossWatch.

{% hint style="warning" %}
Floppy is experimental. Floppy API changes can affect the connection or supported features.

Floppy is not optimized for large datasets. Synchronization can time out or fail unexpectedly. Use this adapter with care.
{% endhint %}

### What CrossWatch can sync

**Read** brings data into CrossWatch; **Write** sends changes to this provider.

| 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.               |

**Live scrobbling:** Scrobble destination; cannot be a Watcher source.

See the [synchronization guide](https://wiki.crosswatch.app/crosswatch/settings/synchronization/trackers/floppy.md) for matching rules and feature restrictions.

### Connect Floppy

Floppy connects to CW with its server URL and an API token.

#### Get an API token

1. Open Floppy.
2. Go to **Settings** → **Integrations**.
3. Create or copy an API token.

#### Connect Floppy

1. Open CW.
2. Go to **Settings** → **Connections** → **Trackers** → **Floppy**.
3. Enter the Floppy server URL. For example:

   ```
   http://<floppy-server>:8000
   ```
4. Enter the API token from Floppy.
5. Enable **Verify SSL** when Floppy uses HTTPS with a trusted certificate.
6. Click **Connect Floppy**.

CW validates the server URL and API token through the Floppy API. Its status then changes to **Connected**.

Create additional profiles to connect multiple Floppy servers or users.

### Feature details

#### Watchlist

Movies and shows are supported. CW uses the configured Floppy list name.

The default list name is **Watchlist**. CW creates the list when needed.

#### Ratings

Movies, shows, seasons and episodes are supported. Ratings use a scale from 0 to 10.

#### History

Movies and individual episodes are supported. Show-level and season-level history are not supported.

#### Progress

Movies and individual episodes are supported. Show-level and season-level progress are not supported.

All supported Floppy synchronization requires TMDb identifiers.

#### Playlists

Your own lists support reading, creation, rename, deletion, item changes, and ordering. The configured `watchlist_name` list is a built-in endpoint when ownership is established.

Its items can change, but it cannot be renamed or deleted. Collaborated lists allow additions and removals only. If ownership is uncertain, owner-only actions remain unavailable.

Floppy does not support public-list resolution or add-by-link. Avoid rules that manage the same list through both Watchlist and playlist mappings.

### Troubleshooting

* If the API token is invalid, create a new token under **Floppy Settings** → **Integrations**.
* If CW cannot reach Floppy, confirm its URL is accessible from the CW host or container.
* When both apps use Docker, do not use `localhost` unless they share a container. Use the Floppy container name, host address, or another reachable address.
* If SSL validation fails, verify the certificate and **Verify SSL** setting.
* If CW reports an unexpected response, confirm Floppy is supported and exposes `/api/v1`.
* Items without a TMDb identifier cannot synchronize. CW reports them as unresolved.
* If Floppy returns `429 Too Many Requests`, reduce the Floppy provider throttling values.
  {% endtab %}

{% tab title="Power users" %}

## Power users

### Limitations

Floppy support is experimental.

Public-list resolution and add-by-link are not supported.

CW does not define validated stable volume limits for Floppy.

Floppy reads are paginated in batches of up to 200 items. CW applies an internal safety limit of 1,000 pages.

This is a CW safety limit. It is not a confirmed Floppy capacity limit.

The default provider throttling allows 20 GET requests and 20 POST requests per second.
{% endtab %}
{% endtabs %}


---

# 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/connections/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.
