HTTP debug

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.

debugCreateSession

Create a unified debug session

debugCreateSession description

Creates a debug session for a Roku app spanning the TypeScript runtime over CDP (port 9999), the BrightScript runtime over Roku's own BrightScript debug protocol (port 8081, not the Microsoft Debug Adapter Protocol), or both. The mode is fixed for the lifetime of the session. A dap_only session leaves the app stopped before its first statement once creation completes. Returns 409 when a session is already active for the device, and maps Roku Cloud Emulator failures to 404, 409, 429, 500, 502 or 504. A session whose creation fails is kept readable as failed, so its device console output stays available. Over plain HTTP this route is not exempt from the 30-second request timeout: a longer build or sideload returns 408 while the session keeps starting; poll GET /api/debug/session/status or send Accept: text/event-stream.

debugCreateSession contract

POST /api/debug/session/create

Responses: 200, 400, 404, 409, 429, 500, 502, 504; middleware can also return 403, 408 or 429.

debugCreateSession see also

debugCreateSession body.root

Absolute path to the Roku app root.

debugCreateSession body.mode

cdp_only (default), dap_only, or unified. unified requires an rk build --debug package and the remotedebug sideload fields, both validated at creation.

debugCreateSession body.dap

Deprecated synonym for mode dap_only, kept for one release.

debugCreateSession body.device

Target device ID, IP, or exact name.

debugCreateSession body.host

Direct target host or IP, bypassing the device store.

debugCreateSession body.password

Device password override.

debugCreateSession body.config

Build config name.

debugCreateSession body.connectionMode

watch (default, auto-reconnect) or manual.

debugCreateSession body.coordinatedStop

CDP to DAP only: a TypeScript pause triggers a BrightScript stop of all threads, budgeted at 500ms. Defaults to false.

debugCreateSession body.resumeOnEnd

Send CONTINUE before disconnecting the BrightScript debugger when the session ends. Defaults to false.

debugCreateSession body.autoStop

Lets BrightScript eval halt a running app automatically before evaluating. This halts every thread, including render and task threads.

debugEndSession

End a debug session

debugEndSession description

Ends a debug session, tearing down whichever CDP and DAP backends are active. Disconnecting a BrightScript backend leaves the app stopped on screen unless continueFirst sends CONTINUE first.

debugEndSession contract

POST /api/debug/session/end

Responses: 200, 400, 404, 500; middleware can also return 403, 408 or 429.

debugEndSession see also

debugEndSession body.sessionId

Session ID returned by session create. Uses the active session when omitted.

debugEndSession body.continueFirst

Send CONTINUE to the BrightScript debugger before disconnecting.

debugGetSessionStatus

Get debug session status

debugGetSessionStatus description

Reports a debug session's overall state and, per backend, its connection state, the negotiated DAP protocol version and capabilities, and the thread count. When no session matches, answers 200 with active false and a null sessionId rather than an error.

debugGetSessionStatus contract

GET /api/debug/session/status

Responses: 200; middleware can also return 403, 408 or 429.

debugGetSessionStatus see also

debugGetSessionStatus query.sessionId

Session ID. Uses the active session when omitted.

debugUpdateSession

Update or rebuild a debug session

debugUpdateSession description

Toggles coordinated stop on a debug session, or rebuilds it. The mode cannot be changed; asking for a different mode returns 400. rebuild tears the session down and re-establishes it from a fresh build and sideload with a forced version bump, then re-applies every breakpoint under its original ID and reports breakpoints the device rejected in failedBreakpoints. Without a sessionId this can also rebuild the sole failed session. Over plain HTTP this route is not exempt from the 30-second request timeout: a longer rebuild returns 408 while the rebuild keeps running; poll GET /api/debug/session/status or send Accept: text/event-stream.

debugUpdateSession contract

POST /api/debug/session/update

Responses: 200, 400, 404; middleware can also return 403, 408 or 429.

debugUpdateSession see also

debugUpdateSession body.sessionId

Session ID returned by session create. Uses the active session when omitted.

debugUpdateSession body.mode

Accepted only when it matches the session's current mode; the mode cannot change.

debugUpdateSession body.coordinatedStop

Toggle coordinated stop, CDP to DAP only.

debugUpdateSession body.rebuild

Full teardown and re-establish with a forced version bump, re-applying breakpoints under their original IDs.

debugGetStackTrace

Get the BrightScript call stack

debugGetStackTrace description

Returns the BrightScript call stack for a stopped thread, innermost frame first. Only frame 0 carries a code snippet. Requires the whole app to be stopped and returns 409 NOT_STOPPED while it runs. Returns 400 when the session has no DAP backend and 409 when the shared DAP connection is bound to a different device. Also returns 400 UNKNOWN_THREAD for a thread ID the session does not know, and 409 NO_THREAD_SELECTED or NO_ACTIVE_DAP_CONNECTION.

debugGetStackTrace contract

GET /api/debug/stacktrace

Responses: 200, 400, 404, 409, 500; middleware can also return 403, 408 or 429.

debugGetStackTrace see also

