Live TV

The channels, and what is on them now and next

configured when a source with channels is switched on (the sidebar shows Live TV then). An account with an age limit gets canWatch: false and no channels: what a broadcast shows is nobody’s to vouch for. Each channel carries the programme on now and the next, from its guide channel, and the DVR’s recording of either.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

Put the channels in your own order

The channels given come first, in that order, in your channel list and the guide; every other comes after them, as everyone has them. An empty list puts them all back. 204.

Authorisation

Bearer token or API key · Session cookie

Body

application/json · object

• 204Done; no body.
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

Every channel, hidden ones too

With its guide match, auto or manual, for the admin’s list.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

Hide or show many channels at once

A group of a big playlist, say: {channelIds, isHidden}, up to 5,000. Answers how many were changed.

Authorisation

Bearer token or API key · Session cookie

Body

application/json · object

• 200Success. application/json · object
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

Hide a channel, or choose its guide channel

guide: null says it has none, and matching leaves it alone after; a guide channel chosen is kept until changed.

Authorisation

Bearer token or API key · Session cookie

Body

application/json · object

• 200Success. application/json · object
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. VALIDATION_FAILED: that guide has no such channel application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

Make a channel one of your favourites, or not

Your own: your favourites come first in your channel list and the guide, after any you placed yourself. 204.

Authorisation

Bearer token or API key · Session cookie

Body

application/json · object

• 204Done; no body.
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. NOT_FOUND: no such channel application/json · ErrorEnvelope

A channel’s logo, through this server

Its playlist’s logo, else its guide channel’s icon, fetched once and kept: from a public address, or the host the playlist came from. PNG, JPEG, WebP or GIF, never SVG.

Authorisation

Bearer token or API key · Session cookie

