> 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/main-dashboard/navigation/playlists/published-lists.md).

# Published lists

Publish CrossWatch lists for Kometa, Radarr, Sonarr, and MDBList JSON readers.

Publishing gives a CrossWatch list a web address that other tools can read. Use it to:

* build Plex collections with **Kometa** from any list CrossWatch can read, including SIMKL and AniList sources;
* let **Radarr** add the movies on a list;
* let **Sonarr** add the shows on a list.
* load the mixed list in an **MDBList JSON reader**, such as Kodi TMDBHelper.

### How it works

1. A CrossWatch list holds the items.
2. A normal mapping fills that list from a watchlist or playlist on any provider.
3. You publish the list. Kometa, Radarr, Sonarr and MDBList JSON readers such as Kodi TMDBHelper fetch it on their own schedule.

### Set it up

1. In **Playlists**, select **Advanced**, then **Add endpoint**, and choose **CrossWatch** as the provider.
2. Select the **+** button (**Create provider playlist**), enter a name and select **Create playlist**. Select the new list and save with **Create endpoint**.
3. Use **New mapping** to connect your source endpoint to that CrossWatch endpoint, then run the mapping. Add the source with **Add endpoint** first if needed.
4. In **Published lists**, select **Publish** on the list.
5. Copy the block for your tool from the dialog.

| Tool                | What to do                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Kometa**          | Paste the lines into a collection file of the matching library. There is one block for a movie library and one for a show library. Needs Kometa 2.4.5 or newer.                                                                                                                                                                                                                                                                                                                                                                                                         |
| **Radarr**          | Settings, Import Lists, add a Custom List and paste the address.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **Sonarr**          | Settings, Import Lists, add a Custom List and paste the address.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **MDBList JSON**    | Copy the MDBList JSON address from the publish window and paste it into any tool that reads MDBList-style JSON lists.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| **Kodi TMDBHelper** | Copy the Kodi TMDBHelper path from the publish window and use it as the path of a widget, menu item or button. The path looks like `plugin://plugin.video.themoviedb.helper/?info=mdblist_locallist&&https://your-crosswatch/published/<id>/mdblist.json?key=<key>`. Keep the double `&&` exactly as shown. Put options after it, for example `...&&http://your-crosswatch:port/published/<id>/mdblist.json?key=<key>&sort=random`. Do not use `&&` inside the CrossWatch address. TMDBHelper uses it to split the path. In skin XML files, write every `&` as `&amp;`. |

Kometa example:

```yaml
collections:
  My Watchlist:
    text_file: http://your-crosswatch:port/published/<id>/kometa-movies.json?key=<key>
    sync_mode: sync
```

### What each tool receives

| Address       | Contains                                                                   | Left out                  |
| ------------- | -------------------------------------------------------------------------- | ------------------------- |
| Kometa movies | Movies, by IMDb ID, otherwise TMDB ID                                      | Movies with neither       |
| Kometa shows  | Shows, by TVDB ID, otherwise IMDb ID                                       | Shows with only a TMDB ID |
| Radarr        | Movies with title and IMDb ID                                              | Movies without an IMDb ID |
| Sonarr        | Shows with title and TVDB ID                                               | Shows without a TVDB ID   |
| MDBList JSON  | Movies, shows, seasons and episodes in one list, by TMDB ID, in list order | Items without a TMDB ID   |

For Kometa and Sonarr, seasons and episodes on a list count as their show. MDBList JSON keeps them as separate entries. Radarr is movies only and Sonarr is shows only.

Items without the required ID are left out on purpose, so a tool cannot pick the wrong title by name.

**Address options**

Every published address can take extra options at the end. Add each one with `&`, after the `key`.

| Option      | What it does                                                                                                      | Example                 |
| ----------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `key`       | Required. The access key for this list.                                                                           | `?key=abc123`           |
| `sort`      | Sort by a field available in the format, or use `random` to shuffle each read. Empty or `rank` keeps saved order. | `&sort=title`           |
| `order`     | `asc` (default) or `desc`. Without a sort field, `desc` reverses the saved order. Ignored for random sorting.     | `&order=desc`           |
| `mediatype` | Keep `movie`, `show`, `season`, or `episode`; combine types with commas.                                          | `&mediatype=movie,show` |
| `offset`    | Skip this many formatted items. Starts at `0`.                                                                    | `&offset=20`            |
| `limit`     | Return at most this many items. Use a positive whole number.                                                      | `&limit=20`             |

Media-type filtering happens before formatting. CrossWatch then sorts the formatted rows and applies `offset` and `limit`. These options work for every published format, but a format can only return the types and fields it supports.

For MDBList JSON, useful sort fields include `title`, `year`, `mediatype` (or `media_type`), and `id` (or `tmdb_id`). Other formats can use their available fields, such as `title`, `imdb_id`, or `tvdb_id`. Text sorting ignores letter case. Missing values stay at the end in either direction. An unknown sort field leaves the order unchanged.

Unknown media types are ignored. If none of the supplied types are recognized, the list is not filtered. Omitted or invalid offsets use `0`; omitted, zero, negative, or invalid limits return all remaining items.

CrossWatch leaves out items without the required IDs and removes duplicates before returning the list. MDBList JSON keeps season and episode entries; these need the show TMDB ID and their season or episode numbers.

```
http://your-crosswatch:port/published/<id>/mdblist.json?key=<key>&sort=random
```

{% hint style="info" %}
Each random read shuffles the list again. It returns the full list unless you set a limit or offset. To page through a stable list without repeats between pages, leave out `sort=random`.
{% endhint %}

For scripts, `X-CrossWatch-Skipped` reports how many entries could not be included in that format. `X-Total-Items` is the size after media-type filtering and formatting, before pagination.

For example, this returns up to 20 movies in title order after skipping the first 20:

```
http://your-crosswatch:port/published/<id>/mdblist.json?key=<key>&mediatype=movie&sort=title&order=asc&offset=20&limit=20
```

### Manage a published list

| Action              | Result                                                                                        |
| ------------------- | --------------------------------------------------------------------------------------------- |
| **Show addresses**  | Opens the dialog with the addresses again.                                                    |
| **New access key**  | Replaces the key. The old addresses and Kodi paths stop working until you paste the new ones. |
| **Stop publishing** | The addresses stop working. The list itself is kept.                                          |

**Last read** shows when a tool last fetched the list and in which format. MDBList JSON appears as a format there.

{% hint style="warning" %}
**Security:** A published address works without logging in, because these tools cannot log in. It is protected only by the access key inside the address. Anyone who has the address can read that one list. Create a new access key if an address leaks.
{% endhint %}

The other tool decides when it reads the list. CrossWatch cannot start a Kometa, Radarr, Sonarr or Kodi TMDBHelper run.

### Troubleshooting

#### A published list is empty or short

Check that the mapping into the CrossWatch list has run and that the list has items.

Items without the ID a tool needs are left out; see [What each tool receives](#what-each-tool-receives).

For MDBList JSON, items without a TMDB ID are left out.

Kometa only adds titles that exist in the Plex library.

#### A tool cannot read a published list

Confirm the tool can reach the CrossWatch address from its own container or machine.

If CrossWatch uses HTTPS with a self-signed certificate, the tool may refuse the connection. Use an address it trusts.

Check that the key in the address is the current one.

For Kodi, the CrossWatch address must be reachable from the Kodi device. The TMDBHelper path must keep the double `&&` before the address.


---

# 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/main-dashboard/navigation/playlists/published-lists.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.
