Guide API Recording Rules

Introduction:

A Series recording rule will record every unique episode that matches the given criteria within a TV series. The rule does not expire. Only one Series rule can exist per TV series.

A one-time recording rule (DateTimeOnly+ChannelOnly recording rule) will record a single airing of the specified TV series at the specified date/time and on the specified channel. The rule will automatically expire once the time has passed even if it did not result in a recording. Multiple unique one-time recording rules can exist for the same series.

API URL:

GET|POST https://api.hdhomerun.com/api/recording_rules

List recording rules:

GET https://api.hdhomerun.com/api/recording_rules

Parameter	Type	Description
DeviceAuth	string	Concatenation of the DeviceAuth strings from all HDHomeRun tuners.

Returns: Details all matching recording rules, or "null" if no matching rules exist. Results are ordered DateTimeOnly first, then by priority highest first.

Add/modify a series recording rule:

POST https://api.hdhomerun.com/api/recording_rules

Parameter	Type	Description
DeviceAuth	string	Concatenation of the DeviceAuth strings from all HDHomeRun tuners.
Cmd	string	"add"
SeriesID	string	SeriesID identifying the series or movie to record.
ChannelOnly	string	Optional. Pipe separated list of virtual channel numbers - record only on the specified channels.
TeamOnly	string	Optional. Pipe separated list of team names - record only if one of the specified teams is playing.
RecentOnly	bool	Optional. Record only recent episodes (default 0).
AfterOriginalAirdateOnly	int64	Optional. Record only if the original airdate is the same or after (UTC unixtime).
StartPadding	uint	Optional. Start recording early (seconds, default 30s, max 1h).
EndPadding	uint	Optional. Continue recording past end (seconds, default 30s, max 3h).

Returns: Details of all recording rules.

Add/modify a one-time recording rule:

POST https://api.hdhomerun.com/api/recording_rules

Parameter	Type	Description
DeviceAuth	string	Concatenation of the DeviceAuth strings from all HDHomeRun tuners.
Cmd	string	"add"
SeriesID	string	SeriesID identifying the series or movie to record.
DateTimeOnly	int64	Record only the airing that starts at this time (UTC unixtime).
ChannelOnly	string	Record only the airing on this virtual channel number.
StartPadding	uint	Optional. Start recording early (seconds, default 30s, max 1h).
EndPadding	uint	Optional. Continue recording past end (seconds, default 30s, max 3h).

Both DateTimeOnly and ChannelOnly are required. ChannelOnly must be a single channel number.

Returns: Details of all recording rules.

Change the priority of a recording rule:

POST https://api.hdhomerun.com/api/recording_rules

Parameter	Type	Description
DeviceAuth	string	Concatenation of the DeviceAuth strings from all HDHomeRun tuners.
Cmd	string	"change"
RecordingRuleID	string	ID identifying the rule to modify.
AfterRecordingRuleID	string	The new priority of the rule by specifying which rule it should be directly after, or 0 to make the highest priority.

Priority applies to Series and Movie rules only. DateTimeOnly-ChannelOnly rules are always highest priority.

Returns: Details of all recording rules.

Delete a recording rule:

POST https://api.hdhomerun.com/api/recording_rules

Parameter	Type	Description
DeviceAuth	string	Concatenation of the DeviceAuth strings from all HDHomeRun tuners.
Cmd	string	"delete"
RecordingRuleID	string	ID identifying the rule to delete.

Returns: Details of all recording rules.

Result format:

[
    {
        "RecordingRuleID": "403922",
        "SeriesID": "11579711",
        "Title": "Skyfall",
        "Synopsis": "With MI6 under attack, James Bond comes to M's rescue when her daunting past comes back to haunt her, forcing him to seek revenge and take down whoever gets in his way in an effort to find the dangerous assassin before its too late. (3.5/4.0)",
        "ImageURL": "http://my.hdhomerun.com/fyimediaservices/v_3_3_6_1/Program.svc/96/1579711/Primary",
        "ChannelOnly": "2.1|702",
        "AfterOriginalAirdateOnly": 1351209600,
        "TeamOnly": "England|Wales",
        "DateTimeOnly": 1455212160,
        "Priority": 1,
        "StartPadding": 30,
        "EndPadding": 30
    },
    {
        ...
    }
]

Additional Details:

Specifying AfterOriginalAirdateOnly will restrict recordings to first-airings and shows with an original airdate greater than or equal to the given date. A first-airing will match regardless of the original airdate - this ensures shows without per-episode information are recorded. Repeats without a known original airdate are not recorded.

Any time a recording rule is added, deleted, or modified the client is required to send a message to every local device with a StorageURL to tell it to recompute upcoming record tasks - see Recording Rule Sync.

History:

20250928:

• Minor improvements to the documentation.

20201024:

• API changes.

20160318:

• Add TeamOnly rules.
• Expand delete command.

20160218:

• Add command will update an existing rule if a collision occurs.
• The OriginalAirdate associated with the series no longer reported in the recording rule results.
• Results include all matching rules if a SeriesID is specified.

Copyright © 2016-2025 Silicondust USA Inc. <www.silicondust.com>.