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.

Establish (or re-establish) the web console connection for an instance

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

Establishes the UI-requested console connection for the selected instance in the active tenant/subscription/project scope, as triggered by the "Connect" action button in the instance console page. The API allocates (or refreshes) a console session and returns the full session facts the console page renders: the wss:// endpoint with an embedded one-time console token, protocol (RFB/noVNC), frame encoding, TLS cipher, resolution, keyboard layout, clipboard policy, token expiry and session start time. Re-connecting after a disconnect resets the framebuffer epoch so the boot stream replays from the beginning. Validation: scopeId must be accessible to the caller (404 via ErrNotFound when unknown); instanceId must identify an instance in that scope (404 NOT_FOUND otherwise); the instance's current state must permit a console connection — an instance that is deleted or in a state that cannot accept console sessions maps to 409 CONFLICT. Async & state: Synchronous command returning 200 with the established ConsoleSession; the session transitions connecting → connected server-side and the console badge state is surfaced to other open consoles via resource.updated SSE frames of kind compute.consoleSession (patch: state, startedAt, tokenExpiresAt). No durable instance state is changed. Errors: 401 unauthenticated; 403 caller lacks an instance-console-capable role (owner|admin|contributor) on the scope; 404 unknown scopeId or instanceId; 409 when the instance state does not permit connect (e.g. stopped/terminating); 422 on malformed input; 500 on console-broker failure. Idempotency/Concurrency: Send an Idempotency-Key; replaying the same key returns the same session (same token and wsUrl) instead of allocating a second session. Concurrent connects to the same instance from the same principal coalesce onto one session.

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 whose console is being connected.

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

Console session established; session facts including the one-time console token (revealed only in this response).

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