compute
POST /v1/compute/servers/{serverId}/console
Open an out-of-band console onto a server.
Authentication
Send an API key as a bearer token. The key must carry the sites.restart permission; a key without it is refused with 403, not 404.
This endpoint takes no organisation id. Your key already identifies the organisation it belongs to, and the response is scoped to it.
Try it
Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.
curl -X POST https://api.zinndigital.com/v1/compute/servers/{serverId}/console \
-H "Authorization: Bearer zdk_live_…"Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console
Details
⭐⭐ The control that works when SSH does not — a bad firewall rule, a broken sshd config, a full disk, a kernel that will not boot. It is what turns "my server is unreachable, open a ticket" into something the customer fixes themselves. ⛔ POST, not GET, because it MINTS a credential. It is not idempotent, not cacheable, and must never end up in a browser history, a proxy log or a prefetch. The response carries a one-shot URL that reaches the machine's console as if sitting at its keyboard; it is returned once and stored nowhere. Every call is audit-logged — that one was opened and by whom, never the URL or the password. ⛔⛔ A wss address is ours and is SINGLE-USE (W43-49). It is relayed by Zinn®'s own gateway, so the session's url names api.zinndigital.com and never the machine's supplier; a client that needs a second connection calls this again rather than reconnecting with the first address. 503 on a range whose provider offers no console. Requires sites.restart.
Parameters
| Name | Type | Required | What it is |
|---|---|---|---|
serverId (path) | Uuid | Yes | The server's id, as listComputeServers reports it. Ours (UUIDv7), minted when the order row was written — never the provider's own identifier for the machine. |
Response
| Name | Type | Required | What it is |
|---|---|---|---|
url | string | Yes | The console address, for kind: url (a page a browser opens) and kind: wss (a WebSocket endpoint a VNC client connects to). ⛔… |
password | string | Yes | The password the console asks for, when the provider issues one alongside the URL. "" when the URL alone authenticates. |
expires_at | string | Yes | When it stops working, ISO-8601, or "" when the provider does not say. ⛔ Blank does not mean "never" — these last minutes by design. A url and a wss console are both… |
kind | string<url, wss, vnc> | Yes | ⛔⛔ THREE genuinely different consoles, not three spellings of one, and wss was missing (W22-B, D10906). url is a page a browser opens. wss is a one-shot WebSocket… |
host | string | Yes | The VNC host, for kind: vnc. ⛔ May be blank, and that is a refusal rather than a gap: where the only hostname a supplier states is its own branded one, we do not pass it on. |
port | integer | Yes | The VNC port, 0 when the provider does not state one. |
allowed_ips | string[] | Yes | The addresses currently permitted to reach the console. ⛔⛔ An empty list on an IP-restricted console means NOBODY may connect — the exact opposite of the "no restriction" an… |
ip_restricted | boolean | Yes | Whether the caller's address must be allow-listed before anything can connect. false means the credential alone is enough. |
Errors this endpoint can return
401 · 403 · 404 · 422 · 429 · 503