> 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/media-servers/silo.md).

# Silo

Silo adapter notes for syncing watchlist, history, ratings, progress, and playlists with stable external IDs.

{% hint style="info" %}
Connect Silo first. See [Silo](/crosswatch/settings/connections/media-servers/silo.md).
{% endhint %}

{% hint style="warning" %}
Silo support is **experimental**. Silo remains pre-release. Its API can change before version 1.0.
{% endhint %}

### What it supports

* **Direction:** source or target in a one-way or two-way pair.
* **Features:**
  * **Watchlist** for movies and shows
  * **History** for movies and episodes
  * **Ratings** for movies and shows
  * **Progress** for resume positions
  * **Playlists** through Silo collections and Favorites
  * **Collection** through Silo collections
* **Indexing:** present-state snapshot of existing items.
* **Profiles:** all data belongs to a household profile.

### How matching works

CrossWatch matches by provider IDs only.

* CrossWatch reads your Silo library once per run. It indexes movies, shows, and episodes.
* Movies match on TMDb, IMDb, or TVDB IDs.
* Episodes match show IDs with season and episode numbers.
* Missing show IDs trigger one lookup. CrossWatch caches the result.

{% hint style="warning" %}
Strict ID matching is the default.

Items must exist in your Silo library. Local files without a TMDb, IMDb, or TVDB match cannot sync.

When IDs are missing, CrossWatch prefers a missing peer over a wrong match.
{% endhint %}

### Watchlist behavior

* **Read:** the connected profile's Silo watchlist.
* **Write:** add or remove titles in your library.
* Titles outside your library can be added when Silo **Requests** is enabled. Otherwise, they remain unresolved.
* CrossWatch does not use fuzzy title matching.

{% hint style="info" %}
Silo hides fully watched shows from its watchlist. CrossWatch remembers them, so it does not treat them as removed.
{% endhint %}

### History behavior

* **Read:** the Silo watch ledger, including completed items and watch dates.
* **Write:**
  * Add with a date marks an item watched using that date.
  * Add without a date marks an item watched now.
  * Remove unwatches an item and hides it from the Silo history feed.
* CrossWatch verifies every write.

{% hint style="warning" %}
After you unwatch an item in Silo, Silo ignores earlier watches for that title.

CrossWatch marks these records as **ignored by server** and stops retrying them.
{% endhint %}

Rewatches are unsupported. Silo stores one watch per item.

### Ratings behavior

* **Read:** movie and show ratings.
* **Write:**
  * Add sets a rating. Silo uses one to five stars.
  * Remove clears the rating.
* Episode ratings are unsupported.

CrossWatch maps one-to-ten ratings to stars by rounding halves. A rating of 7 becomes four stars. A rating of 2 becomes one star.

CrossWatch preserves the original value it wrote. A 7 that Silo stores as four stars reads back as 7. Ratings therefore do not change every run.

### Progress behavior

* **Read:** resume positions for movies and in-progress episodes.
* **Write:** sets the resume position.
* **Clear:** supported.
* CrossWatch verifies every write. If Silo has a newer position, CrossWatch skips the item.

See [Progress](/crosswatch/settings/configure-pairs/features/progress.md).

### Playlists behavior

* **Favorites** appears as one playlist.
* Each Silo collection appears as its own playlist.
* You can create, rename, reorder, edit, and delete your manual collections.
* Smart collections and collections shared by other users are read-only.

### Collection behavior

* **Read:** manual Silo collections and Favorites.
* **Write:** create, update, and remove manual Silo collections.
* **Direction:** Collection sync is one-way only.
* Smart collections and collections shared by other users are read-only.
* **Media info:** reads each collection item's resolution, HDR format, and audio details.

### Household profiles

Each household profile has separate watchlist, ratings, history, and progress. A pair always syncs one profile.

To sync more profiles:

* Select them on the Silo connection's **Users** tab, then enable **Sync all matched users** in the pair.
* Or create another CrossWatch Silo connection and select that household profile.

**Sync all matched users** pairs each selected Silo profile with a same-named Plex, Emby, or Jellyfin user.

{% hint style="warning" %}
If a Silo profile PIN changes, CrossWatch pauses that profile. Enter the PIN again on the **Users** tab to resume synchronization.
{% endhint %}

### Settings

<details>

<summary>Common keys and knobs</summary>

**Connection**

* `silo.server_url`
* `silo.verify_ssl`
* `silo.timeout` — seconds; default `20`
* `silo.max_retries` — default `3`

**Rate limits**

* `silo.rate_limit.get_per_sec` — default `20`
* `silo.rate_limit.post_per_sec` — default `10`

Silo returns `429` after bursts of several hundred calls. CrossWatch waits for `Retry-After`, then continues.

</details>

### Diagnostics

<details>

<summary>State files</summary>

CrossWatch stores these files in `/config/.cw_state/`:

* `silo_details.<server>.json` — cached show IDs, kept for 30 days
* `silo_watchlist_series.<profile>.json` — watchlist shows, including completed ones
* `silo_ratings_written.<profile>.json` — ratings CrossWatch wrote, kept on the one-to-ten scale

Deleting these files is safe. CrossWatch rebuilds them during the next run.

</details>

<details>

<summary>Unresolved reasons</summary>

* `not_in_library` — the title is not in your Silo library
* `unsupported_type` — for example, a season or episode rating
* `ignored_by_server` — Silo ignored a watch after a later unwatch
* `missing_duration` — Silo has no item runtime, so CrossWatch cannot write the watch
* `write_failed` — Silo rejected the write

</details>

### Notes and limitations

* CrossWatch uses only Silo's `/api/v2` API.
* With an `https://` `silo.server_url`, the certificate must be valid inside the CrossWatch container. Otherwise, disable **Verify SSL**.
* Silo tracks watched episodes, not watched shows.
* Start with one-way synchronization and one feature. Expand after you confirm the results.


---

# 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/media-servers/silo.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.