HTTP cdp
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.
cdpCreateSession
Create a debugging session
cdpCreateSession description
Builds and sideloads the app in debug mode (equivalent to rk dev -d), loads its source map, and connects to the device's Hermes CDP server (port 9999). Failures from Roku Cloud Emulator devices keep their own status and code; other failures return 400. Over plain HTTP this route is not exempt from the 30-second request timeout: a longer build or redeploy returns 408 while the session keeps starting; poll GET /api/cdp/status or send Accept: text/event-stream.
cdpCreateSession contract
POST /api/cdp/session/create
Responses: 200, 400, 404, 409, 429, 500, 502, 504; middleware can also return 403, 408 or 429.
cdpCreateSession see also
cdpCreateSession body.root
Project root; resolved to an absolute path on the server.
cdpCreateSession body.device
Target device ID, IP, exact name, or rce:<name>. Uses active device when omitted.
cdpCreateSession body.host
Direct target host/IP (bypasses device store selection for target resolution).
cdpCreateSession body.password
Device password override (applies to host mode and can override stored device password).
cdpCreateSession body.mode
Connection mode: watch (auto-reconnect) or manual.
cdpAttachSession
Attach to a device
cdpAttachSession description
Gets or creates a build-free, password-free session for a device address, with no source map and no source tree behind it. A reused session that isn't currently connected is reconnected. created is true only when this request opened the session.
cdpAttachSession contract
POST /api/cdp/session/attach
Responses: 200, 400; middleware can also return 403, 408 or 429.
cdpAttachSession body.host
Device address to connect to.
cdpAttachSession body.port
Hermes CDP port to dial. Defaults to 9999; exists for local tunnels and proxies that remap the address.
cdpEndSession
End an active session
cdpEndSession description
Ends a CDP debug session: disconnects from the device and clears its source map from memory. Uses the active session when sessionId is omitted or empty.
cdpEndSession contract
POST /api/cdp/session/end
Responses: 200, 400, 404, 500; middleware can also return 403, 408 or 429.
cdpEndSession see also
cdpEndSession body.sessionId
Target session ID.
cdpUpdateSession
Update an active session
cdpUpdateSession description
Rebuilds and redeploys the app into an existing session with the project root, device and build config it was created with, reloads the source map and re-applies every breakpoint. Breakpoints that can no longer be mapped are reported as failed. A session created by attach has no build to update and returns 409. Over plain HTTP this route is not exempt from the 30-second request timeout: a longer build or redeploy returns 408 while the session keeps starting; poll GET /api/cdp/status or send Accept: text/event-stream.
cdpUpdateSession contract
POST /api/cdp/session/update
Responses: 200, 400, 404, 409, 429, 500, 502, 504; middleware can also return 403, 408 or 429.
cdpUpdateSession see also
cdpUpdateSession body.sessionId
Target session ID.
cdpUpdateSession body.password
Device password for the redeploy.
cdpGetStatus
Show active session status
cdpGetStatus description
Reports the state of a CDP debug session: connection state, pause state, source map load state, and captured console/error counts. A missing session is not an error: it returns active false with a null sessionId.
cdpGetStatus contract
GET /api/cdp/status
Responses: 200; middleware can also return 403, 408 or 429.
cdpGetStatus see also
cdpGetStatus query.sessionId
Target session ID. Uses the active session when omitted.
cdpEvaluate
Evaluate a JavaScript expression
cdpEvaluate description
Evaluates a JavaScript expression in the global scope of the debugged Roku app via CDP Runtime.evaluate. result is the raw Runtime.evaluate response. Unavailable while the session is paused; evaluate on a call frame instead.
cdpEvaluate contract
POST /api/cdp/eval
Responses: 200, 400, 404, 409, 500; middleware can also return 403, 408 or 429.
cdpEvaluate see also
cdpEvaluate body.expression
JavaScript expression to evaluate in the global scope.
cdpEvaluate body.sessionId
Target session ID. Uses the active session when omitted.
cdpGetHeapUsage
Get heap usage statistics
cdpGetHeapUsage description
Returns lightweight JS heap usage (total/used bytes) for the debugged Roku app via CDP Runtime.getHeapUsage.
cdpGetHeapUsage contract
GET /api/cdp/heap-usage
Responses: 200, 404, 500; middleware can also return 403, 408 or 429.
cdpGetHeapUsage see also
cdpGetHeapUsage query.sessionId
Target session ID. Uses the active session when omitted.
cdpListSources
List all loaded source files
cdpListSources description
Lists every source file available in the currently loaded source map, as local disk paths.
cdpListSources contract
GET /api/cdp/source/list
Responses: 200, 400, 404; middleware can also return 403, 408 or 429.
cdpListSources see also
cdpListSources query.sessionId
Target session ID. Uses the active session when omitted.
cdpGetSource
Get source code for a file
cdpGetSource description
Returns lines of source content from one file in the loaded source map, optionally restricted to a line range. A startLine beyond the end of the file returns 400.
cdpGetSource contract
GET /api/cdp/source/get
Responses: 200, 400, 404; middleware can also return 403, 408 or 429.
cdpGetSource see also
cdpGetSource query.file
A local disk path as returned by the source list.
cdpGetSource query.startLine
1-based, inclusive start line.
cdpGetSource query.endLine
1-based, inclusive end line; must not be less than startLine.
cdpGetSource query.sessionId
Target session ID. Uses the active session when omitted.
cdpGrepSources
Search source files for a pattern
cdpGrepSources description
Searches the loaded source map's file contents for a regular expression pattern, across all files or one specific file.
cdpGrepSources contract
GET /api/cdp/source/grep
Responses: 200, 400, 404; middleware can also return 403, 408 or 429.
cdpGrepSources see also
cdpGrepSources query.pattern
A JavaScript regular expression pattern.
cdpGrepSources query.file
Restrict the search to one file.
cdpGrepSources query.maxResults
Maximum number of matches to return. Defaults to 100.
cdpGrepSources query.sessionId
Target session ID. Uses the active session when omitted.
cdpResolveSource
Resolve a source map path
cdpResolveSource description
Resolves a path between its source-map representation and its local disk path. A path the source map does not contain returns 404.
cdpResolveSource contract
GET /api/cdp/source/resolve
Responses: 200, 400, 404; middleware can also return 403, 408 or 429.
cdpResolveSource see also
cdpResolveSource query.path
The path to resolve.
cdpResolveSource query.direction
to-local (default, resolves a source-map path to the local disk path) or to-source-map (resolves a local disk path to its source-map path).
cdpResolveSource query.sessionId
Target session ID. Uses the active session when omitted.
cdpReadConsole
Get buffered console output
cdpReadConsole description
Reads captured console output (from CDP Runtime.consoleAPICalled), optionally filtered, with decoded stack traces (mapped back to original source via the loaded source map) attached when available.
cdpReadConsole contract
GET /api/cdp/console
Responses: 200, 400, 404; middleware can also return 403, 408 or 429.
cdpReadConsole see also
cdpReadConsole query.level
Filter to a single console level.
cdpReadConsole query.since
Only return entries with timestamp >= this value (epoch ms).
cdpReadConsole query.limit
Maximum number of entries to return, keeping the most recent. 0 returns none. Defaults to 50.
cdpReadConsole query.sessionId
Target session ID. Uses the active session when omitted.
cdpReadErrors
Get buffered error messages
cdpReadErrors description
Reads captured runtime exceptions (from CDP Runtime.exceptionThrown), with decoded stack traces attached when available.
cdpReadErrors contract
GET /api/cdp/errors
Responses: 200, 400, 404; middleware can also return 403, 408 or 429.
cdpReadErrors see also
cdpReadErrors query.since
Only return entries with timestamp >= this value (epoch ms).
cdpReadErrors query.limit
Maximum number of entries to return, keeping the most recent. 0 returns none. Defaults to 50.
cdpReadErrors query.sessionId
Target session ID. Uses the active session when omitted.
cdpClearConsoleAndErrors
Clear console/error buffers
cdpClearConsoleAndErrors description
Clears both the console and error buffers for a session.
cdpClearConsoleAndErrors contract
POST /api/cdp/console/clear
Responses: 200, 400, 404; middleware can also return 403, 408 or 429.
cdpClearConsoleAndErrors see also
cdpClearConsoleAndErrors body.sessionId
Target session ID. Uses the active session when omitted.
cdpClearConsole
Clear the console buffer
cdpClearConsole description
Clears only the console buffer for a session, leaving the error buffer intact.
cdpClearConsole contract
POST /api/cdp/console/clear-console
Responses: 200, 400, 404; middleware can also return 403, 408 or 429.
cdpClearConsole see also
cdpClearConsole body.sessionId
Target session ID. Uses the active session when omitted.
cdpClearErrors
Clear the error buffer
cdpClearErrors description
Clears only the error buffer for a session, leaving the console buffer intact.
cdpClearErrors contract
POST /api/cdp/console/clear-errors
Responses: 200, 400, 404; middleware can also return 403, 408 or 429.
cdpClearErrors see also
cdpClearErrors body.sessionId
Target session ID. Uses the active session when omitted.
cdpDebuggerPause
Pause execution
cdpDebuggerPause description
Pauses JS execution via CDP Debugger.pause and waits for the resulting Debugger.paused event before returning. Pause only takes effect at the next JS statement the app executes; on an idle app the call times out after 5s and returns 500. Enables the CDP Debugger domain on first use for the current connection.
cdpDebuggerPause contract
POST /api/cdp/debugger/pause
Responses: 200, 400, 404, 500; middleware can also return 403, 408 or 429.
cdpDebuggerPause see also
cdpDebuggerPause body.sessionId
Target session ID. Uses the active session when omitted.
cdpDebuggerResume
Resume execution
cdpDebuggerResume description
Resumes JS execution via CDP Debugger.resume and waits for the resulting Debugger.resumed event before returning. Fails with 500 when the session is not paused.
cdpDebuggerResume contract
POST /api/cdp/debugger/resume
Responses: 200, 400, 404, 500; middleware can also return 403, 408 or 429.
cdpDebuggerResume see also
cdpDebuggerResume body.sessionId
Target session ID. Uses the active session when omitted.
cdpDebuggerStepOver
Step over the next statement
cdpDebuggerStepOver description
Steps over the current line via CDP Debugger.stepOver and waits for the resulting Debugger.paused event before returning. Only valid while already paused; otherwise returns 500.
cdpDebuggerStepOver contract
POST /api/cdp/debugger/step-over
Responses: 200, 400, 404, 500; middleware can also return 403, 408 or 429.
cdpDebuggerStepOver see also
cdpDebuggerStepOver body.sessionId
Target session ID. Uses the active session when omitted.
cdpDebuggerStepInto
Step into the next function call
cdpDebuggerStepInto description
Steps into the function call on the current line via CDP Debugger.stepInto and waits for the resulting Debugger.paused event before returning. Only valid while already paused; otherwise returns 500.
cdpDebuggerStepInto contract
POST /api/cdp/debugger/step-into
Responses: 200, 400, 404, 500; middleware can also return 403, 408 or 429.
cdpDebuggerStepInto see also
cdpDebuggerStepInto body.sessionId
Target session ID. Uses the active session when omitted.
cdpDebuggerStepOut
Step out of the current function
cdpDebuggerStepOut description
Steps out of the current function via CDP Debugger.stepOut and waits for the resulting Debugger.paused event before returning. Only valid while already paused; otherwise returns 500.
cdpDebuggerStepOut contract
POST /api/cdp/debugger/step-out
Responses: 200, 400, 404, 500; middleware can also return 403, 408 or 429.
cdpDebuggerStepOut see also
cdpDebuggerStepOut body.sessionId
Target session ID. Uses the active session when omitted.
cdpSetBreakpoint
Set a breakpoint
cdpSetBreakpoint description
Sets a breakpoint at a TypeScript/source line via CDP Debugger.setBreakpoint. The file and line are mapped to the compiled JS location using the session's loaded source map; a line that cannot be mapped returns 400 with code NO_SOURCE_MAP. Enables the CDP Debugger domain on first use for the current connection.
cdpSetBreakpoint contract
POST /api/cdp/breakpoint/set
Responses: 200, 400, 404, 500; middleware can also return 403, 408 or 429.
cdpSetBreakpoint see also
cdpSetBreakpoint body.file
Local source file path, as returned by the source list or resolve routes.
cdpSetBreakpoint body.line
1-based line number in that source file.
cdpSetBreakpoint body.condition
JS expression; the breakpoint only triggers when it evaluates truthy.
cdpSetBreakpoint body.sessionId
Target session ID. Uses the active session when omitted.
cdpRemoveBreakpoint
Remove a breakpoint by ID
cdpRemoveBreakpoint description
Removes a previously-set breakpoint via CDP Debugger.removeBreakpoint. An unknown breakpointId returns 404.
cdpRemoveBreakpoint contract
POST /api/cdp/breakpoint/remove
Responses: 200, 400, 404, 500; middleware can also return 403, 408 or 429.
cdpRemoveBreakpoint see also
cdpRemoveBreakpoint body.breakpointId
The breakpointId of a breakpoint returned by set or list.
cdpRemoveBreakpoint body.sessionId
Target session ID. Uses the active session when omitted.
cdpListBreakpoints
List all breakpoints
cdpListBreakpoints description
Lists all breakpoints currently tracked for a session, with their source location, compiled line, condition and active flag.
cdpListBreakpoints contract
GET /api/cdp/breakpoint/list
Responses: 200, 404; middleware can also return 403, 408 or 429.
cdpListBreakpoints see also
cdpListBreakpoints query.sessionId
Target session ID. Uses the active session when omitted.
cdpGetDebuggerState
Get current debugger state
cdpGetDebuggerState description
Returns the cached pause state from the last Debugger.paused event, with call frames mapped to original source when a source map is loaded. Never sends a CDP request.
cdpGetDebuggerState contract
GET /api/cdp/debugger/state
Responses: 200, 404; middleware can also return 403, 408 or 429.
cdpGetDebuggerState see also
cdpGetDebuggerState query.sessionId
Target session ID. Uses the active session when omitted.
cdpEvaluateOnCallFrame
Evaluate an expression in a stack frame
cdpEvaluateOnCallFrame description
Evaluates an expression in a paused call frame's scope via CDP Debugger.evaluateOnCallFrame, for access to its locals and closures. result is the raw CDP response. Returns 409 when the debugger is not paused.
cdpEvaluateOnCallFrame contract
POST /api/cdp/debugger/eval-frame
Responses: 200, 400, 404, 409, 500; middleware can also return 403, 408 or 429.
cdpEvaluateOnCallFrame see also
cdpEvaluateOnCallFrame body.callFrameId
Call frame ID to evaluate in.
cdpEvaluateOnCallFrame body.expression
Expression to evaluate.
cdpEvaluateOnCallFrame body.sessionId
Target session ID. Uses the active session when omitted.
cdpStartCpuProfile
Start a CPU profiling capture
cdpStartCpuProfile description
Starts a CPU profiling capture via CDP Profiler.start. The capture is written to a .cpuprofile file under the project root; the response is a handle, not the profile. Only one active CPU capture per session is allowed; a duplicate start returns 409 CAPTURE_ALREADY_ACTIVE.
cdpStartCpuProfile contract
POST /api/cdp/profile/start
Responses: 200, 400, 404, 409, 500; middleware can also return 403, 408 or 429.
cdpStartCpuProfile see also
cdpStartCpuProfile body.sessionId
Target session ID. Uses the active session when omitted.
cdpStartCpuProfile body.samplingHz
Sampling frequency in Hz. Defaults to 100 Hz.
cdpStartCpuProfile body.streamIntervalMs
Profiler.start stream interval in milliseconds.
cdpStartCpuProfile body.durationMs
If set, the server automatically stops and writes the capture after this many milliseconds.
cdpStartCpuProfile body.output
Output .cpuprofile file path (must stay within project root). Auto-generated under the project root when omitted.
cdpStopCpuProfile
Stop a CPU profiling capture and write the .cpuprofile
cdpStopCpuProfile description
Stops an active CPU profiling capture and writes the .cpuprofile to disk. The response includes metadata only.
cdpStopCpuProfile contract
POST /api/cdp/profile/stop
Responses: 200, 400, 404, 409, 500; middleware can also return 403, 408 or 429.
cdpStopCpuProfile see also
cdpStopCpuProfile body.sessionId
Target session ID. Uses the active session when omitted.
cdpStopCpuProfile body.captureId
Handle returned by profile start. Stops the active capture when omitted.
cdpTakeHeapSnapshot
Capture a heap snapshot to a .heapsnapshot file
cdpTakeHeapSnapshot description
Captures a heap snapshot via CDP HeapProfiler.takeHeapSnapshot and writes it to a .heapsnapshot file as chunks arrive. The call blocks until the whole snapshot is written (up to two minutes on a large heap); the response is metadata only. A concurrent request returns 409 SNAPSHOT_ALREADY_ACTIVE.
cdpTakeHeapSnapshot contract
POST /api/cdp/heap/snapshot
Responses: 200, 400, 404, 409, 500; middleware can also return 403, 408 or 429.
cdpTakeHeapSnapshot see also
cdpTakeHeapSnapshot body.sessionId
Target session ID. Uses the active session when omitted.
cdpTakeHeapSnapshot body.output
Output .heapsnapshot file path (must stay within project root). Auto-generated under the project root when omitted.
cdpStartHeapSampling
Start a lightweight heap allocation sampling capture
cdpStartHeapSampling description
Starts a heap allocation sampling capture via CDP HeapProfiler.startSampling. The response is a handle only; stop the capture to write the .heapprofile. Only one active heap sampling capture per session is allowed; a duplicate start returns 409 SAMPLING_ALREADY_ACTIVE.
cdpStartHeapSampling contract
POST /api/cdp/heap/sampling/start
Responses: 200, 400, 404, 409, 500; middleware can also return 403, 408 or 429.
cdpStartHeapSampling see also
cdpStartHeapSampling body.sessionId
Target session ID. Uses the active session when omitted.
cdpStartHeapSampling body.samplingIntervalBytes
Average number of bytes allocated between samples. Defaults to 32768.
cdpStartHeapSampling body.output
Output .heapprofile file path (must stay within project root). Auto-generated under the project root when omitted.
cdpStopHeapSampling
Stop a heap sampling capture and write the .heapprofile
cdpStopHeapSampling description
Stops an active heap sampling capture and writes the .heapprofile to disk. It only shows allocations still live at this stop call, not total allocation churn since start. The response includes metadata only.
cdpStopHeapSampling contract
POST /api/cdp/heap/sampling/stop
Responses: 200, 400, 404, 409, 500; middleware can also return 403, 408 or 429.
cdpStopHeapSampling see also
cdpStopHeapSampling body.sessionId
Target session ID. Uses the active session when omitted.
cdpStopHeapSampling body.captureId
Handle returned by heap sampling start. Stops the active capture when omitted.
Updated about 4 hours ago