API reference

Terminal API

Open an interactive login shell in a running machine over a WebSocket. Browsers first mint a single-use ticket.

Open a terminal: GET /v1/machines/{machine_id}/terminal
Create a terminal ticket: POST /v1/machines/{machine_id}/terminal/tickets

Open a terminal

GET /v1/machines/{machine_id}/terminal

Opens an interactive login shell over a WebSocket (Upgrade: websocket). A browser session presents its cookie, an Origin the service serves the UI from, and ticket from POST .../terminal/tickets; the CLI presents Authorization: Bearer with a use_existing or higher key. After the upgrade the server sends {"type":"opened"}, then binary messages carry terminal output and the client's binary messages are stdin; text messages are JSON control (TerminalClientMessage in, TerminalServerMessage out). exit or closed is final and the server closes the WebSocket.

This is a WebSocket upgrade, not a JSON request: connect with a WebSocket client (wss://), not curl. A browser adds ticket, cols, and rows to the ticket's url and must connect from the console's origin. Messages, limits, and close reasons are in the Web terminal guide.

API key: Authorization: Bearer vmy_… with preset use_existing, create_and_use, full_access.
Browser session: the vmyard_session cookie.
Who: Owner, Admin, or Operator.

Parameters

Name	In	Type	Required	Description
`machine_id`	path	`string (uuid)`	Yes
`ticket`	query	`string`	No	Required with a session cookie; refused with an API key.
`cols`	query	`integer`	No	Initial width, 1-1000 (default 80).
`rows`	query	`integer`	No	Initial height, 1-1000 (default 24).

Responses

Status	Description	Body
`101`	Switching protocols: the terminal is open	—
`400`	Not a WebSocket upgrade request	`ProblemDetails`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`403`	`forbidden` (Viewer or Billing), `insufficient_scope` (a `read_only` key), `origin_not_allowed`, or `terminal_ticket_invalid` (missing, expired, used, or for another machine or session)	`ProblemDetails`
`404`	Not found in this organization (`resource_not_found`).	`ProblemDetails`
`409`	`machine_not_running`, `machine_not_created`, `machine_deleted`, or `terminal_refused` (the runtime refused it, for example at its host or machine limit)	`ProblemDetails`
`422`	Invalid `cols` or `rows`	`ProblemDetails`
`429`	`terminal_limit_reached` (per-user or per-organization concurrency) or `rate_limited` (opens per minute)	`ProblemDetails`
`503`	`terminals_unavailable` or `runtime_unavailable`	`ProblemDetails`

Request

curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/terminal" \
  -H "Authorization: Bearer $VMYARD_API_KEY"

Create a terminal ticket

POST /v1/machines/{machine_id}/terminal/tickets

The ticket is valid once, for 30 seconds, for this machine and the session that minted it. API keys open the terminal directly instead (403 session_required).

API key: not accepted (403 session_required).
Browser session: the vmyard_session cookie and the x-csrf-token header.
Who: Owner, Admin, or Operator.

Parameters

Name	In	Type	Required	Description
`machine_id`	path	`string (uuid)`	Yes
`X-Organization-ID`	header	`string (uuid)`	No	Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.

Responses

Status	Description	Body
`201`	A single-use ticket for `GET /v1/machines/{machine_id}/terminal`, valid 30 s, redeemable only by the minting session	`TerminalTicketDto`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`403`	Viewer or Billing (`forbidden`), a bad CSRF token, or an API key (`session_required`: keys open terminals directly)	`ProblemDetails`
`404`	Not found in this organization (`resource_not_found`).	`ProblemDetails`
`409`	`machine_not_running`, `machine_not_created` (its create is pending or failed), or `machine_deleted`	`ProblemDetails`
`429`	Too many requests; wait for `Retry-After`.	`ProblemDetails`
`503`	`terminals_unavailable`	`ProblemDetails`

Request

curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/terminal/tickets" \
  -b "vmyard_session=$VMYARD_SESSION" \
  -H "x-csrf-token: $VMYARD_CSRF" \
  -H "X-Organization-ID: $VMYARD_ORGANIZATION_ID"

Response 201

{
  "expires_at": "string",
  "ticket": "string",
  "url": "https://hooks.example.com/vmyard"
}