> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kernelmedia.tv/llms.txt
> Use this file to discover all available pages before exploring further.

# Plex & Jellyfin Import

> Bring over Libraries, Users, Watch History, Watchlists and Show Themes

<sup>New in 0.9.0</sup> Import from an existing Plex or Jellyfin server. The same endpoints are mounted twice:

* `/api/admin/import/*`, which needs an [admin token](https://docs.kernelmedia.tv/api-reference/admin/overview.md#authentication)
* `/api/setup/import/*`, which is open only while the first-run setup wizard is running

The Plex token or Jellyfin API key you send is used only for that request and the import it starts. It is never stored.

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/admin/import/discover` | Find Plex and Jellyfin servers on your local network. Returns `{"servers": [...]}`. In Docker this needs host networking. |
| `POST` | `/api/admin/import/preview` | Connect to a source and see its libraries and users, with suggested matches |
| `POST` | `/api/admin/import/run` | Start the import. Returns `{"task_id": "..."}`. |
| `GET` | `/api/admin/import/status/{taskId}` | Progress, plus the result when it finishes: `{"task": {...}, "result": {...}}` |
| `GET` | `/api/admin/import/profile?source=` | What the last run for `plex` or `jellyfin` remembered (URL and choices, never the token) |

## Connection

`preview` and `run` both take the connection fields:

**source** `string` *required*

`plex` or `jellyfin`

**url** `string` *required*

The source server's address

**token** `string` *required*

Plex token or Jellyfin API key

**path\_rewrites** `object[]`

`[{"from": "/data/movies", "to": "/media/movies"}]` when the source sees your files at different paths than Kernel does

In the preview, each source user comes back with a `suggested_username`, whether it was `already_imported`, and whether an existing Kernel account `matched` by name (with `matched_username`).

## Run

On top of the connection fields, `run` takes what to import:

**library\_map** `object`

Source library ID → Kernel library ID, or `"__create__"` to create a matching library

**users** `object[]`

One plan per source user: `source_user_id`, `target` (`new`, `existing` or `skip`), plus `username` for a new account or `existing_user_id` to merge into an existing one. PIN-protected Plex Home users also take a `pin`.

**watch\_activity** `boolean`

Import Watch History and progress

**apply\_to\_existing** `boolean`

Also apply watch activity to accounts that already exist

**watchlist** `boolean`

Import Watchlists

**skip\_users** `boolean`

**skip\_libraries** `boolean`

**skip\_markers** `boolean`

Don't bring over intro and credits markers

**themes\_only** `boolean`

Import only Show Themes (Plex theme music)

Imported Show Themes are served at `GET /theme/{item_id}` (see [Libraries & Items](https://docs.kernelmedia.tv/api-reference/libraries-and-items.md)).

## Plex Home PIN sync

A Plex Home user protected by a PIN can't be synced during the admin's import. That user can sync their own watch state and watchlist later by entering the PIN once:

* `GET /api/user/me/plex-sync`: whether the signed-in user has a pending PIN sync
* `POST /api/user/me/plex-sync`: run it. Body: `{"pin": "1234"}`

The PIN is used for that sync and never stored.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.