Channels HTTP API

Hey everyone, we just released an update to Channels that adds an HTTP API to let you control and query the Channels app.

Full confession: it’s partially been there for a while, that’s how the Play To features work from iOS :stuck_out_tongue_closed_eyes:, but now it’s more fleshed out and publicly available and documented!

So now you can do things like pause, resume, or stop your video remotely from something else. Do you dabble in home automation? Now you can control Channels with it! Do you hate that streams don’t stop when your TV is turned off? Integrate Channels into your home automation and now you can. I’ve been doing this for months, heh. It’s great.

It’s important to know and remember that the API will be as available as the platform it’s running on allows. For tvOS this means only when Channels is open and active. For Android and Fire TV it will work if Channels is active or backgrounded, but only if it has been launched at least once.

The API is super simple and you can use it directly from CURL. All endpoints respond with the current status of Channels.


The Channels API advertises itself with Bonjour. You can search for all of the apps on your network with Bonjour using the _channels_app._tcp service name.


$ curl -X POST
  "status": "paused",
  "muted": false,
  "channel": {
    "number": "552",
    "name": "TBS HD",
    "image_url": ""
  "now_playing": {
    "season_number": 3,
    "title": "Seinfeld",
    "image_url": "",
    "episode_title": "The Truth",
    "episode_number": 2,
    "summary": "A woman (Valerie Mahaffey) wants to know why George doesn't want to see her."

It’s as simple as that!

Not only is it available, we whipped up a couple of API clients so you can integrate Channels with any of your projects even faster. There’s a Python package and Ruby gem ready to go.

If you’re a Home Assistant fan, you’ll be excited to hear that a Channels component has already been added to it and will be in the next official release. A Homebridge plugin will be available a little later if you’re a Homekit user.

You can learn more about the Channels API on our site. We hope you have fun with it!


So does this create the possibility of incorporating trakt?

In a way. It gives users a way to incorporate Trakt yourself, if that’s what you want to do.

You could poll the /api/status looking for what’s being currently watched, but you won’t have an easy way to know that it’s been completely watched and check it off in Trakt. But you could at least do check ins.

It will also be left off to the user to figure out how to map what’s currently playing to a show on Trakt. So yeah, you could do it, it’s an easier path than was there before, but it wouldn’t be super duper easy, and certainly isn’t turn key like Trakt being built in.

Gotcha, thank you

Looking forward to the homebridge plugin. I’ll have to spin up my QNAP LXC homebridge container again and take it for a spin. (@maddox Still miss all the stuff we could do with SiriProxy. I forked your pugme plugin to make picturejokes. It was fun while it lasted.)

1 Like

Hadn’t heard of Home Assistant before until this thread. I have Ikea TRÅDFRI lights and Tado heating as well as Channels so was keen to try it out. I’ve set it up in a Python venv on the same PC I have my DVR on. Works nicely so far but haven’t installed the Channels plugin yet.
I was wondering if I could use the Channels DVR DDNS address in the Home Assistant iPhone app? I’ve got my port forwarding g setup okay and a quick test with my WAN address works but it is dynamic so won’t stay working if my IP address changes.
How do I get the URL of my account’s DDNS?


Open and copy the browser url.

New HomeAssistant release is out today with support for the Channels API:

Thanks - works a treat

Does this work with iOS clients?

The API is only on the TV clients. If you have a use-case for iOS we would be interested in hearing it.

No use case. Just have my phone in front of me right now and no TV client ;). I was going to try to write some PowerShell cmdlets. I’ll wait until I get home to play.

Have you thought about creating a Swagger spec?

How do I find recording IDs? I assume I would need to query the DVR server for this. And available channels numbers and/or guide data?

Any plans to release API specs for the DVR server?

Oh, the possibilities!

HSo someone could create an Alexa skill and/or a SmartThings SmartApp to control Channels? Is it possible to identify multiple instances of channels running on a network by what ATV or what FTV it’s running on?

Cant wait for the homebridge plugin, this is awesome :slight_smile:


I tried using: curl -X POST

I getting: curl: (7) Failed to connect to port 57000: Connection refused is the IP of my QNAP NAS that is hosting the DVR.

What am I doing wrong?

This API is for the Channels app, not the DVR. You need to use the IP of your Apple TV or Android TV. The API only works if the app is running (and on tvOS it must be active on the screen).

1 Like

Also /api/status is a GET, so you can exclude -x POST.

I am a homebridge user so I looking forward for a plugin.

I have two Apple TV 4k’s so I am hoping that the plugin will support more than 1.

From a home kit perspective, I am not sure what I can do with it. Will homekit have status info and or controls?

For example, can I say “hey siri” channels fast forward with home kit.

Obviously, I would have remote capability…wish I could remotely control my apple tv and not just channels.

1 Like

Is there any reason you are not using home kit itself now security is software based and not hardware based?

Media players aren’t a native object type in HomeKit, so Apple would never approve it. We also don’t have any interest in going down the road of licensing and approval with Apple.

1 Like