openapi: 3.0.3
info:
title: Roku External Control Protocol (ECP)
version: '1.0'
description: |
The External Control Protocol (ECP) is an HTTP-based API exposed on port 8060 of every Roku
streaming device on the local network. It enables third-party applications, mobile remote-control
apps, automated testing systems, and home-automation hubs to discover Roku devices via SSDP,
inject simulated remote-control key presses, launch installed apps with deep-link parameters,
query device state, and retrieve diagnostic information.
The protocol is plain HTTP/1.1 (no TLS) and is intended for trusted local-network use only.
Most control operations require the user to enable "Control by mobile apps" on the device.
Additional diagnostic endpoints (chanperf, sgnodes, registry, etc.) are gated behind Roku
Developer Mode.
contact:
name: Roku Developer Program
url: https://developer.roku.com
x-generated-from: documentation
x-source-url: https://developer.roku.com/docs/developer-program/dev-tools/external-control-api.md
servers:
- url: http://{rokuDeviceIp}:8060
description: A Roku device on the local network
variables:
rokuDeviceIp:
default: 192.168.1.100
description: The IPv4 address of the Roku device, discovered via SSDP
tags:
- name: Discovery
description: Device discovery and metadata
- name: KeyPress
description: Simulated remote-control key injection
- name: Apps
description: Application listing, launching, and termination
- name: Query
description: Device, media, and TV state queries
- name: Diagnostics
description: Developer-mode diagnostics and performance counters
- name: Input
description: Custom input event injection
paths:
/:
get:
operationId: getDeviceRoot
summary: Roku Get Device Root
description: Returns the SSDP device description XML used for UPnP discovery.
tags: [Discovery]
responses:
'200':
description: Device description XML
content:
application/xml:
schema:
type: string
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/query/device-info:
get:
operationId: queryDeviceInfo
summary: Roku Query Device Info
description: Returns metadata about the Roku device including model, serial number, software version, network status, supported features, and user account state.
tags: [Query, Discovery]
responses:
'200':
description: Device info XML
content:
application/xml:
schema:
$ref: '#/components/schemas/DeviceInfo'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/query/apps:
get:
operationId: queryApps
summary: Roku Query Installed Apps
description: Returns the list of channels (apps) installed on the device with their app ID, name, version, and type.
tags: [Apps, Query]
responses:
'200':
description: Apps XML list
content:
application/xml:
schema:
$ref: '#/components/schemas/AppList'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/query/active-app:
get:
operationId: queryActiveApp
summary: Roku Query Active App
description: Returns the currently running app (or Roku home if no channel is active).
tags: [Apps, Query]
responses:
'200':
description: Active app XML
content:
application/xml:
schema:
$ref: '#/components/schemas/ActiveApp'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/query/icon/{appId}:
get:
operationId: queryAppIcon
summary: Roku Query App Icon
description: Returns the binary icon image for the given installed app.
tags: [Apps, Query]
parameters:
- name: appId
in: path
required: true
description: The Roku channel/app identifier
schema:
type: string
responses:
'200':
description: Icon image
content:
image/png:
schema:
type: string
format: binary
image/jpeg:
schema:
type: string
format: binary
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/query/media-player:
get:
operationId: queryMediaPlayer
summary: Roku Query Media Player
description: Returns the playback state, stream URI, current position, duration, and buffering metrics for the active video player.
tags: [Query]
responses:
'200':
description: Media player state XML
content:
application/xml:
schema:
$ref: '#/components/schemas/MediaPlayer'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/launch/{appId}:
post:
operationId: launchApp
summary: Roku Launch App
description: Launches the specified installed app. Optional `contentId` and `mediaType` query parameters provide deep-link parameters delivered to the app on launch.
tags: [Apps]
parameters:
- name: appId
in: path
required: true
description: The Roku channel/app identifier (or `dev` for the side-loaded developer channel)
schema:
type: string
- name: contentId
in: query
required: false
description: Deep-link content identifier passed to the app
schema:
type: string
- name: mediaType
in: query
required: false
description: Deep-link content type (movie, episode, season, series, shortFormVideo, tvEpisode, special, live)
schema:
type: string
enum: [movie, episode, season, series, shortFormVideo, tvEpisode, special, live]
responses:
'200':
description: App launched
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/install/{appId}:
post:
operationId: installApp
summary: Roku Install App
description: Opens the channel store details page for the specified app, prompting the user to install it.
tags: [Apps]
parameters:
- name: appId
in: path
required: true
description: The Roku channel/app identifier
schema:
type: string
responses:
'200':
description: Channel store details opened
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/exit-app/{appId}:
post:
operationId: exitApp
summary: Roku Exit App
description: Suspends or terminates the specified running app. Requires Roku OS 14.1 or later and "Control by mobile apps" enabled.
tags: [Apps]
parameters:
- name: appId
in: path
required: true
description: The Roku channel/app identifier
schema:
type: string
responses:
'200':
description: App exit requested
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/keypress/{key}:
post:
operationId: keyPress
summary: Roku Press Key
description: Simulates a momentary press-and-release of a remote-control key.
tags: [KeyPress]
parameters:
- name: key
in: path
required: true
description: Key name (e.g., Home, Up, Down, Left, Right, Select, Back, Play, Rev, Fwd, InstantReplay, Info, Backspace, Search, Enter, VolumeUp, VolumeDown, VolumeMute, PowerOff, ChannelUp,
ChannelDown, InputTuner, InputHDMI1, etc.) or `Lit_<urlencodedchar>` to send a literal text character.
schema:
type: string
responses:
'200':
description: Key press accepted
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/keydown/{key}:
post:
operationId: keyDown
summary: Roku Hold Key Down
description: Simulates pressing and holding a remote-control key. Must be paired with `/keyup/{key}` to release.
tags: [KeyPress]
parameters:
- name: key
in: path
required: true
description: Key name
schema:
type: string
responses:
'200':
description: Key down accepted
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/keyup/{key}:
post:
operationId: keyUp
summary: Roku Release Key
description: Releases a previously held key.
tags: [KeyPress]
parameters:
- name: key
in: path
required: true
description: Key name
schema:
type: string
responses:
'200':
description: Key release accepted
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/input:
post:
operationId: sendInput
summary: Roku Send Input Event
description: Sends a custom input event (key/value query parameters) to the active channel via the `roInput` SceneGraph node. Used for deep-linking, sensor data, and external control
integrations.
tags: [Input]
responses:
'200':
description: Input event delivered
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/search/browse:
post:
operationId: searchBrowse
summary: Roku Search Browse
description: Performs a Roku search across installed channels using query parameters such as keyword, title, season, type, provider-id, and launch.
tags: [Apps]
responses:
'200':
description: Search initiated
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/query/tv-channels:
get:
operationId: queryTvChannels
summary: Roku Query TV Channels
description: Returns the list of antenna or TV-input channels tuned on a Roku TV device.
tags: [Query]
responses:
'200':
description: TV channel list XML
content:
application/xml:
schema:
type: string
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/query/tv-active-channel:
get:
operationId: queryTvActiveChannel
summary: Roku Query Active TV Channel
description: Returns the currently tuned TV channel and signal information on a Roku TV device.
tags: [Query]
responses:
'200':
description: Active TV channel XML
content:
application/xml:
schema:
type: string
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/query/chanperf:
get:
operationId: queryChanPerf
summary: Roku Query Channel Performance
description: Returns CPU and memory utilization metrics for the foreground channel. Requires Roku Developer Mode.
tags: [Diagnostics]
responses:
'200':
description: Channel perf metrics XML
content:
application/xml:
schema:
type: string
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/query/r2d2-bitmaps:
get:
operationId: queryR2d2Bitmaps
summary: Roku Query R2D2 Bitmaps
description: Lists currently loaded texture/bitmap assets and their memory footprint. Requires Roku Developer Mode.
tags: [Diagnostics]
responses:
'200':
description: Bitmap inventory XML
content:
application/xml:
schema:
type: string
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/query/sgnodes/all:
get:
operationId: querySgNodesAll
summary: Roku Query SceneGraph Nodes
description: Enumerates all SceneGraph nodes currently allocated by the channel along with reference counts. Requires Roku Developer Mode.
tags: [Diagnostics]
responses:
'200':
description: SceneGraph node tree XML
content:
application/xml:
schema:
type: string
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/query/registry/{appId}:
get:
operationId: queryRegistry
summary: Roku Query Registry
description: Returns the persistent registry entries written by the specified channel. Requires Roku Developer Mode.
tags: [Diagnostics]
parameters:
- name: appId
in: path
required: true
description: The Roku channel identifier
schema:
type: string
responses:
'200':
description: Registry entries XML
content:
application/xml:
schema:
type: string
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/query/app-state/{appId}:
get:
operationId: queryAppState
summary: Roku Query App State
description: Returns whether the specified channel is currently active, in the background, or inactive.
tags: [Diagnostics, Query]
parameters:
- name: appId
in: path
required: true
description: The Roku channel identifier
schema:
type: string
responses:
'200':
description: App state XML
content:
application/xml:
schema:
type: string
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
DeviceInfo:
type: object
description: Roku device metadata returned as XML.
x-schema-source: documentation
properties:
udn:
type: string
description: Unique Device Name (UUID).
serialNumber:
type: string
description: Hardware serial number.
deviceId:
type: string
modelNumber:
type: string
description: Hardware model number (e.g., 4660X).
modelName:
type: string
description: Marketing model name (e.g., Roku Ultra).
friendlyDeviceName:
type: string
softwareVersion:
type: string
example: '12.5.0'
softwareBuild:
type: string
userDeviceName:
type: string
wifiMac:
type: string
ethernetMac:
type: string
networkType:
type: string
enum: [wifi, ethernet]
countryCode:
type: string
language:
type: string
timeZone:
type: string
powerMode:
type: string
enum: [PowerOn, DisplayOff, Headless, Ready]
supportsEcsTextedit:
type: boolean
supportsEcsMicrophone:
type: boolean
supportsWakeOnWlan:
type: boolean
developerEnabled:
type: boolean
AppList:
type: object
description: Container for the list of installed channels.
x-schema-source: documentation
properties:
apps:
type: array
items:
$ref: '#/components/schemas/App'
App:
type: object
description: An installed Roku channel.
x-schema-source: documentation
properties:
id:
type: string
description: The Roku channel/app identifier.
example: '12'
type:
type: string
enum: [appl, menu, tvin]
description: appl = installed channel, menu = system menu, tvin = TV input.
version:
type: string
subtype:
type: string
name:
type: string
description: Human-readable channel name.
ActiveApp:
type: object
description: Currently active app or screensaver/home if none.
x-schema-source: documentation
properties:
app:
$ref: '#/components/schemas/App'
screensaver:
$ref: '#/components/schemas/App'
MediaPlayer:
type: object
description: State of the active video player.
x-schema-source: documentation
properties:
state:
type: string
enum: [none, buffer, play, pause, stop, error, finished, startup, open]
error:
type: boolean
plugin:
type: object
properties:
id:
type: string
name:
type: string
format:
type: object
properties:
audio:
type: string
captions:
type: string
container:
type: string
drm:
type: string
video:
type: string
videoRes:
type: string
position:
type: integer
description: Current playback position in milliseconds.
duration:
type: integer
description: Total stream duration in milliseconds.
is_live:
type: boolean
runtime:
type: integer
buffering:
type: object
properties:
current:
type: integer
max:
type: integer
target:
type: integer
new_stream:
type: object
properties:
speed:
type: integer
stream_segment:
type: object
properties:
bitrate:
type: integer
media_sequence:
type: integer
segment_type:
type: string
time:
type: integer