HTTP build
The OpenAPI 3.1 document is generated beside this preview as openapi.json. Schemas document current behavior; they never validate runtime requests. The built-in server is loopback/host-guarded and has no authentication.
buildApp
Build an app
buildApp description
Builds the project once, streaming progress as server-sent events, and closes the stream when the build finishes; the rk build command uses this route. Requests must send Accept: text/event-stream. The body, root and config are checked first and answer JSON errors: invalid fields answer 400 VALIDATION_ERROR, a root outside the allowed project roots 403 PATH_VALIDATION_ERROR, a missing root 400 ROOT_NOT_FOUND, a config outside root or not ending in .ts 400 INVALID_CONFIG_PATH, a missing config 400 NO_PROJECT_CONFIG, and a missing Accept header 400 SSE_REQUIRED. Once the stream opens with HTTP 200, failures arrive as error events. Event data is JSON: stdout and stderr {message}, log {line}, status {status, lines?, device?, port?}, progress {phase, percent}, time {label}, timeEnd {label, duration}, complete {success, duration} and error {message, stack?, category?, code?}, with durations in milliseconds. A : ping comment is sent every 30 seconds. An active watch session for the same root gets an error event with code SESSION_IN_PROGRESS; a finished or running non-watch session for the root is replaced. Structured fields fill the build command's options, and raw args are appended after them. A raw --config or --build-type in args, given as --flag value or --flag=value, stands in for the structured field and is checked the same way, so a raw --config outside root or not ending in .ts also answers 400 INVALID_CONFIG_PATH. A request may set the structured field or the raw flag but not both; setting both, repeating the raw flag or giving it no value answers 400 VALIDATION_ERROR. Unexpected failures before the stream answer 500 BUILD_ERROR.
buildApp contract
POST /api/build
Responses: 200, 400, 403, 500; middleware can also return 403, 408 or 429.
buildApp see also
buildApp body.root
Absolute project directory inside the server's allowed project roots; required.
buildApp body.buildType
Build type forwarded to the build session. May come from a raw --build-type in args instead, but not from both.
buildApp body.config
Project config file inside root, ending in .ts; relative paths resolve against root; defaults to roku-config.ts. May come from a raw --config in args instead, but not from both.
buildApp body.args
Raw CLI arguments, forwarded to the build command; a raw --config or --build-type, as --flag value or --flag=value, is used as the structured field and validated the same way, may not be combined with that field, and may be given only once and with a value.
buildApp body.dropConsole
Drop console calls from the bundle; an explicit false keeps them.
buildApp body.dropDebugger
Drop debugger statements from the bundle.
buildApp body.lowerArrayDestructuring
Lower array destructuring during compilation.
buildApp body.disableTypeChecking
Skip TypeScript type checking.
buildApp body.perfettoPaths
Folder paths whose files get Perfetto instrumentation; overrides app.perfetto.instrumentPaths for this run.
buildApp body.perfettoExclude
Babel visitor shapes to skip: FunctionDeclaration, VariableDeclarator, FunctionExpression or ObjectMethod; overrides app.perfetto.exclude for this run.
buildApp body.perfettoFilter
Trace name substrings to instrument; overrides app.perfetto.filter for this run.
buildApp body.pkg
Create a package archive; when omitted, raw --archive or --package args turn it on.
buildApp body.outDir
Build output directory.
buildApp body.output
Package archive file name.
buildApp body.bumpMinor
Increment the manifest minor version.
buildApp body.bumpBuild
Increment the manifest build version.
buildApp body.metafile
Write the bundler metafile to this path.
buildApp body.dev
Build with the debug preset.
buildApp body.solidDevMode
Enable Solid development mode when true.
buildApp body.buildVariables
Build-time variable overrides as a plain object; currently only SIGNAL: true is applied, enabling Solid development mode like solidDevMode, and other entries are accepted but ignored.
startDev
Build and install a development app
startDev description
Builds the project, installs it on a Roku device and launches it, streaming progress as server-sent events; the rk dev command uses this route. Requests must send Accept: text/event-stream. The body, root and config are checked first and answer JSON errors: invalid fields answer 400 VALIDATION_ERROR, an incompatible flag combination 400 INVALID_ARGS, a root outside the allowed project roots 403 PATH_VALIDATION_ERROR, a missing root 400 ROOT_NOT_FOUND, a config outside root or not ending in .ts 400 INVALID_CONFIG_PATH, a missing config 400 NO_PROJECT_CONFIG, and a missing Accept header 400 SSE_REQUIRED. A raw --config or --build-type in args, given as --flag value or --flag=value, stands in for the structured field and is checked the same way, so a raw --config outside root or not ending in .ts also answers 400 INVALID_CONFIG_PATH. A request may set the structured field or the raw flag but not both; setting both, repeating the raw flag or giving it no value answers 400 VALIDATION_ERROR. Raw args and the target device are then checked, also before the stream opens: unknown raw args answer 400 VALIDATION_ERROR, dapDebug on a Roku Cloud Emulator device 400 DEVICE_KIND_UNSUPPORTED, and an unknown or unusable device or a missing developer password 400 with its own code, such as DEVICE_NOT_FOUND, NO_ACTIVE_DEVICE or NO_DEVICE_PASSWORD. Roku Cloud Emulator failures answer 409 for a device state that has to change, 404 for a missing device, snapshot or firmware, 400 for a rejected request, 429 for a rate or trial limit, 504 for a timeout, 500 for an unreadable local emulator store and 502 for other emulator service failures. Once the stream opens with HTTP 200, failures arrive as error events. Event data is JSON: stdout and stderr {message}, log {line}, status {status, lines?, device?, port?}, progress {phase, percent}, time {label}, timeEnd {label, duration}, complete {success, duration} and error {message, stack?, category?, code?}, with durations in milliseconds. A : ping comment is sent every 30 seconds. A session-attach {sessionId, watch?} event names a watch session, or a session kept alive for its console, so it can be stopped with DELETE /api/dev/{sessionId}; watch is true for a watch session, which can also be rebuilt with POST /api/dev/{sessionId}/rebuild. A watch request for a root with an active watch session attaches to it; a non-watch request for that root, or a watch request while another root is watching, gets an error event with code SESSION_IN_PROGRESS. Disconnecting stops the console subscription but not a watch session. Unexpected failures before the stream answer 500 START_DEV_ERROR. Device selectors handled by a registered server extension are deployed by that extension and are not described here.
startDev contract
POST /api/dev
Responses: 200, 400, 403, 404, 409, 429, 500, 502, 504; middleware can also return 403, 408 or 429.
startDev see also
- rk dev
- MCP deploy_app
startDev body.root
Absolute project directory inside the server's allowed project roots; required.
startDev body.buildType
Build type forwarded to the build session. May come from a raw --build-type in args instead, but not from both.
startDev body.config
Project config file inside root, ending in .ts; relative paths resolve against root; defaults to roku-config.ts. May come from a raw --config in args instead, but not from both.
startDev body.args
Raw CLI arguments, forwarded to the build command; they fill in structured fields that are omitted, inspect, inspectPersist and dapDebug are on when either the field or the raw flag is set, and a raw --config or --build-type, as --flag value or --flag=value, is used as the structured field and validated the same way, may not be combined with that field, and may be given only once and with a value.
startDev body.dropConsole
Drop console calls from the bundle; an explicit false keeps them.
startDev body.dropDebugger
Drop debugger statements from the bundle.
startDev body.lowerArrayDestructuring
Lower array destructuring during compilation.
startDev body.disableTypeChecking
Skip TypeScript type checking.
startDev body.perfettoPaths
Folder paths whose files get Perfetto instrumentation; overrides app.perfetto.instrumentPaths for this run.
startDev body.perfettoExclude
Babel visitor shapes to skip: FunctionDeclaration, VariableDeclarator, FunctionExpression or ObjectMethod; overrides app.perfetto.exclude for this run.
startDev body.perfettoFilter
Trace name substrings to instrument; overrides app.perfetto.filter for this run.
startDev body.device
Stored device ID, IP address or name; omitted selects the active device.
startDev body.host
Direct device host or IP address, bypassing device store selection.
startDev body.password
Device developer password override for host mode or a stored device.
startDev body.watch
Rebuild and reinstall on source changes. A watch request for a root with an active watch session attaches to it without replaying history; only one watch session runs server-wide.
startDev body.debug
Build with the debug preset.
startDev body.inspect
Enable debugging and launch with inspect=true.
startDev body.inspectPersist
Enable persistent inspection; implies debugging.
startDev body.dapDebug
Start a DAP debugging session; refused for Roku Cloud Emulator devices.
startDev body.console
Stream the device console into the event stream.
startDev body.autoConsoleClose
Close the console stream shortly after the dev operation finishes, even if the app keeps running; only applies with console.
startDev body.noLaunch
Install without launching the app.
startDev body.release
Build with the release preset; cannot be combined with debug, inspect or inspectPersist.
startDev body.launchParams
Launch parameters passed to the app; inspect adds inspect=true unless inspectPersist is set.
startDevLegacy
Build and install a development app
startDevLegacy description
Former name of POST /api/dev, kept so older clients still work; new callers use /api/dev. Builds the project, installs it on a Roku device and launches it, streaming progress as server-sent events; the rk dev command uses this route. Requests must send Accept: text/event-stream. The body, root and config are checked first and answer JSON errors: invalid fields answer 400 VALIDATION_ERROR, an incompatible flag combination 400 INVALID_ARGS, a root outside the allowed project roots 403 PATH_VALIDATION_ERROR, a missing root 400 ROOT_NOT_FOUND, a config outside root or not ending in .ts 400 INVALID_CONFIG_PATH, a missing config 400 NO_PROJECT_CONFIG, and a missing Accept header 400 SSE_REQUIRED. A raw --config or --build-type in args, given as --flag value or --flag=value, stands in for the structured field and is checked the same way, so a raw --config outside root or not ending in .ts also answers 400 INVALID_CONFIG_PATH. A request may set the structured field or the raw flag but not both; setting both, repeating the raw flag or giving it no value answers 400 VALIDATION_ERROR. Raw args and the target device are then checked, also before the stream opens: unknown raw args answer 400 VALIDATION_ERROR, dapDebug on a Roku Cloud Emulator device 400 DEVICE_KIND_UNSUPPORTED, and an unknown or unusable device or a missing developer password 400 with its own code, such as DEVICE_NOT_FOUND, NO_ACTIVE_DEVICE or NO_DEVICE_PASSWORD. Roku Cloud Emulator failures answer 409 for a device state that has to change, 404 for a missing device, snapshot or firmware, 400 for a rejected request, 429 for a rate or trial limit, 504 for a timeout, 500 for an unreadable local emulator store and 502 for other emulator service failures. Once the stream opens with HTTP 200, failures arrive as error events. Event data is JSON: stdout and stderr {message}, log {line}, status {status, lines?, device?, port?}, progress {phase, percent}, time {label}, timeEnd {label, duration}, complete {success, duration} and error {message, stack?, category?, code?}, with durations in milliseconds. A : ping comment is sent every 30 seconds. A session-attach {sessionId, watch?} event names a watch session, or a session kept alive for its console, so it can be stopped with DELETE /api/dev/{sessionId}; watch is true for a watch session, which can also be rebuilt with POST /api/dev/{sessionId}/rebuild. A watch request for a root with an active watch session attaches to it; a non-watch request for that root, or a watch request while another root is watching, gets an error event with code SESSION_IN_PROGRESS. Disconnecting stops the console subscription but not a watch session. Unexpected failures before the stream answer 500 START_DEV_ERROR. Device selectors handled by a registered server extension are deployed by that extension and are not described here.
startDevLegacy contract
POST /api/start-dev
Responses: 200, 400, 403, 404, 409, 429, 500, 502, 504; middleware can also return 403, 408 or 429.
startDevLegacy body.root
Absolute project directory inside the server's allowed project roots; required.
startDevLegacy body.buildType
Build type forwarded to the build session. May come from a raw --build-type in args instead, but not from both.
startDevLegacy body.config
Project config file inside root, ending in .ts; relative paths resolve against root; defaults to roku-config.ts. May come from a raw --config in args instead, but not from both.
startDevLegacy body.args
Raw CLI arguments, forwarded to the build command; they fill in structured fields that are omitted, inspect, inspectPersist and dapDebug are on when either the field or the raw flag is set, and a raw --config or --build-type, as --flag value or --flag=value, is used as the structured field and validated the same way, may not be combined with that field, and may be given only once and with a value.
startDevLegacy body.dropConsole
Drop console calls from the bundle; an explicit false keeps them.
startDevLegacy body.dropDebugger
Drop debugger statements from the bundle.
startDevLegacy body.lowerArrayDestructuring
Lower array destructuring during compilation.
startDevLegacy body.disableTypeChecking
Skip TypeScript type checking.
startDevLegacy body.perfettoPaths
Folder paths whose files get Perfetto instrumentation; overrides app.perfetto.instrumentPaths for this run.
startDevLegacy body.perfettoExclude
Babel visitor shapes to skip: FunctionDeclaration, VariableDeclarator, FunctionExpression or ObjectMethod; overrides app.perfetto.exclude for this run.
startDevLegacy body.perfettoFilter
Trace name substrings to instrument; overrides app.perfetto.filter for this run.
startDevLegacy body.device
Stored device ID, IP address or name; omitted selects the active device.
startDevLegacy body.host
Direct device host or IP address, bypassing device store selection.
startDevLegacy body.password
Device developer password override for host mode or a stored device.
startDevLegacy body.watch
Rebuild and reinstall on source changes. A watch request for a root with an active watch session attaches to it without replaying history; only one watch session runs server-wide.
startDevLegacy body.debug
Build with the debug preset.
startDevLegacy body.inspect
Enable debugging and launch with inspect=true.
startDevLegacy body.inspectPersist
Enable persistent inspection; implies debugging.
startDevLegacy body.dapDebug
Start a DAP debugging session; refused for Roku Cloud Emulator devices.
startDevLegacy body.console
Stream the device console into the event stream.
startDevLegacy body.autoConsoleClose
Close the console stream shortly after the dev operation finishes, even if the app keeps running; only applies with console.
startDevLegacy body.noLaunch
Install without launching the app.
startDevLegacy body.release
Build with the release preset; cannot be combined with debug, inspect or inspectPersist.
startDevLegacy body.launchParams
Launch parameters passed to the app; inspect adds inspect=true unless inspectPersist is set.
stopDev
Stop a development session
stopDev description
Stops a build session named by a session-attach event from POST /api/dev. An unknown session ID answers 404 SESSION_NOT_FOUND, and a session that cannot be stopped answers 500 STOP_SESSION_FAILED or STOP_SESSION_ERROR.
stopDev contract
DELETE /api/dev/:sessionId
Responses: 200, 404, 500; middleware can also return 403, 408 or 429.
stopDev see also
stopDev params.sessionId
Session ID from a session-attach event.
rebuildDev
Available since @roku-sdk/tooling 2.19.0
Rebuild a watch session
rebuildDev description
Runs one full rebuild in a watch session named by a session-attach event from POST /api/dev, the same as pressing r in the terminal of a local rk dev --watch: the output directory is cleaned, the app is built again and installed. The request has no body. Queued behind any rebuild already running in the session, it answers when its own rebuild ends, with the build output on the session's event stream. An unknown session ID answers 404 SESSION_NOT_FOUND, a session that is not watching, or whose watch has stopped, 409 REBUILD_NOT_AVAILABLE, and a rebuild that failed 500 REBUILD_FAILED.
rebuildDev contract
POST /api/dev/:sessionId/rebuild
Responses: 200, 404, 409, 500; middleware can also return 403, 408 or 429.
rebuildDev see also
rebuildDev params.sessionId
Available since @roku-sdk/tooling 2.19.0
Session ID from a session-attach event.
stopDevLegacy
Stop a development session
stopDevLegacy description
Former name of DELETE /api/dev/{sessionId}, kept so older clients still work. Stops a build session named by a session-attach event from POST /api/dev. An unknown session ID answers 404 SESSION_NOT_FOUND, and a session that cannot be stopped answers 500 STOP_SESSION_FAILED or STOP_SESSION_ERROR.
stopDevLegacy contract
DELETE /api/start-dev/:sessionId
Responses: 200, 404, 500; middleware can also return 403, 408 or 429.
stopDevLegacy params.sessionId
Session ID from a session-attach event.
sideloadApp
Install a built app
sideloadApp description
Installs an already built app on a Roku device without rebuilding, streaming progress as server-sent events; the rk sideload command uses this route. It installs the pkg-dir folder inside outDir. Requests must send Accept: text/event-stream. Invalid fields answer 400 VALIDATION_ERROR, a missing Accept header 400 SSE_REQUIRED, and a root outside the allowed project roots or an outDir outside root 403 PATH_VALIDATION_ERROR. Once the stream opens with HTTP 200, failures arrive as error events. PKG_DIR_NOT_FOUND, when no built package is found, ends the stream without a complete event; SIDELOAD_FAILED, when the device rejects the install, and the device resolution code, or DEVICE_RESOLUTION_ERROR, when the target device cannot be used, are followed by complete {success: false}. Event data is JSON: stdout and stderr {message}, log {line}, status {status, lines?, device?, port?}, progress {phase, percent}, time {label}, timeEnd {label, duration}, complete {success, duration} and error {message, stack?, category?, code?}, with durations in milliseconds. A : ping comment is sent every 30 seconds. A warning about which artifact was chosen arrives as stderr. Unexpected failures before the stream answer 500 SIDELOAD_ERROR; after it opens, an unexpected failure ends the connection without an event. Device selectors handled by a registered server extension are deployed by that extension and are not described here.
sideloadApp contract
POST /api/sideload
Responses: 200, 400, 403, 500; middleware can also return 403, 408 or 429.
sideloadApp see also
- MCP sideload_app
sideloadApp body.root
Absolute project directory inside the server's allowed project roots; required.
sideloadApp body.outDir
Build output directory holding pkg-dir, inside root; defaults to dist-dev.
sideloadApp body.device
Stored device ID, IP address or name; omitted selects the active device.
sideloadApp body.host
Direct device host or IP address, bypassing device store selection.
sideloadApp body.password
Device developer password override for host mode or a stored device.
sideloadApp body.launchParams
Launch parameters passed to the app.
sideloadApp body.noLaunch
Install without launching the app.
Updated about 4 hours ago