TVHeadend API Documentation

February 14, 2026 · View on GitHub

Comprehensive OpenAPI 3.1 specification and documentation for the TVHeadend JSON API.

What is TVHeadend?

TVHeadend is a TV streaming server for Linux supporting multiple input sources (DVB-S, DVB-T, DVB-C, IPTV, etc.). It provides:

Live TV streaming via HTTP, HTSP, and SAT>IP protocols
Electronic Program Guide (EPG) from multiple sources
Digital Video Recording (DVR) with series/keyword recording
Multi-user support with fine-grained access control
Web interface for configuration and management

This documentation covers TVHeadend's JSON API for programmatic access to these features.

What's in This Documentation

📘 OpenAPI Specification

Machine-readable API specification in OpenAPI 3.1 format. Use this for:

Generating client code (TypeScript, Python, Go, etc.)
API validation and testing
Interactive API exploration (Swagger UI, Redoc)

View with:

# From project root — serves unified API landing page
pnpm run docs:serve
# Open http://localhost:8080 and click "TVHeadend API"
# Or open directly: http://localhost:8080/tvheadend/index.html

# Watch for changes with auto-reload
pnpm run docs:watch

📖 Guides

Comprehensive guides for common topics:

Authentication Guide - HTTP Basic Auth setup, privilege system, security best practices
Pagination Guide - Working with grid responses, handling large datasets
Filtering Guide - Complex filtering, search queries, field operators
Error Handling Guide - HTTP status codes, error responses, recovery strategies

💡 Examples

Ready-to-use code examples:

Shell Scripts:

Channel Operations - List, search, and filter channels
DVR Recording - Schedule recordings, manage DVR
EPG Queries - Query program guide, search shows

Use Case Walkthroughs:

01 - List Channels - Complete channel list implementation
02 - Schedule Recording - One-click recording from EPG
03 - Query Program Guide - Build EPG grid view

🔍 API Reference

Detailed endpoint documentation organized by category (53 endpoints total):

EPG Endpoints (6 endpoints) - Program guide queries, event details, brand list
Channel Endpoints (10 endpoints) - Channel management, tags, categories, rename
DVR Endpoints (23 endpoints) - Recording management, auto-rec rules, series timers, status filtering
Config Endpoints (5 endpoints) - System configuration, server capabilities (admin only)
Status Endpoints (9 endpoints) - Server health, monitoring, subscriptions, activity status

Quick Start

1. Setup Authentication

Create a user in TVHeadend with appropriate privileges:

# Open TVHeadend UI
open http://localhost:9981

# Navigate to: Configuration → Users → Access Entries
# Create user with 'streaming' and 'recording' privileges

2. Test Connection

# Test with curl
curl -u username:password \
  http://localhost:9981/api/serverinfo | jq '.'

# Expected response
{
  "name": "TVHeadend",
  "version": "4.3.2024",
  "api_version": 18
}

3. Query EPG

# Get currently airing programs
curl -u username:password \
  'http://localhost:9981/api/epg/events/grid?mode=now&limit=10' | jq '.'

4. List Channels

# Get all channels sorted by number
curl -u username:password \
  'http://localhost:9981/api/channel/grid?sort=number&dir=ASC&limit=50' | jq '.'

5. Schedule Recording

# Find a program
EVENT_ID=$(curl -s -u username:password \
  'http://localhost:9981/api/epg/events/grid?limit=1' | \
  jq -r '.entries[0].eventId')

# Schedule recording
curl -u username:password -X POST \
  -H "Content-Type: application/json" \
  -d "{\"event_id\":$EVENT_ID}" \
  'http://localhost:9981/api/dvr/entry/create_by_event'

Key Concepts

Grid Pattern

Most TVHeadend endpoints use a consistent "grid" pattern for paginated data:

{
  "entries": [...],  // Array of items
  "total": 142,      // Total count (all pages)
  "start": 0,        // Current offset
  "limit": 50        // Page size
}

Learn more: Pagination Guide

Filtering

Complex filtering supported via JSON filter parameter:

# Simple string search
?filter=news

# Field-specific filter
?filter={"field":"channelname","type":"string","value":"BBC"}

# Multiple conditions (AND logic)
?filter=[
  {"field":"channelname","type":"string","value":"BBC"},
  {"field":"start","type":"numeric","value":1704067200,"comparison":"gte"}
]

Learn more: Filtering Guide

Authentication

HTTP Basic Authentication required for all API requests:

curl -u username:password http://localhost:9981/api/...

Privilege levels:

admin - Full access
streaming - View EPG, channels
recording - Schedule recordings
htsp_streaming - HTSP streaming access

Learn more: Authentication Guide

Common Use Cases

Building an EPG Application

Monitoring & Automation

Check server info: GET /api/serverinfo
Check server capabilities: GET /api/config/capabilities
Monitor active connections: GET /api/status/connections
Monitor active subscriptions: GET /api/status/subscriptions
Check low-power mode suitability: GET /api/status/activity
Monitor recordings: GET /api/dvr/entry/grid?status=recording
View upcoming recordings: GET /api/dvr/entry/grid_upcoming
View failed recordings: GET /api/dvr/entry/grid_failed
Auto-record by keywords: POST /api/dvr/autorec/create
Create series timer: POST /api/dvr/autorec/create_by_series
View system logs: GET /api/log
Reset input statistics: POST /api/status/inputclrstats

