Support Articles

Channels API

The Channels app exposes a simple HTTP API that you can reach on port 57000 of the IP address of your device.

Learn more about how you can use it below. Monitor what’s currently playing, integrate Channels into your home automation, or just make your family think there are ghosts.

Note

The Channels 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.

Discovery

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

API Clients

Use these API clients in your existing projects. They’re ready to roll. Let us know if you make one yourself.

  • rbchannels - Ruby client for talking directly to your Channels app.
  • pychannels - Python client for talking directly to your Channels app.

Data Model

Read below about the models that are used in the API responses.

The status model

The status model is the default response to all requests in the Channels API. It contains information about the current status of Channels.

Note: Properties with null values will be ommited from the response.

Properties

status string

The current playing status of Channels.

Options

  • playing

    Channels is currently playing something.

  • stopped

    Channels is currently stopped.

  • paused

    Channels is currently playing something, but it is paused..

muted boolean

Whether or not Channels is currently muted.

playback_time float

The playback position the currently playing content is at.

channel Channel

The channel that is currently being watched.

now_playing Content

The metadata item describing the currently playing content.

The channel model

The channel model contains the information about the current channel that is being watched in Channels.

Note: Properties with null values will be ommited from the response.

Properties

name string

The name of the channel.

number string

The channel number.

image_url string

The URL of the logo for the channel.

The content model

The content model contains all of the information about the current movie or show that’s being watched in Channels.

Note: Properties with null values will be ommited from the response.

Properties

title string

The title of the content.

episode_title string

The episode title of the content.

season_number string

The season number of the content.

episode_number string

The episode number of the content.

summary string

The summary of the content.

image_url string

The URL of the poster image for the content.

Endpoints

Read below about the various endpoints supported in the API.

GET /api/status

Get status

Returns the current status of Channels

Request
GET /api/status
curl http://192.168.1.3:57000/api/status
Response
{
  "status": "paused",
  "muted": false,
  "channel": {
    "number": "552",
    "name": "TBS HD",
    "image_url": "http://tmsimg.fancybits.co/h5/NowShowing/58515/s58515_h5_aa.png"
  },
  "now_playing": {
    "title": "Seinfeld",
    "episode_title": "The Truth",
    "season_number": 3,
    "episode_number": 2,
    "summary": "A woman (Valerie Mahaffey) wants to know why George doesn't want to see her."
    "image_url": "http://tmsimg.fancybits.co/a/p183875_b_h6_ab.jpg",
  }
}

        

GET /api/favorite_channels

Get status

List favorite channels in Channels

Request
GET /api/favorite_channels
curl http://192.168.1.3:57000/api/favorite_channels

POST /api/toggle_pip

Toggle Picture in Picture

Turn on/off Picture in Picture in Channels

Request
POST /api/toggle_pip
curl http://192.168.1.3:57000/api/toggle_pip

POST /api/toggle_mute

Toggle mute

Mute and unmute audio in Channels

Request
POST /api/toggle_mute
curl http://192.168.1.3:57000/api/toggle_mute

POST /api/toggle_cc

Toggle Closed Captions

Turn on/off Closed Captions in Channels

Request
POST /api/toggle_cc
curl http://192.168.1.3:57000/api/toggle_cc

POST /api/toggle_pause

Toggle Play/Pause

Toggle between Playing and Paused

Request
POST /api/toggle_pause
curl http://192.168.1.3:57000/api/toggle_pause

POST /api/toggle_record

Toggle Record

Start and stop recording of the currently playing item in Channels

Request
POST /api/toggle_record
curl http://192.168.1.3:57000/api/toggle_record

POST /api/channel_up

Channel Up

Change the channel by jumping to the next channel up

Request
POST /api/channel_up
curl http://192.168.1.3:57000/api/channel_up

POST /api/channel_down

Channel Down

Change the channel by jumping to the next channel down

Request
POST /api/channel_down
curl http://192.168.1.3:57000/api/channel_down

POST /api/pause

Pause

Pause playback in Channels

Request
POST /api/pause
curl http://192.168.1.3:57000/api/pause

POST /api/resume

Resume

Resume playback in Channels

Request
POST /api/resume
curl http://192.168.1.3:57000/api/resume

POST /api/stop

Stop

Stop playback in Channels

Request
POST /api/stop
curl http://192.168.1.3:57000/api/stop

POST /api/seek_forward

Seek Forward

Seek playback ahead the amount set it settings

Request
POST /api/seek_forward
curl http://192.168.1.3:57000/api/seek_forward

POST /api/seek_backward

Seek Backward

Seek playback backwards the amount set it settings

Request
POST /api/seek_backward
curl http://192.168.1.3:57000/api/seek_backward

POST /api/skip_forward

Skip Forward

Skip forward in the timeline to the next commercial marker

Request
POST /api/skip_forward
curl http://192.168.1.3:57000/api/skip_forward

POST /api/skip_backward

Skip Backward

Skip backward in the timeline to the previous commercial marker

Request
POST /api/skip_backward
curl http://192.168.1.3:57000/api/skip_backward

POST /api/seek/:seconds

Seek by seconds

Seek in timeline the amount of seconds passed in

Required Attributes

seconds integer

The amount of seconds to seek. Negative values will seek backwards.

Request
POST /api/seek/120
curl http://192.168.1.3:57000/api/seek/120

POST /api/play/channel/:channel_number

Play a channel

Play the channel corresponding to the channel number

Required Attributes

channel_number string

The channel number to start playing in channels

Request
POST /api/play/channel/512
curl http://192.168.1.3:57000/api/play/channel/512

POST /api/play/recording/:recording_id

Play a recording

Play the recording corresponding to the recording ID

Required Attributes

recording_id integer

The unique identifier of an episode, video, or movie

Request
POST /api/play/recording/5334
curl http://192.168.1.3:57000/api/play/recording/5334

POST /api/navigate/:section_name

Navigate to a section

Navigate to a main section of Channels by providing its name

Required Attributes

section_name string

The name of the section. This can be any section in the main navigation sidebar.

Request
POST /api/navigate/Library
curl http://192.168.1.3:57000/api/navigate/Library

POST /api/notify

Show a notification

Displays a notification in the top right corner when Channels is playing.

Required Attributes

title string

The title of the notification

message string

The main message of the notification

Optional Attributes

icon string

An icon to show in the notification. This should be in the format of "fa:icon-name" where icon-name is the name of the icon from the FontAwesome icon set.

Request
POST /api/notify -d '{"title": "Alert", "message": "Dad is home", "icon": "fa:door"}'
curl http://192.168.1.3:57000/api/notify -d '{"title": "Alert", "message": "Dad is home", "icon": "fa:door"}'