> 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/publicmetadb.md).

# PublicMetaDB

{% 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%2FvYjAPY67Cky0Lvah2i1o%2Fimage.png?alt=media&amp;token=168fb3e2-d01f-4aa5-8cbb-b2b094ba75c9" alt=""><figcaption></figcaption></figure>

Connect PublicMetaDB to synchronize supported activity with CrossWatch.

{% hint style="warning" %}
**PublicMetaDB support is experimental.**

Prefer a one-way flow into PublicMetaDB.

Start with your media server as the source and PublicMetaDB as the target.

TMDb Metadata is required for proper enrichment.
{% endhint %}

{% hint style="info" %}
PublicMetaDB uses an API key.

CrossWatch can also enrich missing titles and release years for PublicMetaDB items in watchlist, history, ratings, and progress.

That enrichment needs [TMDb Metadata](https://wiki.crosswatch.app/crosswatch/settings/connections/metadata/tmdb-metadata.md) and a TMDb API key.

It runs only when the PublicMetaDB item already has a TMDb ID and is missing the field.
{% 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; requires TMDb IDs.              |
| History    | Yes  | Yes   | Movies and episodes.                              |
| Ratings    | Yes  | Yes   | Movies, shows and episodes; requires TMDb IDs.    |
| Progress   | Yes  | Yes   | Movies and episodes; writes need a known runtime. |
| Playlists  | Yes  | Yes   | Actions depend on list ownership and permissions. |
| Collection | No   | No    | Unsupported.                                      |

**Live scrobbling:** Not supported.

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

### Connect PublicMetaDB

1. Open **Settings → Connections**.
2. Open **PublicMetaDB**.
3. In PublicMetaDB, create an API key in **Settings → API**.
4. Paste the key into **API Key**.
5. Click **Connect**.
6. If needed, click **Verify** once.

API keys usually start with `pm-`.

### Instances

PublicMetaDB supports multiple instances.

Use **Instance** to switch between `Default` and extra instances.

Click **New** to add an instance.

Click **Delete** to remove a non-default instance.

Guide: [Instances](https://wiki.crosswatch.app/crosswatch/settings/connections/instances.md)

### Playlists

Your own lists are writable. Other users’ public lists can be resolved by a supported link as read-only sources. This still requires the connection’s API key.

CrossWatch uses TMDb identifiers for movies and shows. In Playlists, choose **Private** (default) or **Public** when creating a list. Privacy cannot be changed later through CrossWatch. Rename and ordering are unsupported.

Unknown list IDs are not writable. Usernames in PublicMetaDB list links are case-sensitive.

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

### Troubleshooting

* “Connected” only means CrossWatch saved an API key.
* **Verify** checks the key against PublicMetaDB.
* Missing titles or years usually mean TMDb metadata is not configured, the item has no TMDb ID, or the field already came from PublicMetaDB.
* If verify fails, rotate the key in PublicMetaDB and reconnect.
  {% endtab %}

{% tab title="Power users" %}

## Power users

### Config keys

Stored under:

* `publicmetadb.api_key`
* `publicmetadb.instances.<instance>.api_key`

Common shared settings:

* `publicmetadb.base_url`
* `publicmetadb.watchlist_name`
* `publicmetadb.watchlist_list_id`
* `publicmetadb.ratings_label`
* `publicmetadb.rate_limit.get_per_sec`
* `publicmetadb.rate_limit.post_per_sec`

Pair-level watchlist overrides are stored under:

* `providers.publicmetadb.watchlist_name`

### Auth behavior

CrossWatch stores the API key and marks the provider as connected.

A deeper health check validates the key against PublicMetaDB.

CrossWatch sends the key as a bearer token.

### Related docs

* Instances: [Instances](https://wiki.crosswatch.app/crosswatch/settings/connections/instances.md)
* Pair setup: [Configure Pairs](https://wiki.crosswatch.app/crosswatch/settings/configure-pairs.md)
* Watchlist settings: [Watchlist](https://wiki.crosswatch.app/crosswatch/settings/configure-pairs/features/watchlist.md)
* Progress settings: [Progress](https://wiki.crosswatch.app/crosswatch/settings/configure-pairs/features/progress.md)
  {% 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/publicmetadb.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.
