> 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/editor.md).
# Editor
Inspect provider data, correct item mappings, edit dates, ratings and progress, manage blocks, and send or remove selected records on your providers.
The **Editor** works with **Current State** and configured **Playlist Endpoints**. Current State combines stored provider data with your local corrections. **Send to…** lets you apply selected data directly to provider profiles through **Add to…** or **Remove from…**.
{% tabs %}
{% tab title="End users" %}
### Quick start
1. Open **Editor** from the main navigation.
2. Choose **Current State**, or **Playlist Endpoint** if you have configured an endpoint.
3. For Current State, choose the dataset, provider and profile.
4. Choose the **Mapping scope** when working with local corrections or blocks.
5. Search for the items you want to inspect or change.
6. Use **Save changes** to persist staged edits, or select rows and open **Send to…** for a direct provider operation.
### What each action changes
| Action | Result |
| --------------------------------------- | ------------------------------------------------------------------------------- |
| **Save changes** in Current State | Saves local additions, corrections and blocks for future sync processing. |
| **Add to…** in Send to | Writes the selected data to the chosen provider profiles. |
| **Remove from…** in Send to | Removes matching records from the chosen eligible provider profiles. |
| **Save changes** on a Playlist Endpoint | Applies supported playlist changes to the connected provider. |
| **Import provider state** | Reads provider data and refreshes the stored baseline in CrossWatch. |
| **Mappings & blocks** actions | Saves rule changes immediately, except mapping edits opened in the main Editor. |
{% hint style="info" %}
Saving Current State changes does not directly update the provider account. Use Send to when you want to write selected data immediately. Direct sends and removals do not create a permanent sync pair or save other staged Editor changes.
{% endhint %}
### Current State
Current State displays the provider data CrossWatch has stored, together with local policy for the selected provider profile and dataset.
Opening this view does not fetch a fresh inventory from the provider. Run a sync or use **Import provider state** when you need newer data.
The available datasets depend on provider support:
| Dataset | What you can inspect or edit |
| ----------- | -------------------------------------------------------- |
| Watchlist | Item presence and identity. |
| History | Watched information and watched date. |
| Ratings | Rating values, with a selector from 1 to 10. |
| Progress | Playback position, duration, percentage and update time. |
| Collections | Collection membership and collected date. |
#### Mapping scope
Use **Mapping scope** to choose where local changes apply.
Scope
Applies to
All pairs using this provider instance
Syncs using this provider profile for the selected dataset.
A specific sync pair
The selected sync relationship only.
A correction saved for a specific pair takes precedence over a shared correction for that pair. Check the scope before creating or editing rules. If you switch scope with unsaved changes, Editor asks whether to discard them.
#### Editing dates, ratings and progress
Click the dataset value in the **Extra** column to open its editor. Editing a baseline value creates a local correction. Save it with **Save changes** to use it during future sync processing.
| Dataset | Editor controls |
| ----------- | --------------------------------------------------------------------------------- |
| History | **Watched at**, date and time, with Save and Clear. |
| Ratings | Select a value from 1 to 10, or Clear the local value. |
| Progress | **Position**, **Duration**, **Percent**, and **Updated at**, with Save and Clear. |
| Collections | **Collected at**, date and time, with Save and Clear. |
Times are displayed and saved in **UTC**.
For Progress, you can enter playback time or a percentage from 0 to 100. When both position and duration are present, Editor calculates the percentage from those values. If you enter progress without an update time, it uses the current time.
Clearing a value here is a local edit. To remove an existing provider record, use **Remove from…** where supported.
#### Add an item manually
1. Click **Add row**.
2. Enter a unique item **Key**.
3. Set the media type, title and year.
4. Add the external IDs needed to identify the item.
5. Enter a watched date, rating, progress value or collection date when applicable.
6. Click **Save changes**.
A nonempty active row needs a key before it can be saved. Accurate IDs help providers resolve the intended title. For an episode, also verify the series identity, season and episode number.
A manual addition makes the item part of the effective source data used by CrossWatch. It does not add it to the source provider account by itself.
### Correct an item mapping
Use a mapping correction when an item has resolved to the wrong movie, series, season or episode.
1. Select **Current State**, the dataset, provider and profile.
2. Check **Mapping scope**.
3. Find the incorrect item and open its mapping action.
4. Search for and select the correct identity in the mapping workspace.
5. For episodes, verify the series, season and episode coordinates.
6. Save the result in the mapping workspace.
7. Click **Save changes** in the main Editor.
The mapping workspace is shared with Interactive Sync. Its save action stages the correction in Editor. The main **Save changes** action persists it.
When a correction replaces an item key, CrossWatch can also create a protective block for the original identity. This keeps the original and corrected identities from being processed independently.
### Mappings & blocks
Open **Mappings & blocks** to manage saved corrections and exclusions. The dialog follows the current mapping scope and initially uses the current source and dataset.
Use **Search**, **Source and profile**, and **Feature** to locate records. The results are paginated, with **Previous**, **Next**, and **Refresh** controls.
#### Review and edit a mapping
The **Mappings** view compares the original item with the saved correction. It also shows where the rule applies, its origin and its saved time when available. Corrections can come from Editor, Interactive Sync or Analyzer.
Click the pencil to open a correction in Editor. Make the change, save the mapping workspace, then click **Save changes**. Editing an existing mapping preserves its scope.
#### Delete a mapping
Click the delete action on the saved mapping and confirm.
Deletion takes effect immediately. It also removes the automatic block associated with that mapping's original item. Remaining rules apply again, including a shared mapping when you delete an overriding pair correction.
Deleting a mapping does not delete anything from a provider account.
#### Block an item
A block excludes an item from future sync processing within its scope.
To create a standalone block:
1. Open **Mappings & blocks**, then **Blocked items**.
2. Select the source, profile and feature.
3. Check the displayed scope.
4. Enter the item key, such as `tmdb:123` or `tmdb:123#s01e02`.
5. Click **Block item**.
Click **Unblock** to remove a standalone rule. Both actions take effect immediately. Blocks associated with a mapping are managed through that mapping.
Save or discard staged Editor changes before adding, removing or importing rules in this dialog.
#### Block rows from Current State
Use the row block action or select rows and choose **Block selected**. Click **Save changes** to persist the exclusions. **Unblock selected** stages the reverse action.
For datasets other than Watchlist, **Block rules** also lets you choose a media type and apply **Block all** or **Unblock all**. These actions affect matching baseline rows and require **Save changes**. Manual additions are not converted into blocks by this operation.
{% hint style="info" %}
Blocking an item changes CrossWatch policy. It leaves the provider record in place. Use Remove from if you also want to remove matching data from a provider.
{% endhint %}
#### Export mappings and blocks
Click **Export** in Mappings & blocks to download `crosswatch-mappings-blocks.json`.
The export includes mappings and blocks for the selected scope, source and feature. The search text and currently selected tab do not restrict the export to the visible rows.
#### Import mappings and blocks
1. Click **Import** in Mappings & blocks.
2. Select a Mappings & blocks JSON export, version 1, up to 20 MB.
3. Review and confirm the import.
4. Check the imported and skipped counts.
Records are imported into the provider, profile, feature and pair scopes stored in the file. Current dialog filters do not limit the import. Existing or conflicting records are skipped.
### Send to, add or remove selected data
Select rows in the table and click **Send to…** in the selection toolbar. Choose **Add to…** or **Remove from…** inside the dialog.
Both operations use the current dataset. Multiple provider profiles can be processed in one operation, with separate results for each profile.
#### Add to…
Use Add to to send selected Watchlist, History, Ratings, Progress or Collections data to supported provider profiles.
1. Select the active rows you want to send.
2. Open **Send to…** and choose **Add to…**.
3. Select the destination profiles.
4. Check the dataset and row count.
5. Click **Send selected data**.
6. Review the results for each provider.
Only configured, accessible profiles supporting the dataset are offered. The profile you are viewing is excluded from Add to targets. Another profile of the same provider can still be eligible.
Blocked or deleted rows are excluded from Add to. Playlist Endpoint rows are sent as Watchlist data, rather than copied into a destination playlist.
Collections targets do not include Plex, Emby, Jellyfin or Kodi in this workflow.
#### Remove from…
Use Remove from to remove matching data from provider profiles with existing sync evidence.
1. Select the records you want to remove.
2. Open **Send to…** and choose **Remove from…**.
3. Wait for the matching provider profiles to load.
4. Review the matching count shown for each profile.
5. Select the profiles to change.
6. Click **Remove selected data**.
7. Click **Confirm removal of … records** to proceed.
8. Review the verified results.
The removal list is based on stored sync pair baselines and provider removal capabilities. A configured provider does not automatically qualify. Each target must have an unambiguous matching record in an accessible sync pair for the dataset.
The profile currently being viewed can appear as a removal target. Blocked baseline rows can also be selected for removal, allowing you to exclude an item from sync processing and remove its provider record separately.
When a specific mapping pair is selected, removal discovery uses that pair. Without a specific pair scope, it checks accessible pairs for the dataset.
If pair baselines are missing, run the relevant sync first. Importing Current State alone does not create the pair evidence required by this operation.
#### What removal does
CrossWatch checks the preview again before processing the request. It reads each selected provider's current data, resolves the matching records, applies the provider's removal operation and reads the provider again to verify the result.
Only confirmed removals update the corresponding stored Current State. Unresolved records are retained. Records already absent from the provider are reported as skipped.
Removal changes the selected dataset, such as watchlist membership, rating or watched status. It does not delete media files from your server.
{% hint style="warning" %}
Other sync sources or saved manual additions can restore removed records during a later sync. Removal does not create a block or rewrite your sync rules. Review the relevant rules if the item should remain excluded.
{% endhint %}
#### History removal
History removal uses each provider's existing sync removal behavior. Select a watched status row, rather than an individual dated watch event. Removing one specific watch date is not supported by this Editor workflow.
For **FLOPPY**, removal deletes one watch entry for each selected movie or episode. Other watches can remain. The result can therefore report **still watched (other watches remain)** after a successful removal.
#### Read the results
| Result | Meaning |
| --------------- | ------------------------------------------------------------------------------------ |
| Sent or Removed | Records confirmed by the operation. |
| Attempted | Records processed across the selected targets. |
| Skipped | Records skipped by the provider operation, including removal records already absent. |
| Unresolved | Items that could not be resolved or whose removal could not be confirmed. |
| Errors | Provider or processing failures. |
| Invalid | Selected input rows that could not be used for the send. |
Totals cover all selected targets, so they can exceed the number of selected source rows. A successful result for one provider does not mean every other provider succeeded.
If removal targets change after the preview, review the refreshed selection and confirm again. If another sync or provider operation is running, wait until it finishes before retrying removal.
### Search, selection and layout
Search can match titles, series titles, item keys, media types, years and external IDs. Episode searches also accept values such as `S01`, `S01E02`, `1x2`, or `season 1 episode 2`.
Use the media type chips to filter Movies, Shows, Anime, Seasons or Episodes where applicable. **Blocked** filters Current State to blocked rows.
Use **Columns** to choose and reorder visible fields. Columns include identity fields, title, year, external IDs and **Extra** for dataset values. You can resize columns, sort the table and toggle **Wide view**.
The browser retains layout, filters, sorting and page size preferences. Page sizes are 50, 100, 150 or 200 rows. The page selection checkbox selects the currently visible page, so check the selection count before a provider operation.
Use **Advanced fields** to inspect metadata beyond the default columns, including series IDs, episode coordinates, timestamps and provider identifiers.
### Import provider state
Use this to fetch fresh provider data into Current State when provider import is available.
1. Select **Current State**.
2. Expand **Import provider state**.
3. Choose the provider and profile.
4. Select the supported datasets to import.
5. Choose an import mode.
6. Click **Import** and wait for completion.
| Mode | Behavior |
| -------------------- | ------------------------------------------------------------------------ |
| **Replace baseline** | Refreshes the selected datasets from the provider. |
| **Merge (keep old)** | Keeps existing baseline rows and adds or updates returned provider rows. |
Import reads the provider account and updates stored data in CrossWatch. Existing local policy remains separate and continues to apply.
### Playlist Endpoint
Configure an endpoint on the **Playlists** page first. Then choose **Playlist Endpoint** in Editor and select the endpoint.
Editor loads its playlist items. Available changes depend on endpoint capabilities, which can include adding, removing and reordering. Smart or read only endpoints cannot be edited.
Click **Save changes** to apply supported changes to the provider playlist. Review any provider warnings and removal confirmation shown during save.
Sending selected endpoint rows through **Add to…** is a separate Watchlist operation. Saving the endpoint is the action that edits the configured playlist itself.
### Policy backup
Expand **Policy backup** to export local Current State policy using **Download JSON**, or restore a policy JSON file through **Import file**. The Editor's policy import uses merge mode.
Use this for local policy backup. Use the separate **Mappings & blocks** export when you want the dedicated mapping and block transfer format. Neither export is a full backup of provider accounts or media libraries.
{% endtab %}
{% tab title="Power users" %}
### State and policy
Current State has two distinct layers: stored provider baselines and persistent local policy. Policy includes manual additions, blocks and mapping corrections, with provider, profile, feature and optional pair scope.
Current CrossWatch stores policy in its local database. Exported JSON is a transfer and backup representation, rather than the primary runtime store.
A standard Current State save persists policy. Provider import refreshes baseline data. Confirmed direct sends can update the target's stored state. Verified removals update affected Current State records while preserving pair comparison baselines for subsequent sync processing.
### Mapping precedence and lifecycle
Shared corrections apply to the selected provider instance and feature. Pair corrections override shared corrections within their pair.
A correction can own a block for the original identity. Deleting the correction also removes that associated block, while remaining rules continue to apply. Standalone blocks are managed independently.
Mappings & blocks export uses the selected source, feature and scope. Import restores the scopes recorded in the file and skips existing or conflicting records. It is a separate format from Policy backup.
### Removal constraints
Removal eligibility comes from saved pair baselines. The operation checks provider access, dataset and media type support, and an unambiguous identity match. Server specific IDs are not used to match items across different provider accounts. Episode matching includes coordinates to avoid matching another episode from the same series.
The server accepts between 1 and 1000 selected rows for removal. It requires confirmation and an unchanged preview, coordinates with running sync operations, and verifies provider state after the write. Individual dated history events are rejected.
Provider failures are reported per target. CrossWatch does not discard unresolved cached records merely because a removal was requested.
### API reference
These routes are relative to `/api/editor`:
| Method and route | Purpose |
| --------------------------- | -------------------------------------------------------------------------------------------- |
| `GET /mappings` | List saved mappings or standalone blocks. |
| `POST /mapping` | Prepare or resolve a mapping. |
| `POST /mapping-block` | Add or remove a standalone block. |
| `POST /mappings/delete` | Delete a saved mapping and its associated original identity block. |
| `GET /mappings/export` | Export mappings and blocks for the requested scope. |
| `POST /mappings/import` | Import a dedicated mappings and blocks JSON file. |
| `GET /send/providers` | Discover configured targets for a dataset. |
| `POST /send/preview` | Preview eligible removal targets and matching counts. |
| `POST /send` | Add selected data, or remove it with `operation: "remove"`, confirmation and the preview ID. |
| `GET /state/manual/export` | Export Current State policy. |
| `POST /state/manual/import` | Import Current State policy. |
| `POST /state/import` | Read supported provider datasets into stored Current State. |
Available data and actions depend on the active CrossWatch profile and its permissions.
{% 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/main-dashboard/navigation/editor.md?ask=&goal=
```
`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.