Compute

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)

POST
/scopes/{scopeId}/compute/instances/{instanceId}/console/actions/connect-console

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.

Authorization

bearerToken
headerAuthorizationBearer <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.

Path Parameters

scopeId*string

Opaque ownership+authorization scope resolving to tenant + subscription + project.

instanceId*string

Identifier of the compute instance for which an interactive console session is created.

Header Parameters

Idempotency-Key?string

Optional; 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.

Formatuuid

Response Body

Interactive console session created; includes the one-time console token (revealed only here).

application/json
  1. 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*string

WebSocket endpoint for the VNC stream, including the embedded one-time console token.

host*string

A label shown with the connection details (console.<region>), not an address: the console connects through wsUrl.

protocol*string

Remote framebuffer protocol descriptor (e.g. "RFB 003.008 (noVNC)").

encoding*string

Frame encoding negotiated for the session (e.g. "Tight + zlib (compression 6)").

cipher*string

Transport security descriptor (e.g. "TLS 1.3 · AES-256-GCM").

resolution*string

Framebuffer resolution (e.g. "1024×768").

latencyMs*integer

Measured round-trip latency to the console broker in milliseconds.

keyboard*string

Keyboard layout applied to the session (e.g. "en-US (auto-detected)").

clipboard*string

Clipboard policy for the session (e.g. "Paste to guest only").

token*string

One-time console token. Sensitive — returned only in the session-creating response, never in reads.

tokenExpiresAt*string

ISO-8601 timestamp at which the console token expires.

startedAt*string

ISO-8601 timestamp at which the session started.

osName*string

Guest operating system name (e.g. "Ubuntu 24.04.2 LTS").

kernel*string

Guest kernel version (e.g. "6.8.0-41-generic").

display*string

Guest 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"}