debugGetStackTrace query.threadId

Namespaced thread ID, for example brs:0. Uses the session's default thread when omitted.

debugGetStackTrace query.sessionId

Session ID. Uses the active session when omitted.

debugGetState

Get unified debugger state

debugGetState description

Returns a top-level paused flag plus the current call stack per active runtime under runtimes.ts and runtimes.brs. paused is true when at least one runtime is stopped. A running BrightScript app reports runtimes.brs as an error code and message without failing the call.

debugGetState contract

GET /api/debug/state

Responses: 200, 404, 500; middleware can also return 403, 408 or 429.

debugGetState see also

debugGetState query.sessionId

Session ID. Uses the active session when omitted.

debugEval

Evaluate an expression

debugEval description

Evaluates an expression on the TypeScript runtime over CDP or the BrightScript runtime over DAP. BrightScript eval assigns the expression to a temporary and reads it back, so result.variables holds the full readback; the expression is not sandboxed. TypeScript eval without frameIndex uses Runtime.evaluate and returns 409 EVAL_UNAVAILABLE_WHILE_PAUSED while paused; with frameIndex it evaluates in that paused frame and returns 409 NOT_PAUSED otherwise. Typed failures include 400 FRAME_OUT_OF_RANGE when frameIndex is past the end of the stack, 409 NOT_STOPPED, 400 EVAL_FAILED and 404 EVAL_TEMP_NOT_FOUND for BrightScript, 409 AUTO_STOP_TIMEOUT when autoStop cannot halt the app in time, 400 UNKNOWN_THREAD, and 409 NO_THREAD_SELECTED or NO_ACTIVE_DAP_CONNECTION. A BrightScript result that contains a Long_Integer value cannot be encoded as JSON and returns 500.

debugEval contract

POST /api/debug/eval

Responses: 200, 400, 404, 409, 500; middleware can also return 403, 408 or 429.

debugEval see also

debugEval body.expression

Expression to evaluate.

debugEval body.runtime

Force a backend. Defaults to the session's mode: cdp_only and unified use typescript, dap_only uses brightscript.

debugEval body.frameIndex

Evaluate in a specific stack frame, innermost first.

debugEval body.threadId

BrightScript only: namespaced thread ID, for example brs:0. Ignored for TypeScript.

debugEval body.print

BrightScript only: wrap the expression in a print statement instead of reading a value back.

debugEval body.sessionId

Session ID returned by session create. Uses the active session when omitted.

debugSetBreakpoint

Set a breakpoint

debugSetBreakpoint description

Sets a line breakpoint, routed by file extension: .ts, .tsx, .js and .jsx go to the TypeScript debugger over CDP, .brs and .xml go to the BrightScript debugger over DAP. A BrightScript path is converted to the pkg:/ URI the device requires. A BrightScript breakpoint is armed only when the response's verified field is true.

debugSetBreakpoint contract

POST /api/debug/breakpoint/set

Responses: 200, 400, 404, 409; middleware can also return 403, 408 or 429.

debugSetBreakpoint see also

debugSetBreakpoint body.file

Local file path (.ts, .tsx, .js, .jsx, .brs or .xml).

debugSetBreakpoint body.line

1-based line number.

debugSetBreakpoint body.condition

Condition gating when the breakpoint triggers.

debugSetBreakpoint body.ignoreCount

BrightScript only: hits to skip before actually stopping. Rejected with 400 for TypeScript files.

debugSetBreakpoint body.sessionId

Session ID returned by session create. Uses the active session when omitted.

debugRemoveBreakpoint

Remove a breakpoint

debugRemoveBreakpoint description

Removes a breakpoint set through this session, routed to whichever backend it was set on. Returns 404 when no breakpoint has the ID.

debugRemoveBreakpoint contract

POST /api/debug/breakpoint/remove

Responses: 200, 400, 404, 409; middleware can also return 403, 408 or 429.

debugRemoveBreakpoint see also

debugRemoveBreakpoint body.id

Stable breakpoint ID returned by set breakpoint; not a device-side ID.

debugRemoveBreakpoint body.sessionId

Session ID returned by session create. Uses the active session when omitted.

debugListBreakpoints

List breakpoints

debugListBreakpoints description

Lists every breakpoint tracked for the session: TypeScript line breakpoints and BrightScript line and exception breakpoints. Reads local state only, so it answers while the app is running.

debugListBreakpoints contract

GET /api/debug/breakpoints/list

Responses: 200, 404; middleware can also return 403, 408 or 429.

debugListBreakpoints see also

debugListBreakpoints query.sessionId

Session ID. Uses the active session when omitted.

debugSetExceptionBreakpoints

Set BrightScript exception breakpoints

debugSetExceptionBreakpoints description

Replaces the whole set of BrightScript exception filters; an empty array clears them. Requires BrightScript debug protocol 3.3.0 or later and returns 400 EXCEPTION_BREAKPOINTS_UNSUPPORTED otherwise. An uncaught exception always stops the app once a debugger is attached, so caught is the filter that changes behavior.

debugSetExceptionBreakpoints contract

