HTTP server
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.
Any other path under /api that no route matches answers 404 with the shared HttpError body and code ENDPOINT_NOT_FOUND. That catch-all is not an operation; openapi.json publishes it as the EndpointNotFound response component.
getHealth
Report server health
getHealth description
Reports that the server is up, with its port, process ID, uptime, start time and root directory, the number of open log, Perfetto, CDP and debug sessions, the lifecycle mode and active client lease count, device configuration cache and file watcher statistics, and where the server reads its RCE token from (env, file or none, never the token itself). leaseTtlMs is present only in managed lifecycle mode, and watcher is null when no configuration file watcher is running. rk server start --detach and rk server status read this route. It is exempt from the rate limiter and does not count as activity for the inactivity timeout. A server with extensions enabled adds one key per extension; those keys are not documented here.
getHealth contract
GET /api/health
Responses: 200; middleware can also return 403, 408 or 429.
getHealth see also
registerClient
Register a client lease
registerClient description
Registers a client lease, or refreshes an existing one with the same clientId, keeping its original creation time. Registering cancels any pending zero-client shutdown. The response gives the lease TTL (90 seconds) and the heartbeat interval clients should use (30 seconds). Available only when the server was started with --lifecycle managed; otherwise the route answers 409 LIFECYCLE_UNMANAGED. A missing or empty clientId answers 400 INVALID_CLIENT_ID. Optional fields that are not strings are ignored rather than rejected.
registerClient contract
POST /api/clients/register
Responses: 200, 400, 409; middleware can also return 403, 408 or 429.
registerClient body.clientId
Opaque, non-empty client identifier chosen by the client; one per VS Code window.
registerClient body.workspaceRoot
Workspace root of the client, kept for diagnostics and listed by the status route.
registerClient body.clientType
Client type, kept for diagnostics.
registerClient body.clientVersion
Client version, kept for diagnostics.
heartbeatClient
Renew a client lease
heartbeatClient description
Renews an existing client lease and cancels any pending zero-client shutdown. A lease that is not renewed within its TTL is pruned. An unknown or already pruned clientId answers 404 CLIENT_NOT_FOUND, and the client should register again. Available only in managed lifecycle mode; otherwise the route answers 409 LIFECYCLE_UNMANAGED.
heartbeatClient contract
POST /api/clients/heartbeat
Responses: 200, 400, 404, 409; middleware can also return 403, 408 or 429.
heartbeatClient body.clientId
Opaque, non-empty client identifier chosen by the client; one per VS Code window.
releaseClient
Release a client lease
releaseClient description
Releases a client lease. Releasing an unknown clientId still succeeds, so a client can release on deactivate without checking first. When no leases remain, the server shuts down after a 10-second grace period unless a client registers or renews in the meantime. Available only in managed lifecycle mode; otherwise the route answers 409 LIFECYCLE_UNMANAGED.
releaseClient contract
POST /api/clients/release
Responses: 200, 400, 409; middleware can also return 403, 408 or 429.
releaseClient body.clientId
Opaque, non-empty client identifier chosen by the client; one per VS Code window.
getClientStatus
List client leases
getClientStatus description
Lists the lifecycle mode and the active client leases, with each lease's clientId, workspaceRoot (when the client gave one) and last heartbeat time in milliseconds since the epoch. Unlike the other lease routes it also answers in unmanaged mode, reporting zero active clients, an empty list and no leaseTtlMs.
getClientStatus contract
GET /api/clients/status
Responses: 200; middleware can also return 403, 408 or 429.
stopServer
Stop the server
stopServer description
Answers success, then stops the server: it first stops the RCE devices the server started through MCP device_start, then closes its sessions, then the listener (forced after 10 seconds), and finally the server process exits. The response arrives before shutdown completes; rk server stop waits for the process to exit. The route takes no request body.
stopServer contract
POST /api/stop
Responses: 200; middleware can also return 403, 408 or 429.
Updated about 3 hours ago