iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Roku’s External Control Protocol (ECP) is a documented REST interface available on a Roku device’s local network, normally at TCP port 8060. Use HTTP GET requests to read device and playback information, and send empty-body POST requests to press keys, launch channels, or control a Roku TV’s volume, power, inputs, and tuner. You can address a known IP or discover devices with SSDP. The examples below show a complete curl workflow and the equivalent JavaScript fetch calls, plus the Roku OS settings and version limits that determine which commands work.
What is the Roku TV REST API?
Roku calls its local HTTP interface the External Control Protocol (ECP). Roku’s developer documentation describes it this way: “The External Control Protocol (ECP) enables a Roku device to be controlled over a local area network by providing a number of external control services.” ECP is not a cloud service or a separate software package. It is an HTTP service running on the Roku itself, so a controller and the Roku must be able to reach one another on the same network.
The documented service normally listens on port 8060. Endpoints fall into two useful groups:
- Queries: HTTP GET requests return XML describing the device, current app, media player, icons, or TV tuner state.
- Actions: HTTP POST requests with an empty body perform key presses, key-down/key-up events, app launches, and other controls.
The interface is deliberately simple: construct a URL containing the Roku address and endpoint, then send the appropriate HTTP method. Capabilities still depend on Roku OS version, device type, and settings.
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
What must be configured before sending ECP requests?
Put the computer, phone, or server running your script on a network that can route to the Roku, identify the Roku’s current IP address, and enable mobile-app control in Roku’s settings. A guest Wi-Fi network or client-isolation feature can prevent otherwise correct requests from reaching port 8060.
Enable control by mobile apps
On Roku OS 14.1, open Settings > System > Advanced system settings > Control by mobile apps and set it to Enabled. This setting is required for keypress, keydown, keyup, query/icon, query/tv-channels, and query/tv-active-channel. Roku can change this path or the set of protected commands in later releases, so check the labels on the target device when troubleshooting.
Know when Developer Mode is required
Diagnostic endpoints such as query/chanperf, query/registry, and query/app-state, along with exit-app, require Roku Developer Mode. Ordinary navigation, media queries, and the TV controls listed in this guide do not automatically imply that Developer Mode is enabled.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Keep the address current
A DHCP lease can change the Roku IP after a reboot or router change. You can reserve the address in your router, store it in a configuration file, or discover it at runtime with SSDP. Do not assume that an address shown in an old script remains valid.
How do I discover a Roku IP address with SSDP?
Roku devices advertise ECP through SSDP multicast at 239.255.255.250:1900. Send an M-SEARCH request with ST: roku:ecp; each Roku that answers includes a Location header such as http://192.168.1.134:8060/. Extract the host and port from that URL instead of guessing the address.
Multiple Rokus can answer one search. Keep a map keyed by each response’s USN (Unique Service Name), storing its location URL and descriptive headers, then let the user select a device by its friendly name or serial information. The documentation says a discovery response includes Cache-Control: max-age=3600; treat the result as current for no longer than that period and rediscover sooner when a request fails.
What an SSDP search looks like
M-SEARCH * HTTP/1.1
Host: 239.255.255.250:1900
Man: "ssdp:discover"
ST: roku:ecp
MX: 3
The exact socket code differs between operating systems and runtimes, but the important values are the multicast host and port, the ssdp:discover method header, and the Roku-specific search target. A discovery implementation should ignore malformed responses, handle several replies during the MX wait interval, and refresh an entry when its cache lifetime expires.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
When is a configured IP better?
A manually configured or DHCP-reserved address is simplest for a single, known television on a stable home network. SSDP is better for installers, multi-room controllers, and applications that must find devices after an address change. A robust client can use a saved address first, then fall back to SSDP when the saved endpoint times out.
How do I query a Roku with curl?
Set the target address once, then append ECP paths to port 8060. Query endpoints use GET and return XML, which is easy to inspect in a terminal or pass to an XML parser.
export ROKU_DEV_TARGET=192.168.1.134
curl "http://$ROKU_DEV_TARGET:8060/query/device-info"
curl "http://$ROKU_DEV_TARGET:8060/query/media-player"/query/device-info reports identifying and software information. /query/media-player reports the current playback state. Save the raw responses while integrating so you can see which elements a particular Roku model and app actually returns; XML fields can vary with state.
Read Roku TV tuner information
For a Roku TV with an antenna or tuner, use:
curl "http://$ROKU_DEV_TARGET:8060/query/tv-channels"
curl "http://$ROKU_DEV_TARGET:8060/query/tv-active-channel"The first returns the channel data known to the TV tuner. The second returns the channel currently selected by the tuner. These endpoints are subject to the mobile-app control setting described earlier.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Retrieve an app icon
query/icon is also protected by the mobile-app control setting. Request the endpoint with the app identifier and handle the returned image bytes according to the response headers. If the request is denied, verify the setting before treating it as an application error.
How do I send key presses and remote-control actions with curl?
Send an empty-body POST to an action endpoint. The body is intentionally empty; using GET for an action or omitting the POST method can produce a failure or no action.
curl -d '' "http://$ROKU_DEV_TARGET:8060/keypress/home"
curl -d '' "http://$ROKU_DEV_TARGET:8060/keydown/left"
sleep 10
curl -d '' "http://$ROKU_DEV_TARGET:8060/keyup/left"keypress represents a complete button press. keydown starts a held button and keyup releases it; always send the matching release, including when your program handles an error or cancellation. A ten-second hold in the example is only a demonstration, not a recommended navigation delay.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Launch an app or deep link
Use the launch path with the app’s identifier and any documented query parameters. This example launches a season deep link:
curl -d '' "http://$ROKU_DEV_TARGET:8060/launch/dev?contentID=13234&MediaType=season"URL-encode parameter values when they contain spaces, ampersands, or other reserved characters. Keep the POST body empty; the parameters belong in the URL. The app must support the supplied deep-link fields, so a syntactically valid request can still result in an app-specific “not found” or ignored-content response.
Account for the removed search command
Roku OS 12.0 removed the search command. Do not build a new controller around that endpoint, and remove it from older automation when upgrading a device. Use app launches or the on-screen search flow instead, depending on the experience you need.
Which Roku TV controls are available?
Roku TV models expose television-specific key values in addition to common navigation keys. Send each value after /keypress/, or use the same value with /keydown/ and /keyup/ when a held action is appropriate.
| Function | Documented key value | Typical endpoint |
|---|---|---|
| Volume down | VolumeDown |
/keypress/VolumeDown |
| Mute | VolumeMute |
/keypress/VolumeMute |
| Volume up | VolumeUp |
/keypress/VolumeUp |
| Power off | PowerOff |
/keypress/PowerOff |
| Channel up | ChannelUp |
/keypress/ChannelUp |
| Channel down | ChannelDown |
/keypress/ChannelDown |
| TV tuner input | InputTuner |
/keypress/InputTuner |
| HDMI 1–4 | InputHDMI1, InputHDMI2, InputHDMI3, InputHDMI4 |
For example, /keypress/InputHDMI1 |
| Composite AV | InputAV1 |
/keypress/InputAV1 |
These values are Roku TV controls, not a guarantee that every Roku streaming player has a television tuner, power circuit, or the same input layout. A command can be valid for ECP yet have no useful effect on hardware that lacks that feature.
Free tools Windows power users keep installed
One-click scans. No signup required.
How do I call the Roku API from JavaScript?
JavaScript uses the same HTTP contract: call query endpoints with GET, call action endpoints with POST, and parse XML returned by queries. The following browser-compatible pattern uses fetch:
const rokuIp = "192.168.1.134";
const base = `http://${rokuIp}:8060`;
const infoResponse = await fetch(`${base}/query/device-info`);
if (!infoResponse.ok) {
throw new Error(`Device query failed: ${infoResponse.status}`);
}
const infoXml = await infoResponse.text();
const keyResponse = await fetch(`${base}/keypress/home`, {
method: "POST",
body: ""
});
if (!keyResponse.ok) {
throw new Error(`Key press failed: ${keyResponse.status}`);
}In a browser, parse the XML string with DOMParser:
const xml = new DOMParser().parseFromString(infoXml, "application/xml");
const errorNode = xml.querySelector("parsererror");
if (errorNode) throw new Error("Roku returned invalid XML");
const friendlyName = xml.querySelector("friendly-device-name")?.textContent;Element names should be verified against the response from your device rather than assumed. A missing element can mean that the current app or TV state does not expose that value, not that the network request failed.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
Browser versus server-side JavaScript
A browser page served over HTTPS may block a request to an http:// Roku address as mixed content. Browser cross-origin rules can also prevent a page from reading the response unless the Roku response supplies suitable CORS headers. A server-side script, desktop utility, or home-automation service generally avoids those browser restrictions because it makes the request outside the page security model. If a browser cannot reach ECP, inspect the browser console before changing the Roku command.
Handle discovery in JavaScript
SSDP requires sending and receiving UDP multicast, which ordinary browser JavaScript cannot do directly. Perform discovery in a native or server-side component, then pass the selected Location URL to the browser client. A browser-only application therefore usually needs a user-entered IP, a companion service, or a platform API that exposes local-network discovery.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
How should a reliable ECP client handle errors?
Separate transport failures, authorization or setting failures, unsupported commands, and stale state. This makes troubleshooting much faster than retrying every error identically.
- Timeout or connection refused: verify the IP, port 8060, Wi-Fi isolation, and whether the Roku is awake and on the same routed network. Rediscover with SSDP if the address may have changed.
- Navigation or query commands rejected: confirm Control by mobile apps is enabled under the current Roku OS menu.
- Diagnostic endpoint rejected: enable Developer Mode only when that diagnostic command actually requires it.
- Command worked on an older device but not after an update: check Roku OS release notes and the command’s current support. In particular, do not expect
searchon Roku OS 12.0 or newer. - TV input or tuner action has no effect: confirm that the target is a Roku TV, that the input exists on that model, and that the television is not in a state that suppresses the requested action.
- XML parsing fails: log the HTTP status and raw response, then parse only after checking that the response is actually XML. Do not silently treat an HTML error page or empty body as a valid query result.
For held keys, pair every successful keydown with keyup in a cleanup path. For discovery, expire cached devices according to the advertised max-age=3600 rather than retaining an address indefinitely.
Should I use SSDP discovery or a fixed IP?
The right choice depends on whether your controller targets one stable television or a changing set of devices.
| Decision point | SSDP discovery | Manually configured IP |
|---|---|---|
| Setup | Finds Roku devices automatically through multicast. | Requires the user or administrator to enter an address. |
| Address changes | Can locate a device after DHCP changes. | Needs a router reservation or configuration update. |
| Multiple Rokus | Returns several responses; the client must present a chooser. | Simple when exactly one known target exists. |
| Network requirements | Multicast must pass between the client and Roku. | Only normal unicast routing to port 8060 is needed. |
| Browser use | Requires a native or server-side discovery helper. | Can be supplied directly to a browser, subject to mixed-content and CORS rules. |
Many production controllers combine both: retain a selected device’s USN and location, try the cached endpoint, and run SSDP again when it expires or becomes unreachable.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteWhat is the difference between GET queries and POST actions?
GET is read-only in the ECP usage documented here; POST expresses an instruction to the Roku. Keeping that distinction explicit prevents accidental actions and makes your code easier to audit.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
| Operation | HTTP method | Body | Examples |
|---|---|---|---|
| Read state or metadata | GET | None | /query/device-info, /query/media-player, /query/tv-channels |
| Press or release a key | POST | Empty | /keypress/home, /keydown/left, /keyup/left |
| Launch an app or deep link | POST | Empty; parameters in URL | /launch/dev?contentID=13234&MediaType=season |
Always check the HTTP result before acting on a response. A successful network connection does not prove that the requested feature exists on that model or that the Roku accepted the command under its current settings.
How do I secure a Roku ECP integration?
ECP is intended for a trusted local network and is normally plain HTTP. Anyone who can reach the Roku’s ECP port may be able to send remote-control commands, so do not expose port 8060 directly to the public internet or forward it through a router. Put controllers and televisions on a trusted VLAN or firewall segment, restrict which hosts can connect, and treat SSDP responses as untrusted input.
Because the protocol is local and unauthenticated in the documented request pattern, a home-automation server is usually safer than embedding control logic in a publicly reachable web page. If your application logs requests, omit sensitive network details from shared logs and validate every discovered IP and URL before connecting.
What is a practical implementation checklist?
- Confirm the Roku and controller share a routable local network.
- Enable Control by mobile apps on Roku OS 14.1 or the equivalent setting on your release.
- Choose a discovery strategy: reserve a fixed address or implement SSDP at
239.255.255.250:1900withST: roku:ecp. - Store the selected device’s IP, ECP location, and USN, honoring the advertised one-hour cache lifetime.
- Probe
/query/device-infowith GET and parse the XML before sending controls. - Use empty-body POST requests for
keypress,keydown,keyup, andlaunch. - For Roku TV features, test the exact input, tuner, volume, or power key on the target model.
- Implement timeouts, status checks, XML validation, rediscovery, and guaranteed key-up cleanup.
- Keep an OS compatibility note in your code, including the removal of
searchin Roku OS 12.0.
With those pieces in place, curl is useful for testing individual endpoints, while JavaScript or another runtime can add discovery, device selection, state polling, and a user interface around the same ECP calls.
What should you remember about Roku’s REST interface?
ECP gives a Roku TV a straightforward local control surface: discover the device with SSDP or configure its address, read XML with GET, and perform actions with empty-body POST requests on port 8060. The main implementation risks are not HTTP syntax but network isolation, browser security policies, Roku OS command changes, and confusing a generic Roku player with a Roku TV’s hardware-specific controls. Build those checks into the client and the documented API is practical for scripts, testing tools, and local automation.
Frequently Asked Questions
Can I use Roku ECP from a phone without installing a Roku app?
Yes, if the phone is on the same network and can send HTTP requests to the Roku’s port 8060. A mobile browser may still be limited by mixed-content and cross-origin rules, so a native app or local companion service is often more reliable.
Does ECP work when the Roku is connected through a guest Wi-Fi network?
Usually not when the guest network enables client isolation or blocks multicast and device-to-device traffic. Move both devices to a network that permits local unicast traffic and, for SSDP, multicast to 239.255.255.250.
How can I tell which Roku answered an SSDP search?
Use each response’s USN as a stable discovery key and combine its Location URL with identifying data from a subsequent query such as device information. Present the resulting friendly names or serial details to the user when several devices respond.
Can ECP turn a Roku TV on as well as off?
The documented TV key list includes PowerOff, but it does not establish a universal power-on command. Whether a television can wake from standby depends on the model, power state, network behavior, and Roku OS support; test the target hardware rather than assuming symmetry.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
