System API: Tasks, Backups, and Server Health Endpoints

The System API provides access to Tunarr’s operational internals: background task management, server health checks, system and FFmpeg settings, feature flags, and streaming configuration. These endpoints are especially useful for monitoring, automation, and integration with home-lab orchestration tools.

Health Check

Runs all registered health checks and returns a structured report. Useful for liveness/readiness probes in Docker or Kubernetes deployments.

GET /api/system/health

Response 200 — Record<string, HealthCheck> — map of check name → result.

[checkName].healthy

boolean

true if the component is operating normally.

[checkName].message

string

Optional human-readable status description.

curl http://localhost:8000/api/system/health

Example response:

{
  "database": { "healthy": true },
  "guideService": { "healthy": true },
  "searchIndex": { "healthy": true }
}

Server Version

Returns version information for Tunarr, FFmpeg, and Node.js.

GET /api/version

Response 200 — version object:

tunarr

string

Tunarr application version (e.g. "1.2.0").

ffmpeg

string

Version string of the FFmpeg binary Tunarr is configured to use.

nodejs

string

Node.js runtime version.

curl http://localhost:8000/api/version

System State

Returns runtime environment flags—useful for detecting whether Tunarr is running inside a container.

GET /api/system/state

Response 200:

isDocker

boolean

true when Tunarr is running inside a Docker container.

isPodman

boolean

true when running inside Podman.

isInContainer

boolean

true when running in any OCI container runtime.

curl http://localhost:8000/api/system/state

System Settings

Get System Settings

Returns the current system-wide configuration including logging, backup schedule, caching, and server options.

GET /api/system/settings

Response 200 — SystemSettingsResponse:

logging.logLevel

string

Active log level: trace | debug | info | warn | error.

logging.useEnvVarLevel

boolean

When true, the log level is determined by the LOG_LEVEL environment variable.

logging.logsDirectory

string

Path on disk where log files are written.

backup

object

Backup schedule and retention settings.

cache

object

Caching configuration.

dataDirectory

string

Absolute path to the Tunarr data/database directory.

searchServerAddress

string

Internal URL of the Meilisearch instance used for program search.

curl http://localhost:8000/api/system/settings

Update System Settings

Updates one or more system settings. Omitted fields retain their current values.

PUT /api/system/settings

logging

object

Logging configuration:

logLevel (string) — trace | debug | info | warn | error
useEnvVarLevel (boolean) — override level from LOG_LEVEL env var
categoryLogLevel.scheduling (string) — per-category level for scheduling
categoryLogLevel.streaming (string) — per-category level for streaming

backup

object

Backup schedule configuration (same shape as BackupSettings).

cache

object

Cache settings.

server

object

Server settings (e.g. bind address, port).

Response 200 — the updated SystemSettingsResponse.

curl -X PUT http://localhost:8000/api/system/settings \
  -H "Content-Type: application/json" \
  -d '{
    "logging": {
      "useEnvVarLevel": false,
      "logLevel": "debug"
    }
  }'

Update Backup Settings

Updates only the backup-related portion of system settings.

PUT /api/system/settings/backup

enabled

boolean

Enable or disable automated backups.

schedule

string

Cron expression for the backup schedule (e.g. "0 3 * * *" for 3 AM daily).

maxBackups

integer

Maximum number of backup archives to retain before pruning old ones.

FFmpeg Settings

Get FFmpeg Settings

Returns the current FFmpeg transcoding configuration used as the global default.

GET /api/ffmpeg-settings

Response 200 — FfmpegSettings object.

ffmpegExecutablePath

string

Absolute path to the ffmpeg binary.

ffprobeExecutablePath

string

Absolute path to the ffprobe binary.

enableSubtitleExtraction

boolean

Whether Tunarr extracts embedded subtitles for burn-in.

curl http://localhost:8000/api/ffmpeg-settings

Update FFmpeg Settings

Replaces the global FFmpeg configuration.

PUT /api/ffmpeg-settings

Request body — FfmpegSettings object. All fields present in the body replace the stored values. Response 200 — the updated FfmpegSettings. Response 500 — update failed.

curl -X PUT http://localhost:8000/api/ffmpeg-settings \
  -H "Content-Type: application/json" \
  -d '{
    "ffmpegExecutablePath": "/usr/bin/ffmpeg",
    "ffprobeExecutablePath": "/usr/bin/ffprobe",
    "enableSubtitleExtraction": true
  }'

Reset FFmpeg Settings

Resets FFmpeg configuration to built-in defaults while preserving the specified executable path.

POST /api/ffmpeg-settings

ffmpegPath

string

required

Path to the ffmpeg binary to use after reset.

Response 200 — the reset FfmpegSettings.

Background Tasks

Tunarr runs a number of recurring background tasks—updating the EPG, scanning libraries, extracting subtitles, and more. The Tasks API lets you inspect the task registry and trigger any task on demand.

List Tasks

Returns all registered tasks along with their scheduled execution metadata.

GET /api/tasks

Response 200 — array of Task objects.

string

Task identifier (also used as the path parameter for triggering).

name

string

Human-readable task name.

description

string

Description of what the task does.

scheduledTasks

array

Active schedule entries for this task, each with:

running (boolean) — currently executing
lastExecution (string) — ISO 8601 datetime of last run
lastExecutionEpoch (number) — epoch seconds of last run
nextExecution (string) — ISO 8601 datetime of next scheduled run
nextExecutionEpoch (number) — epoch seconds of next run

