Appearance

API Overview ​

OmniLux exposes a REST API for the parts of the self-hosted server that external clients and household tools need most: authentication, catalog browsing, playback, Live TV, profile preferences, and error handling.

Start here ​

Auth

Get a bearer token first

Most integrations start with login and the standard Authorization header.

Library

Browse media and metadata

Use this surface for catalogs, dashboards, search, and media detail lookups.

Playback

Start playback and report progress

Use this surface for players, HLS consumers, and continue-watching flows.

Base URL ​

text
http://your-server:4000/api

All endpoints are prefixed with /api.

Authentication ​

Most endpoints require a bearer token:

http
Authorization: Bearer <token>

Use HTTPS whenever the server is reachable outside your local network, and keep tokens out of screenshots, logs, and shared example commands.

Response format ​

Successful responses return data directly. Error responses use a compact JSON structure:

json
{
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE"
}

See Errors for common error codes and general rate-limiting behavior.

Main surfaces ​

  • Authentication for login and bearer-token usage.
  • Library for catalogs, item details, metadata repair, scans, collections, and dashboard summaries.
  • Streaming and Live TV for playback, progress, guide data, and external-client exports.
  • Profile and Errors for user preferences and operational handling.

The runtime also publishes request, activity, discover, notification, plugin, system, and cloud-link route groups. Those surfaces are intentionally documented more selectively until the public integration contract needs full examples for each group.