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