curl http://localhost:8000/api/tasks

Run a Task

Triggers a task to run immediately. By default the task runs in the background and the endpoint returns immediately with 202 Accepted. Set background=false to wait for the result.

POST /api/tasks/:id/run

string

required

Task ID (from the id field in List Tasks). Common task IDs:

UpdateXmlTvTask — regenerates the XMLTV EPG file
BackupTask — creates a database backup
CleanupTask — removes orphaned data
SubtitleExtractorTask — extracts embedded subtitle tracks

background

boolean

When true (default), run the task asynchronously and return 202. When false, wait for completion and return 200 with the task result.

Request body — optional task-specific arguments object (varies by task; send {} or omit for tasks with no arguments). Response 202 — task started in background. Response 200 — task completed (only when background=false), response contains task output. Response 400 — invalid task arguments. Response 404 — task ID not found.

# Trigger an XMLTV update in the background
curl -X POST http://localhost:8000/api/tasks/UpdateXmlTvTask/run

# Trigger a backup and wait for it to finish
curl -X POST "http://localhost:8000/api/tasks/BackupTask/run?background=false"

Feature Flags

Tunarr ships with experimental and configurable feature flags that can be toggled without a restart.

Get Feature Flags

Returns the current state of all feature flags plus metadata.

GET /api/system/feature-flags

Response 200 — GetFeatureFlagsResponse:

flags

object

Map of flag key → boolean value.

metadata

array

Descriptor for each flag: key, displayName, description, category, and envOverride (whether an environment variable forces this flag’s value).

curl http://localhost:8000/api/system/feature-flags

Update Feature Flags

Overrides one or more feature flag values.

PUT /api/system/feature-flags

Request body — partial map of flag key → boolean. Only the keys present in the body are changed. Response 200 — updated GetFeatureFlagsResponse.

curl -X PUT http://localhost:8000/api/system/feature-flags \
  -H "Content-Type: application/json" \
  -d '{ "proxyArtwork": true }'

Media Source Settings

Global settings that apply to all media source integrations (e.g. rescan interval).

Get Media Source Settings

GET /api/settings/media-source

Response 200 — GlobalMediaSourceSettings:

rescanIntervalHours

number

How often Tunarr automatically rescans all enabled libraries, in hours. Default 6.

curl http://localhost:8000/api/settings/media-source

Update Media Source Settings

PUT /api/settings/media-source

rescanIntervalHours

number

New rescan interval in hours (minimum 0).

Response 200 — updated GlobalMediaSourceSettings.

curl -X PUT http://localhost:8000/api/settings/media-source \
  -H "Content-Type: application/json" \
  -d '{ "rescanIntervalHours": 12 }'

FFmpeg Hardware Info

Returns the audio encoders, video encoders, and hardware acceleration types that the configured FFmpeg binary supports. Useful for determining which transcode settings are available on the host system.

GET /api/ffmpeg-info

Response 200:

audioEncoders

array

List of supported audio encoders: { name, ffmpegName }.

videoEncoders

array

List of supported video encoders: { name, ffmpegName }.

hardwareAccelerationTypes

array

Hardware acceleration modes available: e.g. ["cuda", "vaapi", "videotoolbox"].

curl http://localhost:8000/api/ffmpeg-info

Log Access

Stream Logs (SSE)

Opens a Server-Sent Events stream that tails the live Tunarr log file. Connect with an SSE client to receive log entries in real time.

GET /api/system/debug/logs

pretty

boolean

Format log output as human-readable text instead of raw JSON. Default false.

download

boolean

Return the log file as a downloadable attachment instead of a stream.

lineLimit

integer

When download=true, limit output to the last N lines.

Response — text/event-stream (SSE) when not downloading, text/plain attachment when download=true.

# Download the last 500 lines of logs
curl "http://localhost:8000/api/system/debug/logs?download=true&lineLimit=500" -o tunarr.log

Overview

Endpoints

System API: Tasks, Backups, and Server Health Endpoints

Health Check

Server Version

System State

System Settings

Get System Settings

Update System Settings

Update Backup Settings

FFmpeg Settings

Get FFmpeg Settings

Update FFmpeg Settings

Reset FFmpeg Settings

Background Tasks

List Tasks

Run a Task

Feature Flags

Get Feature Flags

Update Feature Flags

Media Source Settings

Get Media Source Settings

Update Media Source Settings

FFmpeg Hardware Info

Log Access

Stream Logs (SSE)

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Health Check

​Server Version

​System State

​System Settings

​Get System Settings

​Update System Settings

​Update Backup Settings

​FFmpeg Settings

​Get FFmpeg Settings

​Update FFmpeg Settings

​Reset FFmpeg Settings

​Background Tasks

​List Tasks

​Run a Task

​Feature Flags

​Get Feature Flags

​Update Feature Flags

​Media Source Settings

​Get Media Source Settings

​Update Media Source Settings

​FFmpeg Hardware Info

​Log Access

​Stream Logs (SSE)

Build docs developers (and LLMs) love

Health Check

Server Version

System State

System Settings

Get System Settings

Update System Settings

Update Backup Settings

FFmpeg Settings

Get FFmpeg Settings

Update FFmpeg Settings

Reset FFmpeg Settings

Background Tasks

List Tasks

Run a Task

Feature Flags

Get Feature Flags

Update Feature Flags

Media Source Settings

Get Media Source Settings

Update Media Source Settings

FFmpeg Hardware Info

Log Access

Stream Logs (SSE)