API reference

Every route of the VMYard Product API: authentication, conventions, and endpoint groups.

The VMYard Product API (version 1.0.0) has 147 operations in 29 groups. Every page here is generated from the control plane's OpenAPI document when the docs are built.

Base URL

Send requests to your VMYard API origin, for example https://api.example.com. The clients read it from VMYARD_API_URL; there is no default, so a key is never sent to a guessed host. Every path starts with /v1.

Authentication

Most routes accept an organization API key (Authorization: Bearer vmy_…). The key fixes the organization, so X-Organization-ID is optional and must match when sent. Browser sessions use the vmyard_session cookie plus the x-csrf-token header on changes, and must send X-Organization-ID. API key management, sign-in, and device approval accept only a browser session. See API keys and presets.

Scheme	Type	Description
`api_key`	HTTP bearer	Organization-scoped API key. Bearer requests skip CSRF, and X-Organization-ID becomes optional but must match the key's organization when sent. The key's preset and its creator's current role bound the action. Key management routes reject API keys.
`csrf_token`	apiKey in header `x-csrf-token`	—
`session_cookie`	apiKey in cookie `vmyard_session`	—

Requests and responses

Bodies are JSON (Content-Type: application/json). Request bodies refuse unknown fields.
Changes to machines return 202 Accepted with an operation to follow. See Operations and idempotency.
Changes that create operations require an Idempotency-Key header. Reusing a key with the same body returns the original operation; with a different body it is 409 idempotency_conflict.
Lists return {items, next_cursor}. Pass next_cursor back as cursor until it is null.
Money is integer micros of USD (1,000,000 micros = $1). Times are UTC RFC 3339.
Errors are application/problem+json with a stable code. See Errors.

Groups

Group	Operations	Description
Machines	9	Create, list, read, change, start, stop, restart, and delete machines. Every lifecycle change is an asynchronous operation.
Operations	2	Read an operation's status and result, or follow its persisted events as server-sent events.
Machine metrics	1	Read a machine's CPU, memory, disk, I/O, and network history at one-minute resolution, or the host's live samples.
Exec	1	Run a foreground command inside a machine, optionally streaming its output as NDJSON frames.
Background commands	3	Start detached commands, read their status and log, and kill them.
Terminal	2	Open an interactive login shell in a running machine over a WebSocket. Browsers first mint a single-use ticket.
Desktop	2	View a running machine's graphical desktop, or only its web browser, over a WebSocket carrying VNC. Browsers first mint a single-use ticket.
Agents	6	Run a coding agent (Claude Code, Codex, or Pi) inside a running machine: prompt it, follow its events, steer or interrupt a running turn, and resume conversations.
Command history	3	Search a machine's past commands, read one entry, and page through its stored stdout and stderr.
Snapshots and templates	13	Push a stopped machine, save it as a named template, and copy a machine with fork or restore.
Files	2	Write and read files inside a machine's `/work` directory.
File browser	2	List a running machine's folders under `/work`, `/root`, or `/home` as a live tree, and download a folder as a `.tar.gz` archive.
Ports and SSH	6	Expose guest ports as HTTPS URLs, issue access tokens for private ports, and install an SSH key.
Environments	12	Named, versioned sets of environment variables and secret files that VMYard applies to machines.
Catalog	3	The plans, images, and regions a machine is created from, each selected by ID and exact version.
Billing and usage	18	Balances, limits, metered usage, invoice preview, and billing management.
Webhooks	7	Register HTTPS endpoints for signed lifecycle events and inspect their deliveries.
Email alerts	4	Read and change your email alert preferences, and the unsubscribe link every alert email carries.
Organizations	4	List, read, create, and rename the organizations the caller belongs to.
Waitlist and access	8	Invite-only access: the form service's sign-up hook, and for the people who run the service, the waitlist and access grants. Operator routes need the operator token.
Members and invitations	11	List an organization's members, change roles, remove members, invite by email, accept invitations, transfer ownership, delete an organization, and choose the active organization. These routes need a browser session.
Capacity (operators)	5	For the people who run the service: the capacity loop's decisions, the budget guard, and the server purchases waiting for approval. These routes need the operator token.
API keys	4	Create, list, rotate, and revoke organization API keys. These routes need a browser session.
Identity	1	The signed-in user or API key caller and their memberships.
Sign-in	4	Browser sign-in with a configured provider, and sign-out.
Email sign-in	3	Sign in with an emailed 6-digit code or magic link.
Sign-in methods	2	Link another sign-in method to the signed-in user, or remove one.
Operator	4	For the people who run the service: suspend an organization or lift a suspension, and review the abuse guard's flags. These routes need the operator token.
Device authorization	5	The RFC 8628 device grant that `vy login` uses to receive an API key.
Schemas	—	Every request and response body.