BingeBop

Returns the complete API catalog as structured JSON — endpoints, parameters, workflows, and settings reference. This is the recommended entry point for AI agents and automation tools.

Returns the current playback state: what's playing, codec, resolution, stream position, device UUID, etc. Returns {"error":"No player active"} with HTTP 404 when nothing is playing.

Search the catalog by name. Returns channels, movies, series, and EPG programmes.

Response

{
  "q": "BBC",
  "elapsed_ms": 12,
  "count": 5,
  "results": [
    {
      "type": "media",
      "id": 4521,
      "media": "c",
      "name": "BBC One HD",
      "poster": "http://...",
      "channel_id": "bbc1.uk"
    }
  ]
}

Returns the device's hardware tier (FLOOR / LOW / MID / HIGH), capability manifest, and current provisioned settings.

Add a new IPTV data source. Supports four provider types. Parameters can be sent as query string or form body.

Example

# Xtream Codes provider (recommended: header auth + form body)
curl -X POST -H "X-Api-Token: AB3KQ7M2X9V4" \
  "http://tv:18080/api/data_source" \
  -d "type=xtream&url=http://provider.com:8080&username=myuser&password=mypass&name=My+IPTV"

# M3U playlist
curl -X POST -H "X-Api-Token: AB3KQ7M2X9V4" \
  "http://tv:18080/api/data_source" \
  -d "type=m3u&url=http://example.com/channels.m3u"

# Query params also accepted (discouraged — credentials visible in logs)
curl -X POST "http://tv:18080/api/data_source?type=m3u&url=http://example.com/channels.m3u&token=AB3KQ7M2X9V4"

Response

{"success":true, "id":3, "type":"xtream", "name":"My IPTV", "refresh":"started"}

The source starts importing immediately. Poll /api/data_sources to check progress.

Remove a data source and all its channels, credentials, and MACs.

curl -X DELETE -H "X-Api-Token: AB3KQ7M2X9V4" "http://tv:18080/api/data_source?id=3"

List all configured data sources with their type, URL, EPG priority, refresh status, and (for Xtream) account info (username, expiry date, max connections, active connections).

Trigger a channel re-import for a single data source.

Change a source's base URL (e.g. migrate to a mirror host). Cluster-synced.

Set the country (ISO code) for a data source, used for channel-name normalization.

Set the EPG priority for a data source (lower number = higher priority when multiple sources provide guide data).

Play a stream URL directly.

curl -H "X-Api-Token: ABCD" "http://tv:18080/api/play?url=http://stream.example.com/live.ts&play=true"

Tune to a channel by its catalog ID. Use /api/search to find the ID.

Play a movie by catalog ID through the full StreamRouter path (source selection, failover).

Play a series episode by catalog ID.

Pause playback.

Resume playback.

Jump back to the live edge (exits timeshift).

Seek forward in the current stream.

Seek backward in the current stream.

Change playback speed.

Adjust the audio-video synchronization offset.

Stop a specific stream slot.

List all supported display modes with id, width, height, refreshRate, and active flag.

Switch to a specific display mode.

Set the compositor layout for multi-stream viewing.

Set which stream slot has focus in PIP mode.

List audio tracks for the current stream. Returns trackIndex, language, label, mimeType, channels, bitrate, isSelected.

Select an audio track.

Returns the currently selected audio track, or null.

List subtitle tracks for the current stream. Returns trackIndex, language, label, mimeType, isSelected.

Select a subtitle track.

List available OCR languages and their download status.

Download OCR tessdata for a language.

Add or remove a channel from the user's favourites.

Add or remove a VOD title from the user's watchlist ("My List").

Set a custom display name for a channel (user override — does not change the source data).

List all user profiles with their IDs, names, and child flags. Also returns active_user_id.

Create a new user profile.

curl -H "X-Api-Token: AB3KQ7M2X9V4" "http://tv:18080/api/user/add?name=Kids&child=true"
→ {"success":true, "id":2, "uuid":"a1b2c3...", "name":"Kids", "child":true}

Switch the active user profile. Returns 404 if the user ID doesn't exist.

Start recording the currently-playing channel.

Stop a recording.

List all recordings with their UUIDs, titles, durations, and status.

Play back a recording.

Delete a recording.

Create, list, or cancel scheduled recordings.

Set, list, or cancel reminders for upcoming programmes.

Trigger an urgent EPG guide data refresh. EPG also refreshes automatically every few hours.

Pin a channel to a specific EPG source (overrides automatic matching).

Remove an EPG pin (revert to automatic matching).

Check EPG pin status for a channel — returns active pin, persisted pin, and total pin count.

Get all settings and their current values for the active user. Returns user_id and a settings object.

Read or write a single setting.

# Read a setting
curl -H "X-Api-Token: AB3KQ7M2X9V4" "http://tv:18080/api/setting?key=local:scaling_method"
→ {"key":"local:scaling_method", "value":"0"}

# Write a setting
curl -H "X-Api-Token: AB3KQ7M2X9V4" "http://tv:18080/api/setting?key=local:scaling_method&value=2"
→ {"success":true, "key":"local:scaling_method", "value":"2"}

Read or write a device-global (local:) setting, always stored under user 0. Use this instead of /api/setting for device-level config that shouldn't vary per user.

Apply (or re-apply) the per-tier device manifest into settings. With ?force=true, re-seeds all tier defaults.

Test a Samba/NAS storage connection without changing any settings.

Response

{"success":true, "message":"Connected successfully"}
{"success":false, "message":"Connection timed out"}

List available filesystem roots (local storage, USB, Samba shares).

List files and directories at a given path.

Create an encrypted backup ZIP containing all settings, data sources, and credentials.

Response

{"ok":true, "path":"/data/.../bingebop-backup.zip", "bytes":524288, "tables":12, "encryption":"aes256"}

Decrypt and validate a backup file without applying it. Use this to check a backup before restoring.

Apply a backup and restart the app. This is destructive — it replaces the entire database.

Returns the current cluster state: cluster ID/name, this device's UUID, list of paired peers, and discoverable clusters on the network.

Request to join a discovered cluster. The cluster owner must approve.

List pending join requests on this device.

Approve a pending join request.

Send a remote-control key press. Injects real Android KeyEvents — the native focus system handles navigation exactly like a physical remote.

Valid Keys

up, down, left, right, select, back, menu, enter, backspace, space, channel_up, channel_down, play_pause, a–z, 0–9, text

# Navigate down and select
curl -H "X-Api-Token: ABCD" "http://tv:18080/api/input?key=down"
curl -H "X-Api-Token: ABCD" "http://tv:18080/api/input?key=select"

# Type text into a focused field
curl -H "X-Api-Token: ABCD" "http://tv:18080/api/input?key=text&value=hello+world"

# Long press on a channel row
curl -H "X-Api-Token: ABCD" "http://tv:18080/api/input?key=select&long_press=true"

Read-back of the currently-focused text field. Returns the field name and current value. Sensitive fields (passwords) report active:true but withhold the value.

Navigate directly to a UI screen by route path.

Set a text field's value by name (bypasses keyboard input).

Read the diagnostic event log — errors, channel changes, codec issues, imports, cluster events. Data is PII-scrubbed.

Run a full network-path diagnostic: device → router → internet → source → stream. Takes 10–30 seconds. Returns hop-by-hop results including bandwidth measurement and per-source probes. Use a generous HTTP timeout (≥ 120 s).