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

# API Reference

> Authenticate and call Kernel's client-facing HTTP API

This reference covers the HTTP API used by Kernel's own clients (web, Roku, Android, iOS, Apple TV): signing in, browsing libraries, and playing back VOD and Live TV. Admin and setup-wizard endpoints aren't included here.

## Base URL

```text theme={null}
http://<your-server>:9014
```

There's no separate API host. The same server that serves the web app serves the API.

## Authentication

Call `POST /login` with your username and password to get a token:

```bash theme={null}
curl -X POST http://<your-server>:9014/login \
  -H "Content-Type: application/json" \
  -d '{"username": "you", "password": "your-password"}'
```

```json theme={null}
{"auth": {"token": "<jwt>", "device_id": "<id>"}}
```

Send the token back on every subsequent request:

```text theme={null}
Authorization: Bearer <jwt>
```

<Warning>
  Login tokens don't expire. Treat them like a long-lived credential; don't log them or embed them in client-side code you don't control.
</Warning>

## Device headers

Send these on login and on playback requests so Kernel can pick the right format and bitrate for your client:

| Header | Purpose |
| - | - |
| `Device-Id` | Stable identifier for this install. If omitted, Kernel derives one from your User-Agent. |
| `Device-OS` | e.g. `Roku OS`, `android ...`. Drives the HLS vs. DASH decision for Live TV. |
| `Device-Max-Height` | Caps the resolution Kernel will serve. |
| `Device-Codecs` | Video codecs your client can decode (e.g. hevc/av1 support). |
| `Device-HDR` | `1`/`true` if your client supports HDR. |
| `Device-Audio-Codecs` | Comma-separated audio codecs your client decodes (e.g. `aac,ac3`). |
| `Device-Audio-Channels` | Max audio channels your client supports. |
| `Device-Containers` | Containers your client can play directly. |

## Errors

Errors are always a JSON object with a single `error` field:

```json theme={null}
{"error": "User Account Inactive"}
```

## Next steps

<CardGroup cols={2}>
  <Card title="Playback Guide" icon="play" href="/api-reference/playback-guide">
    How VOD and Live TV playback URLs work together
  </Card>

  <Card title="Auth & Account" icon="user" href="/api-reference/auth-and-account">
    Sign in, favorites, password, avatar
  </Card>

  <Card title="Libraries & Items" icon="film" href="/api-reference/libraries-and-items">
    Browse movies and TV shows
  </Card>

  <Card title="Live TV & EPG" icon="satellite-dish" href="/api-reference/live-tv-and-epg">
    Channels, guide, and recordings
  </Card>
</CardGroup>


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