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

# Watchlist & Search

> Universal search, the watchlist, requests and user preferences

<sup>New in 0.9.0</sup>

## Search

`GET /api/search?q=`

One search across your libraries, Live TV channels, what's on now, upcoming programs, and titles that aren't in your library yet (from TMDB).

```bash theme={null}
curl "http://<server>:9014/api/search?q=wrexham" -H "Authorization: Bearer <jwt>"
```

The response groups results by where they came from: `library`, `channels`, `onNow`, `upcoming` and `external`, plus the `query` and `tmdbConfigured`. Channel results carry `match_program_id` and `match_start` so you can highlight the matching program in the guide.

### Title details

`GET /api/titles/{mediaType}/{tmdbId}`, where `mediaType` is `movie` or `series`

Details for a TMDB title, including ones not in your library. Returns `503` if TMDB isn't configured on the server.

## Watchlist

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/watchlist` | Your watchlist: `{"items": [...]}` |
| `POST` | `/api/watchlist` | Add a title |
| `GET` | `/api/watchlist/{entryId}` | One entry: `{"item": {...}}` |
| `DELETE` | `/api/watchlist/{entryId}` | Remove one entry |
| `POST` | `/api/watchlist/remove` | Remove several. Body: `{"entryIds": [...]}`. Returns `{"removed": N}`. |
| `POST` | `/api/watchlist/status` | Check which titles are on your watchlist |
| `POST` | `/api/watchlist/{entryId}/request` | Retry a failed Radarr/Sonarr request |
| `GET` | `/api/watchlist/{entryId}/image?type=poster\|backdrop&width=` | Artwork for a title that isn't in a library. No token needed, so it works in `<img>` tags. |

### List

**type** `string` (default: all)

`all`, `movie` or `series`

**sort** `string` (default: added)

`added`, `title` or `year`

**order** `string`

`asc` or `desc`

### Add

Send either a library item, or a TMDB title that isn't in your library yet:

```json theme={null}
{"itemId": "<library-item-id>"}
```

```json theme={null}
{"mediaType": "movie", "tmdbId": 603}
```

If Radarr or Sonarr is set up, adding a title that isn't in your library sends a request for it. See [Radarr & Sonarr](https://docs.kernelmedia.tv/api-reference/admin/arr.md).

### Status

```json theme={null}
{"itemIds": ["<library-item-id>"], "refs": [{"mediaType": "series", "tmdbId": 1399}]}
```

Returns `{"status": ...}` saying which of those are on your watchlist.

## Preferences

`GET /api/user/me/preferences` returns your preferences; `PATCH` changes them.

**startScreen** `string`

`home` or `guide`: the screen apps open to

**watchlistAutoRemoveWatched** `boolean`

Remove titles from your watchlist once you've watched them


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