Preview — pending review
This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.
Create an interactive console session for an instance (console route load)
Creates an interactive web console session for the selected instance when the console route
(/compute/instances/{instanceId}/console) is opened and its connect controls fire. Unlike the
in-page re-connect action, this is the session-bootstrap command: it authorizes the caller
against Identity, resolves the instance's Network attachment for the guest IP/MAC facts shown in
the "Connection details" panel, provisions a console broker endpoint and mints the console
token. The returned ConsoleSession drives both the VNC tab and the serial log tab.
Validation: scopeId must be accessible (404 when unknown); instanceId must exist in the
scope (404 NOT_FOUND); the instance state must permit an interactive console (409 CONFLICT when
it does not, e.g. while terminating); identity and network references resolved during bootstrap
must be accessible (404/409 with an actionable ApiError otherwise).
Async & state: Synchronous command returning 200 with the new ConsoleSession in its
connecting/connected handshake; the broker-side handshake completes within the session and state
flips connecting → connected, surfaced via resource.updated SSE frames of kind
compute.consoleSession (patch: state). No durable instance state is mutated.
Errors: 401 unauthenticated; 403 caller lacks console access on the scope
(owner|admin|contributor); 404 unknown scopeId/instanceId; 409 instance state forbids an
interactive console; 422 malformed input; 500 broker/identity/network resolution failure.
Idempotency/Concurrency: Send an Idempotency-Key; replays return the already-created
session rather than minting a new token. A fresh route load after token expiry creates a new
session; expired tokens are rejected by the broker, never silently renewed.
bearerTokenAuthorizationBearer <token>An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
instanceId*stringIdentifier of the compute instance for which an interactive console session is created.
Idempotency-Key?stringOptional; recommended for safe retries. When sent, the same key+body within 24h replays the original result and the same key with a different body is 409 CONFLICT; keys are unique per tenant. When an API token or service-account (bearer) caller omits it, the request is applied once with no replay protection (a retry may apply it again). A console session gets one from the edge.
uuidInteractive console session created; includes the one-time console token (revealed only here).
application/json- response
Established web console session for an instance. The token is sensitive and is revealed only in the connect/connect-console response that creates the session.
wsUrl*stringWebSocket endpoint for the VNC stream, including the embedded one-time console token.
host*stringA label shown with the connection details (console.<region>), not an address: the console connects through wsUrl.
protocol*stringRemote framebuffer protocol descriptor (e.g. "RFB 003.008 (noVNC)").
encoding*stringFrame encoding negotiated for the session (e.g. "Tight + zlib (compression 6)").
cipher*stringTransport security descriptor (e.g. "TLS 1.3 · AES-256-GCM").
resolution*stringFramebuffer resolution (e.g. "1024×768").
latencyMs*integerMeasured round-trip latency to the console broker in milliseconds.
keyboard*stringKeyboard layout applied to the session (e.g. "en-US (auto-detected)").
clipboard*stringClipboard policy for the session (e.g. "Paste to guest only").
token*stringOne-time console token. Sensitive — returned only in the session-creating response, never in reads.
tokenExpiresAt*stringISO-8601 timestamp at which the console token expires.
startedAt*stringISO-8601 timestamp at which the session started.
osName*stringGuest operating system name (e.g. "Ubuntu 24.04.2 LTS").
kernel*stringGuest kernel version (e.g. "6.8.0-41-generic").
display*stringGuest display identifier (e.g. ":0 (ttyS0 mirrored)").
curl -X POST "https://example.com/scopes/string/compute/instances/string/console/actions/connect-console"{ "wsUrl": "string", "host": "string", "protocol": "string", "encoding": "string", "cipher": "string", "resolution": "string", "latencyMs": 0, "keyboard": "string", "clipboard": "string", "token": "string", "tokenExpiresAt": "string", "startedAt": "string", "osName": "string", "kernel": "string", "display": "string"}