POST /api/debug/exception-breakpoints/set

Responses: 200, 400, 404, 409; middleware can also return 403, 408 or 429.

debugSetExceptionBreakpoints see also

debugSetExceptionBreakpoints body.filters

Exception filters to break on, each with filter caught or uncaught and an optional condition.

debugSetExceptionBreakpoints body.sessionId

Session ID returned by session create. Uses the active session when omitted.

debugContinue

Resume execution

debugContinue description

Resumes the app on the TypeScript or BrightScript runtime. BrightScript CONTINUE always resumes every thread. Returns 409 NOT_PAUSED when the TypeScript debugger is not paused, and 409 CANT_CONTINUE when the device reports the BrightScript app cannot continue from its current state.

debugContinue contract

POST /api/debug/continue

Responses: 200, 400, 404, 409, 500; middleware can also return 403, 408 or 429.

debugContinue see also

debugContinue body.runtime

Force a backend. Defaults to brightscript for dap_only, and for unified to whichever runtime is stopped, preferring typescript, or typescript when neither is. cdp_only always uses typescript.

debugContinue body.sessionId

Session ID returned by session create. Uses the active session when omitted.

debugStep

Step over, into or out

debugStep description

Steps the app over, into or out on the TypeScript or BrightScript runtime. BrightScript stepping requires every thread to be stopped and can fail with codes including 409 NOT_STOPPED, THREAD_DETACHED, CANT_CONTINUE, STEP_TIMEOUT, NO_THREAD_SELECTED or NO_ACTIVE_DAP_CONNECTION, and 400 INVALID_THREAD or UNKNOWN_THREAD. TypeScript stepping returns 409 NOT_PAUSED when the debugger is not paused, and rejects threadId with 400.

debugStep contract

POST /api/debug/step

Responses: 200, 400, 404, 409, 500; middleware can also return 403, 408 or 429.

debugStep see also

debugStep body.type

Step direction.

debugStep body.threadId

BrightScript only: namespaced thread ID, for example brs:0.

debugStep body.runtime

Force a backend. Defaults to brightscript for dap_only, and for unified to whichever runtime is stopped, preferring typescript, or typescript when neither is. cdp_only always uses typescript.

debugStep body.sessionId

Session ID returned by session create. Uses the active session when omitted.

debugStop

Halt execution

debugStop description

Halts the app on every backend the session has and reports an outcome per runtime under brs and ts. BrightScript STOP halts every thread. An idle TypeScript runtime that cannot pause reports not-paused, which is not a failure. A BrightScript outcome of error makes success false while the status stays 200.

debugStop contract

POST /api/debug/stop

Responses: 200, 400, 404; middleware can also return 403, 408 or 429.

debugStop see also

debugStop body.sessionId

Session ID returned by session create. Uses the active session when omitted.

debugReadConsole

Read merged console output

debugReadConsole description

Reads captured console output from the TypeScript runtime, BrightScript app output and the device's port 8085 log stream, merged in timestamp order and tagged by source. BrightScript and device lines carry the level print. When the sessionId is omitted and the only session failed, sessionStatus is failed and its device output stays readable.

debugReadConsole contract

GET /api/debug/console

Responses: 200, 400, 404; middleware can also return 403, 408 or 429.

debugReadConsole see also

debugReadConsole query.runtime

Filter to one source: ts, brs or device.

debugReadConsole query.level

Filter to entries that carry exactly this level.

debugReadConsole query.since

Only return entries with timestamp >= this value (epoch ms).

debugReadConsole query.limit

Maximum number of entries to return, keeping the most recent. 0 returns none. Defaults to 50.

debugReadConsole query.sessionId

Session ID. Uses the active session when omitted.

debugReadErrors

Read merged runtime errors

debugReadErrors description

Reads captured errors from both runtimes, merged in timestamp order and tagged by source. A BrightScript runtime-error stop carries the thread ID, stop reason, top frame and code snippet when available. BrightScript compile errors are never reported here; read the device console instead.

debugReadErrors contract

GET /api/debug/errors

Responses: 200, 400, 404; middleware can also return 403, 408 or 429.

debugReadErrors see also

debugReadErrors query.runtime

Filter to one source: ts or brs. device is accepted but no errors carry it.

debugReadErrors query.since

Only return entries with timestamp >= this value (epoch ms).

debugReadErrors query.limit

Maximum number of entries to return, keeping the most recent. 0 returns none. Defaults to 50.

debugReadErrors query.sessionId

Session ID. Uses the active session when omitted.

debugClearConsole

Clear console and error buffers

debugClearConsole description

Clears captured console entries, error entries or both for a debug session.

debugClearConsole contract

POST /api/debug/console/clear

Responses: 200, 400, 404; middleware can also return 403, 408 or 429.

debugClearConsole see also

debugClearConsole body.target

Which buffer to clear: console, errors or both. Defaults to both.

debugClearConsole body.runtime

Restrict the clear to one source: ts, brs or device. Clears all sources when omitted.

debugClearConsole body.sessionId

Session ID returned by session create. Uses the active session when omitted.