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

# Live TV

> Sources, EPG, categories, channel mapping, bitrate fallback and sports logos

All endpoints need an [admin token](https://docs.kernelmedia.tv/api-reference/admin/overview.md#authentication). Create endpoints (`POST`) and updates (`PUT`) return the saved object.

## Sources

Xtream Codes, M3U and HDHomeRun sources.

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/admin/livetv/sources` | List sources |
| `POST` | `/api/admin/livetv/sources` | Add a source |
| `PUT` | `/api/admin/livetv/sources` | Update a source (include its `id`) |
| `DELETE` | `/api/admin/livetv/sources/{id}` | Remove a source |

Main fields: `name`, `type`, `url`, `username`, `password` (Xtream Codes), `enabled`, `connection_limit`, `backup_channels`, `http_origin`, `http_referer`, `preferred_output_format`, `enable_vod`. Account details such as `account_status`, `expiration_date` and `active_connections` are read-only.

## EPG sources

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/admin/livetv/epg-sources` | List EPG sources |
| `POST` | `/api/admin/livetv/epg-sources` | Add one: `{"name": "...", "url": "...", "enabled": true}` |
| `PUT` | `/api/admin/livetv/epg-sources` | Update one (include its `id`) |
| `DELETE` | `/api/admin/livetv/epg-sources/{id}` | Remove one |
| `GET` | `/api/admin/livetv/epg-channels/search?q=` | Search guide channels, for matching a channel to EPG data |

## EPG categories

Your own guide categories. These become the guide's tabs on every app.

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/admin/livetv/epg-categories` | List categories |
| `POST` | `/api/admin/livetv/epg-categories` | Add one |
| `PUT` | `/api/admin/livetv/epg-categories` | Update several, e.g. to save a new order |
| `PUT` | `/api/admin/livetv/epg-categories/{id}` | Update one |
| `DELETE` | `/api/admin/livetv/epg-categories/{id}` | Remove one |

**name** `string` *required*

**sort\_order** `integer`

Tab position

**live\_event** `boolean`

Mark this as a live event category. On each source refresh, new provider channels whose group matches the category name are enabled automatically, so one-off event channels appear without manual mapping.

## Channels and mapping

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/admin/livetv/channels?group=` | Channels available for mapping, optionally limited to one provider group |
| `PUT` | `/api/admin/livetv/channels/mapping` | Save the mapped lineup |
| `PUT` | `/api/admin/livetv/channels/{id}` | Update one channel |
| `POST` | `/api/admin/livetv/channels/{id}/probe` | Probe a channel's stream. Returns `video_codec`, `audio_codec`, `width`, `height`, `frame_rate`, `bitrate`, `video_bitrate`, `audio_bitrate`. |
| `POST` | `/api/admin/livetv/channels/upload-logo` | Upload a custom channel logo |
| `GET` | `/api/admin/livetv/filter-groups` | The provider groups you can filter by |

`PUT /channels/mapping` takes an array of channels. For each one send its `id` plus `enabled`, `sort_order`, `epg_category` and `filter_group`.

`PUT /channels/{id}` accepts any of: `name`, `custom_name`, `tvg_id` / `epg_tvg_id` and `tvg_name` / `epg_tvg_name` (map the channel to guide data), `tvg_logo`, `live_event`, `channel_type` and `pip_layout`. A channel's `live_event` overrides its category's setting; send `null` to go back to the category default.

Event channels whose names follow the provider pattern (for example `NBA 01 Celtics vs. Pistons @ 20 Oct 02:58 PM ET`) come back with a cleaned-up `display_name` (`Celtics vs. Pistons`) for clients to show.

## Channel filters

Rules that include or exclude provider channels automatically.

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/admin/livetv/filters` | List filters |
| `POST` | `/api/admin/livetv/filters` | Add one |
| `PUT` | `/api/admin/livetv/filters` | Update one (include its `id`) |
| `DELETE` | `/api/admin/livetv/filters/{id}` | Remove one |

Fields: `source_id`, `filter_type`, `filter_value`, `action`, `enabled`.

## Picture in Picture channels

A PiP channel is a virtual channel that shows two existing channels at once.

| Method | Path | Description |
| - | - | - |
| `POST` | `/api/admin/livetv/pip-channels` | Create one |
| `DELETE` | `/api/admin/livetv/pip-channels/{id}` | Remove one (only PiP channels can be removed this way) |

Body: `name`, `main_channel_id`, `pip_channel_id`, `pip_layout`, and optionally `epg_category`, `sort_order` and `tvg_logo`.

## Settings and bitrate fallback

| Method | Path | Description |
| - | - | - |
| `GET` / `PUT` | `/api/admin/livetv/settings` | `auto_update_enabled`, `update_schedule`, `refresh_on_startup`, `bitrate_fallback_enabled` |
| `GET` | `/api/admin/livetv/output-settings` | The fallback streams |
| `POST` | `/api/admin/livetv/output-settings` | Add a fallback stream |
| `PUT` / `DELETE` | `/api/admin/livetv/output-settings/{id}` | Change or remove one |

With bitrate fallback on, everyone gets the original stream. When one viewer keeps buffering, the channel also starts sending the lighter fallback streams and only that viewer drops to one. Each fallback stream has a `resolution`, `video_bitrate`, `audio_bitrate` and `sort_order`.

## Refresh and sessions

| Method | Path | Description |
| - | - | - |
| `POST` | `/api/admin/livetv/refresh?force=` | Re-fetch sources from the database |
| `POST` | `/api/admin/livetv/refresh-guide` | Rebuild the guide cache only, with no external calls |
| `POST` | `/api/admin/livetv/sessions/stop` | Stop a viewer's stream. Body: `{"device_id": "<uuid>", "channel_id": "<uuid>"}`; leave out `channel_id` to stop all of that device's streams. |

## Start times <sup>New in 0.9.0</sup>

Kernel learns how much buffer each channel needs before its first frame. A channel that stalls on start is moved to a safer tier with a bigger cushion.

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/admin/livetv/start-times` | Each channel's start tier and its recent starts, with phase timings and outcome. Newest first. |
| `DELETE` | `/api/admin/livetv/start-times/{channel_id}` | Reset a channel so its next start uses the normal tier |

## Sports team logos <sup>New in 0.9.0</sup>

Used for the generated matchup artwork on game channels.

| Method | Path | Description |
| - | - | - |
| `POST` | `/api/admin/livetv/team-logos/sync` | Pull every league's team list from ESPN and rebuild matchup artwork. Returns `{"leagues": N, "teams": N, "errors": [...]}`. |
| `GET` | `/api/admin/livetv/team-logos/explain?text=` | Show how a channel name or program title is parsed and which teams and leagues it matches, or why it doesn't match |

```bash theme={null}
curl "http://<server>:9014/api/admin/livetv/team-logos/explain?text=Wrexham%20vs%20Birmingham%20City" \
  -H "Authorization: Bearer <admin-jwt>"
```


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