• 200Success. image/* ·
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

Watch a channel

A live HLS stream of the channel, joined if someone is watching it already, else started on a free tuner. Answers once its first segment is written (a few seconds). The playlist keeps the last half minute; a session nobody fetches anything of for 45 seconds is stopped.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. PERMISSION_AGE_RESTRICTED: the account has an age limit PERMISSION_TIME_RESTRICTED: outside the account’s viewing hours application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. NOT_FOUND: no such channel, or it is hidden or its source switched off application/json · ErrorEnvelope
• 502LIVE_TV_UNREACHABLE: the stream did not start application/json · ErrorEnvelope
• 503LIVE_TV_NO_TUNER: every tuner of the source is watching another channel or recording application/json · ErrorEnvelope

The DVR: recordings to come and made, and series recordings

With the libraries recordings are filed into (livetv.dvr_show_library, livetv.dvr_movie_library), and deletionAllowed: whether library.allow_media_deletion lets a rule delete what it lets go. A rule’s yours says whether the caller may change what it keeps. defaults (2026-10-11): the padding a new recording and rule start with, and whether a new rule replaces SD copies, as the DVR’s settings say.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

Record one airing

A programme on a channel shown, from the guide, padded as the DVR’s settings say (livetv.dvr_pad_before_min, livetv.dvr_pad_after_min: a minute before and three after) unless said. Recorded as the source sends it (or converted to H.264 with livetv.dvr_convert), run through the owner’s post-processing script when one is chosen, then filed into the library for recorded shows or films (Show/Season 01/Show - S01E02 - Name.ts), and that library given a quick scan when livetv.dvr_scan_after is on. One the tuners can’t take is conflict.

Authorisation

Bearer token or API key · Session cookie

Body

application/json · object

• 201Success. application/json · object
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: the programme is not in the guide any more application/json · ErrorEnvelope
• 409DVR_LIBRARY_REQUIRED: no library is chosen for recordings of its kind CONFLICT: that airing is already being recorded application/json · ErrorEnvelope

Remove a recording from the list

One that is over. Its file stays in the library, which is where it is deleted. 204.

Authorisation

Bearer token or API key · Session cookie

• 204Done; no body.
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
• 409CONFLICT: it is to come or under way: cancel it first application/json · ErrorEnvelope

Find a recording’s ad breaks

Looked for by hand in a recording filed in its library (each new one is looked at by itself only while livetv.dvr_find_ad_breaks is on, off by default): from where the picture goes black and the sound drops between spots, and the lengths spots have. One recording at a time, at low priority. What is found becomes ad markers on its library item while the recording is that item’s only file, which the player offers to skip; the file is never cut. 202.

Authorisation

Bearer token or API key · Session cookie

• 202Success. application/json · object
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. NOT_FOUND: no such recording application/json · ErrorEnvelope
• 409CONFLICT: it isn’t filed in a library yet application/json · ErrorEnvelope

Cancel a recording, or stop one under way

One to come is cancelled; one under way stops now, and what was recorded is filed.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
• 409CONFLICT: it is over application/json · ErrorEnvelope

Watch a recording while it is made

From its start, as far as it has got: an HLS playlist that keeps every segment and grows while it records, then closes. Held as watching a channel is: no age limit, the viewing hours, the account’s streams at once. One stream a recording, however many watch it.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. PERMISSION_AGE_RESTRICTED: the account has an age limit PERMISSION_TIME_RESTRICTED: outside the account’s viewing hours application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. NOT_FOUND: no such recording, or its channel is hidden or switched off application/json · ErrorEnvelope
• 409CONFLICT: it isn’t being recorded now application/json · ErrorEnvelope
• 429STREAM_LIMIT_REACHED: the account is at its streams at once application/json · ErrorEnvelope

Record every airing of a title, or of anything with certain words

On one channel or any, new episodes only (the default) or all, each episode once, the HD airing chosen where the same episode is on several channels. kind: keyword (P7-10) records every programme whose title (with searchDescription, its episode name and description too) has the words: phrases apart by commas, a quoted phrase as written, a word after a minus ruling a programme out; at most 50 of its recordings are to come at once. What it keeps: keepNewest, removeWatchedAfterDays, replaceLowerResolution; nothing is deleted while library.allow_media_deletion is off. Scheduled from the guide at once, and again each time a guide is read.

Authorisation

Bearer token or API key · Session cookie

Body

application/json · object

• 201Success. application/json · object
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 409DVR_LIBRARY_REQUIRED: no library is chosen for recorded shows application/json · ErrorEnvelope

Change what a series recording records and keeps

New episodes only or all, a keyword rule’s searching of descriptions, padding, and what it keeps: the newest keepNewest only, removeWatchedAfterDays after its person watched one, an SD copy let go once the episode is recorded whole in HD and a scan has made the HD copy’s item, surely the same episode (the guide’s id, season and episode, or a film’s year: never its name alone), what was watched of it carried over (replaceLowerResolution). Only whoever made the rule changes what it keeps. What it keeps is seen to at once, and only while library.allow_media_deletion is on: a recording let go has its file deleted, and its library item put in the library’s trash unless the item has another file.

Authorisation

Bearer token or API key · Session cookie

Body

application/json · object

• 200Success. application/json · object
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. FORBIDDEN: what it keeps is changed by someone other than who made it application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. NOT_FOUND: no such series recording application/json · ErrorEnvelope

Stop a series recording

The rule goes, with the recordings it scheduled that are still to come. 204.

Authorisation

Bearer token or API key · Session cookie

• 204Done; no body.
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

What a rule would record

From the guide as it is now, before the rule is made: a title’s airings, or a keyword rule’s matches, one of each episode (the HD airing first), at most 60.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

The post-processing scripts to choose from

The files in the server’s scripts folder (<config>/scripts, 2026-10-11), each with why it can’t be chosen as livetv.dvr_postprocess_script when it can’t (problem): it must have a plain name, be a regular file, and sit directly in the folder (a link leading out of it is refused). settings:manage.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

Stop watching a recording

The stream stops once nobody is watching it. 204.

Authorisation

Bearer token or API key · Session cookie

• 204Done; no body.
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

A recording’s playlist or segment, while it is made

index.m3u8 (never cached), or a segNNNNN.ts segment it lists.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/vnd.apple.mpegurl ·
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
• 410TRANSCODE_SESSION_GONE: the stream has stopped application/json · ErrorEnvelope

The guide’s grid

Every channel’s programmes that overlap from (the half hour before now, unless given) and the hours after it (6 unless given, at most 24).

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. PERMISSION_AGE_RESTRICTED: the account has an age limit application/json · ErrorEnvelope

A guide’s channels, to match one to

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

The XMLTV guides

Each says whether it is being read now (reading).

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

Add an XMLTV guide

An http(s) address or a file on the server, gzip or not, read at once (a big one takes a minute) and after that as often as livetv.guide_refresh_hours says (twelve hours), or only when asked with livetv.guide_refresh off: a fortnight ahead is kept. Channels are matched by the playlist’s guide id, else the number, else the name. A guide of more than 800 channels keeps only the programmes of matched channels. Not kept if its first read fails.

Authorisation

Bearer token or API key · Session cookie

Body

application/json · object

• 201Success. application/json · object
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. VALIDATION_FAILED: it is not an XMLTV guide application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 409CONFLICT: that guide is already added application/json · ErrorEnvelope
• 413PAYLOAD_TOO_LARGE: it is over 800 MB application/json · ErrorEnvelope
• 502LIVE_TV_UNREACHABLE: the address did not answer application/json · ErrorEnvelope

Rename or switch off a guide, or give a Schedules Direct account’s new password

A new password is tried with Schedules Direct before it is kept, and only its SHA-1 is kept, sealed.

Authorisation

Bearer token or API key · Session cookie

Body

application/json · object

• 200Success. application/json · object
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. VALIDATION_FAILED: Schedules Direct refused the password application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

Remove a guide

Its programmes go with it; channels matched to it have none until matched to another. 204.

Authorisation

Bearer token or API key · Session cookie

• 204Done; no body.
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

Read a guide again

As happens by itself every livetv.guide_refresh_hours while livetv.guide_refresh is on; series recordings then see what is new in it.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
• 502LIVE_TV_UNREACHABLE: the address did not answer application/json · ErrorEnvelope

A Schedules Direct account as the service says it now

When it runs out, how many lineups it may have, the lineups it has, and whether the service is up.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
• 502PROVIDER_UNAVAILABLE: Schedules Direct refused the account or Collectoh application/json · ErrorEnvelope

The lineups to be had in a place

By country (ISO 3166-1 alpha-3: USA, GBR) and postal code: an aerial’s, and each provider’s.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

Add a lineup to the Schedules Direct account

The service allows an account a few lineups (four, unless it says otherwise) and six changes a day. The guide is read again for it.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. NOT_FOUND: Schedules Direct has no such lineup application/json · ErrorEnvelope
• 409CONFLICT: it is on the account already, or the account is at its limit application/json · ErrorEnvelope

Take a lineup off the Schedules Direct account

A change, as adding one is. The guide is read again without it.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. NOT_FOUND: it isn’t on the account application/json · ErrorEnvelope

Read every guide again now

Every guide switched on, one after another, in the background (2026-10-11); the guides as they are, each saying reading until its turn is over. Series recordings then see what is new.

Authorisation

Bearer token or API key · Session cookie

• 202Success. application/json · object
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

Add your own Schedules Direct account as a guide

Your own account (schedulesdirect.org): Collectoh licenses no guide data. Signed in to before it is kept; only the SHA-1 of the password, which is all the service takes, is kept, sealed. Its lineups’ channels are matched to yours as an XMLTV guide’s are, and a fortnight is read, fetching only what changed since. When the service refuses the account, or Collectoh itself (it chooses which apps it serves), the guide says so.

Authorisation

Bearer token or API key · Session cookie

Body

application/json · object

• 201Success. application/json · object
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. VALIDATION_FAILED: Schedules Direct didn’t accept the username and password application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 409CONFLICT: that account is added already application/json · ErrorEnvelope
• 502PROVIDER_UNAVAILABLE: Schedules Direct refused the account or Collectoh, or is down application/json · ErrorEnvelope

Search the guide by title

Programmes still to end whose title has the words, soonest first, at most 60.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. PERMISSION_AGE_RESTRICTED: the account has an age limit application/json · ErrorEnvelope

A programme’s picture, through this server

Its guide’s picture of it, for a programme of a channel shown from a source switched on: an XMLTV guide’s from a public address, or Schedules Direct’s, asked for when first wanted (the account has so many pictures a day, and none are asked for while the service asks to be left). Kept under a cap, the least lately shown let go first; one that can’t be had isn’t asked for again for an hour. PNG, JPEG, WebP or GIF.

Authorisation

Bearer token or API key · Session cookie

• 200Success. image/* ·
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. NOT_FOUND: it has no picture, or it can’t be had just now application/json · ErrorEnvelope

Stop watching

The caller is done; the stream stops, and its tuner is free, once nobody is watching. 204.

Authorisation

Bearer token or API key · Session cookie

• 204Done; no body.
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

A live stream’s playlist or segment

live.m3u8 (never cached), or a segNNNNN.ts MPEG-TS segment it lists. For the stream’s viewers, and whoever may manage sessions.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/vnd.apple.mpegurl ·
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
• 410TRANSCODE_SESSION_GONE: the stream has stopped application/json · ErrorEnvelope

The tuners and playlists

A playlist’s address is shown as its host or file name only: it can hold an IPTV provider’s sign-in.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

Add a tuner or a playlist

An HDHomeRun by its address on the home network (it says what it is at /discover.json; copy-protected channels are left out), an M3U playlist at an http(s) address or a file on the server, read before it is kept, or a country’s free channels ({kind: 'free', country}): the iptv-org project’s playlist for it, kept as a playlist, never with adult channels. Its channels are matched to the guides already added, and the guides are read again for them.

Authorisation

Bearer token or API key · Session cookie

Body

application/json ·

• 201Success. application/json · object
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. VALIDATION_FAILED: the playlist has no channels, or the address is neither http(s) nor a full path application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 409CONFLICT: that tuner, or that country’s free channels, is already added application/json · ErrorEnvelope
• 502LIVE_TV_UNREACHABLE: nothing at the address answered as a tuner, or the playlist could not be read application/json · ErrorEnvelope

Rename, switch off, or set how many tuners a source has

And an HDHomeRun EXTEND’s own transcode profile (transcode, 2026-10-11): what its stream addresses ask for as ?transcode=; original sends the broadcast as it is. A source that can’t convert (transcode: null on it) is refused one.

Authorisation

Bearer token or API key · Session cookie

Body

application/json · object

• 200Success. application/json · object
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. VALIDATION_FAILED: a transcode profile for a source that can’t convert application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

Remove a source

Its channels go with it, and anyone watching one is stopped. Recordings made from them stay. 204.

Authorisation

Bearer token or API key · Session cookie

• 204Done; no body.
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

Read a source’s channels again

As happens every day by itself. Channels it no longer lists are removed; an admin’s hiding and guide choices are kept.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
• 409CONFLICT: the tuner is scanning for channels (2026-10-11) application/json · ErrorEnvelope
• 502LIVE_TV_UNREACHABLE: the tuner or playlist did not answer application/json · ErrorEnvelope

An HDHomeRun’s channel scan, as the tuner says it

From the tuner’s lineup_status.json (2026-10-11): under way with how far it has got and what it has found, or not, with the signal sources it can scan (Antenna, Cable) and whether it can now.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 400VALIDATION_FAILED: the source is not an HDHomeRun application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
• 502LIVE_TV_UNREACHABLE: the tuner did not answer application/json · ErrorEnvelope

Start an HDHomeRun’s channel scan

Of the signal source given ({source: 'Antenna'}) or the tuner’s own, through its own HTTP API (lineup.post?scan=start). Refused while the tuner records or is watched, or a recording on it is due within half an hour; until the scan is done nothing plays from it, a recording that comes due waits, and its channels aren't read. The server follows the scan, and reads the tuner’s channels again once it says it is done. 202.

Authorisation

Bearer token or API key · Session cookie

Body

application/json · object

• 202Success. application/json · object
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. VALIDATION_FAILED: not an HDHomeRun, or a signal source the tuner hasn’t application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
• 409CONFLICT: the tuner is in use, a recording is due, or it says it can’t scan now application/json · ErrorEnvelope
• 502LIVE_TV_UNREACHABLE: the tuner did not answer, or did not start the scan application/json · ErrorEnvelope