Data Export

Export channel list to CSV
Generate weekly EPG schedule
Backup recording configuration
Generate usage reports

See examples/ for complete implementations.

API Stability Warning

⚠️ Important: TVHeadend's API is not officially documented or versioned by the project. This documentation is reverse-engineered and may not cover all endpoints or edge cases.

Recommendations:

Pin your TVHeadend version in production
Test thoroughly before upgrading TVHeadend
Implement defensive error handling
Monitor for breaking changes in new releases
Contribute improvements to this documentation

Known compatibility:

TVHeadend 4.2.x ✓ (Core APIs stable)
TVHeadend 4.3.x ✓ (Tested, minor additions)
TVHeadend 4.4+ ⚠️ (Test before deployment)

Version-Specific Features

Some endpoints require specific TVHeadend versions:

Requires TVHeadend 4.3.652+:

POST /api/channel/rename - Channel renaming functionality

Requires TVHeadend 4.3-2405+:

GET /api/status/activity - Low-power mode suitability information

Deprecated Endpoints

⚠️ Deprecated in TVHeadend 4.3.1059+:

GET /api/epg/brand/list - List commonly-available shows (may be removed in future versions)

Untested Endpoints

⚠️ Untested - Use with caution:

GET /api/channelcategory/list - EPG event categories (test against your TVHeadend version)

Project Structure

docs/api/tvheadend/
├── index.html                # Stoplight Elements documentation viewer
├── openapi.yaml              # Main OpenAPI spec
├── README.md                 # This file
├── components/               # Reusable OpenAPI components
│   ├── schemas/             # Data models
│   ├── parameters/          # Query parameters
│   ├── responses/           # Response definitions
│   ├── examples/            # Example data
│   └── security-schemes.yaml
├── paths/                    # API endpoint definitions
│   ├── epg.yaml
│   ├── channel.yaml
│   ├── dvr.yaml
│   ├── config.yaml
│   └── status.yaml
├── guides/                   # Documentation guides
│   ├── authentication.md
│   ├── pagination.md
│   ├── filtering.md
│   └── errors.md
└── examples/                 # Code examples
    ├── curl/                # Shell scripts
    └── use-cases/           # Walkthrough tutorials

Tools & Validation

Validate OpenAPI Spec

# From project root
pnpm run validate:openapi

Generate Client Code

TypeScript:

npm install -g @openapitools/openapi-generator-cli

openapi-generator-cli generate \
  -i docs/api/tvheadend/openapi.yaml \
  -g typescript-axios \
  -o src/generated/tvheadend-client

Python:

pip install openapi-generator-cli

openapi-generator-cli generate \
  -i docs/api/tvheadend/openapi.yaml \
  -g python \
  -o tvheadend_client

Go:

openapi-generator-cli generate \
  -i docs/api/tvheadend/openapi.yaml \
  -g go \
  -o tvheadend-client

Interactive Documentation

Stoplight Elements (recommended):

# From project root — serves unified API landing page
pnpm run docs:serve
# Open http://localhost:8080 and click "TVHeadend API"
# Or open directly: http://localhost:8080/tvheadend/index.html

# With live reload during development
pnpm run docs:watch

Features:

✨ Interactive API Explorer - Try out API endpoints directly from the docs
📱 Responsive Design - Works on desktop, tablet, and mobile
🎨 Clean UI - Modern, professional documentation interface
🔄 Live Reload - Changes automatically refresh the browser

Alternative viewers:

# Swagger UI (optional)
docker run -p 8081:8080 \
  -e SWAGGER_JSON=/openapi.yaml \
  -v $(pwd)/docs/api/tvheadend/openapi.yaml:/openapi.yaml \
  swaggerapi/swagger-ui
# Open http://localhost:8081

Contributing

This documentation is part of the tvh-guide-ng project. Contributions welcome!

How to contribute:

Fork the repository
Add/improve documentation
Validate with pnpm run validate:openapi
Submit pull request

What to contribute:

New endpoint documentation
Code examples in other languages
Error scenarios and solutions
Performance tips
Real-world use cases

TVHeadend

OpenAPI & Tools

OpenAPI 3.1 Specification
Stoplight Elements - Interactive API documentation
Spectral OpenAPI Linter - Validation & linting
OpenAPI Generator - Client code generation

This Project

License

This documentation is part of the tvh-guide-ng project and is licensed under the same terms as the project.

TVHeadend is licensed under GPL-3.0. This documentation is independently created and not officially endorsed by the TVHeadend project.

Version

Documentation Version: 2.0.0
API Endpoints: 53 (expanded from 28)
TVHeadend Compatibility: 4.2.x, 4.3.x (some endpoints require 4.3.652+ or 4.3-2405+)
Last Updated: 2026-02-13

Need Help?

Check the guides for common topics
Browse examples for code samples
Search the OpenAPI spec for specific endpoints
Open an issue on GitHub for bugs/questions