> 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

{% 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 a MUST HAVE for proper enrichment
{% endhint %}

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

<figure><img src="/files/HEHPP5ZrPFKKwvmJv4Lg" alt=""><figcaption></figcaption></figure>

{% 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](/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 %}

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

### Profiles

PublicMetaDB supports multiple profiles.

Use **Profile** to switch between `Default` and extra profiles.

Click **New** to add a profile.

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

Guide: [Profiles](/crosswatch/settings/connections/profiles.md)

### 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" %}

### Config keys

Stored under:

* `publicmetadb.api_key`
* `publicmetadb.instances.<profile>.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

* Profiles: [Profiles](/crosswatch/settings/connections/profiles.md)
* Pair setup: [Configure Pairs](/crosswatch/settings/configure-pairs.md)
* Watchlist settings: [Watchlist](/crosswatch/settings/configure-pairs/features/watchlist.md)
* Progress settings: [Progress](/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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://wiki.crosswatch.app/crosswatch/settings/connections/trackers/publicmetadb.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.