# VMYard documentation

> VMYard runs isolated Linux machines for agents and developers. You create a machine from a plan, image, and region; run commands in it with streamed output; move files in and out of /work; expose ports as HTTPS URLs; reach it over SSH; and stop, start, or delete it. Every change is an idempotent operation you can follow to its observed result. Use the vy CLI, the TypeScript or Python SDK, or the HTTP API.

---

<!-- Source: /docs/index.md -->

# VMYard documentation

> Isolated Linux machines you create, run commands in, and reach over HTTPS and SSH, from the CLI, the SDKs, or the HTTP API.

VMYard gives you isolated Linux machines on demand. Create a machine from a plan, an image, and a region; run commands in it and stream their output; move files in and out of its `/work` directory; open its ports as HTTPS URLs; reach it over SSH; and stop, start, or delete it when you are done. You pay per second while a machine runs.

Every change is an **operation**. The API accepts it, a worker carries it out, and the operation only reports success once VMYard has observed the result on the machine's host. Each change carries an idempotency key, so a retry after a dropped connection never creates a second machine or runs a command twice.

## Start here

- [Quickstart](/docs/quickstart): sign in, get an API key, and run your first machine in about five minutes.
- [Machines](/docs/concepts/machines): what a machine is and what it is made of.
- [Operations and idempotency](/docs/concepts/operations): how changes are accepted, tracked, and retried.
- [API reference](/docs/api): every route, generated from the OpenAPI document.

## Ways to use VMYard

| Tool | Use it for |
| --- | --- |
| [Console](/) | Signing in, API keys, webhooks, billing, and day-to-day machine work in the browser. |
| [`vy` CLI](/docs/cli) | Terminal and scripting: `vy new`, `vy exec`, `vy cp`, `vy usage`. |
| [TypeScript SDK](/docs/sdk/typescript) | Node.js 20+ applications and agents (`@vmyard/sdk`). |
| [Python SDK](/docs/sdk/python) | Python 3.9+ applications and agents (`vmyard-sdk`). |
| [HTTP API](/docs/api) | Anything else. JSON over HTTPS with `Authorization: Bearer vmy_…`. |

## What you can do today

- Create, list, rename, start, stop, restart, and delete machines; choose plan, image, and region from a versioned [catalog](/docs/concepts/catalog).
- [Run commands](/docs/guides/commands) with streamed output, and [background commands](/docs/guides/background-commands) with logs.
- [Write and read files](/docs/guides/files) up to 32 MiB.
- [Expose ports](/docs/guides/ports) as public or token-protected HTTPS URLs, and connect over [SSH](/docs/guides/ssh).
- Run a [setup script](/docs/guides/setup-scripts) once when a machine first starts.
- Keep variables and secret files in encrypted, versioned [environments](/docs/guides/environments) that VMYard installs in machines.
- Push stopped machines as [snapshots](/docs/guides/snapshots), save [templates](/docs/guides/templates), and [fork or restore](/docs/guides/fork-and-restore) machines into new ones.
- Stop idle spend with [auto-stop](/docs/concepts/auto-stop) and opt-in [idle sleep](/docs/concepts/idle-sleep).
- Receive signed [webhooks](/docs/guides/webhooks) when lifecycle operations finish.
- Track [usage, balances, and limits](/docs/guides/billing).

## Waking a machine

VMYard does not wake a stopped machine when a request arrives for it; start it to wake it. See [Sleep and wake](/docs/concepts/sleep-and-wake).

## For agents and LLMs

Every page is also available as Markdown: add `.md` to its URL, or use **Copy page** at the top. [/llms.txt](/llms.txt) lists every page, and [/llms-full.txt](/llms-full.txt) holds the whole documentation in one file.

---

<!-- Source: /docs/quickstart.md -->

# Quickstart

> Sign in, get an API key, and create, use, reach, stop, and delete your first machine with the CLI, TypeScript, or Python.

This guide takes you from a new account to a running machine and back. Each step shows the `vy` CLI, the TypeScript SDK, and the Python SDK; pick a tab once and every example on the page follows it. Port and SSH steps use the HTTP API so every client can follow them; the CLI also has `vy ports` and `vy ssh`.

## 1. Sign in

Open the VMYard console and sign in with one of the methods it offers, such as GitHub, Google, or a 6-digit code sent to your email. Your first sign-in creates your VMYard user. See [Sign-in methods](/docs/guides/sign-in).

> [!NOTE]
> Organizations are set up by your VMYard operator. If the console says **No organizations available**, ask them to add you; machines, keys, and billing all belong to an organization.

## 2. Install the tools

The CLI and SDKs are in private preview and are not published to npm or PyPI. Get access to the [erphq/vmyard-sdk](https://github.com/erphq/vmyard-sdk) repository from your VMYard contact, then build from a checkout:

```sh tab="CLI"
git clone https://github.com/erphq/vmyard-sdk.git
cd vmyard-sdk && npm ci && npm run build
npm install -g ./cli
```

```sh tab="TypeScript"
git clone https://github.com/erphq/vmyard-sdk.git
cd vmyard-sdk && npm ci && npm run build
cd your-project && npm install ../vmyard-sdk/typescript
```

```sh tab="Python"
git clone https://github.com/erphq/vmyard-sdk.git
pip install ./vmyard-sdk/python
```

The CLI needs Node.js 20 or newer, the TypeScript SDK Node.js 20 or newer, and the Python SDK Python 3.9 or newer. None of them has a default server: set `VMYARD_API_URL` to your API origin.

```sh
export VMYARD_API_URL=https://api.example.com   # your VMYard API origin
```

## 3. Get an API key

With the CLI, `vy login` opens the console, you approve the request, and the CLI stores a new API key. See [CLI device login](/docs/guides/cli-login).

```sh tab="CLI"
vy login
vy whoami
```

```ts tab="TypeScript"
// Create a key in the console: API keys → Create key → preset "Create and use".
// The SDK reads VMYARD_API_KEY and VMYARD_API_URL from the environment.
import { VMYard } from "@vmyard/sdk";

const vy = new VMYard();
console.log(await vy.me());
```

```python tab="Python"
# Create a key in the console: API keys -> Create key -> preset "Create and use".
# The SDK reads VMYARD_API_KEY and VMYARD_API_URL from the environment.
from vmyard import VMYard

vy = VMYard()
print(vy.me())
```

For the SDKs, create a key in the console under **API keys** with the **Create and use** preset and export it as `VMYARD_API_KEY`. The secret (`vmy_…`) is shown once. See [API keys and presets](/docs/guides/api-keys).

## 4. Create a machine

Pick a plan from the catalog (`vy plans`), or let the client use the first one. `--auto-stop 2` stops the machine two hours after it starts so a forgotten machine doesn't keep billing.

```sh tab="CLI"
vy plans
vy new --plan small --name dev --auto-stop 2 --wait
```

```ts tab="TypeScript"
const machine = await vy.machines.create({
  name: "dev",
  plan: "small",
  autoStopAfterSeconds: 2 * 3600,
}); // resolves when the create operation succeeds
console.log(machine.data.id, machine.data.observed_state);
```

```python tab="Python"
machine = vy.machines.create(name="dev", plan="small", auto_stop_after_seconds=2 * 3600)
print(machine.id, machine.state)
```

Creating returns an operation; the CLI (with `--wait`) and the SDKs wait until it succeeds, which means VMYard observed the machine running. See [Operations and idempotency](/docs/concepts/operations).

## 5. Run a command

```sh tab="CLI"
vy exec dev -- uname -a
vy exec dev -c 'cd /work && echo hello > hello.txt && ls -l'
```

```ts tab="TypeScript"
const result = await machine.exec("uname -a");
console.log(result.exitCode, result.stdout);

for await (const frame of machine.exec(["ls", "-l", "/work"], { stream: true })) {
  if (frame.type === "stdout") process.stdout.write(frame.data);
}
```

```python tab="Python"
result = machine.exec("uname -a")
print(result.exit_code, result.stdout)

with machine.exec(["ls", "-l", "/work"], stream=True) as stream:
    for frame in stream:
        if frame.type == "stdout":
            print(frame.data.decode(), end="")
```

The CLI streams output as it arrives and exits with the command's exit code. See [Running commands](/docs/guides/commands).

## 6. Open a port

Start a web server as a [background command](/docs/guides/background-commands), then expose its port. Private ports (the default) need a short-lived token.

```ts tab="TypeScript"
await machine.commands.start("python3 -m http.server 8080");
```

```python tab="Python"
machine.commands.start("python3 -m http.server 8080")
```

```sh tab="curl"
MACHINE_ID=$(vy get dev --json | jq -r .id)

curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/commands" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"command": "python3 -m http.server 8080"}'
```

```sh title="Expose port 8080 and get a link (HTTP API)"
MACHINE_ID=$(vy get dev --json | jq -r .id)   # or machine.data.id in the SDKs

curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/ports" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"port": 8080}'

curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/ports/8080/token" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl_seconds": 900}'
```

Exposing a port is an operation: follow the returned `operation_url` until it succeeds. Open `url_with_token` from the token response in a browser. The example assumes the image has `python3`; use any server your image provides. See [Ports and private URLs](/docs/guides/ports).

> [!NOTE]
> When you signed in with `vy login`, the key lives in the CLI's config file rather than in `VMYARD_API_KEY`. For the HTTP examples, export a key you created in the console.

## 7. Connect over SSH

Install your public key; VMYard allocates an SSH gateway port and reports how to connect in the machine's `ssh` field.

```sh title="Install a key and connect (HTTP API)"
curl -X PUT "$VMYARD_API_URL/v1/machines/$MACHINE_ID/ssh-key" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{\"public_key\": \"$(cat ~/.ssh/id_ed25519.pub)\"}"

# After the operation succeeds:
vy get dev --json | jq .ssh      # {"host": "...", "port": 2201, "user": "vmyard"}
ssh -p 2201 vmyard@<host>
```

See [SSH](/docs/guides/ssh).

## 8. Stop and start

Stopping ends metering. Files in `/work` are kept, and starting brings the same machine back.

```sh tab="CLI"
vy stop dev --wait
vy start dev --wait
```

```ts tab="TypeScript"
await machine.stop();
await machine.start();
```

```python tab="Python"
machine.stop()
machine.start()
```

## 9. Delete the machine

```sh tab="CLI"
vy rm dev --wait
```

```ts tab="TypeScript"
await machine.delete();
```

```python tab="Python"
machine.delete()
```

Deleting is permanent. The delete operation succeeds once VMYard confirms the machine is gone from its host.

## Next steps

- Check what you spent with `vy usage` and read [Usage, billing, and limits](/docs/guides/billing).
- Get notified when machines become ready or fail with [webhooks](/docs/guides/webhooks).
- Browse the [CLI reference](/docs/cli) and the [API reference](/docs/api).

---

<!-- Source: /docs/concepts/machines.md -->

# Machines

> What a VMYard machine is, how it is identified, what it is made of, and who may change it.

A **machine** is an isolated Linux environment that belongs to one organization. You create it from a plan, an image, and a region, then run commands in it, move files in and out of `/work`, expose its ports, and reach it over SSH.

## Identity

| Field | What it is |
| --- | --- |
| `id` | The machine's UUID. Use it in every API path. |
| `tenant_alias` | A name fixed at creation (1–63 lowercase letters, digits, and `-`, starting with a letter). It never changes and is part of how VMYard correlates the machine with its host. |
| `name` | The display name. It follows the same rules, defaults to the tenant alias, and can be changed with `PATCH /v1/machines/{id}` or `vy rename`. |

The CLI and SDK `find` accept a machine ID, a tenant alias, or a unique display name. The HTTP API takes IDs only.

## What a machine is made of

| Field | Meaning |
| --- | --- |
| `plan` | `{id, version}` of the [plan](/docs/concepts/catalog): size, price, and backend. |
| `image` | `{id, version}` of the image the disk starts from. |
| `region` | `{id, version}` of the region it runs in. |
| `resources` | `cpu`, `memory_mib`, and `disk_gib`. |
| `backend` | `kvm` (virtual machines), `docker` (development only), or `mock` (tests). |
| `desired_state` / `observed_state` | What you asked for and what VMYard last saw. See [Lifecycle states](/docs/concepts/lifecycle). |
| `auto_stop_after_seconds` / `auto_stop_at` | The [auto-stop](/docs/concepts/auto-stop) duration and the current deadline. |
| `idle_sleep_after_seconds` / `idle_since` / `idle_sleep_at` / `last_active_at` | The [idle-sleep](/docs/concepts/idle-sleep) window (`null` is off), the current idle window and when it ends, and the last observed activity. |
| `setup_operation_id` | The [setup script](/docs/guides/setup-scripts) operation, when one was given. |
| `environment` | The [environment](/docs/guides/environments) version the machine should have and whether it is installed; `null` without one. |
| `ssh` | `{host, port, user}` once an SSH key is installed. See [SSH](/docs/guides/ssh). |

Selections are pinned by **exact version**. Renaming a plan or publishing a new image version never changes a machine that already exists.

## The `/work` directory

Files you write through the API live under `/work`, and file paths are relative to it. Background-command logs are written there too. Files in `/work` are kept while the machine is stopped and are removed when it is deleted.

## Networking

Nothing reaches a machine from outside unless you [expose a port](/docs/guides/ports) or [install an SSH key](/docs/guides/ssh); exposed ports are served only through VMYard's HTTPS edge. What a machine may reach outbound is its [egress policy](/docs/guides/networking), `internet` or `none`, chosen when you create it and changeable later. Machines on the `docker` development backend have no network, so ports and SSH are not available there.

## Roles

Organization members have one role each:

| Role | Read machines | Create, change, use, and delete machines | Webhooks | Manage billing |
| --- | --- | --- | --- | --- |
| Owner | Yes | Yes | Yes | Yes |
| Admin | Yes | Yes | Yes | No |
| Operator | Yes | Yes | No | No |
| Billing | Yes | No | No | Yes |
| Viewer | Yes | No | No | No |

"Use" includes running commands, reading and writing files, ports, and SSH keys. An API key is further limited by its [preset](/docs/guides/api-keys) and always by its creator's current role.

## Copies of a machine

A stopped machine can be pushed as a [snapshot](/docs/guides/snapshots) or saved as a [template](/docs/guides/templates); a running machine can be [forked](/docs/guides/fork-and-restore), and a snapshot restored. Each copy is a new machine with its own ID and guest identity that keeps its source's tenant alias, so two machines can share a machine name. Its display name tells them apart, and `forked_from_machine_id` or `restored_from_snapshot_id` says where it came from.

---

<!-- Source: /docs/concepts/operations.md -->

# Operations and idempotency

> How VMYard accepts a change, carries it out, reports the truth about the result, and makes retries safe.

Every change to a machine (create, start, stop, restart, delete, running a command, writing a file, exposing a port, installing an SSH key, changing internet access) is an **operation**. The API answers `202 Accepted` right away and a worker carries out the change in the background.

```json title="202 Accepted"
{
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "machine_id": "0b6f6c55-2f1d-4f0e-9a51-6f0f4cba7a10",
  "status": "pending",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "requested_action": "create"
}
```

## Following an operation

Poll `GET /v1/operations/{id}` until `status` is terminal, or stream `GET /v1/operations/{id}/events` as server-sent events. The event stream replays the persisted history first, then live events; send `Last-Event-ID` to resume after a disconnect.

| Status | Meaning |
| --- | --- |
| `pending` | Accepted and queued. |
| `running` | A worker is carrying it out. |
| `succeeded` | Done, and VMYard observed the requested result on the machine's host. |
| `failed` | It definitely did not happen. `error_code` says why. |
| `uncertain` | The outcome could not be confirmed yet. VMYard retries it with the exact same request until it settles. |
| `correlation_miss` | The work finished but the observed machine did not match what was asked for. Treat it as not done. |

`succeeded`, `failed`, and `correlation_miss` are terminal. The SDKs and `vy … --wait` poll for you (250 ms, growing to 2 s, for up to 10 minutes) and raise an error for anything but `succeeded`. They raise on `uncertain` too; replaying the same request with the same idempotency key is safe and picks the operation up again. A wait that times out does not cancel the operation.

> [!IMPORTANT]
> A worker finishing is not the same as the change happening. An operation only succeeds when VMYard sees the expected state on the host: a running machine with a new boot after a restart, a machine that is gone after a delete. If `completed_but_unchanged` is `true`, the machine did not change; don't report it as done.

## Ordering

Operations on one machine run one at a time, in the order they were accepted. A long command on one machine never delays another machine.

## Idempotency keys

Send a unique `Idempotency-Key` header with every request that creates an operation. The key is scoped to your organization.

- Repeating a request with the **same key and the same body** returns the original operation instead of doing the work again. This is how you recover from a timeout or a dropped connection: retry with the same key.
- Using a key again with a **different body** is refused with `409 idempotency_conflict`. For creates this includes the name, auto-stop, idle sleep, and setup script.
- A new key is a new request.

```sh
KEY=$(uuidgen)
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/stop" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $KEY" \
  -H "Content-Type: application/json" -d '{}'
# Safe to repeat with the same $KEY: you get the same operation back.
```

The SDKs generate a UUID key for every mutation and reuse it when they retry. Pass your own (`idempotencyKey` / `idempotency_key`) when you need to retry across process restarts.

Settings changes (`PATCH /v1/machines/{id}`), port access tokens, environments, webhooks, API keys, billing, and sign-in routes are not operations and take no idempotency key; they answer synchronously. Upgrading an environment creates operations, but its keys are derived from the version and the machine, so repeating the request replays them.

## Retries

- Retry reads freely.
- Retry a mutation only with the same idempotency key and body.
- The SDKs retry reads on connection errors and `408`, `429`, `502`, `503`, and `504`; they retry mutations only on `429` and `503`, always with the same key, and honour `Retry-After`.

## Operation results

A terminal operation keeps its result. Exec operations carry `exec_result` (exit code, base64 output, and `timed_out`, `cancelled`, `truncated`). A completed file read carries `file_ranges`. A `stop` carries `stop_reason`: `api` when a caller asked for it, or `auto_stop`, `billing`, `idle_sleep`, `suspension`, or `abuse` when VMYard stopped the machine itself ([auto-stop](/docs/concepts/auto-stop), an exhausted balance, [idle sleep](/docs/concepts/idle-sleep), a [suspension](/docs/guides/billing#suspended-organizations) of the organization, or the guard against sustained full CPU use on trials); other kinds have `null`. See [Running commands](/docs/guides/commands) and [Files](/docs/guides/files).

---

<!-- Source: /docs/concepts/lifecycle.md -->

# Lifecycle states

> Desired and observed machine states, the actions that move between them, and how to read a machine that is in between.

A machine has two states. `desired_state` is what you asked for most recently. `observed_state` is what VMYard last confirmed on the machine's host. They differ while an operation is in flight, and the observed state is the one to trust.

## Desired state

| Value | Set by |
| --- | --- |
| `running` | Create, start, or restart. |
| `stopped` | Stop, including an [auto-stop](/docs/concepts/auto-stop), [idle sleep](/docs/concepts/idle-sleep), or a stop because the balance ran out. |
| `deleted` | Delete. |

## Observed state

`observed_state` is an object with a `state` field:

| `state` | Meaning |
| --- | --- |
| `absent` | No machine exists on a host yet, or it has been removed. |
| `provisioning` | The machine is being created. |
| `running` | It is up. Also carries `boot_id`, which changes on every boot. |
| `stopped` | It is stopped. Nothing is metered. |
| `degraded` | The host reported a problem with the machine. |
| `unknown` | VMYard could not confirm the machine's state. |

```json
{
  "desired_state": "running",
  "observed_state": { "state": "running", "boot_id": "c1a4e7f0-…" }
}
```

## Actions

| Action | Route | CLI | Result when it succeeds |
| --- | --- | --- | --- |
| Create | `POST /v1/machines` | `vy new` | Observed `running`. Emits `machine.ready`. |
| Stop | `POST /v1/machines/{id}/stop` | `vy stop` | Observed `stopped`. Emits `machine.stopped`. |
| Start | `POST /v1/machines/{id}/start` | `vy start` | Observed `running`. Emits `machine.started`. |
| Restart | `POST /v1/machines/{id}/restart` | `vy restart` | Observed `running` with a new `boot_id`. Emits `machine.started`. See [Restart](#restart). |
| Delete | `POST /v1/machines/{id}/delete` | `vy rm` | The machine is confirmed gone. Emits `machine.deleted`. |

Each action is an [operation](/docs/concepts/operations) and needs an `Idempotency-Key`. When a lifecycle operation ends `failed` or `correlation_miss`, VMYard emits `machine.error`; see [Webhooks](/docs/guides/webhooks).

Creates, starts, and restarts also pass billing admission: the balance, the spend cap, the trial rules, and the concurrency and start-rate limits. See [Usage, billing, and limits](/docs/guides/billing#limits).

## Restart

A restart is one operation that reboots a running machine in place: every process in it ends, `/work` is kept, and it comes back ready. On VM hosts the VM reboots from its own disk; on Docker hosts the workload's processes end. Exposed ports, the SSH port, and the [egress policy](/docs/guides/networking) stay.

The machine never stops: its metered run stays open, no `machine.stopped` is sent, and its [auto-stop](/docs/concepts/auto-stop) deadline starts again. A retry with the same `Idempotency-Key` never reboots twice.

It succeeds only when the machine is running and ready with a `boot_id` different from the one before. A restart that kept the old `boot_id` ends `correlation_miss`; the machine stays running and usable. A host that can't restart its machines yet ends the operation `failed` with `restart_unsupported`: nothing changed and the machine kept running.

## Reading a machine in between

- **Desired `running`, observed `provisioning`:** a create is in progress. Wait for its operation.
- **Desired `stopped`, observed `running`:** a stop is queued or running.
- **Observed `degraded` or `unknown`:** don't assume the machine works. You can still delete it. Check its latest operation's `error_code`.
- **An operation `succeeded` but the state did not change:** look at `completed_but_unchanged`; treat the change as not made.

Guest commands, file operations, port changes, and SSH key changes all need an observed `running` machine.

---

<!-- Source: /docs/concepts/auto-stop.md -->

# Auto-stop

> Stop machines automatically a fixed time after they start, so forgotten machines don't keep billing.

Auto-stop stops a machine a set time after it starts running. New machines stop after **1 hour** unless you choose another duration or turn auto-stop off. The deadline counts from when the machine becomes running; activity inside the machine does not extend it. To stop a machine once it has done nothing for a while instead, turn on [idle sleep](/docs/concepts/idle-sleep); with both on, whichever comes first stops it.

## Settings

| Field | Meaning |
| --- | --- |
| `auto_stop_after_seconds` | 60 to 2,592,000 seconds (1 minute to 30 days). `null` means never. Creates default to 3600. |
| `never_auto_stop` | `true` turns auto-stop off. It can't be combined with `auto_stop_after_seconds`. |
| `auto_stop_at` | The current deadline (UTC, RFC 3339), present only while the machine is meant to run with a deadline. |

## Set it when you create a machine

```sh tab="CLI"
vy new --name dev --auto-stop 2        # hours; also 30m, 1d, or never
```

```ts tab="TypeScript"
await vy.machines.create({ name: "dev", autoStopAfterSeconds: 2 * 3600 });
await vy.machines.create({ name: "always-on", neverAutoStop: true });
```

```python tab="Python"
vy.machines.create(name="dev", auto_stop_after_seconds=2 * 3600)
vy.machines.create(name="always-on", never_auto_stop=True)
```

```sh tab="curl"
# In the create body:
#   "auto_stop_after_seconds": 7200      or      "never_auto_stop": true
```

## Change it later

`PATCH /v1/machines/{id}` changes the setting and returns the updated machine right away. Changing auto-stop on a running machine restarts its deadline from now; renaming alone leaves the deadline as it is.

```sh tab="CLI"
vy autostop dev 30m
vy autostop dev never
```

```ts tab="TypeScript"
await machine.update({ autoStopAfterSeconds: 30 * 60 });
await machine.update({ neverAutoStop: true });
```

```python tab="Python"
machine.update(auto_stop_after_seconds=30 * 60)
machine.update(auto_stop_after_seconds=None)  # never
```

```sh tab="curl"
curl -X PATCH "$VMYARD_API_URL/v1/machines/$MACHINE_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auto_stop_after_seconds": 1800}'
```

## How the stop happens

VMYard checks deadlines every second. When one passes, it requests an ordinary stop operation for that machine, exactly once per deadline, even if you change the setting or stop the machine at the same moment. The stop emits `machine.stopped` like any other stop, and its operation has `stop_reason: "auto_stop"`.

A start or restart sets a new deadline. A stop or delete clears it.

---

<!-- Source: /docs/concepts/idle-sleep.md -->

# Idle sleep

> Put a running machine to sleep once it has done nothing for a while, how VMYard decides a machine is idle, and how idle sleep differs from auto-stop.

Idle sleep stops a running machine once it has shown no activity for a window you choose, from 5 minutes to 24 hours. It is **off by default** for every machine: you turn it on per machine when you create it or later.

The stop is an ordinary stop. The machine keeps its disk, and on hosts with snapshot sleep (KVM) also its memory and running processes, so `start` wakes it where it left off. Nothing is billed while it sleeps.

## Idle sleep and auto-stop

| | [Auto-stop](/docs/concepts/auto-stop) | Idle sleep |
| --- | --- | --- |
| Ends a run | a fixed time after the machine starts, whatever it does | once the machine has been idle for the whole window |
| Default | on, 1 hour | off |
| Range | 1 minute to 30 days | 5 minutes to 24 hours |
| Activity extends it | no | yes: any activity restarts the window |

Use both: auto-stop bounds a machine you forgot, and idle sleep ends a run as soon as the work is done. Whichever comes first stops the machine. The console's machine list shows the sooner one under **Stops / sleeps in**.

## How VMYard decides a machine is idle

The control plane checks running machines with idle sleep on about every 30 seconds. A machine is idle only while **every** signal stays quiet, without a break, for the whole window:

- No operation of the machine is pending, running, or uncertain, and none was requested or finished inside the window. Commands, background commands, file transfers, ports, SSH keys, lifecycle changes, environment installs, and snapshots all count.
- No [web terminal](/docs/guides/web-terminal) is open to it, and none closed inside the window.
- Its latest [metrics](/docs/guides/machine-metrics) are current and CPU, disk I/O, and network use are at or below small thresholds, with no minute inside the window above them. Port and SSH traffic shows up as network use.

The thresholds are set by the control plane, not by you, and may change.

**Missing data never counts as idle.** When metrics are missing, stale, or overdue, or the host can't measure a value, the window ends and starts again only once current, quiet metrics return. A machine whose host stopped reporting is never put to sleep because of it.

## Turn it on

In the console, choose **Sleep when idle** when you create a machine, or open the machine's overview and change **Idle sleep**. With the API, send `idle_sleep_after_seconds`:

```sh
# In the create body:
#   "idle_sleep_after_seconds": 900

curl -X PATCH "$VMYARD_API_URL/v1/machines/$MACHINE_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idle_sleep_after_seconds": 900}'
```

`null` (or leaving the field out when you create) turns it off. Values outside 300 to 86,400 seconds answer `422` with a field error. Changing the setting restarts the idle window.

## What a machine reports

| Field | Meaning |
| --- | --- |
| `idle_sleep_after_seconds` | The window in seconds, or `null` when idle sleep is off. |
| `idle_since` | Start of the running machine's current unbroken idle window; `null` while it is active, its metrics are unknown, or idle sleep is off. |
| `idle_sleep_at` | When the machine sleeps if it stays idle (`idle_since` plus the window); `null` without an open window. The console counts down to it as **Sleeps in**. |
| `last_active_at` | The last activity VMYard observed; `null` until it saw any. The console shows it as **Last active**. |

## After it sleeps

An idle-sleep stop is a normal `stop` operation. `GET /v1/operations/{id}` and the `machine.stopped` [webhook](/docs/guides/webhooks) carry `stop_reason: "idle_sleep"`, and members who turned on the `idle_sleep` [email alert](/docs/guides/email-alerts) get an email naming the machine and the operation. In the console, open the machine's overview with `?operation=<id>` to see it as **Stopped: idle**.

Start the machine to wake it. A start, like any activity, begins a new idle window once the machine is quiet again.

---

<!-- Source: /docs/concepts/sleep-and-wake.md -->

# Sleep and wake

> What happens to a machine when it stops and starts, how idle sleep puts it to sleep, how long stops move down the snapshot tiers, and how to wake it.

> [!NOTE]
> VMYard does not wake a machine when a request arrives for it. The API, CLI, and SDKs have no separate sleep or wake routes; sleep is a stop and waking is a start.

## Stop and start

A machine runs until you stop it, [auto-stop](/docs/concepts/auto-stop) stops it, [idle sleep](/docs/concepts/idle-sleep) finds it idle, or the organization's balance runs out.

- Stopping ends metering. Nothing is billed while a machine is stopped.
- Files in `/work` are kept while the machine is stopped.
- Starting brings the same machine back with the same ID and name. Its port URLs keep their label, so a URL never points at another machine.

```sh
vy stop dev --wait
vy start dev --wait
```

On KVM hosts a stop is a hot snapshot: memory, device state, and disk stay on the machine's host, and start resumes its processes where they were. Docker development hosts pause the machine instead. Even so, write what you need to keep to `/work`, and be ready to start services again with a [background command](/docs/guides/background-commands): a [restore from a cold snapshot](/docs/guides/snapshots#tiers) boots fresh from the disk. A [setup script](/docs/guides/setup-scripts) runs only once, after the first start.

## Long stops move down the tiers

A background policy pushes machines that stay stopped to the snapshot store: a warm snapshot after 6 hours and a cold one after 7 days, by default, on KVM machines. It changes nothing about how you start the machine; it makes a long-stopped machine restorable on any host. See [Snapshots and tiers](/docs/guides/snapshots#stopped-machines-move-down-the-tiers).

## Idle cost

A running machine is billed whether it is busy or idle. Turn on [idle sleep](/docs/concepts/idle-sleep) to stop a machine once it has done nothing for a while, set a short auto-stop for development machines, and stop machines when your agent or job finishes.

---

<!-- Source: /docs/concepts/catalog.md -->

# Regions, plans, and images

> The versioned catalog a machine is created from, how to read it, and how sizes are priced.

A machine is created from three catalog entries: a **plan** (size, price, and backend), an **image** (what the disk starts from), and a **region** (where it runs). Each entry has an `id` and a `version`, and a create request names both, so a later change to the catalog never changes an existing machine or a request you already sent.

## Reading the catalog

```sh tab="CLI"
vy plans
vy images
vy regions
```

```ts tab="TypeScript"
const [plans, images, regions] = await Promise.all([
  vy.catalog.plans(),
  vy.catalog.images(),
  vy.catalog.regions(),
]);
```

```python tab="Python"
plans, images, regions = vy.catalog.plans(), vy.catalog.images(), vy.catalog.regions()
```

```sh tab="curl"
curl "$VMYARD_API_URL/v1/plans" -H "Authorization: Bearer $VMYARD_API_KEY"
curl "$VMYARD_API_URL/v1/images" -H "Authorization: Bearer $VMYARD_API_KEY"
curl "$VMYARD_API_URL/v1/regions" -H "Authorization: Bearer $VMYARD_API_KEY"
```

Any member and any API key preset can read the catalog. The exact sizes, images, and regions on offer come from your VMYard deployment; always read them from the catalog rather than hard-coding them.

## Plans

A plan has a `name`, `version`, `cpu`, `memory_mib`, `disk_gib`, `backend`, and a `price` with `hourly` and `monthly` USD amounts. Machines are billed per second at the plan's hourly price while they run.

Sizes are priced like this:

| Size | Price per hour | Multiplier |
| --- | --- | --- |
| `small` | $0.015 | 0.5 |
| `default` | $0.030 | 1 |
| `large` | $0.060 | 2 |
| `xlarge` | $0.170 | about 5.67 |

The multiplier is a size's hourly price relative to `default`. Plan allowances and the trial are counted in `default`-size hours, so one hour of `small` uses half an hour of allowance. Trials can use only `small` and `default`. See [Usage, billing, and limits](/docs/guides/billing).

## Images

An image has a `name`, a `version`, and a content `digest`. A machine's disk starts from the exact image version you choose.

## Regions

A region has a `name`, a `version`, a `backend`, and a `capacity_status`. Choose a region whose backend matches the plan's backend.

## Choosing entries

The SDKs and CLI accept names or IDs and resolve them to the latest version for you. They default to the first plan, the first image, and the first region that matches the plan's backend.

```sh tab="CLI"
vy new --plan small --image ubuntu-24.04 --region eu-central --name dev
```

```ts tab="TypeScript"
const request = await vy.machines.buildCreateRequest({ plan: "small", name: "dev" });
console.log(request.plan, request.image, request.region); // exact {id, version} pairs
```

```python tab="Python"
request = vy.machines.build_create_request(plan="small", name="dev")
print(request["plan"], request["image"], request["region"])
```

The image and region names above are examples; use the names your catalog lists. With the HTTP API, send `plan`, `image`, and `region` as `{id, version}`, plus the plan's `resources` and `backend`. See [Create a machine](/docs/api/machines#create-a-machine).

---

<!-- Source: /docs/guides/api-keys.md -->

# API keys and presets

> Create organization API keys, choose a preset that limits what each key can do, and rotate or revoke keys.

API keys let programs call VMYard without a browser. A key belongs to one organization, has a **preset** that limits which routes it reaches, and acts with its creator's current role.

## Create a key

In the console, open **API keys** and choose **Create key**. Give it a name (1–64 characters), a preset, and a lifetime of 1 to 365 days (90 by default). The secret is shown **once**; copy it then. You can also get a key from the CLI with [`vy login`](/docs/guides/cli-login).

Secrets look like `vmy_` followed by 43 characters. VMYard stores only a hash, the first 12 characters (`prefix`), and the last four, so it can show you which key is which but can never show the secret again.

> [!NOTE]
> Creating, listing, rotating, and revoking keys needs a signed-in browser session. An API key can't manage keys: those routes answer `403 session_required`.

## Use a key

Send it as a bearer token. The key already names its organization, so `X-Organization-ID` is optional; if you send it, it must match (`403 organization_mismatch` otherwise). Bearer requests don't need a CSRF token.

```sh tab="curl"
curl "$VMYARD_API_URL/v1/machines" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```sh tab="CLI"
export VMYARD_API_KEY=vmy_...   # always wins over a key stored by vy login
vy ls
```

```ts tab="TypeScript"
const vy = new VMYard({ apiKey: process.env.VMYARD_API_KEY });
```

```python tab="Python"
vy = VMYard(api_key=os.environ["VMYARD_API_KEY"])
```

Keep keys out of source control and command lines. The CLI accepts keys only on stdin or from the device flow.

## Presets

Each preset includes everything in the presets above it.

| Preset | Adds |
| --- | --- |
| `read_only` | Reads: machines, operations, the catalog, `/v1/me`, billing, limits, usage, port lists, and environments (without values). |
| `use_existing` | Using machines that exist: start, stop, restart, settings, commands and background commands, file reads and writes, ports, port tokens, SSH keys, and environment upgrades. |
| `create_and_use` | Creating and deleting machines, and choosing or changing a machine's [internet access](/docs/guides/networking). |
| `full_access` | Webhooks, environment changes and reveals, and billing management (spend cap, checkout, payment portal). |

A key with too small a preset gets `403 insufficient_scope`. A `read_only` key gets it on every route that reaches inside a machine, including file reads and command status.

## Roles still apply

A key never does more than its creator could. If the creator is a Viewer, the key can only read, whatever its preset; webhooks and environment changes also need the creator to be an Owner or Admin. If the creator leaves the organization, the key stops working.

## Rotate and revoke

The key's creator, an Owner, or an Admin can:

- **Rotate** a key: VMYard issues a new secret with the same name, preset, and lifetime and revokes the old one at once. The person who rotates becomes the new key's creator.
- **Revoke** a key: it stops working at once. Revoking twice is harmless.

Owners and Admins see every key in the organization; other members see the keys they created.

A key that is malformed, unknown, expired, or revoked gets `401 invalid_api_key`.

---

<!-- Source: /docs/guides/sign-in.md -->

# Sign-in methods

> Sign in to the console with GitHub, Google, or an emailed code, and link or remove sign-in methods.

The console uses browser sign-in. Which methods appear depends on your deployment; the usual set is **GitHub**, **Google**, and **email**. Your first sign-in creates your VMYard user.

## GitHub and Google

Choosing a provider sends you to it and back. VMYard identifies you by the provider's account, not by email address. GitHub sign-in needs a **verified primary email** on your GitHub account.

## Email codes and magic links

1. Enter your address. VMYard always answers the same way, whether or not an account exists.
2. Check your email for a **6-digit code** and a sign-in link. They are one credential: valid for 10 minutes, usable once, and replaced by any newer request. Five wrong codes use it up.
3. Type the code, or click the link. The link works only in the browser that asked for it; on another device, type the code.

You can request 5 emails per address and 20 per network address per hour, and verify 30 codes per network address per 10 minutes. Beyond that, VMYard answers `429 rate_limited` with a `Retry-After` delay.

## One person, several methods

Sign-in methods never merge on their own: a GitHub account and an email address with the same address are two different users until you link one to the other.

To link a method, sign in, open **Account**, and choose the method to add. For email, VMYard sends a code to the new address. Linking and removing need a sign-in within the last **15 minutes**; if yours is older, the console asks you to confirm it's you first.

- You can't remove your last sign-in method (`409 last_login_method`).
- A method that already belongs to another user can't be linked (`identity_in_use`).
- Removing a method doesn't end sessions that are already signed in.

## Sign-in errors

When sign-in fails, the console shows one of these codes in the address (`/sign-in?error=…`) with an explanation:

| Code | Meaning |
| --- | --- |
| `access_denied` | You declined at the provider. |
| `identity_in_use` | That identity is already linked to another user. |
| `oidc_failed` | The provider's answer couldn't be verified, or GitHub had no verified primary email. |
| `oidc_unavailable` | The provider couldn't be reached. Try again later. |
| `session_expired` | The sign-in attempt expired or was already used. Start again. |
| `unsupported_provider` | That method isn't configured on this deployment. |

## Signing out

**Sign out** in the console ends the browser session. API keys aren't affected; revoke a key to stop it working.

---

<!-- Source: /docs/guides/cli-login.md -->

# CLI device login

> Sign the vy CLI in through the browser with the device authorization grant, or give it a key on stdin.

`vy login` signs the CLI in without copying secrets around. It uses the OAuth 2.0 device authorization grant (RFC 8628): the CLI shows a code, you approve it in the console, and the CLI receives an ordinary [API key](/docs/guides/api-keys).

## Sign in

```sh
export VMYARD_API_URL=https://api.example.com
vy login
```

1. The CLI prints a URL and a code such as `BCDF-GHJK`, and opens the console's **/device** page (pass `--no-browser` to open it yourself, for example over SSH).
2. In the console, check that the code and the device name (`vy <version> on <hostname>`) match what your terminal shows. **Approve only a request you started.**
3. Choose the organization, the key's preset, its lifetime (1–90 days, 90 by default), and its name, then approve.
4. The CLI receives the key and stores it with its organization.

`--scope` asks for a preset: `read_only`, `use_existing`, `create_and_use` (the default), or `full_access` (needed for webhooks). The person approving can choose a different one. Any member of the organization can approve; the key is limited by their role like any key.

```sh
vy login --scope full_access
vy whoami
```

## Other ways to sign in

```sh
vy login --key-stdin < ~/vmyard-key.txt   # a key you created in the console
export VMYARD_API_KEY=vmy_...             # or set it in the environment
```

`VMYARD_API_KEY` always wins over a stored key. `--key-stdin` checks the key with `/v1/me` before storing it (`--no-verify` skips the check). The CLI never accepts a key as a command-line argument and never prints a key.

## Where the key is stored

| System | Path |
| --- | --- |
| Linux and others | `$XDG_CONFIG_HOME/vmyard/config.json` (default `~/.config/vmyard/`) |
| macOS | `~/Library/Application Support/vmyard/config.json` |
| Windows | `%APPDATA%\vmyard\config.json` |

`VMYARD_CONFIG_DIR` overrides the directory. The file is written with mode `0600` in a `0700` directory, and `vy` warns if other users can read it.

`vy logout` deletes the stored key from this computer only. The key itself stays valid until it expires; revoke it in the console under **API keys** if you no longer need it. Each `vy login` creates a new key.

## The protocol

Other tools can use the same flow; the SDKs ship it as `DeviceAuthorization`.

1. `POST /v1/auth/device/code` with optional `client_name` and `scope`. No authentication. The answer has `device_code` (keep it secret), `user_code`, `verification_uri`, `verification_uri_complete`, `expires_in` (600 seconds), and `interval` (5 seconds).
2. Show the user `user_code` and `verification_uri`.
3. Poll `POST /v1/auth/device/token` with `grant_type` `urn:ietf:params:oauth:grant-type:device_code` and the `device_code`, waiting `interval` seconds between polls.

```sh
curl -X POST "$VMYARD_API_URL/v1/auth/device/token" \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "urn:ietf:params:oauth:grant-type:device_code", "device_code": "'"$DEVICE_CODE"'"}'
```

Until the user decides, polls answer `400` with an RFC 8628 error:

| `error` | What to do |
| --- | --- |
| `authorization_pending` | Keep polling. |
| `slow_down` | You polled too fast. Add 5 seconds to the interval. |
| `access_denied` | The user denied it, or the approver left the organization. Stop. |
| `expired_token` | The code expired. Start again. |
| `invalid_grant` | Unknown or already used device code. Start again. |
| `invalid_request` | The request is malformed. |
| `unsupported_grant_type` | Wrong `grant_type`. |

After approval, the next poll returns the key once: `access_token` (the `vmy_…` secret), `token_type: "Bearer"`, `expires_in` (seconds until the key expires), `scope` (the preset), and `api_key` (its details).

Requesting codes is limited to 30 per network address per 10 minutes.

---

<!-- Source: /docs/guides/commands.md -->

# Running commands

> Run a command in a machine, wait for its result or stream its output as it arrives, and handle exit codes, timeouts, and retries.

`POST /v1/machines/{id}/exec` runs one command in a running machine and returns its exit code and output. The command is an [operation](/docs/concepts/operations), so it gets an idempotency key and runs after any earlier operation on the same machine. Past commands and their output stay in the machine's [command history](/docs/guides/command-history).

## Run and wait

```sh tab="CLI"
vy exec dev -- uname -a                 # argv, run directly
vy exec dev -c 'cd /work && make test'  # a shell command
```

```ts tab="TypeScript"
const { exitCode, stdout, stderr } = await machine.exec("cd /work && make test");
const listing = await machine.exec(["ls", "-l", "/work"]);
```

```python tab="Python"
result = machine.exec("cd /work && make test")
print(result.exit_code, result.stdout, result.stderr)
listing = machine.exec(["ls", "-l", "/work"])
```

```sh tab="curl"
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/exec" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"command": "uname -a", "timeout_ms": 30000}'
# 202 Accepted: poll operation_url until it is terminal, then read exec_result.
```

Send exactly one of:

- `argv`: the program and its arguments, run directly without a shell.
- `command`: a string run as `/bin/sh -c <command>`, at most 8 KiB.

In the SDKs a string becomes `command` and an array becomes `argv`. In the CLI, words after `--` are `argv` and `-c` is `command`. On a machine with an [environment](/docs/guides/environments), commands run with its variables loaded.

## The result

The finished operation's `exec_result` holds:

| Field | Meaning |
| --- | --- |
| `exit_code` | The command's exit status; `null` if it didn't exit normally. |
| `stdout_base64`, `stderr_base64` | The output, base64-encoded. |
| `timed_out` | It hit `timeout_ms` and was killed. |
| `cancelled` | It was cancelled. |
| `truncated` | Output went over 1 MiB and was cut. |

The operation **succeeds** only when the command exits with code 0. Otherwise it ends `failed`, still carries `exec_result` with the output, and its `error_code` says why:

| `error_code` | Meaning |
| --- | --- |
| `exec_nonzero` | The command exited with a non-zero code. |
| `exec_timed_out` | It ran past `timeout_ms`. |
| `exec_cancelled` | It was cancelled. |
| `exec_no_exit_status` | It ended without an exit status, for example killed by a signal. |

The SDKs raise `OperationError` for a failed exec; its `operation.exec_result` holds the output. The CLI exits with the remote exit code, `124` if the command timed out, and `125` if VMYard couldn't run it. A failed exec also emits the `operation.failed` [webhook](/docs/guides/webhooks).

```ts tab="TypeScript"
import { OperationError } from "@vmyard/sdk";

try {
  await machine.exec("make test");
} catch (error) {
  if (error instanceof OperationError && error.errorCode === "exec_nonzero") {
    console.log("tests failed", error.operation.exec_result?.exit_code);
  } else throw error;
}
```

```python tab="Python"
from vmyard import OperationError

try:
    machine.exec("make test")
except OperationError as error:
    if error.error_code != "exec_nonzero":
        raise
    print("tests failed", error.operation["exec_result"]["exit_code"])
```

## Timeouts

`timeout_ms` is 1 to 600,000 (10 minutes) and defaults to the maximum. A larger value is refused with `422 timeout_exceeds_runtime_limit`. When the timeout passes, the command's process group is killed. For anything longer, use a [background command](/docs/guides/background-commands).

## Stream output

Set `stream: true` to get output while the command runs. The response is `200 application/x-ndjson`: one JSON object per line.

```sh tab="CLI"
vy exec dev -- npm test          # streams by default; --no-stream waits instead
```

```ts tab="TypeScript"
for await (const frame of machine.exec(["npm", "test"], { stream: true })) {
  if (frame.type === "stdout") process.stdout.write(frame.data);
  if (frame.type === "stderr") process.stderr.write(frame.data);
  if (frame.type === "exit") console.log("exit", frame.exitCode);
}
```

```python tab="Python"
with machine.exec(["npm", "test"], stream=True) as stream:
    for frame in stream:
        if frame.type in ("stdout", "stderr"):
            print(frame.data.decode(), end="")
        elif frame.type == "exit":
            print("exit", frame.exit_code)
```

```sh tab="curl"
curl -N -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/exec" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"argv": ["npm", "test"], "stream": true}'
```

```json title="Frames"
{"type":"started","operation_id":"6f1c…","operation_url":"/v1/operations/6f1c…"}
{"type":"stdout","data_base64":"PiB0ZXN0Cg=="}
{"type":"stderr","data_base64":"d2FybmluZwo="}
{"type":"exit","operation_id":"6f1c…","status":"succeeded","exit_code":0,"timed_out":false,"cancelled":false,"truncated":false}
```

The stream starts with `started` and ends with exactly one `exit` or `error` frame. `stdout` and `stderr` frames are a preview; the `exit` frame and the operation's `exec_result` are the authoritative result.

- If the connection drops, the command keeps running. Send the **same idempotency key and body** again to stream it from the start, or follow the operation from the `started` frame.
- Output is kept with the operation, up to 1 MiB per operation, and also appears as `stdout`/`stderr` events on `GET /v1/operations/{id}/events`.
- An `error` frame (`code`, `message`) means VMYard couldn't run or finish the command.

## Retries and ordering

Retrying with the same idempotency key and body returns the original operation; it never runs the command twice. A different body with the same key is `409 idempotency_conflict`. Commands on one machine run one at a time in the order they were accepted.

## Who can run commands

Owners, Admins, and Operators, or an API key with at least the `use_existing` preset. The machine must be running.

---

<!-- Source: /docs/guides/background-commands.md -->

# Background commands

> Start long-running commands that outlive the request, page through their logs, and kill them.

A background command runs detached: the request returns as soon as it starts, there is no timeout, and its combined output goes to a log you can page through. Use it for servers, watchers, and jobs longer than the 10-minute [exec](/docs/guides/commands) limit. Each start is also recorded in the machine's [command history](/docs/guides/command-history).

## Start one

```ts tab="TypeScript"
const command = await machine.commands.start("npm run dev");
console.log(command.command_id);
```

```python tab="Python"
command = machine.commands.start("npm run dev")
print(command["command_id"])
```

```sh tab="curl"
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/commands" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"command": "npm run dev"}'
```

The body takes exactly one of `argv` or `command` (a `/bin/sh -c` string of at most 8 KiB). The answer is `202` with a `command_id`, which is also the ID of the operation that starts it, and a `command_url`. The CLI has no background-command subcommand yet; the console's **Terminal** tab can start and watch them.

## Status and logs

```ts tab="TypeScript"
let offset = 0;
const status = await machine.commands.status(command.command_id, { logOffset: offset });
if (status.log) {
  process.stdout.write(Buffer.from(status.log.data_base64, "base64"));
  offset = status.log.next_offset;
}
```

```python tab="Python"
import base64

status = machine.commands.status(command["command_id"], log_offset=0)
if status.get("log"):
    print(base64.b64decode(status["log"]["data_base64"]).decode(), end="")
    next_offset = status["log"]["next_offset"]
```

```sh tab="curl"
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/commands/$COMMAND_ID?log_offset=0&log_limit=65536" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

`GET /v1/machines/{id}/commands/{command_id}` returns the status and a window of the log starting at `log_offset` (default 0), at most `log_limit` bytes (1 to 1,048,576; default 65,536). Pass the returned `next_offset` as the next `log_offset`. If the read is still queued, the answer is `202` with an operation to follow; the SDKs do that for you.

| `status` | Meaning |
| --- | --- |
| `starting` | Being started. |
| `failed_to_start` | It could not start; see `error_code`. |
| `running` | Running. |
| `exited` | Finished; `exit_code` holds its status. |
| `killed` | Killed; `signal` holds the signal when known. |
| `unknown` | The machine has no record of it, for example after a reboot. Stop polling. |

VMYard asks for the status before reading the log, so once a command reports `exited`, its log is complete. Logs are bytes: decode them as a stream so a character split across two pages stays whole.

`machine.commands.wait(id)` in the SDKs polls until the command is `exited`, `killed`, or `failed_to_start`.

## Kill one

```ts tab="TypeScript"
await machine.commands.kill(command.command_id);
```

```python tab="Python"
machine.commands.kill(command["command_id"])
```

```sh tab="curl"
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/commands/$COMMAND_ID/kill" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" -d '{}'
```

Killing is an operation. Read the status afterwards: a command is only `killed` once it reports so.

## Limits

Background commands, like everything inside a machine, need a running machine and Owner, Admin, or Operator access (or a `use_existing` key). Reading the status of a command reaches into the machine, so even reads need `use_existing`; a `read_only` key gets `403 insufficient_scope`.

---

<!-- Source: /docs/guides/command-history.md -->

# Command history

> Search a machine's past commands, check how each one ended, and page through its stored stdout and stderr.

Every command run on a machine is kept in its history: [foreground commands](/docs/guides/commands), [setup scripts](/docs/guides/setup-scripts), and the starts of [background commands](/docs/guides/background-commands). Lifecycle and file operations are not. In the console, open a machine and choose **History**.

History shows command text and output, which can include values an [environment](/docs/guides/environments) exported, so it needs the same role as running commands: Owner, Admin, or Operator, or an API key with at least the `use_existing` preset. Viewers and Billing members get `403 forbidden`, and a `read_only` key gets `403 insufficient_scope`.

## List and search

```sh
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/commands/history?q=npm&mode=sync&limit=25" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

Entries come newest first.

| Parameter | Meaning |
| --- | --- |
| `q` | Text the command contains, ignoring case. At most 128 characters, trimmed; blank means no search. |
| `mode` | `all` (default), `sync` for foreground commands and setup scripts (the console's **Commands**), or `detached` for background command starts (**Processes**). |
| `limit` | 1 to 100 entries (default 50). |
| `cursor` | The `next_cursor` of the previous page. It is opaque and continues strictly after the last entry, so commands started meanwhile never repeat or shift what you haven't read. The last page has no `next_cursor`. |

Invalid values answer `422` with the field in `field_errors`. `GET /v1/machines/{id}/commands/history/{operation_id}` returns one entry.

## What an entry says

| Field | Meaning |
| --- | --- |
| `operation_id` | The exec operation. For a background command it is also the `command_id`. |
| `mode` | `sync` or `detached`. |
| `command`, `argv` | The `/bin/sh -c` string, or the arguments joined by spaces, and the exact arguments. Search matches `command`. |
| `status`, `error_code` | The operation's status and error code, for example `failed` with `exec_nonzero` or `exec_timed_out`. See [Operations](/docs/concepts/operations). |
| `exit_code` | The exit status of a finished foreground command. |
| `timed_out`, `cancelled` | How the command ended when it didn't exit on its own. |
| `truncated` | The machine capped the captured output. |
| `stdout_bytes`, `stderr_bytes` | The size of each stored stream. |
| `output_purged` | Retention removed the stored output. The sizes stay. |
| `created_at`, `started_at`, `finished_at`, `duration_ms` | When it was requested, first started, and finished, and how long it ran across retries. Entries recorded before history existed have no `started_at`. |
| `logs_url` | Where to read the output. |

A `detached` entry describes only the start. The process's exit status and live log come from `GET /v1/machines/{id}/commands/{command_id}`, and its stored stdout and stderr are empty. In the console, **Open live status** follows it on the Terminal tab.

## Read the output

```sh
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/commands/history/$OPERATION_ID/logs?stream=stderr&offset=0&limit=65536" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

`stream` is `stdout` (default) or `stderr`. The answer holds bytes `[offset, offset + limit)` of that stream: `{offset, next_offset, size, data_base64, complete, truncated}`. `limit` is 1 to 1,048,576 (default 65,536). Pass `next_offset` as the next `offset`; an offset at or past `size` returns no data. Output is bytes, so decode it as a stream to keep a character that two pages split whole.

While a streamed foreground command is still running, the answer serves the output relayed so far, `size` grows, and `complete` is `false`. Keep reading from `next_offset` until `complete` is `true`, then re-read the entry for its exit code.

## Retention

Stored output is removed a set number of days after a command finishes (30 by default; the server's operator chooses). The entry, its exit code, flags, timing, and sizes stay, `output_purged` becomes `true`, and reading the output answers `410 output_expired`.

---

<!-- Source: /docs/guides/web-terminal.md -->

# Web terminal

> Open an interactive login shell in a running machine from the console or any WebSocket client, and handle its messages, limits, and close reasons.

The web terminal is an interactive login shell in a running machine, carried over a WebSocket. It is full machine access, so it is allowed exactly like [running a command](/docs/guides/commands): Owner, Admin, or Operator members, and API keys with the `use_existing` preset or higher. Viewer and Billing members get `403 forbidden`; a `read_only` key gets `403 insufficient_scope`.

Each connection starts a new shell. Closing the tab, reconnecting, or losing the network ends that shell and whatever it was running in the foreground; run `tmux` or `screen` in the machine for sessions that should outlive a connection, or start long jobs as [background commands](/docs/guides/background-commands).

## In the console

Open a machine, choose the **Terminal** tab, and pick **Shell**. **Connect** opens a terminal sized to the panel; the status line shows who you are signed in as on the machine. The terminal follows the light or dark theme, resizes with the window, and has **Copy**, **Paste**, and font-size controls. **Disconnect** ends the shell; **Reconnect** opens a new one. If the machine isn't running, the panel offers to start it.

The console never records what you type or what the shell prints.

## Connect from a browser

Browsers can't put headers on a WebSocket, so a session first mints a single-use ticket:

```sh tab="curl"
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"
```

```json title="Response 201"
{
  "ticket": "vyt_…",
  "expires_at": "2026-10-12T12:00:30Z",
  "url": "/v1/machines/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f/terminal?ticket=vyt_…"
}
```

The ticket works once, within 30 seconds, for that machine and the session that minted it. Add the initial size to `url` and connect with the session cookie:

```js tab="JavaScript"
const socket = new WebSocket(
  `wss://api.example.com${ticket.url}&cols=${cols}&rows=${rows}`,
);
socket.binaryType = "arraybuffer";
```

The `Origin` of the page must be the console's configured address (`ui_base_url`), or the upgrade is refused with `403 origin_not_allowed`. An expired, used, or foreign ticket is `403 terminal_ticket_invalid`; mint a new one.

## Connect with an API key

Scripts skip the ticket and send the key on the upgrade request. Any WebSocket client works, for example [websocat](https://github.com/vi/websocat):

```sh tab="websocat"
websocat --binary \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  "wss://api.example.com/v1/machines/$MACHINE_ID/terminal?cols=120&rows=40"
```

An `Origin` header, if sent, must still be allowed. `cols` and `rows` are 1–1000 and default to 80×24; other values are `422`.

## Messages

| Direction | Kind | Content |
| --- | --- | --- |
| Server → client | Text | `{"type":"opened","terminal_id","user"}`, sent first; `user` is the login on the machine. |
| Server → client | Binary | Terminal output, at most 64 KiB per message. |
| Client → server | Binary | Keystrokes and pasted text (UTF-8), at most 64 KiB per message. |
| Client → server | Text | `{"type":"resize","cols","rows"}` (1–1000 each). |
| Client → server | Text | `{"type":"signal","signal"}`: `hup`, `int`, `quit`, `kill`, `term`, `usr1`, `usr2`, `cont`, `stop`, `tstp`, or `winch`, sent to the foreground process group. |
| Client → server | Text | `{"type":"close"}` ends the shell. |
| Server → client | Text | `{"type":"exit","exit_code","signal"}`: the shell ended with that status, or was killed by that signal. |
| Server → client | Text | `{"type":"closed","reason"}`: the terminal ended without the shell's status. |

`exit` and `closed` are final: the server then closes the WebSocket with code 1000 (1008 after an invalid message, 1001 when the server is shutting down). Any other text message from the client ends the terminal as `invalid_message`.

Send a resize when the visible size changes, not on every pixel: the console waits for the size to settle for 150 ms. Send keystrokes as binary messages; a text message is always parsed as control.

## Keepalive and idle time

The server pings every 15 seconds and ends a terminal whose client sent nothing, not even a pong, for 45 seconds (`client_lost`). Browsers answer pings on their own. A terminal with no input and no output for the deployment's idle timeout (30 minutes by default) ends as `idle_timeout`.

Output is acknowledged to the machine only as it is delivered, so a slow reader pauses the program in the machine rather than losing output.

## Limits

| Limit | Default | Answer |
| --- | --- | --- |
| Open terminals per user in an organization | 4 | `429 terminal_limit_reached` |
| Open terminals per organization | 8 | `429 terminal_limit_reached` |
| Opens per user per minute | 20 | `429 rate_limited` with `Retry-After` |
| Terminals per machine, and per host | 16, 64 | `409 terminal_refused` |

Operators can change the first three. Close terminals you no longer use; a tab left open keeps its terminal counted until it closes.

## Close reasons

| `reason` | Meaning |
| --- | --- |
| `exit` | The shell exited. |
| `client_closed` | The client sent `close` or closed the WebSocket. |
| `client_lost` | The client sent nothing for 45 seconds. |
| `idle_timeout` | No input or output for the idle timeout. |
| `invalid_message` | The client sent a text message that isn't a control message. |
| `server_shutdown`, `replica_lost` | The API server restarted or stopped. Reconnect. |
| `channel_lost`, `host_lost`, `peer_lost`, `shutdown` | The machine's host became unreachable or restarted. |
| `sandbox_sleeping`, `sandbox_destroyed` | The machine stopped or was deleted. |
| `revoked` | The organization was [suspended](/docs/guides/billing#suspended-organizations). Reconnecting is refused with `403 organization_suspended` until the suspension is lifted. |
| `replaced`, `fenced`, `identity_reset`, `invalid_frame`, `upgrade_failed` | The connection to the machine was reset. Reconnect. |

Every open and close is recorded in the machine's audit log with who opened it, its size, how long it lasted, and why it closed. Keystrokes and output are never stored.

## Errors

| Status | Code | What to do |
| --- | --- | --- |
| 403 | `forbidden` | Ask an Owner or Admin for the Operator role. |
| 403 | `insufficient_scope` | Use a key with the `use_existing` preset or higher. |
| 403 | `session_required` | API keys don't mint tickets; connect with the key directly. |
| 403 | `origin_not_allowed` | Open the console from its configured address. |
| 403 | `terminal_ticket_invalid` | Mint a new ticket and connect within 30 seconds. |
| 409 | `machine_not_running` | Start the machine and wait until it is running. |
| 409 | `terminal_refused` | The machine or its host has too many terminals. Close some. |
| 429 | `terminal_limit_reached` | Close another terminal first. |
| 429 | `rate_limited` | Wait `Retry-After` seconds. |
| 503 | `terminals_unavailable` | This deployment has no runtime for terminals. |
| 503 | `runtime_unavailable` | The machine's host can't be reached. Retry shortly. |

See [Errors](/docs/guides/errors#web-terminal) for the problem format.

---

<!-- Source: /docs/guides/desktop.md -->

# Desktop

> See and use a running machine's graphical desktop over VNC in the browser, with its security model, latency expectations, and close reasons.

The **Desktop** tab shows a running machine's graphical desktop in the console. It is a VNC session carried over a WebSocket and drawn in the page by [noVNC](https://github.com/novnc/noVNC): you see the screen, and your mouse, touch, and keyboard drive it.

The desktop is VNC first. Machines whose image or host has no graphical desktop yet answer `503 desktop_unavailable`, and the tab says so; use the [web terminal](/docs/guides/web-terminal) for those.

## Who can open it

A desktop is full machine access, so it is allowed like the web terminal: Owner, Admin, and Operator members. Viewer and Billing members get `403 forbidden`. Up to 4 viewers can watch one machine at a time.

## In the console

Open a machine and choose **Desktop**, then **Connect**. The status line shows the remote screen size once the VNC session starts, and focus moves to the screen.

- **Disconnect** ends the session; **Reconnect** opens a new one. Nothing on the machine stops when you disconnect.
- **View only** stops sending your mouse and keyboard; you only watch.
- **Scale to fit** shrinks the remote screen into the panel. Turn it off to see it at 1:1 and scroll.
- **Resize remote to window** asks the machine's VNC server to match the panel's size, so nothing is scaled. The machine applies it if its desktop allows resizing.
- **Full screen** shows only the desktop; press Escape to leave.
- **Send keys** sends combinations your computer keeps for itself: Ctrl+Alt+Del, Ctrl+Esc, Alt+Tab, Alt+F4, the Super (Windows) key, Escape, Tab, and Print Screen. Under **Workspaces** it also sends the desktop's own shortcuts: **Workspace 1** to **Workspace 4** (Ctrl+Alt+1 to 4), **Next workspace** and **Previous workspace** (Ctrl+Alt+Right and Left), and **Open launcher** (Super). Use these when pressing the shortcut yourself does nothing; on a Mac, for example, Ctrl+Option+2 reaches the machine as a plain "2".

While the desktop has focus, every key goes to the machine. **Shift+Escape** moves focus back to the controls.

### Full page in its own tab

**Open in new tab** on the Desktop tab, **Desktop** in a machine's row menu on the Machines page, and **Desktop** at the top of a machine's overview all open the desktop full page in a new browser tab: only the remote screen, edge to edge, with no console around it. It connects as soon as it opens and scales the screen to fit. The tab is titled with the machine's name, such as "agent-primary — Desktop".

A small handle on the left edge opens the controls: **Send keys**, **Clipboard** (send text or your clipboard to the machine, and copy what the machine copied), **Full screen**, **View only**, **Reconnect**, **Disconnect**, and **Back to machine**. Shift+Escape moves focus from the remote screen to the handle. While it connects you see "Connecting to the desktop…"; if that takes more than about 10 seconds the page says why it may be slow and offers **Reconnect** and **Back to machine**. A dropped connection reconnects on its own, as on the tab. The Desktop tab keeps working as before; both can be open at once.

### Browser mode

**Browser** (next to **Open in new tab**, in the row menu, and at the top of the overview) opens the same full page showing only the machine's web browser, with no desktop shell around it. The page asks for it with `mode=browser` on the desktop WebSocket, and opens only when the server confirms browser mode. A machine whose image or host can't stream the browser on its own (`503 browser_unavailable`, or a host that ignores the mode) shows "Browser mode isn't available on this machine" with a link to the full desktop, whose web browser is in the app launcher.

### Opening apps

Applications start from the desktop itself: click the apps-grid icon at the left of the top bar, or press the Super (Windows) key (or **Send keys** › **Open launcher** if your computer keeps that key), then type to search, for example "chrom" for the web browser, and press Enter. Arrow keys move through the list and Escape closes it. Apps open maximized under the top bar. Machine images whose desktop has no launcher yet open apps from the right-click menu instead.

### From the Machines page

The row menu (⋯) of each machine offers **Desktop** and **Browser** (each in a new tab), **Terminal**, **Files**, and **Copy SSH**, next to Open overview, Run command, Start or Stop, Copy ID, and Delete. Desktop and Browser are disabled with "(Machine is not up)" while the machine isn't running, and for roles that can't open a desktop. Copy SSH copies the `ssh` command once an SSH key is installed and the machine's region has an SSH gateway; otherwise it says which is missing.

### Clipboard and typing

- **Text for the remote machine**: **Type it** sends the text as keystrokes, which works in any application and from a phone keyboard. **Send to remote clipboard** puts it on the machine's clipboard to paste there; VNC clipboards carry Latin-1 text unless the server supports more. **Paste my clipboard** sends your clipboard directly, if the browser lets the page read it.
- **Remote clipboard** shows text copied on the machine; **Copy to my clipboard** copies it to yours.

### On phones

The panel keeps the remote screen's shape at narrow widths. Tap to click, and use **Type it** for text. **View only** is useful for watching a long job.

## Latency

Every frame and keystroke travels from your browser to the control plane, on to the machine's host, and back, so expect a delay comparable to the round trip to the machine's region plus a few frames of encoding. Typing and pointing are fine for administration, installers, and checking a GUI test; video and fast animation are not smooth. Scaling a large remote screen down costs your browser some work; **Resize remote to window** avoids it.

## Security model

- **A ticket, no VNC password.** The console mints a single-use ticket with your browser session and CSRF token (`POST /v1/machines/{machine_id}/desktop/tickets`). It works once, within 30 seconds, for that machine and that session. The WebSocket (`GET /v1/machines/{machine_id}/desktop?ticket=…`) also checks your session cookie and that the page is on the console's configured address. The VNC server on the machine is reached only through this bridge, so it has no password of its own; if one ever asks for a password, the console refuses and reports it.
- **The console records nothing.** It relays the screen and your input to the machine without storing or logging them.
- **Your role decides.** Role changes apply to the next connection.

## Status and errors

| What you see                                      | Why                                                                 | What to do                                                           |
| ------------------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------- |
| This machine has no desktop yet                   | `503 desktop_unavailable`: the image or host has no desktop support | Use the terminal                                                     |
| The machine isn't running                         | `409 machine_not_running`                                           | **Start** it, then connect                                           |
| The machine stopped                               | The machine slept or was stopped during the session                 | **Start** it, then connect                                           |
| Too many desktops opened                          | `429 rate_limited`; the panel counts down `Retry-After`             | Reconnect when the countdown ends                                    |
| Your role can't open a desktop                    | `403 forbidden`                                                     | Ask an Owner or Admin                                                |
| Closed: the machine already has 4 desktop viewers | `limit`                                                             | Close a viewer elsewhere, then reconnect                             |
| Another viewer took over this desktop             | `replaced`                                                          | Reconnect to take it back                                            |
| Closed after no input for the idle timeout        | `idle_timeout`                                                      | Reconnect                                                            |
| Connection lost / host became unreachable         | The network or the machine's host dropped                           | The panel reconnects on its own, waiting 1, 2, 4, 8, then 16 seconds |
| Browser mode isn't available on this machine      | `503 browser_unavailable`, or the host ignores `mode=browser`       | Open the full desktop and start the browser from the launcher        |

## Protocol

After the upgrade the server sends one text message, `{"type":"opened","width":1280,"height":800}`. Add `mode=browser` to the WebSocket query (`GET /v1/machines/{machine_id}/desktop?ticket=…&mode=browser`) for browser mode; the server confirms it with `"mode":"browser"` in `opened`, and the default `desktop` needs no parameter. From then on binary messages are raw RFB (VNC protocol) bytes in both directions. Other text messages are JSON control from the server: `{"type":"closed","reason":"…"}` is final (`idle_timeout`, `machine_stopped`, `deleted`, `replaced`, `runtime_unavailable`, `shutdown`, `limit`, `normal`, or `revoked` when the organization was [suspended](/docs/guides/billing#suspended-organizations)), and `{"type":"error","code":"…"}` reports a problem. The remote screen is resized inside RFB (SetDesktopSize), not with a control message.

The desktop routes are not in the [API reference](/docs/api) yet; they follow the web terminal's ticket flow and errors.

---

<!-- Source: /docs/guides/agents.md -->

# Coding agents

> Run Claude Code, Codex, or Pi inside a machine, follow what it does, steer or interrupt it, and pick up a conversation later.

A coding agent runs inside a running machine, in its `/work` directory, with the machine's tools. You send it a prompt, follow its events as they happen, add instructions while it works, and stop it. Each machine keeps several conversations, and you can resume any of them. Prompts, attachments, and the agent's output stay on the machine's disk.

In the console, open a machine and choose **Agents**.

## Provider keys

The agent uses the provider keys in the machine's [environment](/docs/guides/environments): for example `ANTHROPIC_API_KEY` for Claude Code or `OPENAI_API_KEY` for Codex. A machine created without an environment gives the agent no keys, so add one to an environment and create the machine with it. Keys never appear in requests, events, or VMYard's records.

## Start or resume a conversation

```sh
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE/agents/prompt" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"provider": "claude", "model": "sonnet", "reasoning_effort": "medium", "text": "Add a health check endpoint and run the tests."}'
```

The answer (`202`) is the turn, with its `conversation_id`. Send that `conversation_id` with the next prompt to continue the conversation; a conversation keeps its agent. `GET /v1/provider-models` lists each agent's models and reasoning efforts. Up to 16 attachments (16 MiB together) are written to the machine for the agent to read.

## Follow the events

`GET /v1/machines/{id}/agents/events?conversation_id=…` answers JSON by `cursor`, waiting up to `wait_seconds` (at most 30) for an event, or a server-sent event stream with `Accept: text/event-stream`. Each SSE event's `id` is the cursor after it, so a client that reconnects with `Last-Event-ID` resumes where it stopped, without repeats. The stream ends with an `idle` event when no turn is running.

| `type` | Meaning |
| --- | --- |
| `turn_started` | The agent started, with its model and reasoning effort. |
| `input_accepted` | The agent took an input (`kind`: `prompt`, `steer`, or `interrupt`) with this `input_id`. |
| `text_delta`, `message` | Text the agent wrote, piece by piece or whole. |
| `thinking_delta` | The agent's reasoning, when it shares it. |
| `tool_call`, `tool_result` | A tool the agent ran (`id`, `name`, `input`) and what came back (`output`, `is_error`). |
| `usage` | Tokens and the agent's own cost estimate. |
| `error` | Something went wrong (`code`, `message`). |
| `turn_end` | The turn ended: `outcome` is `completed`, `failed`, or `interrupted`. |

## Steer and interrupt

While a turn runs, `POST /v1/machines/{id}/agents/steer` with the `conversation_id` and `text` adds instructions; the agent confirms when it takes them with an `input_accepted` event carrying the steer's `input_id`. `POST /v1/machines/{id}/agents/interrupt` asks the turn to stop, and `force: true` stops it at once. Both need an `Idempotency-Key`. See [Errors](/docs/guides/errors#coding-agents).

---

<!-- Source: /docs/guides/files.md -->

# Files

> Browse a machine's /work as a live tree, and write, read, upload, and download files up to 32 MiB.

Files move in and out of a machine through `/work`. Paths are relative to `/work` (`notes/todo.txt`) or written in full (`/work/notes/todo.txt`). Paths can't contain `.` or `..` segments, empty segments, or NUL, and can't point anywhere else.

## Browse files in the console

A machine's **Files** tab lists `/work` live while the machine runs:

- The header shows how much data `/work` holds and how many files (**Your data 173 MiB · 301 files**). **Refresh** lists it again.
- Each row shows its size (a folder counts everything inside it) and its share of the total, with a small bar. Hover a row for its full path and modified time; the selected row shows the time inline.
- Folders open with a click or the arrow keys. The first listing goes two levels deep; deeper folders are listed when you open them.
- **Fuzzy search files…** matches names and paths in the folders listed so far (`claudeset` finds `.claude/settings.json`), opens the folders on the way to each match, and highlights the matched letters.
- **Name / Size** sorts the tree. Press the active one again to reverse it: names start A to Z with folders first, sizes start largest first.
- Keyboard: ↑ ↓ move, → opens a folder or steps into it, ← closes it or steps out, Home and End jump, Enter opens a folder or a file.

The bar under the tree acts on the selected row (or on `/work` when nothing is selected):

| Action | What it does |
| --- | --- |
| **Open** | Shows a text file under **Read a file**. |
| **Download** | Saves a file (up to 32 MiB) to this device. |
| **Download folder** | Saves a folder as a `.tar.gz` archive. Very large folders answer `413 archive_too_large`; download smaller folders or copy over [SSH](/docs/guides/ssh). |
| **Upload here** | Picks a local file and uploads it into the folder, then confirms it by reading it back. |
| **New file** | Fills **Write a file** with the folder's path. |
| **Copy path** | Copies the absolute path. |

Above the tree, **Latest snapshot** shows when the newest ready [snapshot](/docs/guides/snapshots) was taken and how much data it holds; restore or fork from it on the **Snapshots** tab. Docker development machines never push snapshots, so they show **No snapshots yet**.

A stopped machine shows **Start** in place of the tree. If a listing stops early (very large folders), the tree says so and marks the folder **Partial list**.

The listing comes from `GET /v1/machines/{id}/files/tree?path=/work&depth=2` (`path` may be `/work`, `/root`, or `/home/<user>`, or a folder inside one; `depth` is 1 to 4), which answers `{path, total_bytes, file_count, truncated, entries}`; each entry has `name`, `path`, `type` (`file`, `dir`, or `symlink`), `size_bytes`, `modified_at`, and, within the depth, `children`. Folders download from `GET /v1/machines/{id}/files/archive?path=`, and the snapshot strip reads `GET /v1/machines/{id}/snapshots/latest` (`{id, created_at, completed_at, source, tier, size_bytes}`, or `404 no_snapshot`).

## Write a file

```sh tab="CLI"
vy cp ./build.tar.gz dev:build.tar.gz
echo 'debug=true' | vy cp - dev:app/config.env
```

```ts tab="TypeScript"
await machine.files.write("app/config.json", JSON.stringify({ debug: true }));
await machine.files.write("bin/tool", new Uint8Array(bytes)); // bytes go as base64
```

```python tab="Python"
machine.files.write("app/config.json", '{"debug": true}')
machine.files.write("bin/tool", open("tool", "rb").read())  # bytes go as base64
```

```sh tab="curl"
curl -X PUT "$VMYARD_API_URL/v1/machines/$MACHINE_ID/files?path=app/config.json" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"encoding": "text", "content": "{\"debug\": true}"}'
```

`PUT /v1/machines/{id}/files?path=` takes `{encoding, content}` where `encoding` is `text` or `base64`. It replaces the whole file. Writing is an [operation](/docs/concepts/operations): the answer is `202`, and the file is written once the operation succeeds. VMYard moves files in 512 KiB chunks and checks the size the machine reports against the bytes it sent, so a partial write fails rather than passing silently.

## Read a file

```sh tab="CLI"
vy cp dev:out/report.txt .
vy cp dev:out/report.txt -      # to stdout
```

```ts tab="TypeScript"
const text = await machine.files.read("out/report.txt");
const bytes = await machine.files.readBytes("out/image.png");
```

```python tab="Python"
text = machine.files.read("out/report.txt")
data = machine.files.read_bytes("out/image.png")
```

```sh tab="curl"
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/files?path=out/report.txt&encoding=text" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

`GET /v1/machines/{id}/files?path=&encoding=` returns `{path, size, encoding, content}`. Reads wait up to 30 seconds; if the machine hasn't answered by then, the response is `202` with an operation to follow, and the finished operation carries the content in `file_ranges`. The SDKs and CLI handle that for you.

Read with `encoding=base64` for binary files. Reading a file that isn't valid UTF-8 as `text` fails with `422 file_not_text`.

## Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 404 | `file_not_found` | No file at that path. |
| 413 | `file_too_large` | The file is larger than 32 MiB. |
| 422 | `file_not_text` | Not UTF-8; read it as `base64`. |
| 422 | `invalid_request` | The path is not allowed. |
| 409 | `machine_not_running` | Listing needs a running machine. |
| 413 | `archive_too_large` | The folder is too large for one archive. |

## Access

Reading and writing files needs a running machine and Owner, Admin, or Operator access, or an API key with at least the `use_existing` preset. File content is whatever the machine holds: treat it as untrusted input.

---

<!-- Source: /docs/guides/machine-metrics.md -->

# Machine metrics

> CPU, memory, disk, disk I/O, and network use for each machine, with one-minute history, live samples, and disk warnings.

Every machine's host samples it every 5 seconds. VMYard keeps the latest values and one-minute history for the last 24 hours. Every member of the organization can read them, and so can every API key preset.

## What is measured

| Value | Meaning |
| --- | --- |
| CPU | Millicores used over the host's last sampling interval (1000 = one core), as a share of the machine's CPU limit. |
| Memory | Memory charged to the machine (RAM in use, page cache, and the virtual machine monitor), as a share of its limit. |
| Disk | Blocks the machine's disk image holds, as a share of its size. It is an upper bound: blocks the machine freed stay allocated. |
| Disk I/O | Bytes per second read from and written to the disk. |
| Network | Bytes per second received (`rx`) and sent (`tx`) by the machine. |

A value the host didn't measure is absent, never zero: CPU and memory while the machine is asleep, and Docker machines on macOS. Metrics describe resource use only. They are not used for billing.

## In the console

The machine list has a **CPU / RAM / Disk / IO** column with a bar and a number for each value. Hover or focus it for the used amount, the limit, and the I/O and network rates. On a phone the same values appear in each machine's card. A machine that hasn't been sampled yet shows "—".

The machine's **Overview** has a **Metrics** section with charts for CPU, memory, disk, disk I/O, and network over the last hour, 6 hours, or 24 hours. Hover or focus a chart (then use the arrow keys) to read the values at one minute; the table under the charts gives the latest, average, and peak of each value.

**Live** follows the host's own samples, about 5 seconds apart, for as long as it stays on. Live needs a running or sleeping machine. When it isn't available the console says why and goes back to one-minute history.

### Stale values

When VMYard couldn't read a machine recently, its values are kept and marked **Stale** with the reason. They are the last values known, not zero.

| Reason | Meaning |
| --- | --- |
| Host unreachable | The machine's host couldn't be read. |
| Not reported | The host no longer reports this machine, for example after it stopped. |
| Poll overdue | No reading confirmed the values in the last three polling intervals. |

## Disk warnings

| Flag | Meaning |
| --- | --- |
| `disk_almost_full` | At least 90% of the machine's disk is used. |
| `disk_full` | At least 98% is used. Writes in the machine may fail. |
| `host_disk_low` | The host the machine runs on is low on disk. This is not your machine's disk; nothing for you to clean up. |

The disk flags come from the machine's own filesystem report while it is fresh, otherwise from the disk image, so treat them as advisory: VMYard enforces nothing on them. To free space, find large directories from the terminal (`du -sh /work/* | sort -h`), then delete what you don't need, or read files you want to keep from the [Files](/docs/guides/files) tab first. Owners, admins, and operators also get the `disk_almost_full` and `disk_full` [email alerts](/docs/guides/email-alerts) by default, at most once an hour per machine.

## Guest-reported values

The response may include `guest_reported`: memory and filesystem totals that the machine's own agent reports. Code inside the machine can change them, so the console shows them in a separate, labelled block. They never reach the history, billing, or enforcement.

## Read metrics with the API

The latest values come with every machine as `metrics`, or `null` until it is first sampled:

```json
"metrics": {
  "sampled_at": "2026-10-12T11:59:30Z",
  "stale": false,
  "stale_reason": null,
  "state": "running",
  "cpu_percent": 37.5,
  "cpu_millis": 1500,
  "cpu_limit_millis": 4000,
  "memory_percent": 62.0,
  "memory_bytes": 5325918208,
  "memory_limit_bytes": 8589934592,
  "disk_percent": 91.2,
  "disk_used_bytes": 78383153152,
  "disk_size_bytes": 85899345920,
  "io_read_bps": 1250000,
  "io_write_bps": 420000,
  "net_rx_bps": 96000,
  "net_tx_bps": 18000,
  "flags": ["disk_almost_full"]
}
```

History is one request per machine:

```sh tab="curl"
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/metrics?resolution=1m&since=2026-10-12T11:00:00Z" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

- `resolution=1m` (the default) returns stored minutes, oldest first, from `since` (default: the last 24 hours). Each point averages the minute, with `cpu_millis_max` and `memory_bytes_max` for its peak. A response holds at most 1440 points; when `next_since` is set, ask again with it as `since`.
- `resolution=live` returns the host's retained samples (about 5 seconds apart, for about 15 minutes) newer than `since`. Poll with the last point's `t` as `since`. A machine that isn't running or sleeping answers `409 machine_not_running`; an unreachable host `503 runtime_unavailable`; a server without a runtime `503 metrics_unavailable`. On any of these, read `1m` instead.

Rates are bytes per second. The console shows them in decimal units (1 kB/s = 1,000 B/s) and sizes in binary units (1 GiB = 1,073,741,824 bytes).

---

<!-- Source: /docs/guides/ports.md -->

# Ports and private URLs

> Expose a machine's ports as HTTPS URLs, keep them private with short-lived tokens, or make them public.

Any TCP port in a running machine can be served at its own HTTPS address:

```text
https://<label>-<port>.<edge domain>
```

`label` is 12 random characters given to the machine the first time it exposes a port. It never changes and is never reused, even after the machine is deleted, so a URL can never reach a different machine. VMYard's edge terminates TLS and forwards to the machine; the machine is never reachable directly.

> [!NOTE]
> In the console, a machine's **Network** tab exposes ports and issues links. The CLI has `vy ports` and the SDKs have `machine.ports`; this page shows the HTTP API. Ports need a VMYard deployment with an edge configured; without one, these routes answer `503 ingress_unavailable`. Machines on the `docker` development backend have no network and can't expose ports.

## Expose a port

```sh
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/ports" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"port": 8080}'
```

| Field | Meaning |
| --- | --- |
| `port` | 1–65535, except 22 (use an [SSH key](/docs/guides/ssh) for SSH). |
| `public` | `true` serves the URL to anyone. The default, `false`, requires a token. |
| `localhost` | `true` also reaches a service that listens only on `127.0.0.1` or `[::1]` inside the machine. |

Exposing is an [operation](/docs/concepts/operations); the port is open once it succeeds. Exposing a port that is already open replaces its `public` and `localhost` settings. A machine can have up to **16** exposed ports (`409 port_limit_reached`).

## List ports

```sh
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/ports" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json
{
  "label": "k7f2mq3x9a1b",
  "items": [
    { "port": 8080, "public": false, "localhost": false, "url": "https://k7f2mq3x9a1b-8080.on.example.com" }
  ]
}
```

The list shows ports as the machine's host last confirmed them. Any member and any API key preset can read it.

## Open a private port

Private ports need a token. Ask for one, valid for 1 to 3,600 seconds (900 by default):

```sh
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/ports/8080/token" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl_seconds": 900}'
```

```json
{
  "url": "https://k7f2mq3x9a1b-8080.on.example.com",
  "url_with_token": "https://k7f2mq3x9a1b-8080.on.example.com/?_token=v1.…",
  "header_token": "v1.…",
  "expires_at": "2026-10-12T06:06:01Z"
}
```

- **In a browser**, open `url_with_token`. The edge checks the token, sets a cookie scoped to that one host, and redirects to `url` so the token leaves the address bar.
- **From code**, send the token in a header:

```sh
curl https://k7f2mq3x9a1b-8080.on.example.com/health \
  -H "X-Vmyard-Token: $HEADER_TOKEN"
```

A token opens only the one machine and port it was issued for and stops working at `expires_at`. Missing credentials get `401` from the edge; invalid or expired ones get `403`. VMYard doesn't store tokens; issuing one is recorded with its port and expiry. Asking for a token for a port that isn't exposed is `404 port_not_exposed`.

## What the edge forwards

- HTTP/1.1 requests, streamed responses (server-sent events, long polls), and WebSocket upgrades.
- The edge sets `X-Forwarded-For`, `X-Forwarded-Proto`, and `X-Forwarded-Host`, and removes the token cookie and header before forwarding.
- Idle connections close after 5 minutes without traffic by default.

## Close a port

```sh
curl -X DELETE "$VMYARD_API_URL/v1/machines/$MACHINE_ID/ports/8080" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Closing a port that isn't exposed makes the operation fail. Deleting a machine closes all of its ports.

## Access

Exposing, closing, and issuing tokens need a running machine and Owner, Admin, or Operator access (or a `use_existing` key). Port changes that fail emit `operation.failed`; successful ones emit no webhook.

---

<!-- Source: /docs/guides/ssh.md -->

# SSH

> Install your public key on a machine and connect through VMYard's SSH gateway.

Install one OpenSSH public key on a machine and VMYard gives it a port on an SSH gateway. Connect with any SSH client.

> [!NOTE]
> In the console, a machine's **Network** tab installs a key and copies the `ssh` command. From a terminal, `vy ssh <machine>` installs your key if needed and runs `ssh`; the SDKs have `setSshKey` (`set_ssh_key` in Python); or use the HTTP API below, then your own `ssh`. SSH needs a deployment with an edge configured (otherwise `503 ingress_unavailable`) and an image that runs an SSH server. Machines on the `docker` development backend can't use SSH.

## Install a key

```sh
curl -X PUT "$VMYARD_API_URL/v1/machines/$MACHINE_ID/ssh-key" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{\"public_key\": \"$(cat ~/.ssh/id_ed25519.pub)\"}"
```

`public_key` is one line in OpenSSH format, `TYPE BASE64 [COMMENT]`, with no trailing newline, at most 8 KiB:

- `ssh-ed25519`
- `ecdsa-sha2-nistp256`, `ecdsa-sha2-nistp384`, or `ecdsa-sha2-nistp521`
- `ssh-rsa` of at least 3072 bits

Installing is an [operation](/docs/concepts/operations) and needs a running machine. Installing another key replaces the first and keeps the same gateway port. VMYard records the key's type and `SHA256:` fingerprint, never the key itself.

## Connect

Once the operation succeeds, the machine's `ssh` field says where to connect:

```sh
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID" -H "Authorization: Bearer $VMYARD_API_KEY" | jq .ssh
```

```json
{ "host": "ssh.eu.example.com", "port": 2201, "user": "vmyard" }
```

```sh
ssh -p 2201 vmyard@ssh.eu.example.com
```

The gateway only forwards your connection to port 22 in the machine; the machine's own SSH server checks your key. The login user is `vmyard` when the image has that user, otherwise `root`; use the `user` the API reports. `host` is `null` when the deployment has no gateway configured for the machine's host or region.

## Remove the key

```sh
curl -X DELETE "$VMYARD_API_URL/v1/machines/$MACHINE_ID/ssh-key" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Removing the key releases the gateway port, and `ssh` becomes `null`.

## Host keys

Host keys come from the machine's image and disk. They stay the same across a stop and start of the same machine.

## Access

Installing and removing keys needs Owner, Admin, or Operator access, or an API key with at least the `use_existing` preset. An invalid key is refused with `422` before anything changes.

---

<!-- Source: /docs/guides/networking.md -->

# Internet access and IPv6

> Choose whether a machine can reach the internet, change it later, read its public IPv6 address, and know the limits and the operator's kill switch.

Every machine has an **egress policy** that decides what it can reach outside VMYard. The machine's host applies and enforces it; VMYard requests it and reports what the host applied.

| Policy | The machine can reach |
| --- | --- |
| `internet` | The public internet, within the host's limits (below). |
| `none` | Only the destinations your VMYard operator allows for every machine on the host. |

Nothing reaches a machine from outside because of its egress policy. Inbound traffic still needs an [exposed port](/docs/guides/ports) or an [SSH key](/docs/guides/ssh).

> [!NOTE]
> In the console, the create page has an **Internet access** choice (Host default, Internet, or None), and a machine's **Network** tab shows its policy and public IPv6 address and changes the policy. The CLI has `vy network` and the SDKs have `setNetwork` (`set_network` in Python); this page shows the HTTP API.

## What internet access allows

`internet` is the public internet only. Even with it:

- Private, link-local, metadata, and reserved address ranges stay unreachable, so a machine can't reach its host, your cloud's metadata service, or other machines.
- Port 25 (SMTP) is blocked. Send mail through a provider's submission port or API instead.
- Each machine has its own connection-rate and bandwidth limits, so one busy machine can't starve the others.

## Choose it when you create a machine

Add `network` to the body of `POST /v1/machines`, next to the image, plan, and region you already send:

```json
{
  "network": { "egress": "none" }
}
```

Leave `network` out and the host's default applies: `internet`, unless your operator chose `none`. The policy is part of the request: a retry with the same `Idempotency-Key` resends it, and replaying the key with a different policy answers `409 idempotency_conflict`.

`network` can't be combined with `template` (`422`). A machine created from a [template](/docs/guides/templates), like a [fork or a restore](/docs/guides/fork-and-restore), keeps its host's policy; change it afterwards.

`GET /v1/plans` lists the policies each plan offers in `network_access.egress_options`. Every plan offers both today.

## Change it later

```sh
curl -X PUT "$VMYARD_API_URL/v1/machines/$MACHINE_ID/network" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"egress": "internet"}'
```

The machine must be running or stopped; any other state answers `422`. The change is a `network_set` [operation](/docs/concepts/operations) (`202 Accepted`, `requested_action: "network_set"`). It succeeds only when the host reports the requested policy applied, and it never starts, stops, or restarts the machine.

If the host refuses, for example because it has no guest networking or its operator turned internet access off, the operation ends `failed` and nothing changes. An uncertain change is retried with the exact same request. A failed change sends the `operation.failed` [webhook](/docs/guides/webhooks) and the opt-in `operation_failed` [email alert](/docs/guides/email-alerts); a successful one sends no event.

## Who may choose

Choosing a machine's egress is part of choosing the machine, so it needs the permission to create machines, both at create and when changing it later: Owner, Admin, and Operator members, and API keys with the `create_and_use` or `full_access` [preset](/docs/guides/api-keys). Other members see the policy but can't change it.

## Read it

`GET /v1/machines/{machine_id}` reports `network` as the machine's host last applied it:

```json
{
  "network": { "egress": "internet", "ipv6_address": "2001:db8:7a3:1::2f" }
}
```

| Field | Meaning |
| --- | --- |
| `egress` | `internet` or `none`. |
| `ipv6_address` | The machine's public IPv6 address when its host routes a global IPv6 prefix to its machines, otherwise `null`. Inbound traffic to it still reaches only exposed ports. |

`network` is `null` until a host has reported one, and stays `null` on hosts without guest networking. VMYard records the host's report after every operation it confirms on the machine, so a change made on the host (such as the kill switch below) shows up after the machine's next operation. Webhook events carry the same object as `data.machine.network`.

## The operator's kill switch

There is no organization setting for egress. The operator who runs a host can turn internet access off for the whole host. Then:

- Requests for `internet` on that host fail with nothing changed.
- Machines on it are moved to `none`, which their `network` shows after their next operation.

---

<!-- Source: /docs/guides/setup-scripts.md -->

# Setup scripts

> Run a shell script once, right after a new machine first starts, and check whether it worked.

A setup script runs once, as `/bin/sh -c <script>`, after a new machine is first ready. Use it to install packages, clone a repository, or write configuration.

## Add one when you create a machine

```sh tab="CLI"
vy new --name dev --setup-script ./setup.sh --wait
cat setup.sh | vy new --name dev --setup-script - --wait
```

```ts tab="TypeScript"
const machine = await vy.machines.create({
  name: "dev",
  setupScript: "apt-get update && apt-get install -y jq",
});
```

```python tab="Python"
machine = vy.machines.create(
    name="dev",
    setup_script="apt-get update && apt-get install -y jq",
)
```

```sh tab="curl"
# In the create body:
#   "setup_script": "apt-get update && apt-get install -y jq"
```

The script can be at most 65,527 bytes (65,424 on a machine with an [environment](/docs/guides/environments)) and can't contain NUL. It can only be set at creation. On a machine with an environment, the script runs after the environment is installed, with its variables loaded.

## Check the result

The setup script is its own exec [operation](/docs/concepts/operations), queued with the create and run right after it. The machine's `setup_operation_id` names it.

```ts tab="TypeScript"
import { OperationError } from "@vmyard/sdk";

try {
  await vy.operations.wait(machine.data.setup_operation_id!);
  console.log("setup finished");
} catch (error) {
  if (!(error instanceof OperationError)) throw error;
  console.log("setup failed:", error.errorCode, error.operation.exec_result);
}
```

```python tab="Python"
from vmyard import OperationError

try:
    vy.operations.wait(machine.data["setup_operation_id"])
    print("setup finished")
except OperationError as error:
    print("setup failed:", error.error_code, error.operation.get("exec_result"))
```

```sh tab="curl"
SETUP_ID=$(curl -s "$VMYARD_API_URL/v1/machines/$MACHINE_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY" | jq -r .setup_operation_id)
curl "$VMYARD_API_URL/v1/operations/$SETUP_ID" -H "Authorization: Bearer $VMYARD_API_KEY"
```

| Outcome | What it means |
| --- | --- |
| `succeeded`, `exit_code` 0 | The script ran and exited cleanly. |
| `failed` with `exec_nonzero` | The script exited non-zero. The machine keeps running; read the output in `exec_result`. |
| `failed` with `exec_timed_out` | The script ran longer than 10 minutes. The machine keeps running. |
| `failed` with `setup_prerequisite_failed` | The create, or the environment install before it, didn't succeed, so the script never ran. |

The `vy new --wait` and SDK `create` calls wait for the create operation, not the setup script. Wait for `setup_operation_id` before you rely on what the script installs.

## Limits

The script runs with the longest timeout a command can have (10 minutes). Output is captured up to 1 MiB, like any command. Reusing a create's idempotency key with a different script is `409 idempotency_conflict`.

---

<!-- Source: /docs/guides/environments.md -->

# Environments

> Store environment variables and secret files once, encrypted, and have VMYard install them in machines, with immutable versions and controlled upgrades.

An **environment** is a named set of environment variables and secret files that belongs to your organization. VMYard encrypts it at rest and installs it in machines: when a machine is created, and again when you upgrade the machine to a newer version. An organization can have up to **50** environments.

> [!NOTE]
> Use `vy env`, the SDKs (`environments`), or the HTTP API below. Environments need a deployment with encryption keys configured. Without them, environments can still be listed, but changes and reveals answer `503 environments_unavailable`.

## Create an environment

```sh
curl -X POST "$VMYARD_API_URL/v1/environments" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "staging",
    "vars": {"DATABASE_URL": "postgres://app@db.internal/app", "LOG_LEVEL": "info"},
    "files": [{"path": "secrets/service-account.json", "contents": "{\"type\": \"service_account\"}"}]
  }'
```

| Field | Meaning |
| --- | --- |
| `name` | 1–63 lowercase letters, digits, and `-`, starting with a letter; unique in the organization. Defaults to `base`. |
| `vars` | Variable names to values. |
| `files` | Secret files: `{path, contents, encoding}`, with `encoding` `text` (default) or `base64`. |
| `is_default` | Make it the organization's default. The first environment becomes the default unless you send `false`. |
| `safe_for_third_parties` | A label for environments whose contents may be shared. VMYard stores and returns it but doesn't enforce it yet; for machines shared with third parties, create them with `no_env`. |

The answer is `201` with the new environment. A taken name is `409 environment_name_taken`; a 51st environment is `409 environment_limit_reached`.

## Rules for variables and files

Everything is checked before anything is stored; problems come back as `422` with `field_errors`.

- **Variable names** match `^[A-Za-z_][A-Za-z0-9_]{0,127}$`. Values are at most 32 KiB, without NUL.
- **File paths** are relative to `/work`, for example `secrets/token.txt`. A path can't start with `/` (not even `/work/…`), can't have a component starting with `~`, can't have empty, `.`, or `..` components or control characters, can't be longer than 1024 bytes, and can't be under the reserved `.vmyard` directory. Files are at most 256 KiB.
- A version holds at most 128 variables, 32 files, and 1 MiB of values and contents in total.

## Change variables and files

Each change writes a new version. These routes answer `200` with the environment.

```sh
# Set or replace a variable
curl -X PUT "$VMYARD_API_URL/v1/environments/$ENV_ID/vars/LOG_LEVEL" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" -d '{"value": "debug"}'

# Remove a variable (404 variable_not_found if it isn't there)
curl -X DELETE "$VMYARD_API_URL/v1/environments/$ENV_ID/vars/LOG_LEVEL" \
  -H "Authorization: Bearer $VMYARD_API_KEY"

# Set or replace a secret file
curl -X PUT "$VMYARD_API_URL/v1/environments/$ENV_ID/files" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "secrets/token.txt", "contents": "s3cr3t\n"}'

# Remove a secret file (404 file_not_found if it isn't there)
curl -X DELETE "$VMYARD_API_URL/v1/environments/$ENV_ID/files" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" -d '{"path": "secrets/token.txt"}'
```

`PATCH /v1/environments/{id}` changes only `name`, `is_default`, and `safe_for_third_parties`; that is metadata and doesn't create a version. Setting `is_default: false` on the default leaves the organization without one.

`DELETE /v1/environments/{id}` (`204`) removes the environment and frees its name. Machines keep the version they already have. Deleting the default leaves the organization without one.

## Versions

Versions are numbered 1, 2, 3, … and never change once written. `current_version` on the environment is the newest. `GET /v1/environments/{id}/versions` lists them newest first, with variable names, file paths and sizes, and a `change` summary such as `{"action": "set_variable", "name": "API_TOKEN", "size": 40}`. Values are never included.

## Use an environment in a machine

When you create a machine, choose its environment in the create body:

| Field | Effect |
| --- | --- |
| `environment_id` or `environment` (the name) | Use that environment. |
| neither | Use the organization's default environment, if there is one. |
| `no_env: true` | No environment at all, not even the default. |

Combining them, or naming an environment that doesn't exist, is `422 unknown_environment`. The machine is pinned to the version that was current when it was created; later changes to the environment don't reach it until you upgrade it.

The machine's `environment` field shows where it stands:

```json
{
  "environment_id": "2a7d4c1e-8b3f-4f6a-9c5d-0e1f2a3b4c5d",
  "version_id": "4d2b9c1e-7a3f-4e58-b1c6-2f9d8e7a6b50",
  "version": 3,
  "applied_version_id": "4d2b9c1e-7a3f-4e58-b1c6-2f9d8e7a6b50",
  "status": "applied",
  "error_code": null,
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

`status` is `pending` until the apply operation succeeds, then `applied`, or `failed` with an `error_code`.

## What gets installed

VMYard installs the environment with an `apply_environment` [operation](/docs/concepts/operations) that runs once the machine is first ready, before any [setup script](/docs/guides/setup-scripts):

- Variables go to `/work/.vmyard/environment` as `export NAME='value'` lines, quoted so that sourcing the file never evaluates a value. Login shells load it through `/etc/profile.d/vmyard-environment.sh`.
- Commands, background commands, and the setup script on a machine with an environment run with the variables loaded.
- Each secret file is written to `/work/<path>` with mode `0600` (directories `0700`), created before any content is written. Files from the previous version that the new version no longer has are removed.

Values travel only inside the encrypted version and the file uploads; they never appear in operation requests, operation results, audit records, or logs.

On a machine with an environment, the setup script can be at most 65,424 bytes, because the wrapper that loads the variables counts toward the command-size limit.

If the apply fails, the machine keeps running, `environment.status` becomes `failed`, and VMYard emits `operation.failed`. A setup script waiting on that apply fails with `setup_prerequisite_failed`. Apply error codes include `environment_prepare_failed`, `environment_decrypt_failed`, `environment_keys_unavailable`, and `environment_prerequisite_failed` (the create itself failed).

## Upgrade machines to the current version

```sh
curl -X POST "$VMYARD_API_URL/v1/environments/$ENV_ID/upgrade" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" -d '{}'
```

`POST /v1/environments/{id}/upgrade` applies the current version to every running machine that was created with this environment, or only to the `machine_ids` you list (at most 100). It answers `202` with one `apply_environment` operation per upgraded machine and a `skipped` list with a reason for the rest:

- `already_current`: the machine already has the current version.
- `not_running`: start the machine, then upgrade again.

Repeating the same request replays the same operations, so retries are safe. If a machine's version changed while the request was being made, the answer is `409 environment_upgrade_conflict`; retry it. Listing a machine that wasn't created with this environment is `422`.

## Reveal values

```sh
curl -X POST "$VMYARD_API_URL/v1/environments/$ENV_ID/reveal" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" -d '{}'
```

Reveal returns the variable values and file contents of the current version, or of `version_id`. File contents always come back base64-encoded so the exact bytes survive. Every reveal is recorded with who did it, the version, and the variable names and file paths (never the values).

## Who can do what

| Action | Who |
| --- | --- |
| List and read environments and versions (names, variable names, file paths and sizes) | Any member; any API key preset. |
| Create, change, delete, set or remove variables and files, reveal | Owner or Admin; an API key needs `full_access` and a creator who is still an Owner or Admin. |
| Upgrade machines | Owner, Admin, or Operator; an API key needs at least `use_existing`. |

## Encryption at rest

Each version's values and files are encrypted with AES-256-GCM under a fresh random 256-bit data key. That data key is itself encrypted (wrapped) under a key-encryption key that the VMYard deployment holds outside the database. The encryption is bound to the organization, environment, and version, so ciphertext copied elsewhere doesn't decrypt. Environment names, variable names, file paths, and sizes are stored unencrypted so they can be listed. Operators can rotate the key-encryption key without re-encrypting the data.

---

<!-- Source: /docs/guides/snapshots.md -->

# Snapshots and tiers

> Push a stopped machine to the snapshot store as a warm or cold snapshot, follow it to ready, list and delete snapshots one at a time or in bulk, and how long stops move down the tiers.

A **snapshot** stores a stopped machine in the deployment's snapshot store, so it can later be [restored as a new machine](/docs/guides/fork-and-restore) on any host. Taking a snapshot never changes the machine: it stays stopped, with the same ID, and you can start it as usual.

> [!NOTE]
> Use the **Snapshots** tab of a machine in the console, `vy snapshot` and `vy snapshots`, the SDKs, or the HTTP API below. Owners, Admins, and Operators take, restore, and delete snapshots; every member can list them.

## Tiers

| Tier | What is kept | A restore… |
| --- | --- | --- |
| `warm` (default) | Memory, device state, and disk | resumes the processes that were running when the machine stopped |
| `cold` | The disk | boots fresh from the disk |

Cold snapshots are smaller to keep. They need a KVM machine; Cloud Hypervisor hosts support warm snapshots only. Docker development hosts pause a stopped machine in place and cannot push it at all, and networked VMs cannot be pushed.

## Take a snapshot

The machine must be requested **and** observed stopped. Stop it and wait for the stop to succeed first; otherwise the push answers `409 machine_not_stopped`.

```sh
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/snapshots" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"tier": "warm"}'
```

The answer is `202` with `snapshot_id`, `operation_id`, `machine_id`, `operation_url`, and `snapshot_url`. A push is a durable [operation](/docs/concepts/operations): retry with the same `Idempotency-Key` and body to replay it, never to push twice.

The snapshot is `pending` until its operation settles it:

- `ready`, with `manifest`, `generation` (counting up per machine), `parent_manifest`, `size_bytes`, `uploaded_bytes`, `disk_synced`, and `completed_at`; or
- `failed`, with `error_code`. A push whose outcome stays uncertain through five attempts fails with `snapshot_outcome_unknown`; the machine is unchanged, so take a new snapshot.

```sh
curl "$VMYARD_API_URL/v1/snapshots/$SNAPSHOT_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

A successful push emits the [`snapshot.ready` webhook](/docs/guides/webhooks); a failed one emits `operation.failed`.

A machine keeps at most **20** snapshots you took (`409 snapshot_limit_reached`); delete one to take another.

## List and delete

`GET /v1/machines/{machine_id}/snapshots` lists a machine's snapshots, newest first, in cursor pages. [Templates](/docs/guides/templates) are not included. Each snapshot has a `source`: `api` (one you took), `tier_policy` (a long stop, below), or `automatic` (a capture of the running machine, see [Automatic snapshots](/docs/guides/automatic-snapshots)). The console's **Snapshots** tab filters by source.

```sh
curl -X DELETE "$VMYARD_API_URL/v1/snapshots/$SNAPSHOT_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

Deleting answers `204`. The snapshot disappears from VMYard and can no longer be restored; machines already restored from it are not affected. A push that hasn't settled can't be deleted yet (`409 snapshot_pending`).

## Delete several snapshots

Delete up to **100** snapshots by ID in one request (`422` for none or more than 100; duplicates are reported once):

```sh
curl -X POST "$VMYARD_API_URL/v1/snapshots/bulk-delete" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"snapshot_ids\": [\"$SNAPSHOT_A\", \"$SNAPSHOT_B\"]}"
```

Or delete all of a machine's snapshots, or only one source's with `?source=api`, `tier_policy`, or `automatic`:

```sh
curl -X DELETE "$VMYARD_API_URL/v1/machines/$MACHINE_ID/snapshots" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

Both answer `200` with a result for every snapshot, in request order (a machine's snapshots oldest first), even when some were not deleted:

```json
{
  "deleted": 2,
  "results": [
    { "snapshot_id": "…", "result": "deleted" },
    { "snapshot_id": "…", "result": "pending" },
    { "snapshot_id": "…", "result": "template" }
  ]
}
```

| `result` | Meaning |
| --- | --- |
| `deleted` | Deleted. |
| `not_found` | Unknown, already deleted, or another organization's. |
| `pending` | Kept: its push is still running. Delete it once it settles. |
| `template` | Kept: templates are deleted only through `DELETE /v1/templates/{template}`, so deleting all of a machine's snapshots reports its templates as kept. |

In the console, select snapshots on the **Snapshots** tab and choose **Delete selected**, or use **Delete automatic** and **Delete all**; each asks for confirmation and then lists every result. Owners, Admins, and Operators can delete.

## Stopped machines move down the tiers

Stopping a machine on a KVM host keeps a **hot** copy on that host: memory, device state, and disk, so `start` wakes it with its processes intact. On top of that, a background policy in the control plane pushes long stops to the snapshot store:

| Stopped for | VMYard pushes | Kept in the store |
| --- | --- | --- |
| 6 hours | a `warm` snapshot | memory, device state, disk |
| 7 days | a `cold` snapshot | the disk |

These are the defaults; operators of a deployment can change either threshold or turn the policy off. Policy snapshots have `source: "tier_policy"`, are requested at most once per stop and only while the machine is still in that stop, don't count toward the 20-snapshot limit, and replace the machine's earlier policy snapshots once ready. Only KVM machines qualify.

A policy push makes a stopped machine restorable on any host and protects it if its host is lost. It does not free the host: `start` still wakes the hot copy. [Idle sleep](/docs/concepts/idle-sleep), when you turn it on, stops a running machine that does nothing; VMYard does not yet wake a machine when a request arrives. See [Sleep and wake](/docs/concepts/sleep-and-wake).

---

<!-- Source: /docs/guides/automatic-snapshots.md -->

# Automatic snapshots

> How VMYard captures running KVM machines on an interval, how many automatic snapshots it keeps, and how to see and delete them.

VMYard captures a **running** machine on an interval, so a recent copy exists without stopping it. Each capture is an ordinary [snapshot](/docs/guides/snapshots) with `source: "automatic"`: you can [restore it as a new machine](/docs/guides/fork-and-restore) like any other.

## How captures work

- **Every 5 minutes** by default, a running machine is due for its next automatic snapshot.
- A machine whose disk hasn't changed since its last ready automatic snapshot (same boot, same disk writes) is skipped, so an idle machine doesn't pile up copies. Without fresh metrics it is captured anyway.
- A machine with an operation still running, a previous capture included, waits for the next interval.
- The machine keeps running in the same boot. VMYard copies it at one instant and uploads the copy; the copy is never a machine you see. Operations you request during a capture wait for its upload.
- Only **KVM machines** on hosts that support it are captured. Docker development machines are not.
- Automatic snapshots are `cold` by default: the disk only, uploading just the parts that changed.

These are the defaults; operators of a deployment can change the interval, the number kept, and the tier, or turn captures off.

## How many are kept

Each machine keeps its newest **10** ready automatic snapshots (and its newest 10 failed ones). Older automatic snapshots are deleted as new ones become ready. Retention **never** removes snapshots you took (`source: "api"`), [tier-policy](/docs/guides/snapshots#stopped-machines-move-down-the-tiers) snapshots, or [templates](/docs/guides/templates), and automatic snapshots don't count toward the 20-snapshot limit.

A capture that loses its copy before the upload finishes fails with `snapshot_copy_discarded`; the machine is unchanged and the next interval takes another. Each ready capture emits the [`snapshot.ready` webhook](/docs/guides/webhooks) with `source: "automatic"`.

## See how fresh a machine's copy is

Every machine reports `latest_snapshot`: its newest snapshot that is pending or ready (templates and failed pushes are left out), or `null`.

```json
"latest_snapshot": {
  "id": "0b6f1c2e-…",
  "created_at": "2026-10-12T09:10:00Z",
  "completed_at": "2026-10-12T09:10:41Z",
  "source": "automatic",
  "status": "ready",
  "tier": "cold"
}
```

`created_at` is the instant the copy was taken. The console's machine list shows its age with the source, and an **Automatic** badge for captures; the machine overview shows the same under **Latest snapshot**.

## Find and delete automatic snapshots

The **Snapshots** tab filters a machine's snapshots by source: **Manual** (`api`), **Stop (tier policy)** (`tier_policy`), and **Automatic** (`automatic`). **Delete automatic** removes all of a machine's automatic snapshots at once:

```sh
curl -X DELETE "$VMYARD_API_URL/v1/machines/$MACHINE_ID/snapshots?source=automatic" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

Captures continue while the machine runs. See [Delete several snapshots](/docs/guides/snapshots#delete-several-snapshots) for the answer's format.

---

<!-- Source: /docs/guides/templates.md -->

# Templates

> Save a stopped machine as a named template and create machines from it with the same plan, image, region, and machine name, each with its own identity.

A **template** is a stopped machine saved as a named, warm [snapshot](/docs/guides/snapshots). Machines created from it start from its disk and memory with the template's plan, image, region, resources, backend, and machine name, and their own identity. An organization keeps at most **10** templates.

> [!NOTE]
> Use the console's **Templates** page, `vy templates`, the SDKs, or the HTTP API below. Owners, Admins, and Operators save and delete templates; every member can list them and anyone who can create machines can create from one.

## Save a template

The machine must be requested and observed stopped (`409 machine_not_stopped`).

```sh
curl -X POST "$VMYARD_API_URL/v1/templates" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"machine_id": "'"$MACHINE_ID"'", "name": "python-base"}'
```

- `name` is a lowercase letter or digit followed by up to 63 of `a-z`, `0-9`, `.`, `_`, and `-`. It is unique among the organization's live templates (`409 template_name_taken`); a deleted template's name can be reused at once.
- An eleventh template is `409 template_limit_reached`.

The answer is `202` like a snapshot push; the template is `pending` until it is `ready` or `failed`, and a successful save emits the `template.ready` webhook.

## Create a machine from a template

Send `template` (its name or ID) to `POST /v1/machines`:

```sh
curl -X POST "$VMYARD_API_URL/v1/machines" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"template": "python-base", "name": "worker-1", "auto_stop_after_seconds": 7200}'
```

The template fixes `tenant_alias`, `plan`, `image`, `region`, `resources`, and `backend`: leave them out, or send exactly the template's values (anything else is `422`). Display `name`, auto-stop, [idle sleep](/docs/concepts/idle-sleep), the [environment](/docs/guides/environments) choice, and a [setup script](/docs/guides/setup-scripts) are yours to choose; the environment is applied after the restore, like any create.

The machine is restored running, with its own machine ID, host name, and SSH host keys, and no ports or SSH access. A template that doesn't exist is `422 unknown_template`; one that isn't `ready` is `409 snapshot_not_ready`. Creates from a template are admitted by billing like any create. A replay of the same `Idempotency-Key` and body succeeds even after the template was deleted.

In the console, **Create machine** on a template opens the create page with the plan, image, region, and machine name locked to the template.

## List and delete

`GET /v1/templates` lists templates; `GET /v1/templates/{template}` and `DELETE /v1/templates/{template}` take a name or ID. Deleting answers `204`; machines created from the template keep running. A save that hasn't settled can't be deleted yet (`409 snapshot_pending`).

---

<!-- Source: /docs/guides/fork-and-restore.md -->

# Fork and restore

> Copy a running machine at one instant, or restore one of a machine's snapshots, as a new machine with its own ID and identity.

**Fork** copies a running machine into a new machine at one instant. **Restore** creates a new machine from one of a machine's ready [snapshots](/docs/guides/snapshots). Neither changes the source machine.

> [!NOTE]
> Use `vy fork` and `vy restore`, the SDKs (`machine.fork`, `machine.restore`), the HTTP API below, or the console (**Fork** on a machine's overview or row menu, **Restore as new machine** on its Snapshots tab). Owners, Admins, and Operators fork and restore.

## Fork a running machine

```sh
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/fork" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"live": true, "name": "dev-copy", "keep_ssh_keys": false}'
```

| Field | Meaning |
| --- | --- |
| `live` | Default `true`: the copy starts running. `false` creates it stopped. |
| `name` | Optional display name for the copy. |
| `keep_ssh_keys` | Default `false`. `true` keeps the login user's `authorized_keys` inside the guest. |

The source must be running (`409 machine_not_running`). A fork is **point-in-time**: VMYard pauses the source only while it writes memory and clones the disk, so the copy has every write that completed before the fork, including data still in the page cache. The fork runs in the source's operation queue, after every operation requested on the source before it, so "write a file, then fork" always copies the file.

## Restore a snapshot

```sh
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/restore" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"snapshot_id": "'"$SNAPSHOT_ID"'", "name": "dev-restored", "wake": true}'
```

The snapshot must belong to that machine and be `ready` (`409 snapshot_not_ready`). `wake` (default `true`) starts the new machine; `false` creates it stopped. A warm snapshot resumes its processes; a cold one boots fresh from its disk. The source machine is untouched, so to replace it, delete it after the restore succeeds. `keep_ssh_keys` works as for a fork.

## What a copy is

Both answer `202` with an operation whose `machine_id` names the **new** machine. Follow that operation like a create: it ends with the new machine observed running, or observed stopped when you asked for `live: false` or `wake: false`. The new machine reports `forked_from_machine_id` or `restored_from_snapshot_id`.

- **New identity.** The copy has its own machine ID. Before it is reported running, the guest's machine ID, host name, SSH host keys, and kernel random state are reset, so copies never share them.
- **Same tenant alias.** The copy keeps its source's tenant alias (its machine name), because the runtime scopes snapshots and forks to that alias. Its display name is `name` if you sent one. Search finds both by the alias.
- **Same size and placement.** The exact plan, image, region, resources, and backend of the source; the default auto-stop.
- **No ports or SSH access.** A copy never inherits exposed ports or the SSH gateway key. [Expose ports](/docs/guides/ports) and [set an SSH key](/docs/guides/ssh) again; `keep_ssh_keys` only keeps the key inside the guest.
- **Environment.** A fork carries its source's environment and applied version. A restore carries the version that was applied when the snapshot was taken.
- **Billing.** A copy is admitted like a create (balance, trial machine class, plan price, concurrency, start windows). A copy created stopped holds no auto-stop deadline and is not metered until you start it.

Webhooks: a live fork or woken restore emits `machine.ready` when it is observed running; a copy created stopped emits `machine.stopped`.

---

<!-- Source: /docs/guides/webhooks.md -->

# Webhooks

> Receive signed HTTPS events when machine lifecycle operations finish, verify their signatures, and handle retries.

Webhooks tell your service when machines become ready, stop, start, are deleted, or fail. VMYard sends a signed JSON `POST` to each HTTPS endpoint you register, and retries until the endpoint answers with a `2xx` status.

## Events

Events come from the final, observed result of an operation, never from anything a machine reports about itself.

| Event | Sent when |
| --- | --- |
| `machine.ready` | A create succeeded: the machine was observed running. This includes a live [fork](/docs/guides/fork-and-restore) and a woken restore. |
| `machine.started` | A start or restart succeeded. |
| `machine.stopped` | A stop succeeded, including auto-stops, [idle sleep](/docs/concepts/idle-sleep), and stops because the balance ran out, or a fork or restore created its machine stopped. |
| `machine.deleted` | A delete succeeded: the machine was confirmed gone. |
| `machine.error` | A create, start, stop, restart, or delete ended `failed` or `correlation_miss`. |
| `operation.failed` | Any public operation (lifecycle, command, background command, kill, file write, port or SSH change, [internet access](/docs/guides/networking) change, environment install, snapshot push, template save) ended `failed` or `correlation_miss`. |
| `snapshot.ready` | A [snapshot](/docs/guides/snapshots) push succeeded. `data.snapshot` is `{id, template_name, tier, status}`. |
| `template.ready` | A [template](/docs/guides/templates) save succeeded. `data.snapshot` names the template. |

An `uncertain` operation sends nothing until it settles. Successful command, file, port, SSH, and internet access operations send nothing. A restart never stops its machine, so it sends `machine.started` and never `machine.stopped`.

```json title="machine.ready"
{
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "type": "machine.ready",
  "created_at": "2026-10-12T05:51:01.738927Z",
  "organization_id": "2a7d4c1e-8b3f-4f6a-9c5d-0e1f2a3b4c5d",
  "data": {
    "machine": { "id": "0b6f6c55-2f1d-4f0e-9a51-6f0f4cba7a10", "name": "dev", "network": { "egress": "internet", "ipv6_address": null } },
    "operation": { "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "kind": "create", "status": "succeeded", "error_code": null },
    "state": { "desired": "running", "observed": "running" }
  }
}
```

`data.machine.name` is the machine's display name, and `data.machine.network` its [egress policy and IPv6 address](/docs/guides/networking#read-it) as its host last reported them, or `null` before any report. Events of a stop operation also carry `data.operation.stop_reason`: `api` (a caller asked for it), `auto_stop`, `billing`, or `idle_sleep`. Other events don't have the field.

## Register an endpoint

Only Owners and Admins can see or change webhooks, because endpoint URLs can contain secrets. API keys need the `full_access` preset, and their creator must still be an Owner or Admin. You can also manage endpoints in the console under **Webhooks**.

```sh tab="CLI"
vy webhooks add --name ci --url https://hooks.example.com/vmyard --event machine.ready --event machine.error
vy webhooks ls
```

```ts tab="TypeScript"
const { webhook, secret } = await vy.webhooks.create({
  name: "ci",
  url: "https://hooks.example.com/vmyard",
  events: ["machine.ready", "machine.error"],
});
```

```python tab="Python"
created = vy.webhooks.create(
    name="ci", url="https://hooks.example.com/vmyard", events=["machine.ready", "machine.error"]
)
secret = created["secret"]
```

```sh tab="curl"
curl -X POST "$VMYARD_API_URL/v1/webhooks" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci", "url": "https://hooks.example.com/vmyard", "events": ["machine.ready", "machine.error"]}'
```

The answer includes the signing secret (`whsec_…`). It is shown **only now and when you rotate it**; store it with your receiver.

- `name`: 1–64 characters.
- `url`: `https`, port 443, at most 2048 bytes, no username, password, or fragment, and a public host. Private, loopback, link-local, and other non-public addresses and names such as `localhost` or `*.internal` are refused.
- `events`: one or more of the events above, without duplicates. The CLI subscribes to all eight when you give no `--event`.
- `enabled`: `true` by default.

An organization can have up to **10** endpoints (`409 webhook_limit_reached`).

## Verify signatures

Every delivery carries these headers:

| Header | Value |
| --- | --- |
| `X-VMYard-Signature` | `t=<unix seconds>,v1=<hex HMAC-SHA256>` |
| `X-VMYard-Event-Id` | The event `id`. The same for every endpoint and every attempt. |
| `X-VMYard-Event-Type` | The event type. |
| `X-VMYard-Delivery-Attempt` | 1 for the first attempt, then 2, 3, … |
| `User-Agent` | `VMYard-Webhooks/1` |

`v1` is the HMAC-SHA256 of `t + "." + body`, keyed with the **whole** secret string including `whsec_`. Each attempt is signed again with a fresh timestamp. To verify:

1. Read the raw request body before parsing it.
2. Recompute the HMAC and compare it in constant time.
3. Reject timestamps more than 5 minutes old.
4. Skip any `X-VMYard-Event-Id` you have already processed.

```js tab="Node.js"
import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body as received (Buffer), before JSON parsing.
export function verifyVmyard(secret, rawBody, header, tolerance = 300) {
  const fields = Object.fromEntries(
    header.split(",").map((part) => {
      const at = part.indexOf("=");
      return [part.slice(0, at), part.slice(at + 1)];
    }),
  );
  const timestamp = Number(fields.t);
  if (!Number.isInteger(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > tolerance) return false;
  const expected = createHmac("sha256", secret)
    .update(`${fields.t}.`)
    .update(rawBody)
    .digest();
  const received = Buffer.from(fields.v1 ?? "", "hex");
  return (
    received.length === expected.length &&
    timingSafeEqual(received, expected)
  );
}
```

```python tab="Python"
import hashlib, hmac, time

def verify_vmyard(secret: str, body: bytes, header: str, tolerance: int = 300) -> bool:
    fields = dict(part.split("=", 1) for part in header.split(","))
    timestamp = int(fields["t"])
    if abs(time.time() - timestamp) > tolerance:
        return False  # stale or replayed
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + body,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, fields.get("v1", ""))
```

## Retries and ordering

A `2xx` answer delivers the event. Anything else is a failed attempt: other statuses, redirects (never followed), no answer within 10 seconds, a connection failure, or a destination that resolves to a non-public address. VMYard retries after 1, 2, 4, … minutes, up to 6 hours apart; after 12 attempts (about 20.5 hours) the delivery is marked `dead`.

Delivery is **at least once** and **unordered**: the same event can arrive twice, and events can arrive out of order. Deduplicate on `X-VMYard-Event-Id`, and order by `created_at` or by reading the machine's current state rather than by arrival.

## Deliveries

```sh tab="CLI"
vy webhooks deliveries ci --limit 20
```

```ts tab="TypeScript"
const deliveries = await vy.webhooks.deliveries(webhook.id, { limit: 20 });
```

```python tab="Python"
deliveries = vy.webhooks.deliveries(webhook_id, limit=20)
```

```sh tab="curl"
curl "$VMYARD_API_URL/v1/webhooks/$WEBHOOK_ID/deliveries?limit=20" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

Deliveries are listed newest first with `status` (`pending`, `delivering`, `succeeded`, or `dead`), `attempt_count`, `next_attempt_at`, `last_status_code`, and `last_error`.

## Pause, change, rotate, delete

- **Disable** an endpoint (`PATCH` with `{"enabled": false}`) to pause it. Queued deliveries wait until you enable it again; no new events are queued while it is disabled.
- **Change** its `name`, `url`, or `events` with `PATCH`; omitted fields keep their value.
- **Rotate** the secret (`POST /v1/webhooks/{id}/rotate-secret`, or `vy webhooks rotate`). The old secret stops signing at once, including retries of queued events, so update your receiver promptly.
- **Delete** the endpoint (`DELETE`, or `vy webhooks rm`). Its queued and past deliveries are deleted with it.

---

<!-- Source: /docs/guides/email-alerts.md -->

# Email alerts

> Choose which problems VMYard emails you about in each organization, and how the unsubscribe link in every alert works.

VMYard can email you when something needs attention, such as a machine that couldn't be stopped or a balance that ran out. Each member chooses for themselves in each organization; until you choose, your role's default applies. In the console, open **Account** and choose **Alerts**.

## Alert types

| Type | Sent when | On by default for |
| --- | --- | --- |
| `balance_exhausted` | The organization's spendable balance first reaches zero. | Owner, Billing |
| `auto_refill_failed` | An [automatic refill](/docs/guides/automatic-refill) charge was declined, had no default payment method, or stayed unconfirmed; the alert says when refill turned itself off. | Owner, Billing |
| `machine_unresponsive` | A machine VMYard observes running is missing from its host, or isn't running there. | Owner, Admin, Operator |
| `machine_stop_failed` | A stop fails or can't be confirmed, whether manual, by auto-stop, for billing, or by idle sleep. A restart never stops its machine. | Owner, Admin, Operator |
| `snapshot_failed` | Saving a machine's disk and memory to storage fails or can't be confirmed. | Owner, Admin, Operator |
| `operation_failed` | Any operation fails or can't be confirmed, including an [internet access](/docs/guides/networking) change (the same rule as the `operation.failed` [webhook](/docs/guides/webhooks)). | Nobody; opt in |
| `auto_stop` | A machine's [auto-stop](/docs/concepts/auto-stop) deadline passed and VMYard stopped it. | Nobody; opt in |
| `billing_stop` | The balance stayed exhausted past the grace period and VMYard stopped a machine. | Nobody; opt in |
| `idle_sleep` | A machine was idle for its [idle-sleep](/docs/concepts/idle-sleep) window and VMYard put it to sleep. | Nobody; opt in |
| `abuse_stop` | A trial machine used every vCPU at full load for a long stretch, the pattern of crypto mining, and VMYard stopped it for review. | Owner, Admin, Operator |
| `disk_almost_full`, `disk_full` | A running machine's disk is at least 90% (`disk_almost_full`) or 98% (`disk_full`) used. See [Machine metrics](/docs/guides/machine-metrics#disk-warnings). | Owner, Admin, Operator |
| `product_announcements` | Not sent by VMYard yet. | Nobody; opt in |

The same type is sent at most once an hour per machine (or per organization, for balance alerts). Alerts carry machine and operation IDs, the kind of operation, its status, and its error code, never command output or request bodies. Delivery is retried for a while if the mail provider fails, and an alert more than a day old is dropped rather than sent late.

## Read and change your preferences

```sh
curl "$VMYARD_API_URL/v1/notifications/preferences" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

The answer has the `email` alerts go to and, for every type, `enabled`, `default_enabled` (your role's default), `customized` (you made a choice), `available` (VMYard sends it today), and a one-line `description`.

```sh
curl -X PUT "$VMYARD_API_URL/v1/notifications/preferences" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alerts": {"operation_failed": true, "auto_stop": false}}'
```

`PUT` changes only the types it lists and answers the whole document. An empty map or an unknown type answers `422`. Preferences are personal: any member may read and change their own, and an API key acts for the member who created it. Reading accepts every key preset; changing needs a `full_access` key or a signed-in browser session.

## Unsubscribe links

Every alert email has a link that turns off that one alert type for you in that organization, without signing in. Opening it shows a confirmation page on the VMYard API and changes nothing, so mail scanners that follow links are harmless; the page's button confirms. Mail apps that support one-click unsubscribe (RFC 8058) use the same link. Links don't expire, but they stop working if the server's operator rotates its session secret; a broken link answers `400 invalid_unsubscribe_token`. You can turn the alert back on from **Alerts** at any time.

> [!NOTE]
> An organization's server only sends email when its operator configured an email provider. Without one, alerts are recorded but not sent.

---

<!-- Source: /docs/guides/billing.md -->

# Usage, billing, and limits

> How machine time is metered and paid for, what the trial and plans include, the limits that apply, and how to read usage.

VMYard bills machines **per second while they run**, at the hourly price of their plan. Stopped machines cost nothing. Every organization has a prepaid wallet; nothing is charged after the fact except a plan's renewal.

## How usage is measured

Usage starts when VMYard observes a machine running and ends when it observes it stopped or gone. What a machine reports about itself never counts. A run keeps the hourly price it started with, and its charge after `n` seconds is `floor(n × hourly price ÷ 3600)`, so partial seconds are never billed. Long runs are charged as they go, about once a minute.

| Size | Price per hour | Multiplier |
| --- | --- | --- |
| `small` | $0.015 | 0.5 |
| `default` | $0.030 | 1 |
| `large` | $0.060 | 2 |
| `xlarge` | $0.170 | about 5.67 |

See [Sizes and prices](/docs/guides/sizes-and-prices) for each size's resources and how to read them from the catalog.

All amounts in the API are integer **micros of USD**: 1,000,000 micros is $1. A field such as `cost_micros: 30000` is $0.03.

## The wallet

Usage is paid from three balances, in this order:

1. **Trial:** $1.50 of usage, which is 50 hours of `default` (100 hours of `small`), granted the first time the organization uses VMYard.
2. **Plan:** the current period's allowance, if the organization has a plan. Unused allowance expires at the end of the period.
3. **Credits:** bought in $20 packs. Credits never expire.

| Plan | Price per period | Included usage |
| --- | --- | --- |
| `starter` | $20 | $20 (about 667 `default` hours) |
| `pro` | $100 | $100 (about 3,333 `default` hours) |
| `team` | $500 | $500 |
| `scale` | $2,000 | $2,000 |

Owners and Billing members buy plans and credit packs, open the payment portal (cards, invoices, cancellation), and set two controls, all from the console's **Billing** page:

- **Spend cap:** the most credit spend allowed per UTC calendar month.
- **Minimum balance:** creates and starts need more spendable balance than this. The default is 0.

They can also [cancel a plan at the end of its period or end the trial early](/docs/guides/plans-and-trial), and turn on [automatic refill](/docs/guides/automatic-refill) to buy credit packs when the balance runs low.

Card details stay with the payment provider. Deployments without online payments answer those actions with `503 billing_unavailable`; trial and operator-granted balances still work.

## When the balance runs out

When the spendable balance (trial + plan + credits, with credits limited by the spend cap) reaches zero, VMYard waits a grace period (5 minutes by default) and then stops every machine that is still running. Those are ordinary stops: they emit `machine.stopped`. Buying credits or a plan before the stops begin cancels them. Usage metered during the grace period can make the credit balance slightly negative; the next purchase repays it first.

## Limits

Creates, starts, and restarts are checked against the organization's limits. Replays of an already-accepted request are never refused.

| Status | Concurrent machines | Starts per minute | per hour | per day |
| --- | --- | --- | --- | --- |
| Trial | 2 | 5 | 30 | 100 |
| Pay as you go (credits, no plan) | 5 | 12 | 60 | 200 |
| `starter` ($20) | 5 | 12 | 60 | 200 |
| `pro` ($100) | 20 | 30 | 210 | 840 |
| `team` ($500) | 100 | 65 | 420 | 1,680 |
| `scale` ($2,000) | 250 | 90 | 600 | 2,400 |

Concurrent machines counts every machine that is meant to be running, including creates still in progress. Start windows are rolling and count creates, starts, and restarts. During the trial, only `small` and `default` sizes are allowed, and at most 2 machines run at once.

## Card check

A deployment can require trials to verify a card before their machines start. `GET /v1/billing` reports it in `card_check`: `required` is `true` when the deployment asks for one, and `verified_at` is when a card was verified. Paid organizations never need one.

Until a card is verified, a trial's creates, starts, and restarts answer `402 card_verification_required`. An Owner or Billing member starts the check from the console (the create page, the refusal, or the **Billing** page), or with the API:

```sh
curl -X POST "$VMYARD_API_URL/v1/billing/card-check" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

The answer has a `checkout_url`: the payment provider's page, where the card is checked and screened for fraud but not charged. Once the provider confirms it, `card_check.verified_at` is set and machines can start. Card details never reach VMYard.

## Suspended organizations

To stop abuse, the people who run the service can suspend an organization. While it is suspended, `OrganizationDto.suspended_at` is set, its machines are stopped (`stop_reason: suspension`), and anything that creates, starts, or reaches into a machine (commands, files, terminals, desktops) answers `403 organization_suspended`. Open terminals and desktops close with reason `revoked`. Reads, billing, API keys, and settings still work, and nothing is deleted. Contact support to have a suspension reviewed. When it is lifted, the stopped machines stay stopped until you start them.

Trial machines that use every vCPU at full load for a long stretch, the pattern of crypto mining, are stopped for review (`stop_reason: abuse`) and members who operate machines get an `abuse_stop` [email alert](/docs/guides/email-alerts).

| Status | Code | When |
| --- | --- | --- |
| 402 | `billing_required` | The spendable balance is at or below the minimum balance. |
| 402 | `spend_cap_reached` | Only the spend cap leaves too little to spend. |
| 402 | `card_verification_required` | A trial must [verify a card](#card-check) before machines start. |
| 403 | `trial_machine_class_not_allowed` | A trial asked for a size above `default`. |
| 403 | `organization_suspended` | The organization is [suspended](#suspended-organizations). |
| 409 | `plan_not_priced` | The chosen plan has no current price. |
| 429 | `limit_reached` | `field_errors.limit` is `concurrent_machines`, `starts_per_minute`, `starts_per_hour`, or `starts_per_day`. Start windows send `Retry-After`. |

The SDKs raise `BillingRequiredError`, `SpendCapReachedError`, `TrialMachineClassNotAllowedError`, and `LimitReachedError` for these. Waiting doesn't clear `concurrent_machines`; stop a machine instead.

## Read balances, limits, and usage

Every member, and every API key preset, can read billing.

```sh tab="CLI"
vy billing                       # status, balances, plan, trial, spend cap
vy limits                        # each limit and its current use
vy usage --since 2026-10-01      # per machine, with a total
vy usage dev                     # one machine
```

```ts tab="TypeScript"
const billing = await vy.billing.get();
const limits = await vy.billing.limits();
const usage = await vy.billing.usage({ since: "2026-10-01T00:00:00Z" });
const preview = await vy.billing.invoicePreview();
const machineUsage = await machine.usage();
```

```python tab="Python"
billing = vy.billing.get()
limits = vy.billing.limits()
usage = vy.billing.usage(since="2026-10-01T00:00:00Z")
preview = vy.billing.invoice_preview()
machine_usage = machine.usage()
```

```sh tab="curl"
curl "$VMYARD_API_URL/v1/billing" -H "Authorization: Bearer $VMYARD_API_KEY"
curl "$VMYARD_API_URL/v1/limits" -H "Authorization: Bearer $VMYARD_API_KEY"
curl "$VMYARD_API_URL/v1/usage?since=2026-10-01T00:00:00Z" -H "Authorization: Bearer $VMYARD_API_KEY"
```

| Route | Returns |
| --- | --- |
| `GET /v1/billing` | Status (`trial`, `pay_as_you_go`, or `subscribed`), plan and period, balances, trial, spend cap, minimum balance, `exhausted_since`, limits, and whether payments are available. |
| `GET /v1/limits` | Each limit with its current use. |
| `GET /v1/usage?since=&until=` | Exact seconds and micros per machine in `[since, until)`, including runs still open. Defaults to the current plan period, or the current UTC month without a plan. |
| `GET /v1/machines/{id}/usage` | One machine: `seconds`, `cost_micros`, `multiplier`, `hourly_micros`, and whether a run is open. Defaults to the machine's lifetime. |
| `GET /v1/billing/invoice-preview` | This period's machine time by size, how it was paid, usage not yet charged, and the next automatic charge (the plan renewal). |

---

<!-- Source: /docs/guides/sizes-and-prices.md -->

# Machine sizes and prices

> The small, default, large, and xlarge sizes, their resources and hourly prices, how to read them from the plan catalog, and which sizes a trial can use.

Every machine runs on a **plan** from the catalog: its vCPUs, memory, disk, and hourly price. VMYard offers four sizes on each kind of host.

| Size | vCPU | Memory | Disk | Price per hour | Multiplier |
| --- | --- | --- | --- | --- | --- |
| `small` | 2 | 4 GiB | 12 GiB | $0.015 | 0.5 |
| `default` | 4 | 8 GiB | 50 GiB | $0.030 | 1 |
| `large` | 8 | 16 GiB | 125 GiB | $0.060 | 2 |
| `xlarge` | 16 | 32 GiB | 250 GiB | $0.170 | about 5.67 |

Machines are billed [per second while they run](/docs/guides/billing) at their size's hourly price; stopped machines cost nothing. The multiplier is the price relative to `default`, and is what usage and invoice lines report.

## Read sizes from the catalog

`GET /v1/plans` lists every plan with its `size` (`small`, `default`, `large`, `xlarge`, or `null` for plans a deployment added itself), `backend`, resources, and `price` (`hourly` and `monthly` as decimal strings, `monthly` being 730 hours).

```sh
curl "$VMYARD_API_URL/v1/plans" -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json
{
  "id": "0c47a106-0000-4000-8000-000000000012",
  "version": 1,
  "name": "default",
  "size": "default",
  "backend": "kvm",
  "cpu": 4,
  "memory_mib": 8192,
  "disk_gib": 50,
  "price": { "currency": "USD", "hourly": "0.030000", "monthly": "21.900000", "effective_from": "2026-01-01T00:00:00Z" }
}
```

Each size exists once per host kind (`kvm` and `docker`). A machine's plan must match its region's `backend`, so pick the plan of the right size whose `backend` equals the region's. The console's create page does this for you: its **Size** picker lists the chosen region's sizes with their resources and hourly price, and keeps your size when you switch to a region that offers it.

## Sizes during the trial

While an organization is on its [trial](/docs/guides/plans-and-trial), only `small` and `default` can be created or started; anything priced above `default` answers `403 trial_machine_class_not_allowed`. The console shows `large` and `xlarge` as locked and says why. Buying credits or a plan lifts the restriction once the first payment is confirmed.

---

<!-- Source: /docs/guides/plans-and-trial.md -->

# Cancel a plan or end the trial

> Cancel a plan at the end of its period or keep it again, and end the free trial early, from the console or the API.

Owners and Billing members change plans and the trial from the console's **Billing** page or the API below (an API key needs the `full_access` preset). Every member sees the outcome on the Billing page.

## Cancel a plan

Cancelling never ends a plan early. The plan keeps its allowance and limits until the end of the current period (`plan.period_end`), then ends and doesn't renew. After that, usage is paid from credits at pay-as-you-go limits.

```sh
curl -X POST "$VMYARD_API_URL/v1/billing/subscription/cancel" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

The answer is the updated billing document: `plan.cancel_at_period_end` is `true` and `plan.renews` is `false`. The console asks for confirmation, then shows a banner with the date the plan ends.

To **keep the plan**, resume it before the period ends:

```sh
curl -X POST "$VMYARD_API_URL/v1/billing/subscription/resume" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

Both change the subscription at the payment provider first and record the change only once the provider confirms it.

| Status | Code | Meaning |
| --- | --- | --- |
| 409 | `subscription_missing` | No renewing subscription is linked: none was bought, the plan was granted by an operator, or it already ended. |
| 502 | `payment_provider_error` | The payment provider didn't answer. Nothing changed; try again in a minute. |
| 503 | `billing_unavailable` | Online payments aren't configured on this deployment. |

Cancelling in the payment portal has the same effect.

## End the trial early

The trial's balance is spent before a plan's allowance. If you've just bought a plan, ending the trial lets you use the plan's allowance right away.

```sh
curl -X POST "$VMYARD_API_URL/v1/billing/trial/end" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

> [!WARNING]
> The remaining trial balance is forfeited and can't be restored.

The answer is the billing document with `trial.ended_at` set and no trial balance left. Ending an ended trial changes nothing. The trial's **rules** (two machines, `small` and `default` sizes only) still apply until the first payment, so ending a trial without paying leaves nothing to spend and creates and starts answer `402 billing_required`.

You can also end the trial as part of buying a plan: send `end_trial: true` with a plan checkout, and the trial ends once the plan's first payment is confirmed. In the console, tick **End the trial when the plan starts** before choosing a plan. `end_trial` applies to plan checkouts only; with `credit_packs` it answers `422`.

```sh
curl -X POST "$VMYARD_API_URL/v1/billing/checkout" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan": "pro", "end_trial": true}'
```

---

<!-- Source: /docs/guides/automatic-refill.md -->

# Automatic refill

> Buy credit packs automatically when the balance runs low, with a monthly cap, and what happens when a charge fails.

Automatic refill buys credit packs for you when the organization's balance runs low, so running machines aren't stopped for billing. It charges the **default card** saved at the payment provider.

## Settings

| Field | Meaning |
| --- | --- |
| `enabled` | Whether refill runs. Off by default. |
| `threshold_micros` | Refill when the balance (trial + plan + credits) drops below this. Default $5. |
| `credit_packs` | $20 packs bought per refill, 1 to 50. Default 1. |
| `monthly_cap_micros` | The most refill charges per UTC calendar month, counting pending and confirmed charges. It must cover at least one refill. Default $100. |

Every member can read the settings; Owners and Billing members change them. All four fields are required when changing them:

```sh
curl -X PUT "$VMYARD_API_URL/v1/billing/auto-refill" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "threshold_micros": 10000000, "credit_packs": 2, "monthly_cap_micros": 120000000}'
```

The read (`GET /v1/billing/auto-refill`) also returns `amount_micros` (one refill), `charged_this_month_micros`, `consecutive_failures`, `disabled_reason`, and `last_charge` (`status` `pending`, `submitted`, `succeeded`, or `failed`, with `failure_code`). The console's **Automatic refill** card on the Billing page shows the month's charges against the cap, the last charge, and any failures.

## Turning it on

Enabling refill needs a payment method VMYard can charge without you present:

| Status | Code | What to do |
| --- | --- | --- |
| 409 | `billing_customer_missing` | No purchase has linked a payment customer yet. Buy credits or a plan once, then turn refill on. |
| 409 | `payment_method_missing` | There's no default card at the payment provider. Add one in the payment portal (**Manage payment** on the Billing page), then turn refill on. |
| 503 | `billing_unavailable` | Online payments aren't configured on this deployment. |
| 502 | `payment_provider_error` | The payment provider didn't answer. Try again in a minute. |

## Charges

Credits are added only when the payment provider confirms the charge, so a refill can show as **submitted** for a short while. A charge whose outcome stays unknown is retried, and fails after repeated tries.

When a charge **fails** (for example the card is declined, or needs the cardholder to confirm it), new charges pause for 2 hours, Owners and Billing members get the `auto_refill_failed` [email alert](/docs/guides/email-alerts), and the failure is counted. A successful charge resets the count.

> [!WARNING]
> After **3** failed charges in a row, refill turns itself off: `enabled` becomes `false` and `disabled_reason` is `payment_failures`. Update the card in the payment portal, then turn refill back on; that also clears the failure count.

---

<!-- Source: /docs/guides/errors.md -->

# Errors

> The problem details format, every error code the API returns, and what to do about each one.

Errors are JSON in the `application/problem+json` format. Branch on `code`, which is stable; `message` is for people and may change.

```json
{
  "type": "https://api.vmyard.example/problems/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "code": "insufficient_scope",
  "message": "The API key preset does not allow this action.",
  "remediation": "Use an API key whose preset includes this action.",
  "correlation_id": "0d9f3b9e-5c1a-4b7e-9e0b-2f4c6a8d1e3f",
  "field_errors": {}
}
```

| Field | Meaning |
| --- | --- |
| `code` | The machine-readable error code. |
| `status` | The HTTP status, repeated. |
| `message` | What went wrong, in words. |
| `remediation` | What to do next. |
| `correlation_id` | Quote it when you contact support. It is also sent as the `x-correlation-id` header. |
| `field_errors` | Field name → problem, for invalid requests. |
| `retry_after_seconds` | When a retry can succeed; also sent as `Retry-After`. |

The SDKs turn problems into typed errors: `BadRequestError` (400), `AuthenticationError` (401), `PaymentRequiredError` (402), `PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409), `PayloadTooLargeError` (413), `UnprocessableEntityError` (422), `RateLimitError` (429), and `ServerError` (5xx), all subclasses of `APIError` with `code`, `message`, `remediation`, `correlationId`, `fieldErrors`, and `retryAfterSeconds` (snake_case in Python).

## Authentication and access

| Status | Code | Meaning and fix |
| --- | --- | --- |
| 401 | `unauthenticated` | No valid session. Sign in again, or send an API key. |
| 401 | `invalid_api_key` | The key is malformed, unknown, expired, or revoked. Create or rotate a key. |
| 403 | `csrf_invalid` | A browser-session change is missing the `x-csrf-token` header, or it is wrong. Refresh and retry once. |
| 403 | `session_required` | This route needs a signed-in browser session; API keys can't use it (key management, sign-out, device approval, sign-in methods). |
| 403 | `insufficient_scope` | The key's preset doesn't allow this route. See [presets](/docs/guides/api-keys#presets). |
| 403 | `organization_mismatch` | `X-Organization-ID` doesn't match the API key's organization. Omit it or send the right one. |
| 403 | `forbidden` | Your role can't do this (for example a Viewer starting a machine, or a non-admin reading webhooks). |
| 403 | `organization_suspended` | The organization is suspended, so nothing can create, start, or reach into its machines. Reads, billing, keys, and settings still work. Contact support. See [Suspended organizations](/docs/guides/billing#suspended-organizations). |
| 403 | `recent_auth_required` | Linking or removing a sign-in method needs a sign-in within the last 15 minutes. Sign in again. |
| 404 | `resource_not_found` | Nothing with that ID in this organization. |

## Requests

| Status | Code | Meaning and fix |
| --- | --- | --- |
| 405 | `method_not_allowed` | That HTTP method isn't supported on this path. |
| 409 | `idempotency_conflict` | The `Idempotency-Key` was already used with a different body. Retry the original body, or use a new key. |
| 413 | `body_too_large` | The request body is too large. |
| 422 | `invalid_request` | A field is missing or invalid. `field_errors` names it. On `GET /v1/machines` this includes an unknown `sort`, `order`, `state`, or `desired_state`, a `q` over 128 characters, and a cursor made for another sort or order: start again from the first page. |
| 429 | `rate_limited` | Too many attempts (sign-in, email codes, device codes, or more than 5 organizations created in 24 hours). Wait `Retry-After` seconds. |
| 500 | `internal_error` | Something failed on VMYard's side. Retry later; quote the `correlation_id`. |
| 503 | `creates_quiesced` | Machine creation is paused on this server. Try again later. |

## Machines, commands, and files

| Status | Code | Meaning and fix |
| --- | --- | --- |
| 409 | `machine_deleted` | The machine was deleted; its settings can't change. |
| 409 | `machine_not_created` | The machine's create is still pending or didn't succeed, so only a delete is accepted. |
| 409 | `command_not_started` | The background command's start operation hasn't succeeded, so it can't be killed yet. Wait for it. |
| 422 | `timeout_exceeds_runtime_limit` | `timeout_ms` is above the maximum (600,000). Lower it, or use a background command. |
| 404 | `file_not_found` | No file at that path. |
| 413 | `file_too_large` | The file is over 32 MiB. |
| 422 | `file_not_text` | The file isn't UTF-8. Read it with `encoding=base64`. |
| 502 | `guest_action_failed` | The machine didn't complete a read. Check the operation and retry. |
| 404 | `path_not_found` | The folder to list or download doesn't exist in the machine. List its parent to see what does. |
| 422 | `not_a_directory` | The path to list or download is a file. Read it with `GET /v1/machines/{id}/files` instead. |
| 422 | `path_not_allowed` | The path resolves, through a symlink, outside `/work`, `/root`, and `/home`. Browse the symlink's target by its own path. |
| 422 | `listing_too_large` | The listing is too large to return. Ask for a smaller `depth` or a deeper `path`. |
| 413 | `archive_too_large` | The folder is over 512 MiB. Download smaller folders, or copy it over [SSH](/docs/guides/ssh). |
| 503 | `files_unavailable` | This server doesn't browse files live. Read and write files by path instead. |
| 409 | `machine_not_running` | The machine must be running for this action. Start it and wait until it is observed running. |
| 409 | `machine_not_stopped` | The machine must be stopped for this action. Stop it and wait until the stop succeeds. |
| 410 | `output_expired` | The command's stored output was removed after the retention period. Its exit code, flags, timing, and sizes remain. See [Command history](/docs/guides/command-history#retention). |

## Web terminal

| Status | Code | Meaning and fix |
| --- | --- | --- |
| 403 | `origin_not_allowed` | The terminal WebSocket came from a page other than the console's configured address. Open the console from that address. |
| 403 | `terminal_ticket_invalid` | The terminal ticket is missing, expired (30 seconds), already used, or for another machine or session. Mint a new one. |
| 409 | `terminal_refused` | The machine (16) or its host (64) has too many terminals. Close some. |
| 429 | `terminal_limit_reached` | You or the organization have the maximum number of open terminals. Close one first. |
| 503 | `terminals_unavailable` | This deployment has no runtime for terminals. |
| 503 | `runtime_unavailable` | The machine's host can't be reached. Retry shortly. |

Opening a terminal also needs a key preset above `read_only` (`insufficient_scope`), and a machine that is running (`machine_not_running`). See [Web terminal](/docs/guides/web-terminal#errors).

## Coding agents

| Status | Code | Meaning and fix |
| --- | --- | --- |
| 403 | `organization_suspended` | The organization is suspended, so agents can't run in its machines. Contact support. |
| 404 | `conversation_not_found` | No conversation with that ID on this machine. List them with `GET /v1/machines/{id}/agents/conversations`. |
| 409 | `agent_turn_running` | The conversation already has a running turn. Steer it, interrupt it, or wait for it to end. |
| 409 | `provider_mismatch` | A conversation keeps the agent it started with. Leave `provider` out, or start a new conversation. |
| 409 | `no_active_turn` | Nothing is running to steer or interrupt. Send a prompt instead. |
| 503 | `agents_unavailable` | This deployment or the machine's host can't run agents. |

See [Coding agents](/docs/guides/agents).

## Desktop

| Status | Code | Meaning and fix |
| --- | --- | --- |
| 403 | `desktop_ticket_invalid` | The desktop ticket is missing, expired (30 seconds), already used, or for another machine, session, or a terminal. Mint a new one. |
| 429 | `desktop_limit_reached` | The machine has 4 viewers, or you or the organization have the maximum number of open desktops. Close one first. |
| 503 | `desktop_unavailable` | This deployment has no desktops, or the runtime refused: the machine's image has no desktop, or its host is at a limit. |
| 503 | `browser_unavailable` | The runtime refused browser mode: the machine's image has no browser session, or its host predates browser mode. Open the full desktop instead. |

Opening a desktop also needs a key preset above `read_only` (`insufficient_scope`), the console's address (`origin_not_allowed`), and a running machine (`machine_not_running`). See [Desktop](/docs/guides/desktop).

## Machine metrics

| Status | Code | Meaning and fix |
| --- | --- | --- |
| 409 | `machine_not_running` | Live metrics need a running or sleeping machine. Read the one-minute history instead. |
| 503 | `runtime_unavailable` | The machine's host couldn't be reached for live samples. One-minute history still works; retry later. |
| 503 | `metrics_unavailable` | This server has no runtime for live samples. Use the one-minute history. See [Machine metrics](/docs/guides/machine-metrics). |

## Snapshots and templates

| Status | Code | Meaning and fix |
| --- | --- | --- |
| 409 | `snapshot_pending` | The push is still running, so it can't be deleted yet. Wait for it to settle. |
| 409 | `snapshot_not_ready` | The template's push hasn't finished, or failed. Wait, or use another. |
| 409 | `snapshot_limit_reached` | The machine has 20 live API pushes. Delete one first. |
| 409 | `template_limit_reached` | The organization has 10 live templates. Delete one first. |
| 409 | `template_name_taken` | Another live template in the organization has that name. |
| 422 | `unknown_template` | A create named a template that doesn't exist in the organization. |
| 404 | `no_snapshot` | The machine has no ready snapshot yet. Push one, or wait for the next [automatic snapshot](/docs/guides/automatic-snapshots). |

A fork needs a running machine and a snapshot or template a stopped one (`machine_not_running`, `machine_not_stopped` above). See [Snapshots and tiers](/docs/guides/snapshots), [Templates](/docs/guides/templates), and [Fork and restore](/docs/guides/fork-and-restore).

## Organizations and alerts

| Status | Code | Meaning and fix |
| --- | --- | --- |
| 403 | `waitlisted` | VMYard is invite-only and this account isn't approved yet. Join the waitlist at the problem's `waitlist_url`; you get an email when you're in. Reads, stopping and deleting machines, billing, and settings still work. |
| 409 | `waitlist_decision_conflict` | (Operators) The waitlist entry can't move that way: only a pending entry can be rejected, and only an approved one revoked. |
| 409 | `already_member` | The invited person, or you, already belong to the organization. |
| 409 | `invitation_closed` | The invitation was already accepted, revoked, or has expired. Ask for a new one. |
| 403 | `invitation_email_mismatch` | None of your sign-in addresses is the invited one. Sign in with the invited address, or link it first. |
| 409 | `last_owner` | The organization's only owner can't be removed or demoted. Transfer ownership first. |
| 409 | `subscription_active` | An organization with a renewing plan can't be deleted. Cancel the plan and wait for its period to end. |
| 503 | `invitations_unavailable` | This deployment can't send invitations: email or the console's address (`ui_base_url`) isn't configured. |
| 409 | `organization_name_taken` | You already created an organization with that name (names are unique per creator, ignoring case). |
| 400 | `invalid_unsubscribe_token` | The unsubscribe link is damaged, or the server's session secret was rotated since it was sent. Change the alert from the console's Alerts page instead. See [Email alerts](/docs/guides/email-alerts#unsubscribe-links). |

## Ports and SSH

| Status | Code | Meaning and fix |
| --- | --- | --- |
| 503 | `ingress_unavailable` | This deployment has no edge configured, so ports and SSH aren't available. |
| 409 | `port_limit_reached` | The machine already has 16 exposed ports. Close one first. |
| 404 | `port_not_exposed` | Expose the port before asking for a token. |

## Billing and limits

| Status | Code | Meaning and fix |
| --- | --- | --- |
| 402 | `billing_required` | The spendable balance is at or below the minimum balance. Buy credits or a plan. |
| 402 | `spend_cap_reached` | This month's credit spend reached the spend cap. Raise or remove it, or wait for next month. |
| 402 | `card_verification_required` | The deployment asks trials to verify a card before machines start. An Owner or Billing member starts a [card check](/docs/guides/billing#card-check); the card is not charged. |
| 403 | `trial_machine_class_not_allowed` | Trials can use only `small` and `default`. Choose a smaller size, or buy credits or a plan. |
| 409 | `plan_not_priced` | The plan has no current price. Choose another from `/v1/plans`. |
| 429 | `limit_reached` | A concurrency or start-rate limit. `field_errors.limit` says which; start windows send `Retry-After`. |
| 409 | `insufficient_credit` | (Operators) A claw-back is larger than the organization's credit balance. |
| 409 | `billing_customer_missing` | The payment portal needs a completed purchase first. |
| 409 | `payment_method_missing` | Automatic refill needs a default payment method. Add one in the payment portal. |
| 409 | `subscription_missing` | There is no paid plan subscription to cancel or resume. |
| 502 | `payment_provider_error` | The payment provider failed. Retry later. |
| 503 | `billing_unavailable` | Online payments aren't configured on this deployment. |
| 400 | `invalid_signature` | (Stripe events endpoint) The `Stripe-Signature` didn't verify. |
| 400 | `invalid_event` | (Stripe events endpoint) The event couldn't be read. |

See [Usage, billing, and limits](/docs/guides/billing#limits).

## Environments

| Status | Code | Meaning and fix |
| --- | --- | --- |
| 409 | `environment_name_taken` | Another environment in the organization has that name. |
| 409 | `environment_limit_reached` | The organization already has 50 environments. Delete one first. |
| 409 | `environment_upgrade_conflict` | A machine's environment version changed while the upgrade was being made. Retry. |
| 404 | `variable_not_found` | The environment has no variable with that name. |
| 422 | `unknown_environment` | A create named an environment that doesn't exist, or combined `environment_id`, `environment`, and `no_env`. |
| 503 | `environments_unavailable` | This deployment has no environment encryption keys, so environments can't be changed or revealed. |

See [Environments](/docs/guides/environments).

## Webhooks

| Status | Code | Meaning and fix |
| --- | --- | --- |
| 409 | `webhook_limit_reached` | The organization already has 10 endpoints. Delete one first. |
| 503 | `webhooks_unavailable` | This deployment has no keys to encrypt signing secrets, so endpoints can't be created and secrets can't be rotated. Secrets are never stored in plaintext. |

## Sign-in

These come back from the email and linking routes:

| Status | Code | Meaning and fix |
| --- | --- | --- |
| 400 | `invalid_code` | The email code is wrong, expired, used, or replaced by a newer one. Request a new code. |
| 404 | `unsupported_provider` | That sign-in method isn't configured. |
| 409 | `identity_in_use` | That identity already belongs to another user. |
| 409 | `last_login_method` | You can't remove your only sign-in method. Link another first. |
| 503 | `email_unavailable` | The email couldn't be sent. Retry later. |
| 503 | `oidc_unavailable` | The sign-in provider couldn't be reached. |
| 401 | `oidc_failed` | The provider's answer couldn't be verified. Start again. |

Browser sign-in redirects to `/sign-in?error=<code>` with one of `access_denied`, `identity_in_use`, `oidc_failed`, `oidc_unavailable`, `session_expired`, or `unsupported_provider`. See [Sign-in methods](/docs/guides/sign-in#sign-in-errors).

## Device sign-in

`POST /v1/auth/device/token` uses the OAuth error shape, `400 {"error", "error_description"}`, not problem details: `authorization_pending`, `slow_down`, `access_denied`, `expired_token`, `invalid_grant`, `invalid_request`, and `unsupported_grant_type`. See [CLI device login](/docs/guides/cli-login#the-protocol).

## Operation error codes

An [operation](/docs/concepts/operations) that ends `failed`, `uncertain`, or `correlation_miss` has an `error_code`. These are the ones you are most likely to see:

| `error_code` | Meaning |
| --- | --- |
| `exec_nonzero` | The command exited with a non-zero code. `exec_result` has the output. |
| `exec_timed_out` | The command ran past `timeout_ms`. |
| `exec_cancelled` | The command was cancelled. |
| `exec_no_exit_status` | The command ended without an exit status. |
| `setup_prerequisite_failed` | The create (or the environment apply it waits for) failed, so the setup script never ran. |
| `environment_prepare_failed`, `environment_decrypt_failed`, `environment_keys_unavailable` | Installing the machine's [environment](/docs/guides/environments) failed. The machine keeps running. |
| `environment_prerequisite_failed` | The create failed, so the environment was never installed. |
| `invalid_transition` | The machine's observed state doesn't allow this action. |
| `fleet_error` | The machine's host refused or failed the request, for example closing a port that isn't exposed, or an [internet access](/docs/guides/networking) change on a host without guest networking or with internet access turned off. Nothing changed. |
| `restart_unsupported` | The machine's host can't restart its machines yet, so the [restart](/docs/concepts/lifecycle#restart) never started. Nothing changed and the machine kept running; stop and start it instead. |
| `network_mismatch` | The host answered an internet access change with a different policy than the one requested, so VMYard did not report success. Read the machine's `network` before retrying. |
| `runtime_timeout`, `runtime_transport` | The host didn't answer in time or couldn't be reached. |
| `correlation_missing`, `correlation_mismatch`, `correlation_duplicate`, `ingress_mismatch` | The host's view of the machine didn't match the request, so VMYard did not report success. |
| `snapshot_outcome_unknown` | A snapshot push or template save stayed uncertain through five attempts. The machine is unchanged; take a new snapshot. |
| `snapshot_copy_discarded` | An [automatic snapshot](/docs/guides/automatic-snapshots) lost its copy of the running machine before the upload finished. The machine is unchanged; the next interval takes another. |
| `guest_inventory_unavailable` | VMYard couldn't yet confirm the machine's state after a guest action; the operation stays `uncertain` and is retried. |

Treat any other code as a failure too, and quote the operation ID when you ask for help.

---

<!-- Source: /docs/sdk/typescript.md -->

# TypeScript SDK

> Reference for @vmyard/sdk, the TypeScript client for Node.js 20+ with no runtime dependencies.

`@vmyard/sdk` is the TypeScript client for the VMYard API. It runs on Node.js 20 or newer, ships ESM and CommonJS builds, and has no runtime dependencies (it uses the global `fetch`).

> [!NOTE]
> The SDK is in private preview and is not published to npm. Build it from the [erphq/vmyard-sdk](https://github.com/erphq/vmyard-sdk) repository (ask your VMYard contact for access), then add the local package to your project:

```sh
git clone https://github.com/erphq/vmyard-sdk.git
cd vmyard-sdk && npm ci && npm run build
cd your-project && npm install ../vmyard-sdk/typescript
```

## Create a client

```ts
import { VMYard } from "@vmyard/sdk";

const vy = new VMYard({
  apiKey: process.env.VMYARD_API_KEY, // default: VMYARD_API_KEY
  baseUrl: "https://api.example.com", // default: VMYARD_API_URL
});
```

| Option | Default | Meaning |
| --- | --- | --- |
| `apiKey` | `VMYARD_API_KEY` | A `vmy_…` key. Required. |
| `baseUrl` | `VMYARD_API_URL` | Your API origin. Required: there is no default host. |
| `organizationId` | `VMYARD_ORGANIZATION_ID` | Sent as `X-Organization-ID`. Optional with an API key; must match the key. |
| `maxRetries` | 2 | Retries for retryable failures. |
| `timeoutMs` | 60000 | Timeout per HTTP attempt. |
| `fetch` | `globalThis.fetch` | A custom fetch implementation. |
| `userAgent` | — | Extra `User-Agent` text. |

The client never follows redirects, so the key is never sent to another origin.

## Machines

```ts
const machine = await vy.machines.create({ name: "dev", plan: "small", autoStopAfterSeconds: 7200 });
const same = await vy.machines.find("dev"); // id, tenant alias, or unique display name
const page = await vy.machines.list({ limit: 20 }); // { items, nextCursor }
const all = await vy.machines.listAll();

await machine.update({ name: "api" });
await machine.stop();
await machine.start();
await machine.restart();
await machine.refresh(); // reload machine.data
await machine.delete();
```

| Call | Route | Notes |
| --- | --- | --- |
| `vy.machines.create(params)` | `POST /v1/machines` | Resolves plan, image, and region names or IDs to exact versions; waits for the operation; returns a `Machine`. |
| `vy.machines.beginCreate(params)` | `POST /v1/machines` | Submits without waiting; returns the accepted operation. |
| `vy.machines.buildCreateRequest(params)` | — | The exact request `create` would send. |
| `vy.machines.list({ limit, cursor })` | `GET /v1/machines` | One page. `listAll()` and `iterate()` follow every page. |
| `vy.machines.get(id)` / `find(idOrName)` | `GET /v1/machines/{id}` | `find` accepts an ID, tenant alias, or unique display name. |
| `vy.machines.update(id, params)` / `machine.update(params)` | `PATCH /v1/machines/{id}` | `name`, `autoStopAfterSeconds` (`null` = never), `neverAutoStop`. |
| `vy.machines.start/stop/restart(id, { wait })` | `POST …/{action}` | Returns the refreshed `Machine`. |
| `vy.machines.delete(id, { wait })` | `POST …/delete` | Returns the operation. |
| `vy.machines.usage(id, { since, until })` / `machine.usage()` | `GET …/usage` | Seconds and micros; defaults to the machine's lifetime. |

`create` params: `name`, `alias` (the immutable tenant alias; defaults to `name`, else `vy-xxxxxxxx`), `plan`, `image`, `region` (name, ID, or `{id, version}`; default the first in the catalog), `resources`, `backend`, `autoStopAfterSeconds`, `neverAutoStop`, and `setupScript`.

`machine.data` is the wire `MachineDto`. Pass `{ wait: false }` to any lifecycle call to get the accepted operation instead of waiting.

## Commands

```ts
const result = await machine.exec("uname -a", { timeoutMs: 30_000 });
// { operationId, exitCode, stdout, stderr, stdoutBytes, stderrBytes, timedOut, cancelled, truncated }

const stream = machine.exec(["npm", "test"], { stream: true });
for await (const frame of stream) {
  // started | stdout | stderr | exit | error; stdout/stderr carry decoded bytes in `data`
}
```

A string runs under `/bin/sh -c`; an array runs as argv. A non-zero exit, timeout, or cancellation raises `OperationError` (see [Running commands](/docs/guides/commands#the-result)). Streams skip frame types they don't know.

## Background commands

```ts
const { command_id } = await machine.commands.start("npm run dev");
const status = await machine.commands.status(command_id, { logOffset: 0, logLimit: 65536 });
const finished = await machine.commands.wait(command_id); // exited, killed, or failed_to_start
await machine.commands.kill(command_id);
```

## Files

```ts
await machine.files.write("app/config.json", JSON.stringify({ debug: true })); // string or bytes
const text = await machine.files.read("app/config.json");
const bytes = await machine.files.readBytes("out/image.png");
```

Reads follow a queued `202` answer and reassemble `file_ranges` for you.

## Operations

```ts
const operation = await vy.operations.get(operationId);
const done = await vy.operations.wait(operationId); // throws OperationError unless it succeeds
for await (const event of vy.operations.events(operationId)) console.log(event);
```

Waiting polls every 250 ms, growing 1.5× up to 2 s, for at most 10 minutes; past that it throws `OperationTimeoutError` and the operation keeps going. `events` streams server-sent events and resumes with `Last-Event-ID`.

## Catalog, identity, billing, webhooks

| Call | Route |
| --- | --- |
| `vy.me()` | `GET /v1/me` |
| `vy.catalog.plans()` / `images()` / `regions()` | `GET /v1/plans`, `/v1/images`, `/v1/regions` |
| `vy.billing.get()` / `limits()` / `invoicePreview()` | `GET /v1/billing`, `/v1/limits`, `/v1/billing/invoice-preview` |
| `vy.billing.usage({ since, until })` | `GET /v1/usage` |
| `vy.webhooks.list()` / `get(id)` | `GET /v1/webhooks[/{id}]` |
| `vy.webhooks.create({ name, url, events, enabled })` | `POST /v1/webhooks`; returns `{ webhook, secret }` |
| `vy.webhooks.update(id, params)` / `delete(id)` / `rotateSecret(id)` | `PATCH`/`DELETE /v1/webhooks/{id}`, `POST …/rotate-secret` |
| `vy.webhooks.deliveries(id, { limit })` | `GET /v1/webhooks/{id}/deliveries` |

The SDK reads billing and can change it too: spend caps, checkout, the payment portal, the trial, the plan, and automatic refill (`billing.update`, `billing.checkout`, `billing.portal`, and others). `vy.apiKeys.list()` exists, but the server refuses API keys on key routes (`403 session_required`).

## Device sign-in

```ts
import { DeviceAuthorization } from "@vmyard/sdk";

const device = new DeviceAuthorization({ baseUrl: process.env.VMYARD_API_URL });
const code = await device.requestCode({ clientName: "my-tool on build-host" });
console.log(`Open ${code.verification_uri} and enter ${code.user_code}`);
const token = await device.waitForToken(code); // token.access_token is the new API key
```

`waitForToken` waits `interval` seconds between polls, adds 5 seconds on `slow_down`, and raises `DeviceAuthorizationError` on `access_denied`, `expired_token`, or `invalid_grant`. See [CLI device login](/docs/guides/cli-login#the-protocol).

## Idempotency and retries

Every mutation gets a fresh UUID `Idempotency-Key` unless you pass `idempotencyKey`. Reads retry on connection errors and `408`, `429`, `502`, `503`, and `504`; mutations retry only on `429` and `503`, with the same key. Retries back off exponentially with jitter and honour `Retry-After`. A `Retry-After` longer than 60 seconds is raised at once with `retryAfterSeconds` set, so you can schedule it, and a `429 limit_reached` for concurrent machines is raised without retrying.

## Errors

| Class | When |
| --- | --- |
| `APIError` | Any problem-details answer. Subclasses: `BadRequestError` 400, `AuthenticationError` 401, `PaymentRequiredError` 402, `PermissionDeniedError` 403, `NotFoundError` 404, `ConflictError` 409, `PayloadTooLargeError` 413, `UnprocessableEntityError` 422, `RateLimitError` 429, `ServerError` 5xx. |
| `BillingRequiredError`, `SpendCapReachedError` | `402` billing admission. |
| `TrialMachineClassNotAllowedError` | `403` trial size refusal. |
| `LimitReachedError` | `429 limit_reached`, with `limit` and `retryAfter`. |
| `OperationError` | An operation ended `failed`, `uncertain`, or `correlation_miss`; has `operation`, `status`, `errorCode`. |
| `OperationTimeoutError` | Waiting ran out of time; the operation continues. |
| `ExecStreamError` | A streamed exec ended with an `error` frame or broke off. |
| `DeviceAuthorizationError` | Device sign-in was denied, expired, or invalid. |
| `ConnectionError`, `ConfigurationError`, `ResolutionError` | Network failure, missing key or URL, or a catalog name that didn't resolve. |

All of them extend `VMYardError`. `APIError` carries `status`, `code`, `title`, `message`, `remediation`, `correlationId`, `fieldErrors`, `retryAfterSeconds`, `problem`, and the raw `body`.

## More of the SDK

The SDK also covers ports and port tokens (`machine.ports`), SSH keys (`machine.setSshKey`), internet access (`machine.setNetwork`), snapshots, forks and restores, templates, environments, billing changes, metrics, command history, and organizations; this page shows the common calls. For anything else, call the [HTTP API](/docs/api) directly; wire types such as `MachineDto` and `OperationDto` are exported for that.

---

<!-- Source: /docs/sdk/python.md -->

# Python SDK

> Reference for vmyard-sdk, the Python 3.9+ client built on the standard library alone.

`vmyard-sdk` is the Python client for the VMYard API. It needs Python 3.9 or newer and uses only the standard library (`urllib`), so it adds no dependencies to your project.

> [!NOTE]
> The SDK is in private preview and is not published to PyPI. Install it from a checkout of the [erphq/vmyard-sdk](https://github.com/erphq/vmyard-sdk) repository (ask your VMYard contact for access):

```sh
git clone https://github.com/erphq/vmyard-sdk.git
pip install ./vmyard-sdk/python
```

## Create a client

```python
from vmyard import VMYard

vy = VMYard(base_url="https://api.example.com")  # key from VMYARD_API_KEY
```

| Argument | Default | Meaning |
| --- | --- | --- |
| `api_key` | `VMYARD_API_KEY` | A `vmy_…` key. Required. |
| `base_url` | `VMYARD_API_URL` | Your API origin. Required: there is no default host. |
| `organization_id` | `VMYARD_ORGANIZATION_ID` | Sent as `X-Organization-ID`. Optional with an API key; must match the key. |
| `max_retries` | 2 | Retries for retryable failures. |
| `timeout` | 60.0 | Seconds per HTTP attempt. |
| `user_agent` | — | Extra `User-Agent` text. |

The client never follows redirects, so the key is never sent to another origin. The client is synchronous.

## Machines

```python
machine = vy.machines.create(name="dev", plan="small", auto_stop_after_seconds=7200)
same = vy.machines.find("dev")          # id, tenant alias, or unique display name
page = vy.machines.list(limit=20)       # one page
everything = vy.machines.list_all()

machine.update(name="api")
machine.stop()
machine.start()
machine.restart()
machine.refresh()                       # reload machine.data
machine.delete()
```

| Call | Route | Notes |
| --- | --- | --- |
| `vy.machines.create(**params)` | `POST /v1/machines` | Resolves plan, image, and region names or IDs to exact versions; waits; returns a `Machine`. |
| `vy.machines.begin_create(**params)` | `POST /v1/machines` | Submits without waiting. |
| `vy.machines.build_create_request(**params)` | — | The exact request `create` would send. |
| `vy.machines.list(limit=, cursor=)` | `GET /v1/machines` | One page; `list_all()` and `iterate()` follow every page. |
| `vy.machines.get(id)` / `find(ref)` | `GET /v1/machines/{id}` | `find` accepts an ID, tenant alias, or unique display name. |
| `machine.update(name=, auto_stop_after_seconds=, never_auto_stop=)` | `PATCH /v1/machines/{id}` | `auto_stop_after_seconds=None` means never. |
| `machine.start()` / `stop()` / `restart()` | `POST …/{action}` | `wait=False` returns the accepted operation instead. |
| `machine.delete()` | `POST …/delete` | |
| `machine.usage(since=, until=)` | `GET …/usage` | Seconds and micros; defaults to the machine's lifetime. |

`create` takes `name`, `alias`, `plan`, `image`, `region`, `resources`, `backend`, `auto_stop_after_seconds`, `never_auto_stop`, and `setup_script`. `machine.id`, `machine.name`, `machine.alias`, `machine.state` (observed), and `machine.desired_state` are shortcuts into `machine.data`, the wire `MachineDto`.

## Commands

```python
result = machine.exec("uname -a", timeout_ms=30_000)
print(result.exit_code, result.stdout, result.stderr, result.timed_out, result.truncated)

with machine.exec(["npm", "test"], stream=True) as stream:
    for frame in stream:
        ...  # started, stdout, stderr (frame.data is bytes), exit (frame.exit_code), error
```

A string runs under `/bin/sh -c`; a list runs as argv. A non-zero exit, timeout, or cancellation raises `OperationError` (see [Running commands](/docs/guides/commands#the-result)).

## Background commands

```python
command = machine.commands.start("npm run dev")
status = machine.commands.status(command["command_id"], log_offset=0, log_limit=65536)
finished = machine.commands.wait(command["command_id"])
machine.commands.kill(command["command_id"])
```

## Files

```python
machine.files.write("app/config.json", '{"debug": true}')   # str or bytes
text = machine.files.read("app/config.json")
data = machine.files.read_bytes("out/image.png")
```

## Operations

```python
operation = vy.operations.get(operation_id)
done = vy.operations.wait(operation_id)        # raises OperationError unless it succeeds
for event in vy.operations.events(operation_id):
    print(event)
```

## Catalog, identity, billing, webhooks

| Call | Route |
| --- | --- |
| `vy.me()` | `GET /v1/me` |
| `vy.catalog.plans()` / `images()` / `regions()` | `GET /v1/plans`, `/v1/images`, `/v1/regions` |
| `vy.billing.get()` / `limits()` / `invoice_preview()` | `GET /v1/billing`, `/v1/limits`, `/v1/billing/invoice-preview` |
| `vy.billing.usage(since=, until=)` | `GET /v1/usage` |
| `vy.webhooks.list()` / `get(id)` | `GET /v1/webhooks[/{id}]` |
| `vy.webhooks.create(name=, url=, events=, enabled=)` | `POST /v1/webhooks`; returns `{webhook, secret}` |
| `vy.webhooks.update(id, …)` / `delete(id)` / `rotate_secret(id)` | `PATCH`/`DELETE /v1/webhooks/{id}`, `POST …/rotate-secret` |
| `vy.webhooks.deliveries(id, limit=)` | `GET /v1/webhooks/{id}/deliveries` |

Responses are plain dictionaries with the API's JSON field names.

## Device sign-in

```python
from vmyard import DeviceAuthorization

device = DeviceAuthorization()  # base URL from VMYARD_API_URL
code = device.request_code(client_name="my-tool on build-host")
print(f"Open {code['verification_uri']} and enter {code['user_code']}")
token = device.wait_for_token(code)  # token["access_token"] is the new API key
```

## Idempotency, retries, and errors

Idempotency, retries, and error classes match the [TypeScript SDK](/docs/sdk/typescript#idempotency-and-retries), with snake_case names (`idempotency_key=`, `retry_after_seconds`, `field_errors`, `correlation_id`). The connection error class is `APIConnectionError`.

## More of the SDK

Like the TypeScript SDK, it also covers ports and port tokens, SSH keys (`set_ssh_key`), internet access (`set_network`), snapshots, forks and restores, templates, environments, and billing changes; this page shows the common calls. For anything else, call the [HTTP API](/docs/api) directly.

---

<!-- Source: /docs/cli.md -->

# CLI reference

> The common vy commands, their options, how vy finds your key and server, and its exit codes.

`vy` is the VMYard command-line interface. It needs Node.js 20 or newer.

> [!NOTE]
> The CLI is in private preview and is not published to npm. Build it from the [erphq/vmyard-sdk](https://github.com/erphq/vmyard-sdk) repository (ask your VMYard contact for access):

```sh
git clone https://github.com/erphq/vmyard-sdk.git
cd vmyard-sdk && npm ci && npm run build
npm install -g ./cli
export VMYARD_API_URL=https://api.example.com
vy login
```

`<machine>` is a machine ID, tenant alias, or display name everywhere. `<webhook>` is a webhook ID or name.

## Global options

| Option | Meaning |
| --- | --- |
| `--json` | Machine-readable output on stdout; errors as JSON on stderr. |
| `--api-url URL` | The API origin. Default: `VMYARD_API_URL`, or the one saved by `vy login`. |
| `--org ID` | Send `X-Organization-ID`. Default: `VMYARD_ORGANIZATION_ID`. |
| `-h`, `--help` | Show help. |
| `-v`, `--version` | Show the version. |

## Authentication

| Command | What it does |
| --- | --- |
| `vy login [--no-browser] [--scope PRESET]` | Browser sign-in with a device code; stores a new key and its organization. See [CLI device login](/docs/guides/cli-login). |
| `vy login --key-stdin [--no-verify]` | Store a key read from stdin, after checking it with `/v1/me`. |
| `vy logout` | Remove the stored key from this computer. |
| `vy whoami` | The caller, organizations, API URL, and where the key came from. |
| `vy keys` | List API keys. Today the server needs a browser session for this, so `vy keys` explains that keys are managed in the console. |

The key comes from `VMYARD_API_KEY` when it is set, otherwise from `vy login`. `vy` never accepts a key as an argument and never prints one, even in errors.

## Machines

| Command | What it does |
| --- | --- |
| `vy ls [--limit N]` | List machines. |
| `vy new [--plan P] [--image I] [--region R] [--name N] [--alias A] [--auto-stop HOURS\|never] [--setup-script FILE] [--wait]` | Create a machine. Plan, image, and region take names or IDs and default to the first in the catalog. `--name` is also the alias unless `--alias` is given. `--setup-script -` reads stdin. Without `--wait` it prints the operation ID. |
| `vy get <machine>` | Show one machine. |
| `vy rename <machine> <name>` | Change the display name. The alias keeps working. |
| `vy autostop <machine> <HOURS\|never>` | Set auto-stop: `2`, `0.5`, `30m`, `1d`, or `never`; 1 minute to 30 days. Restarts a running machine's deadline. |
| `vy start <machine> [--wait]` | Start a stopped machine. |
| `vy stop <machine> [--wait]` | Stop a machine. |
| `vy restart <machine> [--wait]` | Restart a machine. |
| `vy rm <machine> [--wait]` | Delete a machine. |

```sh
vy new --plan small --name dev --auto-stop 2 --setup-script ./setup.sh --wait
vy rename dev api
vy autostop api never
vy stop api --wait
vy rm api --wait
```

## Commands and files

| Command | What it does |
| --- | --- |
| `vy exec <machine> [--timeout MS] [--no-stream] -- <argv...>` | Run a program. Output streams as it arrives unless `--no-stream`. |
| `vy exec <machine> -c '<shell command>'` | Run a command under `/bin/sh -c`. |
| `vy cp <local> <machine>:<path>` | Upload a file into `/work`. `-` reads stdin. |
| `vy cp <machine>:<path> <local>` | Download a file. `-` writes stdout; a directory keeps the file's name. |

```sh
vy exec dev -- uname -a
vy exec dev -c 'cd /work && make test'
vy cp ./build.tar.gz dev:build.tar.gz
vy cp dev:out/report.txt .
```

## Catalog and operations

| Command | What it does |
| --- | --- |
| `vy plans`, `vy images`, `vy regions` | List the catalog for `vy new`. |
| `vy op <operation-id> [--wait]` | Show an operation, or wait for it to finish. |

## Billing

| Command | What it does |
| --- | --- |
| `vy usage [<machine>] [--since T] [--until T]` | Metered time and cost per machine with a total, or for one machine. `T` is RFC 3339 or `YYYY-MM-DD` (UTC). Defaults to the current period. |
| `vy billing` | Balances, plan, trial, and spend cap. |
| `vy limits` | Plan limits and current use. |

Billing refusals print their code, a hint, and how long to wait.

## Webhooks

| Command | What it does |
| --- | --- |
| `vy webhooks ls` | List endpoints. |
| `vy webhooks add --name N --url https://… [--event E]… [--disabled]` | Create an endpoint. Events default to all eight; `--event` repeats or takes a comma list. Prints the signing secret once. |
| `vy webhooks rm <webhook>` | Delete an endpoint. |
| `vy webhooks rotate <webhook>` | Rotate the signing secret and print the new one. |
| `vy webhooks deliveries <webhook> [--limit N]` | Recent deliveries. |

Webhooks need an Owner or Admin and a `full_access` key (`vy login --scope full_access`).

## Configuration

| Variable | Meaning |
| --- | --- |
| `VMYARD_API_URL` | The API origin. There is no default. |
| `VMYARD_API_KEY` | An API key. Wins over the stored key. |
| `VMYARD_ORGANIZATION_ID` | Sent as `X-Organization-ID`. |
| `VMYARD_CONFIG_DIR` | Where the config file lives. |

The config file is `config.json` in `$XDG_CONFIG_HOME/vmyard/` (Linux, default `~/.config/vmyard/`), `~/Library/Application Support/vmyard/` (macOS), or `%APPDATA%\vmyard\` (Windows). It is written with mode `0600`.

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success. |
| `1` | An API or runtime error. |
| `2` | A usage error (bad arguments). |
| any | `vy exec` exits with the remote command's exit code. |
| `124` | `vy exec`: the command timed out. |
| `125` | `vy exec`: VMYard couldn't run the command (an error frame or a broken stream). |

## More commands

This page covers the common commands. `vy --help` lists the rest, including `ports`, `ssh`, `shell`, `network`, `snapshot` and `snapshots`, `fork`, `restore`, `templates`, `env`, `history`, `logs`, `orgs`, and `alerts`. The CLI cannot start a background command; use the console, the SDKs, or the [HTTP API](/docs/guides/background-commands).

---

<!-- Source: /docs/api.md -->

# 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](/docs/guides/api-keys).

| 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](/docs/concepts/operations).
- 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](/docs/guides/errors).

## Groups

| Group | Operations | Description |
| --- | --- | --- |
| [Machines](/docs/api/machines) | 9 | Create, list, read, change, start, stop, restart, and delete machines. Every lifecycle change is an asynchronous operation. |
| [Operations](/docs/api/operations) | 2 | Read an operation's status and result, or follow its persisted events as server-sent events. |
| [Machine metrics](/docs/api/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](/docs/api/exec) | 1 | Run a foreground command inside a machine, optionally streaming its output as NDJSON frames. |
| [Background commands](/docs/api/commands) | 3 | Start detached commands, read their status and log, and kill them. |
| [Terminal](/docs/api/terminal) | 2 | Open an interactive login shell in a running machine over a WebSocket. Browsers first mint a single-use ticket. |
| [Desktop](/docs/api/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](/docs/api/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](/docs/api/command-history) | 3 | Search a machine's past commands, read one entry, and page through its stored stdout and stderr. |
| [Snapshots and templates](/docs/api/snapshots) | 13 | Push a stopped machine, save it as a named template, and copy a machine with fork or restore. |
| [Files](/docs/api/files) | 2 | Write and read files inside a machine's `/work` directory. |
| [File browser](/docs/api/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](/docs/api/ports-and-ssh) | 6 | Expose guest ports as HTTPS URLs, issue access tokens for private ports, and install an SSH key. |
| [Environments](/docs/api/environments) | 12 | Named, versioned sets of environment variables and secret files that VMYard applies to machines. |
| [Catalog](/docs/api/catalog) | 3 | The plans, images, and regions a machine is created from, each selected by ID and exact version. |
| [Billing and usage](/docs/api/billing) | 18 | Balances, limits, metered usage, invoice preview, and billing management. |
| [Webhooks](/docs/api/webhooks) | 7 | Register HTTPS endpoints for signed lifecycle events and inspect their deliveries. |
| [Email alerts](/docs/api/notifications) | 4 | Read and change your email alert preferences, and the unsubscribe link every alert email carries. |
| [Organizations](/docs/api/organizations) | 4 | List, read, create, and rename the organizations the caller belongs to. |
| [Waitlist and access](/docs/api/waitlist) | 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](/docs/api/members) | 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)](/docs/api/capacity) | 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](/docs/api/api-keys) | 4 | Create, list, rotate, and revoke organization API keys. These routes need a browser session. |
| [Identity](/docs/api/identity) | 1 | The signed-in user or API key caller and their memberships. |
| [Sign-in](/docs/api/sign-in) | 4 | Browser sign-in with a configured provider, and sign-out. |
| [Email sign-in](/docs/api/email-sign-in) | 3 | Sign in with an emailed 6-digit code or magic link. |
| [Sign-in methods](/docs/api/sign-in-methods) | 2 | Link another sign-in method to the signed-in user, or remove one. |
| [Operator](/docs/api/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](/docs/api/device-authorization) | 5 | The RFC 8628 device grant that `vy login` uses to receive an API key. |
| [Schemas](/docs/api/schemas) | — | Every request and response body. |

---

<!-- Source: /docs/api/machines.md -->

# Machines API

> Create, list, read, change, start, stop, restart, and delete machines. Every lifecycle change is an asynchronous operation.

- [List machines](#list-machines): `GET /v1/machines`
- [Create a machine](#create-a-machine): `POST /v1/machines`
- [Get a machine](#get-a-machine): `GET /v1/machines/{machine_id}`
- [Change machine settings](#change-machine-settings): `PATCH /v1/machines/{machine_id}`
- [Start a machine](#start-a-machine): `POST /v1/machines/{machine_id}/start`
- [Stop a machine](#stop-a-machine): `POST /v1/machines/{machine_id}/stop`
- [Restart a machine](#restart-a-machine): `POST /v1/machines/{machine_id}/restart`
- [Delete a machine](#delete-a-machine): `POST /v1/machines/{machine_id}/delete`
- [Change a machine's egress](#change-a-machines-egress): `PUT /v1/machines/{machine_id}/network`

## List machines

`GET /v1/machines`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | `integer` | No | Page size, 1-100 (default 50). |
| `cursor` | query | `string` | No | `next_cursor` from the previous page, with the same `sort` and `order`. |
| `q` | query | `string` | No | Case-insensitive search, at most 128 characters: contained in the display name or tenant alias, a prefix of the machine ID or port label, or a port host (`<label>-<port>...`). Blank means no search. |
| `state` | query | `string` | No | Observed state: `absent`, `provisioning`, `running`, `stopped`, `degraded`, or `unknown`. |
| `desired_state` | query | `string` | No | Desired state: `running`, `stopped`, or `deleted`. |
| `sort` | query | `string` | No | `created_at` (default), `name` (display name), or `state` (observed state). |
| `order` | query | `string` | No | `asc` or `desc`. Defaults to `desc` for `created_at` (newest first) and `asc` otherwise. Ties break on the machine ID in the same direction. |
| `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 |
| --- | --- | --- |
| `200` | — | [`MachinePage`](/docs/api/schemas#machinepage) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | An unknown `sort`, `order`, `state`, or `desired_state`, an oversized `q`, or a malformed cursor or one made for another sort | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/machines" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "items": [
    {
      "auto_stop_after_seconds": 0,
      "auto_stop_at": "2026-10-12T06:51:01Z",
      "backend": "mock",
      "created_at": "2026-10-12T05:51:01Z",
      "desired_state": "running",
      "environment": {
        "applied_version_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "error_code": "string",
        "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "status": "pending",
        "version": 0,
        "version_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
      },
      "forked_from_machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "idle_since": "2026-10-12T05:36:01Z",
      "idle_sleep_after_seconds": 900,
      "idle_sleep_at": "2026-10-12T05:51:01Z",
      "image": {
        "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "version": 0
      },
      "last_active_at": "2026-10-12T05:36:01Z",
      "latest_snapshot": {
        "completed_at": "2026-10-12T05:51:01Z",
        "created_at": "2026-10-12T05:51:01Z",
        "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "source": "api",
        "status": "pending",
        "tier": "warm"
      },
      "metrics": {
        "cpu_limit_millis": 0,
        "cpu_millis": 0,
        "cpu_percent": 0.5,
        "disk_percent": 0.5,
        "disk_size_bytes": 0,
        "disk_used_bytes": 0,
        "flags": [
          "disk_almost_full"
        ],
        "io_read_bps": 0,
        "io_write_bps": 0,
        "memory_bytes": 0,
        "memory_limit_bytes": 0,
        "memory_percent": 0.5,
        "net_rx_bps": 0,
        "net_tx_bps": 0,
        "sampled_at": "2026-10-12T05:51:01Z",
        "stale": false,
        "stale_reason": "host_unreachable",
        "state": "string"
      },
      "name": "dev",
      "network": {
        "egress": "none",
        "ipv6_address": "string"
      },
      "observed_state": {
        "boot_id": "string",
        "state": "running"
      },
      "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "plan": {
        "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "version": 0
      },
      "region": {
        "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "version": 0
      },
      "resources": {
        "cpu": 0,
        "disk_gib": 0,
        "memory_mib": 0
      },
      "restored_from_snapshot_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "setup_operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "ssh": {
        "host": "ssh.eu.example.com",
        "port": 0,
        "user": "vmyard"
      },
      "starting_soon": {
        "expires_at": "2026-10-12T05:51:01Z",
        "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "position": 0,
        "priority": "paid",
        "queued_at": "2026-10-12T05:51:01Z",
        "reason": "no_host_in_region"
      },
      "tenant_alias": "dev"
    }
  ],
  "next_cursor": "string"
}
```

## Create a machine

`POST /v1/machines`

Billing admission can refuse it: `402 billing_required` or `spend_cap_reached`, `403 trial_machine_class_not_allowed`, `409 plan_not_priced`, or `429 limit_reached`. See [Usage, billing, and limits](/docs/guides/billing#limits). Idle sleep is off unless the body sets `idle_sleep_after_seconds` (300 to 86,400); see [Idle sleep](/docs/concepts/idle-sleep). `network: {egress}` (`none` or `internet`) chooses the machine's egress; omitted, the host's default applies, and it can't be combined with `template` (`422`); see [Internet access and IPv6](/docs/guides/networking).

- **API key:** `Authorization: Bearer vmy_…` with preset `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.
- **Idempotency:** send a unique `Idempotency-Key`; replaying the same key and body returns the same operation.

**Parameters**

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

**Request body** (`application/json`, [`CreateMachineRequest`](/docs/api/schemas#createmachinerequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `auto_stop_after_seconds` | `integer \| null` | No | Seconds the machine may run after it becomes running before the control plane stops it, 60 to 2592000. Omitted means 3600; `null` means never. 60–2592000. |
| `backend` | [`null \| BackendDto`](/docs/api/schemas#backenddto) | No |  |
| `environment` | `string \| null` | No | Environment to apply, by name (alternative to `environment_id`). |
| `environment_id` | `string (uuid) \| null` | No | Environment to apply once the machine is first ready, by ID. Omitting `environment_id`, `environment`, and `no_env` selects the organization's default environment, if it has one. |
| `idle_sleep_after_seconds` | `integer \| null` | No | Seconds the running machine may stay idle (no operation, terminal, or resource activity) before the control plane puts it to sleep, 300 to 86400. Omitted or `null` leaves idle sleep off. 300–86400. |
| `image` | [`null \| VersionedSelectionDto`](/docs/api/schemas#versionedselectiondto) | No |  |
| `name` | `string \| null` | No | Display name, following the `tenant_alias` rules. Defaults to the tenant alias. Unlike the alias it can be changed later. |
| `network` | [`null \| NetworkRequest`](/docs/api/schemas#networkrequest) | No | The machine's egress policy. Omitted, the host's default applies (internet egress unless the operator configured otherwise). Not with `template`: a restored machine keeps its host's policy. Change it later with `PUT /v1/machines/{machine_id}/network`. |
| `never_auto_stop` | `boolean` | No | `true` disables auto-stop. It cannot be combined with `auto_stop_after_seconds`. |
| `no_env` | `boolean` | No | `true` creates the machine without any environment, not even the default (for example, for a machine shared with third parties). |
| `plan` | [`null \| VersionedSelectionDto`](/docs/api/schemas#versionedselectiondto) | No | Required without `template`; with one, the template's exact plan, image, region, resources, and backend are used and these may be omitted (if sent, they must match). |
| `region` | [`null \| VersionedSelectionDto`](/docs/api/schemas#versionedselectiondto) | No |  |
| `resources` | [`null \| ResourcesDto`](/docs/api/schemas#resourcesdto) | No |  |
| `setup_script` | `string \| null` | No | Shell script run once as `/bin/sh -c <script>` after the machine is first ready, at most 65527 bytes without NUL. It is its own exec operation (see `setup_operation_id`) with the runtime's maximum timeout; its failure does not stop the machine. |
| `template` | `string \| null` | No | Create the machine from a ready template (name or ID): a warm restore with its own identity, woken at once. The chosen environment (or the default, or `no_env`) is applied after the restore. |
| `tenant_alias` | `string \| null` | No | Required without `template`. With one, it is the template's (the runtime scopes stored snapshots to their tenant) and may be omitted. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `202` | Accepted. Follow `operation_url` until the operation is terminal. | [`OperationAccepted`](/docs/api/schemas#operationaccepted) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | Conflicts with the current state, such as a reused idempotency key with another body (`idempotency_conflict`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `413` | The request body is too large (`body_too_large`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/machines" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "tenant_alias": "dev",
  "name": "dev",
  "plan": {
    "id": "0b6f6c55-2f1d-4f0e-9a51-6f0f4cba7a10",
    "version": 1
  },
  "image": {
    "id": "4d2b9c1e-7a3f-4e58-b1c6-2f9d8e7a6b50",
    "version": 3
  },
  "region": {
    "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "version": 1
  },
  "resources": {
    "cpu": 2,
    "memory_mib": 4096,
    "disk_gib": 12
  },
  "backend": "kvm",
  "auto_stop_after_seconds": 7200,
  "setup_script": "apt-get update && apt-get install -y jq"
}'
```

```json title="Response 202"
{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "requested_action": "create",
  "status": "pending"
}
```

## Get a machine

`GET /v1/machines/{machine_id}`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**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 |
| --- | --- | --- |
| `200` | — | [`MachineDto`](/docs/api/schemas#machinedto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "auto_stop_after_seconds": 0,
  "auto_stop_at": "2026-10-12T06:51:01Z",
  "backend": "mock",
  "created_at": "2026-10-12T05:51:01Z",
  "desired_state": "running",
  "environment": {
    "applied_version_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "error_code": "string",
    "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "status": "pending",
    "version": 0,
    "version_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
  },
  "forked_from_machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "idle_since": "2026-10-12T05:36:01Z",
  "idle_sleep_after_seconds": 900,
  "idle_sleep_at": "2026-10-12T05:51:01Z",
  "image": {
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "version": 0
  },
  "last_active_at": "2026-10-12T05:36:01Z",
  "latest_snapshot": {
    "completed_at": "2026-10-12T05:51:01Z",
    "created_at": "2026-10-12T05:51:01Z",
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "source": "api",
    "status": "pending",
    "tier": "warm"
  },
  "metrics": {
    "cpu_limit_millis": 0,
    "cpu_millis": 0,
    "cpu_percent": 0.5,
    "disk_percent": 0.5,
    "disk_size_bytes": 0,
    "disk_used_bytes": 0,
    "flags": [
      "disk_almost_full"
    ],
    "io_read_bps": 0,
    "io_write_bps": 0,
    "memory_bytes": 0,
    "memory_limit_bytes": 0,
    "memory_percent": 0.5,
    "net_rx_bps": 0,
    "net_tx_bps": 0,
    "sampled_at": "2026-10-12T05:51:01Z",
    "stale": false,
    "stale_reason": "host_unreachable",
    "state": "string"
  },
  "name": "dev",
  "network": {
    "egress": "none",
    "ipv6_address": "string"
  },
  "observed_state": {
    "boot_id": "string",
    "state": "running"
  },
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "plan": {
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "version": 0
  },
  "region": {
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "version": 0
  },
  "resources": {
    "cpu": 0,
    "disk_gib": 0,
    "memory_mib": 0
  },
  "restored_from_snapshot_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "setup_operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "ssh": {
    "host": "ssh.eu.example.com",
    "port": 0,
    "user": "vmyard"
  },
  "starting_soon": {
    "expires_at": "2026-10-12T05:51:01Z",
    "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "position": 0,
    "priority": "paid",
    "queued_at": "2026-10-12T05:51:01Z",
    "reason": "no_host_in_region"
  },
  "tenant_alias": "dev"
}
```

## Change machine settings

`PATCH /v1/machines/{machine_id}`

Send only what changes. `idle_sleep_after_seconds` takes 300 to 86,400 seconds, or `null` to turn idle sleep off, and restarts the idle window; out of range answers `422` with a field error. See [Auto-stop](/docs/concepts/auto-stop) and [Idle sleep](/docs/concepts/idle-sleep).

- **API key:** `Authorization: Bearer vmy_…` with preset `use_existing`, `create_and_use`, `full_access`.
- **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. |

**Request body** (`application/json`, [`UpdateMachineRequest`](/docs/api/schemas#updatemachinerequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `auto_stop_after_seconds` | `integer \| null` | No | New auto-stop duration, 60 to 2592000 seconds, or `null` for never. The deadline of a running machine restarts from now. 60–2592000. |
| `idle_sleep_after_seconds` | `integer \| null` | No | New idle-sleep window, 300 to 86400 seconds, or `null` to turn idle sleep off. The idle window restarts. 300–86400. |
| `name` | `string \| null` | No | New display name, following the `tenant_alias` rules. The tenant alias itself is immutable. |
| `never_auto_stop` | `boolean` | No | `true` disables auto-stop. It cannot be combined with `auto_stop_after_seconds`. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`MachineDto`](/docs/api/schemas#machinedto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `machine_deleted`: the machine was deleted | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `413` | The request body is too large (`body_too_large`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X PATCH "$VMYARD_API_URL/v1/machines/$MACHINE_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "api",
  "auto_stop_after_seconds": 3600,
  "idle_sleep_after_seconds": 900
}'
```

```json title="Response 200"
{
  "auto_stop_after_seconds": 0,
  "auto_stop_at": "2026-10-12T06:51:01Z",
  "backend": "mock",
  "created_at": "2026-10-12T05:51:01Z",
  "desired_state": "running",
  "environment": {
    "applied_version_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "error_code": "string",
    "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "status": "pending",
    "version": 0,
    "version_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
  },
  "forked_from_machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "idle_since": "2026-10-12T05:36:01Z",
  "idle_sleep_after_seconds": 900,
  "idle_sleep_at": "2026-10-12T05:51:01Z",
  "image": {
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "version": 0
  },
  "last_active_at": "2026-10-12T05:36:01Z",
  "latest_snapshot": {
    "completed_at": "2026-10-12T05:51:01Z",
    "created_at": "2026-10-12T05:51:01Z",
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "source": "api",
    "status": "pending",
    "tier": "warm"
  },
  "metrics": {
    "cpu_limit_millis": 0,
    "cpu_millis": 0,
    "cpu_percent": 0.5,
    "disk_percent": 0.5,
    "disk_size_bytes": 0,
    "disk_used_bytes": 0,
    "flags": [
      "disk_almost_full"
    ],
    "io_read_bps": 0,
    "io_write_bps": 0,
    "memory_bytes": 0,
    "memory_limit_bytes": 0,
    "memory_percent": 0.5,
    "net_rx_bps": 0,
    "net_tx_bps": 0,
    "sampled_at": "2026-10-12T05:51:01Z",
    "stale": false,
    "stale_reason": "host_unreachable",
    "state": "string"
  },
  "name": "dev",
  "network": {
    "egress": "none",
    "ipv6_address": "string"
  },
  "observed_state": {
    "boot_id": "string",
    "state": "running"
  },
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "plan": {
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "version": 0
  },
  "region": {
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "version": 0
  },
  "resources": {
    "cpu": 0,
    "disk_gib": 0,
    "memory_mib": 0
  },
  "restored_from_snapshot_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "setup_operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "ssh": {
    "host": "ssh.eu.example.com",
    "port": 0,
    "user": "vmyard"
  },
  "starting_soon": {
    "expires_at": "2026-10-12T05:51:01Z",
    "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "position": 0,
    "priority": "paid",
    "queued_at": "2026-10-12T05:51:01Z",
    "reason": "no_host_in_region"
  },
  "tenant_alias": "dev"
}
```

## Start a machine

`POST /v1/machines/{machine_id}/start`

Billing admission can refuse it: `402 billing_required` or `spend_cap_reached`, `403 trial_machine_class_not_allowed`, `409 plan_not_priced`, or `429 limit_reached`. See [Usage, billing, and limits](/docs/guides/billing#limits).

- **API key:** `Authorization: Bearer vmy_…` with preset `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.
- **Idempotency:** send a unique `Idempotency-Key`; replaying the same key and body returns the same operation.

**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. |

**Request body** (`application/json`, [`EmptyAction`](/docs/api/schemas#emptyaction))

No fields.

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `202` | Accepted. Follow `operation_url` until the operation is terminal. | [`OperationAccepted`](/docs/api/schemas#operationaccepted) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `machine_deleted`: the machine's deletion was requested; `machine_not_created`: its create is pending or did not succeed, so only a delete is accepted | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `413` | The request body is too large (`body_too_large`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/start" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```json title="Response 202"
{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "requested_action": "start",
  "status": "pending"
}
```

## Stop a machine

`POST /v1/machines/{machine_id}/stop`

- **API key:** `Authorization: Bearer vmy_…` with preset `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.
- **Idempotency:** send a unique `Idempotency-Key`; replaying the same key and body returns the same operation.

**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. |

**Request body** (`application/json`, [`EmptyAction`](/docs/api/schemas#emptyaction))

No fields.

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `202` | Accepted. Follow `operation_url` until the operation is terminal. | [`OperationAccepted`](/docs/api/schemas#operationaccepted) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `machine_deleted`: the machine's deletion was requested; `machine_not_created`: its create is pending or did not succeed, so only a delete is accepted | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `413` | The request body is too large (`body_too_large`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/stop" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```json title="Response 202"
{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "requested_action": "stop",
  "status": "pending"
}
```

## Restart a machine

`POST /v1/machines/{machine_id}/restart`

Billing admission can refuse it: `402 billing_required` or `spend_cap_reached`, `403 trial_machine_class_not_allowed`, `409 plan_not_priced`, or `429 limit_reached`. See [Usage, billing, and limits](/docs/guides/billing#limits). One `restart` operation reboots the running machine without stopping it: `/work` is kept, its run stays open, and it succeeds only with a new `boot_id`. A host that can't restart its machines ends it `failed` with `restart_unsupported`, and the machine keeps running. See [Restart](/docs/concepts/lifecycle#restart).

- **API key:** `Authorization: Bearer vmy_…` with preset `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.
- **Idempotency:** send a unique `Idempotency-Key`; replaying the same key and body returns the same operation.

**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. |

**Request body** (`application/json`, [`EmptyAction`](/docs/api/schemas#emptyaction))

No fields.

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `202` | Accepted. Follow `operation_url` until the operation is terminal. | [`OperationAccepted`](/docs/api/schemas#operationaccepted) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `machine_deleted`: the machine's deletion was requested; `machine_not_created`: its create is pending or did not succeed, so only a delete is accepted | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `413` | The request body is too large (`body_too_large`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/restart" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```json title="Response 202"
{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "requested_action": "restart",
  "status": "pending"
}
```

## Delete a machine

`POST /v1/machines/{machine_id}/delete`

- **API key:** `Authorization: Bearer vmy_…` with preset `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.
- **Idempotency:** send a unique `Idempotency-Key`; replaying the same key and body returns the same operation.

**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. |

**Request body** (`application/json`, [`EmptyAction`](/docs/api/schemas#emptyaction))

No fields.

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `202` | Accepted. Follow `operation_url` until the operation is terminal. | [`OperationAccepted`](/docs/api/schemas#operationaccepted) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `machine_deleted`: the machine's deletion was requested; `machine_not_created`: its create is pending or did not succeed, so only a delete is accepted | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `413` | The request body is too large (`body_too_large`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/delete" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```json title="Response 202"
{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "requested_action": "delete",
  "status": "pending"
}
```

## Change a machine's egress

`PUT /v1/machines/{machine_id}/network`

The machine must be running or stopped (`422` otherwise); the change never starts, stops, or restarts it. The `network_set` operation succeeds only when the host reports the requested policy applied, and `MachineDto.network` then shows it. A host without guest networking, or one whose operator turned internet egress off, ends it `failed` with nothing changed. See [Internet access and IPv6](/docs/guides/networking).

- **API key:** `Authorization: Bearer vmy_…` with preset `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.
- **Idempotency:** send a unique `Idempotency-Key`; replaying the same key and body returns the same operation.

**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. |

**Request body** (`application/json`, [`NetworkRequest`](/docs/api/schemas#networkrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `egress` | [`EgressDto`](/docs/api/schemas#egressdto) | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `202` | The `network_set` operation changes the policy on the machine's host; the machine must be running or stopped. `MachineDto.network` shows the result once it succeeds. | [`OperationAccepted`](/docs/api/schemas#operationaccepted) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | Conflicts with the current state, such as a reused idempotency key with another body (`idempotency_conflict`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X PUT "$VMYARD_API_URL/v1/machines/$MACHINE_ID/network" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "egress": "none"
}'
```

```json title="Response 202"
{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "requested_action": "network_set",
  "status": "pending"
}
```

---

<!-- Source: /docs/api/operations.md -->

# Operations API

> Read an operation's status and result, or follow its persisted events as server-sent events.

- [Get an operation](#get-an-operation): `GET /v1/operations/{operation_id}`
- [Stream operation events](#stream-operation-events): `GET /v1/operations/{operation_id}/events`

## Get an operation

`GET /v1/operations/{operation_id}`

A `stop` reports who asked for it in `stop_reason`: `api`, `auto_stop`, `billing`, `idle_sleep`, `suspension` (the organization was suspended), `abuse` (the sustained-CPU guard stopped a trial machine), or `organization_deleted`. See [Operations and idempotency](/docs/concepts/operations#operation-results).

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `operation_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 |
| --- | --- | --- |
| `200` | — | [`OperationDto`](/docs/api/schemas#operationdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/operations/$OPERATION_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "attempt_count": 0,
  "completed_but_unchanged": false,
  "error_code": "string",
  "exec_result": {
    "cancelled": false,
    "exit_code": 0,
    "stderr_base64": "string",
    "stdout_base64": "string",
    "timed_out": false,
    "truncated": false
  },
  "file_ranges": [
    {
      "data_base64": "string",
      "missing": false,
      "offset": 0,
      "path": "notes/todo.txt",
      "size": 0
    }
  ],
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "kind": "stop",
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "starting_soon": {
    "expires_at": "2026-10-12T05:51:01Z",
    "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "position": 0,
    "priority": "paid",
    "queued_at": "2026-10-12T05:51:01Z",
    "reason": "no_host_in_region"
  },
  "status": "pending",
  "stop_reason": "idle_sleep"
}
```

## Stream operation events

`GET /v1/operations/{operation_id}/events`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `operation_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. |
| `Last-Event-ID` | header | `integer \| null` | No | Resume strictly after this persisted monotonic event ID |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | Persisted history followed by live events | `text/event-stream` |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/operations/$OPERATION_ID/events" \
  -N \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

---

<!-- Source: /docs/api/machine-metrics.md -->

# Machine metrics API

> Read a machine's CPU, memory, disk, I/O, and network history at one-minute resolution, or the host's live samples.

- [Get machine metrics](#get-machine-metrics): `GET /v1/machines/{machine_id}/metrics`

## Get machine metrics

`GET /v1/machines/{machine_id}/metrics`

`resolution=1m` (the default) reads stored one-minute history, at most 1440 points per response; continue with `next_since`. `resolution=live` relays the host's samples and needs a running or sleeping machine (`409 machine_not_running`); fall back to `1m` on `409` or `503`. See [Machine metrics](/docs/guides/machine-metrics).

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**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. |
| `resolution` | query | `string` | No | `1m` (default; stored history) or `live` (the host's samples through the fleet). |
| `since` | query | `string` | No | Only points at or after this time (UTC RFC 3339). Defaults to the last 24 hours for `1m` and everything the host keeps for `live`. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`MachineMetricsDto`](/docs/api/schemas#machinemetricsdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `machine_not_running`: `live` needs a running or sleeping machine | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | An unknown `resolution` or a malformed `since` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | `metrics_unavailable` (no runtime configured for `live`) or `runtime_unavailable` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/metrics" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "cpu_limit_millis": 0,
  "guest_reported": {
    "filesystem_available_bytes": 0,
    "filesystem_total_bytes": 0,
    "memory_available_bytes": 0,
    "memory_total_bytes": 0,
    "reported_at": "2026-10-12T05:51:01Z"
  },
  "interval_ms": 0,
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "memory_limit_bytes": 0,
  "next_since": "string",
  "points": [
    {
      "cpu_millis": 0,
      "cpu_millis_max": 0,
      "cpu_percent": 0.5,
      "disk_percent": 0.5,
      "disk_used_bytes": 0,
      "io_read_bps": 0,
      "io_write_bps": 0,
      "memory_bytes": 0,
      "memory_bytes_max": 0,
      "memory_percent": 0.5,
      "net_rx_bps": 0,
      "net_tx_bps": 0,
      "t": "2026-10-12T05:51:01Z"
    }
  ],
  "resolution": "live"
}
```

---

<!-- Source: /docs/api/exec.md -->

# Exec API

> Run a foreground command inside a machine, optionally streaming its output as NDJSON frames.

- [Run a command](#run-a-command): `POST /v1/machines/{machine_id}/exec`

## Run a command

`POST /v1/machines/{machine_id}/exec`

- **API key:** `Authorization: Bearer vmy_…` with preset `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.
- **Idempotency:** send a unique `Idempotency-Key`; replaying the same key and body returns the same operation.

**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. |

**Request body** (`application/json`, [`ExecRequest`](/docs/api/schemas#execrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `argv` | `string[] \| null` | No | Program and arguments, executed directly. Exactly one of `argv` or `command`. |
| `command` | `string \| null` | No | Shell command run as `/bin/sh -c <command>`, at most 8192 bytes. |
| `stream` | `boolean` | No | Respond with `application/x-ndjson` frames as output arrives instead of `202 Accepted`. |
| `timeout_ms` | `integer \| null` | No | Foreground limit in milliseconds, 1 to the runtime maximum (600000). Defaults to the maximum; the effective value is persisted with the operation. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | With `stream: true`: newline-delimited JSON frames (started, stdout, stderr, then exit or error). Replaying the same Idempotency-Key and body streams the persisted operation again. | [`ExecStreamFrame`](/docs/api/schemas#execstreamframe) |
| `202` | Accepted. Follow `operation_url` until the operation is terminal. | [`OperationAccepted`](/docs/api/schemas#operationaccepted) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | Conflicts with the current state, such as a reused idempotency key with another body (`idempotency_conflict`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `413` | The request body is too large (`body_too_large`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request; `timeout_exceeds_runtime_limit` names the runtime maximum | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/exec" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "command": "uname -a",
  "timeout_ms": 30000,
  "stream": false
}'
```

```json title="Response 202"
{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "requested_action": "exec",
  "status": "pending"
}
```

---

<!-- Source: /docs/api/commands.md -->

# Background commands API

> Start detached commands, read their status and log, and kill them.

- [Start a background command](#start-a-background-command): `POST /v1/machines/{machine_id}/commands`
- [Get a background command](#get-a-background-command): `GET /v1/machines/{machine_id}/commands/{command_id}`
- [Kill a background command](#kill-a-background-command): `POST /v1/machines/{machine_id}/commands/{command_id}/kill`

## Start a background command

`POST /v1/machines/{machine_id}/commands`

- **API key:** `Authorization: Bearer vmy_…` with preset `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.
- **Idempotency:** send a unique `Idempotency-Key`; replaying the same key and body returns the same operation.

**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. |

**Request body** (`application/json`, [`StartCommandRequest`](/docs/api/schemas#startcommandrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `argv` | `string[] \| null` | No | Program and arguments. Exactly one of `argv` or `command`. |
| `command` | `string \| null` | No | Shell command run as `/bin/sh -c <command>`, at most 8192 bytes. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `202` | — | [`CommandAccepted`](/docs/api/schemas#commandaccepted) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | Conflicts with the current state, such as a reused idempotency key with another body (`idempotency_conflict`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `413` | The request body is too large (`body_too_large`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/commands" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "command": "npm run dev > dev.log 2>&1"
}'
```

```json title="Response 202"
{
  "command_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "command_url": "/v1/machines/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f/commands/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "status": "pending"
}
```

## Get a background command

`GET /v1/machines/{machine_id}/commands/{command_id}`

- **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 |  |
| `command_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. |
| `log_offset` | query | `integer` | No | Byte offset into the command log (default 0). |
| `log_limit` | query | `integer` | No | Bytes of log to return, 1 to 1048576 (default 65536). |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`CommandDto`](/docs/api/schemas#commanddto) |
| `202` | The guest read is still queued; follow the operation | [`OperationAccepted`](/docs/api/schemas#operationaccepted) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `502` | The machine's host or a provider failed to answer. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/commands/$COMMAND_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "command_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "error_code": "string",
  "exit_code": 0,
  "log": {
    "data_base64": "string",
    "next_offset": 0,
    "offset": 0,
    "size": 0
  },
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "signal": 0,
  "status": "starting"
}
```

## Kill a background command

`POST /v1/machines/{machine_id}/commands/{command_id}/kill`

- **API key:** `Authorization: Bearer vmy_…` with preset `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.
- **Idempotency:** send a unique `Idempotency-Key`; replaying the same key and body returns the same operation.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `machine_id` | path | `string (uuid)` | Yes |  |
| `command_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. |

**Request body** (`application/json`, [`EmptyAction`](/docs/api/schemas#emptyaction))

No fields.

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `202` | Accepted. Follow `operation_url` until the operation is terminal. | [`OperationAccepted`](/docs/api/schemas#operationaccepted) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | Conflicts with the current state, such as a reused idempotency key with another body (`idempotency_conflict`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/commands/$COMMAND_ID/kill" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```json title="Response 202"
{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "requested_action": "kill",
  "status": "pending"
}
```

---

<!-- Source: /docs/api/terminal.md -->

# Terminal API

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

- [Open a terminal](#open-a-terminal): `GET /v1/machines/{machine_id}/terminal`
- [Create a terminal ticket](#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](/docs/guides/web-terminal).

- **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`](/docs/api/schemas#problemdetails) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#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`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#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`](/docs/api/schemas#problemdetails) |
| `422` | Invalid `cols` or `rows` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `429` | `terminal_limit_reached` (per-user or per-organization concurrency) or `rate_limited` (opens per minute) | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | `terminals_unavailable` or `runtime_unavailable` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="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`](/docs/api/schemas#terminalticketdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Viewer or Billing (`forbidden`), a bad CSRF token, or an API key (`session_required`: keys open terminals directly) | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `machine_not_running`, `machine_not_created` (its create is pending or failed), or `machine_deleted` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `429` | Too many requests; wait for `Retry-After`. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | `terminals_unavailable` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="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"
```

```json title="Response 201"
{
  "expires_at": "string",
  "ticket": "string",
  "url": "https://hooks.example.com/vmyard"
}
```

---

<!-- Source: /docs/api/desktop.md -->

# Desktop API

> View a running machine's graphical desktop, or only its web browser, over a WebSocket carrying VNC. Browsers first mint a single-use ticket.

- [Open a desktop](#open-a-desktop): `GET /v1/machines/{machine_id}/desktop`
- [Create a desktop ticket](#create-a-desktop-ticket): `POST /v1/machines/{machine_id}/desktop/tickets`

## Open a desktop

`GET /v1/machines/{machine_id}/desktop`

Opens a viewer of the machine's graphical desktop over a WebSocket (`Upgrade: websocket`), starting the desktop if needed. A browser session presents its cookie, an `Origin` the service serves the UI from, and `ticket` from `POST .../desktop/tickets`; the CLI presents `Authorization: Bearer` with a `use_existing` or higher key. `mode=browser` shows only a maximized web browser instead of the whole desktop. After the upgrade the server sends `{"type":"opened","width","height","mode"}`, then binary messages carry the VNC server's RFB bytes and the client's binary messages are RFB bytes for it (security type None: the WebSocket is the authentication). Text messages are JSON control (`DesktopClientMessage` in, `DesktopServerMessage` out); `{"type":"resize"}` is accepted and ignored, as clients resize in RFB (`SetDesktopSize`). `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 the ticket and must connect from the console's origin; `mode=browser` shows only the machine's web browser and is refused with `503 browser_unavailable` when the machine can't stream it. Messages and close reasons are in the [Desktop guide](/docs/guides/desktop).

- **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. |
| `width` | query | `integer` | No | Starting width, 320-7680, with `height`. Applies only when this open starts the desktop (default 1920 x 1080); a running desktop keeps its size, which the `opened` message reports. |
| `height` | query | `integer` | No | Starting height, 240-4320, with `width`. |
| `mode` | query | [`DesktopModeDto`](/docs/api/schemas#desktopmodedto) | No | `desktop` (default) or `browser`: the machine's full desktop, or its separate browser-only desktop. A runtime refusing browser mode is `503 browser_unavailable`. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `101` | Switching protocols: the viewer is connected | — |
| `400` | Not a WebSocket upgrade request | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | `forbidden` (Viewer or Billing), `insufficient_scope` (a `read_only` key), `origin_not_allowed`, or `desktop_ticket_invalid` (missing, expired, used, or for another machine, session, or a terminal) | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `machine_not_running`, `machine_not_created`, or `machine_deleted` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid `width`, `height`, or `mode` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `429` | `desktop_limit_reached` (viewers per machine, or per-user or per-organization concurrency) or `rate_limited` (opens per minute, with `Retry-After`) | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | `desktop_unavailable` (desktops are not configured, or the runtime refused: an image without a desktop, a host without desktops, a runtime limit), with `mode=browser` `browser_unavailable` (the runtime refused browser mode: an image without the browser session, or a runtime from before modes), or `runtime_unavailable` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/desktop" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

## Create a desktop ticket

`POST /v1/machines/{machine_id}/desktop/tickets`

The ticket is valid once, for 30 seconds, for this machine and the session that minted it. API keys open the desktop 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}/desktop`, valid 30 s, redeemable only by the minting session | [`DesktopTicketDto`](/docs/api/schemas#desktopticketdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Viewer or Billing (`forbidden`), a bad CSRF token, or an API key (`session_required`: keys open desktops directly) | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `machine_not_running`, `machine_not_created` (its create is pending or failed), or `machine_deleted` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `429` | `rate_limited`, with `Retry-After` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | `desktop_unavailable` (desktops are not configured) | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

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

```json title="Response 201"
{
  "expires_at": "string",
  "ticket": "string"
}
```

---

<!-- Source: /docs/api/agents.md -->

# Agents API

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

- [Prompt an agent](#prompt-an-agent): `POST /v1/machines/{machine_id}/agents/prompt`
- [Follow an agent's events](#follow-an-agents-events): `GET /v1/machines/{machine_id}/agents/events`
- [List agent conversations](#list-agent-conversations): `GET /v1/machines/{machine_id}/agents/conversations`
- [Steer a running agent](#steer-a-running-agent): `POST /v1/machines/{machine_id}/agents/steer`
- [Interrupt a running agent](#interrupt-a-running-agent): `POST /v1/machines/{machine_id}/agents/interrupt`
- [List agent models](#list-agent-models): `GET /v1/provider-models`

## Prompt an agent

`POST /v1/machines/{machine_id}/agents/prompt`

Starts a turn of a coding agent in the machine, in a new conversation or one you resume. The agent's provider keys are the machine's environment variables, so a machine created without an environment gives it none. Follow the turn with `GET /v1/machines/{machine_id}/agents/events`.

- **API key:** `Authorization: Bearer vmy_…` with preset `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.
- **Idempotency:** send a unique `Idempotency-Key`; replaying the same key and body returns the same operation.

**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. |

**Request body** (`application/json`, [`AgentPromptRequest`](/docs/api/schemas#agentpromptrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `attachments` | [`AgentAttachmentRequest[]`](/docs/api/schemas#agentattachmentrequest) | No | At most 16 files, 16 MiB together, written to the machine for the agent to read. |
| `conversation_id` | `string (uuid) \| null` | No | Continue this conversation; omit to start a new one. |
| `model` | `string \| null` | No | A model the agent accepts (see `GET /v1/provider-models`); the agent's default when omitted. Pi takes `provider/model`. |
| `provider` | [`null \| AgentProviderDto`](/docs/api/schemas#agentproviderdto) | No | Required for a new conversation; a conversation keeps its provider. |
| `reasoning_effort` | [`null \| ReasoningEffortDto`](/docs/api/schemas#reasoningeffortdto) | No |  |
| `text` | `string` | No | The prompt, at most 256 KiB. A prompt needs text or an attachment. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `202` | The turn runs in the machine; follow `events_url` | [`AgentTurnDto`](/docs/api/schemas#agentturndto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | `forbidden`, `insufficient_scope`, or `organization_suspended` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Unknown machine, or `conversation_not_found` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `agent_turn_running`, `provider_mismatch`, `idempotency_conflict`, `machine_not_running`, `machine_not_created`, or `machine_deleted` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `413` | The request body is too large (`body_too_large`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `502` | `guest_action_failed`: the machine could not start the turn (the turn is failed) | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | `agents_unavailable`, or `runtime_unavailable` (retry with the same key) | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/agents/prompt" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```json title="Response 202"
{
  "conversation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "created_at": "2026-10-12T05:51:01Z",
  "error_code": "string",
  "events_url": "string",
  "exit_code": 0,
  "finished_at": "2026-10-12T05:51:01Z",
  "interrupt_requested": false,
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "model": "string",
  "provider": "claude",
  "reasoning_effort": "minimal",
  "resume": false,
  "started_at": "2026-10-12T05:51:01Z",
  "status": "starting",
  "turn_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## Follow an agent's events

`GET /v1/machines/{machine_id}/agents/events`

JSON by `cursor` (with `wait_seconds` to long-poll), or server-sent events with `Accept: text/event-stream`. Each SSE event's `id` is the cursor after it: reconnect with `Last-Event-ID` to resume without repeats. The stream ends with an `idle` event once no turn is running.

- **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 |  |
| `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. |
| `Last-Event-ID` | header | `integer \| null` | No | SSE: resume after this event's cursor (overrides `cursor`) |
| `conversation_id` | query | `string (uuid)` | Yes |  |
| `cursor` | query | `integer` | No | The `cursor` of an earlier answer (or an SSE event's `id`); events after it are returned. Default 0, the conversation's first event. |
| `wait_seconds` | query | `integer` | No | JSON only: wait up to this many seconds (0-30, default 0) for an event when none is ready. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | With `Accept: text/event-stream`: an SSE stream of `agent` events (`id` is the cursor after the event), ending with an `idle` event once no turn is running and every event was sent. Otherwise JSON: the events after `cursor`, waiting up to `wait_seconds` for one. | [`AgentEventsDto`](/docs/api/schemas#agenteventsdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Unknown machine, or `conversation_not_found` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `machine_not_running`, `machine_not_created`, or `machine_deleted` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `502` | The machine's host or a provider failed to answer. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | Not available on this server. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/agents/events?conversation_id=conversation_id" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "active": false,
  "conversation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "cursor": 0,
  "events": [
    {
      "code": "string",
      "id": "string",
      "input": "string",
      "input_id": "string",
      "is_error": false,
      "kind": "prompt",
      "message": "string",
      "model": "string",
      "name": "dev",
      "outcome": "completed",
      "output": "string",
      "provider": "claude",
      "reasoning_effort": "minimal",
      "restarted": false,
      "result": "string",
      "resumed": false,
      "seq": 0,
      "session_id": "string",
      "text": "string",
      "time_ms": 0,
      "turn_id": "string",
      "type": "turn_started",
      "usage": {
        "cached_input_tokens": 0,
        "cost_micro_usd": 0,
        "input_tokens": 0,
        "output_tokens": 0
      }
    }
  ],
  "latest_turn": {
    "conversation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "created_at": "2026-10-12T05:51:01Z",
    "error_code": "string",
    "events_url": "string",
    "exit_code": 0,
    "finished_at": "2026-10-12T05:51:01Z",
    "interrupt_requested": false,
    "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "model": "string",
    "provider": "claude",
    "reasoning_effort": "minimal",
    "resume": false,
    "started_at": "2026-10-12T05:51:01Z",
    "status": "starting",
    "turn_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
  }
}
```

## List agent conversations

`GET /v1/machines/{machine_id}/agents/conversations`

- **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 |  |
| `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. |
| `limit` | query | `integer` | No | 1-100 (default 50). |
| `cursor` | query | `string (uuid)` | No | The `next_cursor` of the previous page. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`AgentConversationListDto`](/docs/api/schemas#agentconversationlistdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/agents/conversations" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "conversations": [
    {
      "created_at": "2026-10-12T05:51:01Z",
      "events_url": "string",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "latest_turn": {
        "conversation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "created_at": "2026-10-12T05:51:01Z",
        "error_code": "string",
        "events_url": "string",
        "exit_code": 0,
        "finished_at": "2026-10-12T05:51:01Z",
        "interrupt_requested": false,
        "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "model": "string",
        "provider": "claude",
        "reasoning_effort": "minimal",
        "resume": false,
        "started_at": "2026-10-12T05:51:01Z",
        "status": "starting",
        "turn_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
      },
      "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "provider": "claude",
      "status": "idle",
      "turn_count": 0,
      "updated_at": "2026-10-12T05:51:01Z"
    }
  ],
  "next_cursor": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## Steer a running agent

`POST /v1/machines/{machine_id}/agents/steer`

Adds instructions to the running turn. The agent confirms when it takes them with an `input_accepted` event carrying the answer's `input_id`.

- **API key:** `Authorization: Bearer vmy_…` with preset `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.
- **Idempotency:** send a unique `Idempotency-Key`; replaying the same key and body returns the same operation.

**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. |

**Request body** (`application/json`, [`AgentSteerRequest`](/docs/api/schemas#agentsteerrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `conversation_id` | `string (uuid)` | Yes |  |
| `text` | `string` | Yes | More instructions for the running turn, at most 256 KiB. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `202` | Written to the running turn's inbox; the agent confirms it with an `input_accepted` event | [`AgentInputAccepted`](/docs/api/schemas#agentinputaccepted) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Unknown machine, or `conversation_not_found` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `no_active_turn`, `idempotency_conflict`, or the machine is not running | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `502` | The machine's host or a provider failed to answer. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | Not available on this server. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/agents/steer" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "conversation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "text": "string"
}'
```

```json title="Response 202"
{
  "conversation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "input_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "kind": "steer",
  "stopped": false,
  "turn_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## Interrupt a running agent

`POST /v1/machines/{machine_id}/agents/interrupt`

Asks the running turn to stop; with `force` the agent is killed at once. The turn ends with outcome `interrupted`.

- **API key:** `Authorization: Bearer vmy_…` with preset `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.
- **Idempotency:** send a unique `Idempotency-Key`; replaying the same key and body returns the same operation.

**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. |

**Request body** (`application/json`, [`AgentInterruptRequest`](/docs/api/schemas#agentinterruptrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `conversation_id` | `string (uuid)` | Yes |  |
| `force` | `boolean` | No | Also kill the runner and the agent at once instead of letting the agent stop on its own (it gets 10 s, then SIGTERM, then SIGKILL). |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `202` | The running turn is asked to stop (or, with `force`, killed); it ends with outcome `interrupted` | [`AgentInputAccepted`](/docs/api/schemas#agentinputaccepted) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Unknown machine, or `conversation_not_found` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `no_active_turn`, `idempotency_conflict`, or the machine is not running | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `502` | The machine's host or a provider failed to answer. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | Not available on this server. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/agents/interrupt" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "conversation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}'
```

```json title="Response 202"
{
  "conversation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "input_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "kind": "steer",
  "stopped": false,
  "turn_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## List agent models

`GET /v1/provider-models`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `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 |
| --- | --- | --- |
| `200` | — | [`ProviderModelsDto`](/docs/api/schemas#providermodelsdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/provider-models" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "providers": [
    {
      "models": [
        {
          "attachments": false,
          "context_tokens": 0,
          "id": "string",
          "name": "dev",
          "provider": "anthropic",
          "reasoning": false,
          "release_date": "string"
        }
      ],
      "provider": "claude",
      "reasoning_efforts": [
        "minimal"
      ]
    }
  ],
  "source": "live"
}
```

---

<!-- Source: /docs/api/command-history.md -->

# Command history API

> Search a machine's past commands, read one entry, and page through its stored stdout and stderr.

- [List command history](#list-command-history): `GET /v1/machines/{machine_id}/commands/history`
- [Get a history entry](#get-a-history-entry): `GET /v1/machines/{machine_id}/commands/history/{operation_id}`
- [Read stored command output](#read-stored-command-output): `GET /v1/machines/{machine_id}/commands/history/{operation_id}/logs`

## List command history

`GET /v1/machines/{machine_id}/commands/history`

- **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 |  |
| `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. |
| `q` | query | `string` | No | Case-insensitive text contained in the command, at most 128 characters. |
| `mode` | query | `string` | No | `all` (default), `sync`, or `detached`. |
| `limit` | query | `integer` | No | Page size, 1-100 (default 50). |
| `cursor` | query | `string` | No | `next_cursor` from the previous page. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`CommandHistoryPage`](/docs/api/schemas#commandhistorypage) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/commands/history" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "items": [
    {
      "argv": [
        "string"
      ],
      "cancelled": false,
      "command": "npm test",
      "created_at": "string",
      "duration_ms": 0,
      "error_code": "string",
      "exit_code": 0,
      "finished_at": "string",
      "logs_url": "/v1/machines/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f/commands/history/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f/logs",
      "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "mode": "sync",
      "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "output_purged": false,
      "started_at": "string",
      "status": "pending",
      "stderr_bytes": 0,
      "stdout_bytes": 0,
      "timed_out": false,
      "truncated": false
    }
  ],
  "next_cursor": "string"
}
```

## Get a history entry

`GET /v1/machines/{machine_id}/commands/history/{operation_id}`

- **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 |  |
| `operation_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 |
| --- | --- | --- |
| `200` | — | [`CommandHistoryEntryDto`](/docs/api/schemas#commandhistoryentrydto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/commands/history/$OPERATION_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "argv": [
    "string"
  ],
  "cancelled": false,
  "command": "npm test",
  "created_at": "string",
  "duration_ms": 0,
  "error_code": "string",
  "exit_code": 0,
  "finished_at": "string",
  "logs_url": "/v1/machines/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f/commands/history/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f/logs",
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "mode": "sync",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "output_purged": false,
  "started_at": "string",
  "status": "pending",
  "stderr_bytes": 0,
  "stdout_bytes": 0,
  "timed_out": false,
  "truncated": false
}
```

## Read stored command output

`GET /v1/machines/{machine_id}/commands/history/{operation_id}/logs`

While a streamed command runs, the relayed output is served and `complete` is `false`. After the retention period the output is removed and the answer is `410 output_expired`.

- **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 |  |
| `operation_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. |
| `stream` | query | `string` | No | `stdout` (default) or `stderr`. |
| `offset` | query | `integer` | No | Byte offset into the stream (default 0). |
| `limit` | query | `integer` | No | Bytes to return, 1 to 1048576 (default 65536). |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`CommandLogChunkDto`](/docs/api/schemas#commandlogchunkdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `410` | Retention removed this command's output | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/commands/history/$OPERATION_ID/logs" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "complete": false,
  "data_base64": "UEFTUyAgc3JjL2FwcC50ZXN0LnRzCg==",
  "next_offset": 0,
  "offset": 0,
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "size": 0,
  "stream": "stdout",
  "truncated": false
}
```

---

<!-- Source: /docs/api/snapshots.md -->

# Snapshots and templates API

> Push a stopped machine, save it as a named template, and copy a machine with fork or restore.

- [Push a snapshot](#push-a-snapshot): `POST /v1/machines/{machine_id}/snapshots`
- [List a machine's snapshots](#list-a-machines-snapshots): `GET /v1/machines/{machine_id}/snapshots`
- [Get a machine's latest snapshot](#get-a-machines-latest-snapshot): `GET /v1/machines/{machine_id}/snapshots/latest`
- [Get a snapshot](#get-a-snapshot): `GET /v1/snapshots/{snapshot_id}`
- [Delete a snapshot](#delete-a-snapshot): `DELETE /v1/snapshots/{snapshot_id}`
- [Delete snapshots](#delete-snapshots): `POST /v1/snapshots/bulk-delete`
- [Delete a machine's snapshots](#delete-a-machines-snapshots): `DELETE /v1/machines/{machine_id}/snapshots`
- [Save a template](#save-a-template): `POST /v1/templates`
- [List templates](#list-templates): `GET /v1/templates`
- [Get a template](#get-a-template): `GET /v1/templates/{template}`
- [Delete a template](#delete-a-template): `DELETE /v1/templates/{template}`
- [Fork a machine](#fork-a-machine): `POST /v1/machines/{machine_id}/fork`
- [Restore a snapshot as a new machine](#restore-a-snapshot-as-a-new-machine): `POST /v1/machines/{machine_id}/restore`

## Push a snapshot

`POST /v1/machines/{machine_id}/snapshots`

- **API key:** `Authorization: Bearer vmy_…` with preset `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.
- **Idempotency:** send a unique `Idempotency-Key`; replaying the same key and body returns the same operation.

**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. |

**Request body** (`application/json`, [`CreateSnapshotRequest`](/docs/api/schemas#createsnapshotrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tier` | [`null \| SnapshotTierDto`](/docs/api/schemas#snapshottierdto) | No | Default `warm`. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `202` | The push is a durable operation; the snapshot is `pending` until it settles | [`SnapshotAccepted`](/docs/api/schemas#snapshotaccepted) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `machine_not_stopped`, `snapshot_limit_reached`, or `idempotency_conflict` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/snapshots" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "tier": "warm"
}'
```

```json title="Response 202"
{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "snapshot_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "snapshot_url": "string",
  "status": "string"
}
```

## List a machine's snapshots

`GET /v1/machines/{machine_id}/snapshots`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `machine_id` | path | `string (uuid)` | Yes |  |
| `limit` | query | `integer` | No | 1-100, default 50. |
| `cursor` | query | `string (uuid)` | No | The last ID of the previous page. |
| `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 |
| --- | --- | --- |
| `200` | — | [`SnapshotPage`](/docs/api/schemas#snapshotpage) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/snapshots" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "items": [
    {
      "completed_at": "2026-10-12T05:51:01Z",
      "created_at": "2026-10-12T05:51:01Z",
      "disk_synced": false,
      "error_code": "string",
      "generation": 0,
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "manifest": "string",
      "name": "dev",
      "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "parent_manifest": "string",
      "size_bytes": 0,
      "source": "api",
      "status": "pending",
      "tier": "warm",
      "uploaded_bytes": 0
    }
  ],
  "next_cursor": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## Get a machine's latest snapshot

`GET /v1/machines/{machine_id}/snapshots/latest`

The newest ready snapshot; pending and failed pushes and templates are skipped. A machine without one answers `404 no_snapshot`.

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**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 |
| --- | --- | --- |
| `200` | The machine's newest ready snapshot; pending and failed pushes and templates are skipped | [`ReadySnapshotDto`](/docs/api/schemas#readysnapshotdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Unknown machine, or `no_snapshot`: the machine has no ready snapshot | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/snapshots/latest" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "completed_at": "2026-10-12T05:51:01Z",
  "created_at": "2026-10-12T05:51:01Z",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "size_bytes": 0,
  "source": "api",
  "tier": "warm"
}
```

## Get a snapshot

`GET /v1/snapshots/{snapshot_id}`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `snapshot_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 |
| --- | --- | --- |
| `200` | — | [`SnapshotDto`](/docs/api/schemas#snapshotdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/snapshots/$SNAPSHOT_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "completed_at": "2026-10-12T05:51:01Z",
  "created_at": "2026-10-12T05:51:01Z",
  "disk_synced": false,
  "error_code": "string",
  "generation": 0,
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "manifest": "string",
  "name": "dev",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "parent_manifest": "string",
  "size_bytes": 0,
  "source": "api",
  "status": "pending",
  "tier": "warm",
  "uploaded_bytes": 0
}
```

## Delete a snapshot

`DELETE /v1/snapshots/{snapshot_id}`

- **API key:** `Authorization: Bearer vmy_…` with preset `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `snapshot_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 |
| --- | --- | --- |
| `204` | Deleted from the product; the runtime's store collects its data | — |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `snapshot_pending`: the push has not settled | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X DELETE "$VMYARD_API_URL/v1/snapshots/$SNAPSHOT_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

## Delete snapshots

`POST /v1/snapshots/bulk-delete`

1-100 IDs. Answers `200` with a result per snapshot (`deleted`, `not_found`, `pending`, or `template`) even when some were kept. See [Delete several snapshots](/docs/guides/snapshots#delete-several-snapshots).

- **API key:** `Authorization: Bearer vmy_…` with preset `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `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. |

**Request body** (`application/json`, [`BulkDeleteSnapshotsRequest`](/docs/api/schemas#bulkdeletesnapshotsrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `snapshot_ids` | `string (uuid)[]` | Yes | 1-100 snapshot IDs; duplicates are reported once. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | Each snapshot's result; templates and pending pushes are kept | [`SnapshotDeleteResults`](/docs/api/schemas#snapshotdeleteresults) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | No IDs, or more than 100 | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/snapshots/bulk-delete" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "snapshot_ids": [
    "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
  ]
}'
```

```json title="Response 200"
{
  "deleted": 0,
  "results": [
    {
      "result": "deleted",
      "snapshot_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
    }
  ]
}
```

## Delete a machine's snapshots

`DELETE /v1/machines/{machine_id}/snapshots`

Every snapshot of the machine, or one source's with `source` (`automatic` deletes the [automatic snapshots](/docs/guides/automatic-snapshots)). Pending pushes and templates are kept and reported.

- **API key:** `Authorization: Bearer vmy_…` with preset `use_existing`, `create_and_use`, `full_access`.
- **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 |  |
| `source` | query | [`SnapshotSourceDto`](/docs/api/schemas#snapshotsourcedto) | No | Only this source's snapshots (`automatic` deletes the automatic ones); every snapshot of the machine by default. |
| `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 |
| --- | --- | --- |
| `200` | Each of the machine's snapshots' result, oldest first; templates (without `source`) and pending pushes are kept | [`SnapshotDeleteResults`](/docs/api/schemas#snapshotdeleteresults) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X DELETE "$VMYARD_API_URL/v1/machines/$MACHINE_ID/snapshots" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "deleted": 0,
  "results": [
    {
      "result": "deleted",
      "snapshot_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
    }
  ]
}
```

## Save a template

`POST /v1/templates`

- **API key:** `Authorization: Bearer vmy_…` with preset `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.
- **Idempotency:** send a unique `Idempotency-Key`; replaying the same key and body returns the same operation.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `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. |

**Request body** (`application/json`, [`CreateTemplateRequest`](/docs/api/schemas#createtemplaterequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `machine_id` | `string (uuid)` | Yes | A stopped machine to save as the template. |
| `name` | `string` | Yes | `[a-z0-9]` then up to 63 of `[a-z0-9._-]`; unique among the organization's templates. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `202` | A warm push saved as the template; `pending` until it settles | [`SnapshotAccepted`](/docs/api/schemas#snapshotaccepted) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `machine_not_stopped`, `template_name_taken`, `template_limit_reached`, or `idempotency_conflict` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/templates" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "name": "dev"
}'
```

```json title="Response 202"
{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "snapshot_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "snapshot_url": "string",
  "status": "string"
}
```

## List templates

`GET /v1/templates`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | `integer` | No | 1-100, default 50. |
| `cursor` | query | `string (uuid)` | No | The last ID of the previous page. |
| `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 |
| --- | --- | --- |
| `200` | — | [`SnapshotPage`](/docs/api/schemas#snapshotpage) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/templates" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "items": [
    {
      "completed_at": "2026-10-12T05:51:01Z",
      "created_at": "2026-10-12T05:51:01Z",
      "disk_synced": false,
      "error_code": "string",
      "generation": 0,
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "manifest": "string",
      "name": "dev",
      "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "parent_manifest": "string",
      "size_bytes": 0,
      "source": "api",
      "status": "pending",
      "tier": "warm",
      "uploaded_bytes": 0
    }
  ],
  "next_cursor": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## Get a template

`GET /v1/templates/{template}`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `template` | path | `string` | Yes | Template name or ID |
| `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 |
| --- | --- | --- |
| `200` | — | [`SnapshotDto`](/docs/api/schemas#snapshotdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/templates/$TEMPLATE" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "completed_at": "2026-10-12T05:51:01Z",
  "created_at": "2026-10-12T05:51:01Z",
  "disk_synced": false,
  "error_code": "string",
  "generation": 0,
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "manifest": "string",
  "name": "dev",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "parent_manifest": "string",
  "size_bytes": 0,
  "source": "api",
  "status": "pending",
  "tier": "warm",
  "uploaded_bytes": 0
}
```

## Delete a template

`DELETE /v1/templates/{template}`

- **API key:** `Authorization: Bearer vmy_…` with preset `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `template` | path | `string` | Yes | Template name or ID |
| `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 |
| --- | --- | --- |
| `204` | Deleted; the name is free again | — |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `snapshot_pending`: the save has not settled | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X DELETE "$VMYARD_API_URL/v1/templates/$TEMPLATE" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

## Fork a machine

`POST /v1/machines/{machine_id}/fork`

Billing admission can refuse it: `402 billing_required` or `spend_cap_reached`, `403 trial_machine_class_not_allowed`, `409 plan_not_priced`, or `429 limit_reached`. See [Usage, billing, and limits](/docs/guides/billing#limits).

- **API key:** `Authorization: Bearer vmy_…` with preset `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.
- **Idempotency:** send a unique `Idempotency-Key`; replaying the same key and body returns the same operation.

**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. |

**Request body** (`application/json`, [`ForkMachineRequest`](/docs/api/schemas#forkmachinerequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `keep_ssh_keys` | `boolean` | No | Keep the login user's SSH `authorized_keys` in the copy (default `false`). The SSH gateway port is never inherited. |
| `live` | `boolean \| null` | No | Run the copy at once with the source's processes (default `true`); `false` creates it stopped. |
| `name` | `string \| null` | No | The copy's display name (default: the tenant alias it shares with the source). |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `202` | The copy is created by the operation; `machine_id` names the new machine | [`OperationAccepted`](/docs/api/schemas#operationaccepted) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `402` | — | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `machine_not_running`, `idempotency_conflict`, or a billing limit | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `429` | Too many requests; wait for `Retry-After`. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/fork" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```json title="Response 202"
{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "requested_action": "create",
  "status": "pending"
}
```

## Restore a snapshot as a new machine

`POST /v1/machines/{machine_id}/restore`

Billing admission can refuse it: `402 billing_required` or `spend_cap_reached`, `403 trial_machine_class_not_allowed`, `409 plan_not_priced`, or `429 limit_reached`. See [Usage, billing, and limits](/docs/guides/billing#limits).

- **API key:** `Authorization: Bearer vmy_…` with preset `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.
- **Idempotency:** send a unique `Idempotency-Key`; replaying the same key and body returns the same operation.

**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. |

**Request body** (`application/json`, [`RestoreMachineRequest`](/docs/api/schemas#restoremachinerequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `snapshot_id` | `string (uuid)` | Yes | A ready snapshot of this machine. |
| `keep_ssh_keys` | `boolean` | No | Keep the login user's SSH `authorized_keys` (default `false`). |
| `name` | `string \| null` | No | The new machine's display name. |
| `wake` | `boolean \| null` | No | Wake the new machine at once (default `true`); `false` creates it stopped. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `202` | A new machine is restored from the snapshot; `machine_id` names it | [`OperationAccepted`](/docs/api/schemas#operationaccepted) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `402` | — | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `snapshot_not_ready`, `idempotency_conflict`, or a billing limit | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `429` | Too many requests; wait for `Retry-After`. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/restore" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "snapshot_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}'
```

```json title="Response 202"
{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "requested_action": "create",
  "status": "pending"
}
```

---

<!-- Source: /docs/api/files.md -->

# Files API

> Write and read files inside a machine's /work directory.

- [Read a file](#read-a-file): `GET /v1/machines/{machine_id}/files`
- [Write a file](#write-a-file): `PUT /v1/machines/{machine_id}/files`

## Read a file

`GET /v1/machines/{machine_id}/files`

- **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 |  |
| `path` | query | `string` | Yes | `relative/path` or `/work/relative/path`; no `.`/`..` components. |
| `encoding` | query | [`FileEncodingDto`](/docs/api/schemas#fileencodingdto) | No | `text` (default) or `base64`. |
| `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 |
| --- | --- | --- |
| `200` | — | [`FileContentDto`](/docs/api/schemas#filecontentdto) |
| `202` | The read is still queued; its operation carries `file_ranges` when done | [`OperationAccepted`](/docs/api/schemas#operationaccepted) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Unknown machine, or `file_not_found` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `413` | `file_too_large`: the file exceeds 32 MiB | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid path, or `file_not_text` for non-UTF-8 content read as text | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `502` | The machine's host or a provider failed to answer. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/files?path=notes/todo.txt" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "content": "string",
  "encoding": "text",
  "path": "notes/todo.txt",
  "size": 0
}
```

## Write a file

`PUT /v1/machines/{machine_id}/files`

- **API key:** `Authorization: Bearer vmy_…` with preset `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.
- **Idempotency:** send a unique `Idempotency-Key`; replaying the same key and body returns the same operation.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `machine_id` | path | `string (uuid)` | Yes |  |
| `path` | query | `string` | Yes | `relative/path` or `/work/relative/path`; no `.`/`..` components. |
| `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. |

**Request body** (`application/json`, [`WriteFileRequest`](/docs/api/schemas#writefilerequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `content` | `string` | Yes |  |
| `encoding` | [`FileEncodingDto`](/docs/api/schemas#fileencodingdto) | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `202` | The file is replaced in runtime-sized chunks by the operation | [`OperationAccepted`](/docs/api/schemas#operationaccepted) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | Conflicts with the current state, such as a reused idempotency key with another body (`idempotency_conflict`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `413` | `file_too_large`: the decoded file exceeds 32 MiB | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X PUT "$VMYARD_API_URL/v1/machines/$MACHINE_ID/files?path=notes/todo.txt" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "encoding": "text",
  "content": "hello from VMYard\n"
}'
```

```json title="Response 202"
{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "requested_action": "file_write",
  "status": "pending"
}
```

---

<!-- Source: /docs/api/file-browser.md -->

# File browser API

> List a running machine's folders under /work, /root, or /home as a live tree, and download a folder as a .tar.gz archive.

- [List a folder tree](#list-a-folder-tree): `GET /v1/machines/{machine_id}/files/tree`
- [Download a folder](#download-a-folder): `GET /v1/machines/{machine_id}/files/archive`

## List a folder tree

`GET /v1/machines/{machine_id}/files/tree`

The machine must be running. `path` is `/work` (the default), `/root`, or a home under `/home`, or a folder inside one; `depth` is 1 to 4 (default 2). At most 5,000 entries, breadth first; `truncated` says the listing stopped early. See [Files](/docs/guides/files).

- **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 |  |
| `path` | query | `string` | No | Absolute directory: `/work` (default), `/root`, or a home under `/home`, or inside one of them; no `.`/`..` components. |
| `depth` | query | `integer` | No | Levels to list below `path`, 1-4 (default 2). |
| `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 |
| --- | --- | --- |
| `200` | The live tree below `path`, breadth first; at most 5,000 entries | [`FileTreeDto`](/docs/api/schemas#filetreedto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | `forbidden` (Viewer or Billing) or `insufficient_scope` (a `read_only` key) | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Unknown machine, or `path_not_found` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `machine_not_running`, `machine_not_created`, or `machine_deleted` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid `path` or `depth`, `path_not_allowed` (a symlink out of the roots), `not_a_directory`, or `listing_too_large` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `502` | `guest_action_failed` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | `files_unavailable` (not configured) or `runtime_unavailable` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/files/tree" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "entries": [
    {
      "children": [],
      "modified_at": "2026-10-12T05:51:01Z",
      "name": "dev",
      "path": "notes/todo.txt",
      "size_bytes": 0,
      "type": "file"
    }
  ],
  "file_count": 0,
  "path": "notes/todo.txt",
  "total_bytes": 0,
  "truncated": false
}
```

## Download a folder

`GET /v1/machines/{machine_id}/files/archive`

Streams the folder as a `.tar.gz`; folders over 512 MiB answer `413 archive_too_large`. A download that does not end cleanly is incomplete.

- **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 |  |
| `path` | query | `string` | Yes | The directory to download, as for the tree. |
| `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 |
| --- | --- | --- |
| `200` | The folder as a streamed `tar.gz` (`Content-Disposition: attachment`, `<name>.tar.gz`). A failure after the headers aborts the body, so a download that does not end cleanly is incomplete. | `application/gzip` |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | `forbidden` (Viewer or Billing) or `insufficient_scope` (a `read_only` key) | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Unknown machine, or `path_not_found` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `machine_not_running`, `machine_not_created`, or `machine_deleted` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `413` | `archive_too_large`: the folder exceeds 512 MiB | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid `path`, `path_not_allowed`, or `not_a_directory` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `502` | `guest_action_failed` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | `files_unavailable` (not configured) or `runtime_unavailable` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/files/archive?path=notes/todo.txt" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

---

<!-- Source: /docs/api/ports-and-ssh.md -->

# Ports and SSH API

> Expose guest ports as HTTPS URLs, issue access tokens for private ports, and install an SSH key.

- [List exposed ports](#list-exposed-ports): `GET /v1/machines/{machine_id}/ports`
- [Expose a port](#expose-a-port): `POST /v1/machines/{machine_id}/ports`
- [Close a port](#close-a-port): `DELETE /v1/machines/{machine_id}/ports/{port}`
- [Issue a port access token](#issue-a-port-access-token): `POST /v1/machines/{machine_id}/ports/{port}/token`
- [Install an SSH key](#install-an-ssh-key): `PUT /v1/machines/{machine_id}/ssh-key`
- [Remove the SSH key](#remove-the-ssh-key): `DELETE /v1/machines/{machine_id}/ssh-key`

## List exposed ports

`GET /v1/machines/{machine_id}/ports`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**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 |
| --- | --- | --- |
| `200` | — | [`PortListDto`](/docs/api/schemas#portlistdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | `ingress_unavailable`: no edge is configured | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/ports" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "items": [
    {
      "localhost": false,
      "port": 0,
      "public": false,
      "url": "https://hooks.example.com/vmyard"
    }
  ],
  "label": "k7f2mq3x9a1b"
}
```

## Expose a port

`POST /v1/machines/{machine_id}/ports`

- **API key:** `Authorization: Bearer vmy_…` with preset `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.
- **Idempotency:** send a unique `Idempotency-Key`; replaying the same key and body returns the same operation.

**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. |

**Request body** (`application/json`, [`ExposePortRequest`](/docs/api/schemas#exposeportrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `port` | `integer` | Yes | Guest TCP port, 1-65535 except 22 (use the SSH key for SSH) and the desktop's 5907 and 5908 (open the desktop instead). |
| `localhost` | `boolean` | No | Relay the guest's addresses to a service bound to `127.0.0.1`/`[::1]`. |
| `public` | `boolean` | No | Reachable without a token. Private ports (the default) need a token from `POST /v1/machines/{machine_id}/ports/{port}/token`. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `202` | The port is exposed by the operation; the machine must be running | [`OperationAccepted`](/docs/api/schemas#operationaccepted) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `port_limit_reached` (16 ports), or `idempotency_conflict` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | `ingress_unavailable`: no edge is configured | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/ports" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "port": 8080,
  "public": false
}'
```

```json title="Response 202"
{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "requested_action": "port_expose",
  "status": "pending"
}
```

## Close a port

`DELETE /v1/machines/{machine_id}/ports/{port}`

- **API key:** `Authorization: Bearer vmy_…` with preset `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.
- **Idempotency:** send a unique `Idempotency-Key`; replaying the same key and body returns the same operation.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `machine_id` | path | `string (uuid)` | Yes |  |
| `port` | path | `integer` | 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 |
| --- | --- | --- |
| `202` | The port is closed by the operation; it fails if the port is not exposed | [`OperationAccepted`](/docs/api/schemas#operationaccepted) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | Conflicts with the current state, such as a reused idempotency key with another body (`idempotency_conflict`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | `ingress_unavailable`: no edge is configured | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X DELETE "$VMYARD_API_URL/v1/machines/$MACHINE_ID/ports/$PORT" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

```json title="Response 202"
{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "requested_action": "port_unexpose",
  "status": "pending"
}
```

## Issue a port access token

`POST /v1/machines/{machine_id}/ports/{port}/token`

- **API key:** `Authorization: Bearer vmy_…` with preset `use_existing`, `create_and_use`, `full_access`.
- **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 |  |
| `port` | path | `integer` | 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. |

**Request body** (`application/json`, [`PortTokenRequest`](/docs/api/schemas#porttokenrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ttl_seconds` | `integer \| null` | No | Token lifetime, 1-3600 seconds; default 900. 1–3600. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`PortTokenDto`](/docs/api/schemas#porttokendto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Unknown machine, or `port_not_exposed` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `machine_not_running`: the machine has no running or sleeping sandbox to bind the token to | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | `ingress_unavailable`: no edge is configured; `runtime_unavailable`: the fleet could not name the machine's sandbox | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/ports/$PORT/token" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "ttl_seconds": 900
}'
```

```json title="Response 200"
{
  "expires_at": "string",
  "header_token": "string",
  "url": "https://hooks.example.com/vmyard",
  "url_with_token": "string"
}
```

## Install an SSH key

`PUT /v1/machines/{machine_id}/ssh-key`

- **API key:** `Authorization: Bearer vmy_…` with preset `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.
- **Idempotency:** send a unique `Idempotency-Key`; replaying the same key and body returns the same operation.

**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. |

**Request body** (`application/json`, [`SetSshKeyRequest`](/docs/api/schemas#setsshkeyrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `public_key` | `string` | Yes | One OpenSSH public key line: `ssh-ed25519`, `ecdsa-sha2-nistp256/384/521`, or `ssh-rsa` of at least 3072 bits, with an optional comment, without a trailing newline. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `202` | The key is installed and an SSH port allocated by the operation; the machine must be running | [`OperationAccepted`](/docs/api/schemas#operationaccepted) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | Conflicts with the current state, such as a reused idempotency key with another body (`idempotency_conflict`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | `ingress_unavailable`: no edge is configured | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X PUT "$VMYARD_API_URL/v1/machines/$MACHINE_ID/ssh-key" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGq8n3nXxk0x3Sx3kq9dTq0bS4Cq3k0y8Gx4h0b7Y2pd you@laptop"
}'
```

```json title="Response 202"
{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "requested_action": "ssh_key_set",
  "status": "pending"
}
```

## Remove the SSH key

`DELETE /v1/machines/{machine_id}/ssh-key`

- **API key:** `Authorization: Bearer vmy_…` with preset `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.
- **Idempotency:** send a unique `Idempotency-Key`; replaying the same key and body returns the same operation.

**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 |
| --- | --- | --- |
| `202` | The key is removed and the SSH port released by the operation; the machine must be running | [`OperationAccepted`](/docs/api/schemas#operationaccepted) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | Conflicts with the current state, such as a reused idempotency key with another body (`idempotency_conflict`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | `ingress_unavailable`: no edge is configured | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X DELETE "$VMYARD_API_URL/v1/machines/$MACHINE_ID/ssh-key" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

```json title="Response 202"
{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "requested_action": "ssh_key_revoke",
  "status": "pending"
}
```

---

<!-- Source: /docs/api/environments.md -->

# Environments API

> Named, versioned sets of environment variables and secret files that VMYard applies to machines.

- [List environments](#list-environments): `GET /v1/environments`
- [Create an environment](#create-an-environment): `POST /v1/environments`
- [Get an environment](#get-an-environment): `GET /v1/environments/{environment_id}`
- [Change an environment](#change-an-environment): `PATCH /v1/environments/{environment_id}`
- [Delete an environment](#delete-an-environment): `DELETE /v1/environments/{environment_id}`
- [Set a variable](#set-a-variable): `PUT /v1/environments/{environment_id}/vars/{key}`
- [Remove a variable](#remove-a-variable): `DELETE /v1/environments/{environment_id}/vars/{key}`
- [Set a secret file](#set-a-secret-file): `PUT /v1/environments/{environment_id}/files`
- [Remove a secret file](#remove-a-secret-file): `DELETE /v1/environments/{environment_id}/files`
- [List versions](#list-versions): `GET /v1/environments/{environment_id}/versions`
- [Reveal values](#reveal-values): `POST /v1/environments/{environment_id}/reveal`
- [Upgrade machines](#upgrade-machines): `POST /v1/environments/{environment_id}/upgrade`

## List environments

`GET /v1/environments`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

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

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`EnvironmentList`](/docs/api/schemas#environmentlist) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/environments" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "items": [
    {
      "created_at": "string",
      "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "current_version": {
        "change": {},
        "created_at": "string",
        "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "files": [
          {
            "path": "notes/todo.txt",
            "size": 0
          }
        ],
        "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "vars": [
          "string"
        ],
        "version": 0
      },
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "is_default": false,
      "name": "staging",
      "safe_for_third_parties": false,
      "updated_at": "string"
    }
  ]
}
```

## Create an environment

`POST /v1/environments`

- **API key:** `Authorization: Bearer vmy_…` with preset `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner or Admin.

**Parameters**

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

**Request body** (`application/json`, [`CreateEnvironmentRequest`](/docs/api/schemas#createenvironmentrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `files` | [`SecretFileInput[]`](/docs/api/schemas#secretfileinput) | No |  |
| `is_default` | `boolean \| null` | No | Defaults to `true` when the organization has no default environment. |
| `name` | `string \| null` | No | Lowercase DNS label, unique in the organization. Defaults to `base`. |
| `safe_for_third_parties` | `boolean` | No |  |
| `vars` | `map of string` | No | Variable names (`^[A-Za-z_][A-Za-z0-9_]{0,127}$`) to values. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `201` | The created environment (not the list) | [`EnvironmentDto`](/docs/api/schemas#environmentdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | A role other than owner/admin, or an API key without full_access | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `environment_name_taken` or `environment_limit_reached` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `413` | The request body is too large (`body_too_large`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | `environments_unavailable`: no encryption keys configured | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/environments" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "staging",
  "vars": {
    "DATABASE_URL": "postgres://app@db.internal/app",
    "LOG_LEVEL": "info"
  },
  "files": [
    {
      "path": "secrets/service-account.json",
      "contents": "{\"type\": \"service_account\"}"
    }
  ]
}'
```

```json title="Response 201"
{
  "created_at": "string",
  "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "current_version": {
    "change": {},
    "created_at": "string",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "files": [
      {
        "path": "notes/todo.txt",
        "size": 0
      }
    ],
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "vars": [
      "string"
    ],
    "version": 0
  },
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "is_default": false,
  "name": "staging",
  "safe_for_third_parties": false,
  "updated_at": "string"
}
```

## Get an environment

`GET /v1/environments/{environment_id}`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `environment_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 |
| --- | --- | --- |
| `200` | — | [`EnvironmentDto`](/docs/api/schemas#environmentdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/environments/$ENVIRONMENT_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "created_at": "string",
  "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "current_version": {
    "change": {},
    "created_at": "string",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "files": [
      {
        "path": "notes/todo.txt",
        "size": 0
      }
    ],
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "vars": [
      "string"
    ],
    "version": 0
  },
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "is_default": false,
  "name": "staging",
  "safe_for_third_parties": false,
  "updated_at": "string"
}
```

## Change an environment

`PATCH /v1/environments/{environment_id}`

- **API key:** `Authorization: Bearer vmy_…` with preset `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner or Admin.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `environment_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. |

**Request body** (`application/json`, [`UpdateEnvironmentRequest`](/docs/api/schemas#updateenvironmentrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `is_default` | `boolean \| null` | No | `true` makes this the default; `false` leaves the organization without one. |
| `name` | `string \| null` | No |  |
| `safe_for_third_parties` | `boolean \| null` | No |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | Metadata only; no new version | [`EnvironmentDto`](/docs/api/schemas#environmentdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | Conflicts with the current state, such as a reused idempotency key with another body (`idempotency_conflict`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X PATCH "$VMYARD_API_URL/v1/environments/$ENVIRONMENT_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "is_default": true
}'
```

```json title="Response 200"
{
  "created_at": "string",
  "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "current_version": {
    "change": {},
    "created_at": "string",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "files": [
      {
        "path": "notes/todo.txt",
        "size": 0
      }
    ],
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "vars": [
      "string"
    ],
    "version": 0
  },
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "is_default": false,
  "name": "staging",
  "safe_for_third_parties": false,
  "updated_at": "string"
}
```

## Delete an environment

`DELETE /v1/environments/{environment_id}`

- **API key:** `Authorization: Bearer vmy_…` with preset `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner or Admin.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `environment_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 |
| --- | --- | --- |
| `204` | Deleted; machines keep the versions they have | — |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X DELETE "$VMYARD_API_URL/v1/environments/$ENVIRONMENT_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

## Set a variable

`PUT /v1/environments/{environment_id}/vars/{key}`

- **API key:** `Authorization: Bearer vmy_…` with preset `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner or Admin.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `environment_id` | path | `string (uuid)` | Yes |  |
| `key` | path | `string` | 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. |

**Request body** (`application/json`, [`SetVariableRequest`](/docs/api/schemas#setvariablerequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `string` | Yes | At most 32 KiB without NUL. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | A new version was written | [`EnvironmentDto`](/docs/api/schemas#environmentdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | Not available on this server. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X PUT "$VMYARD_API_URL/v1/environments/$ENVIRONMENT_ID/vars/$KEY" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "value": "info"
}'
```

```json title="Response 200"
{
  "created_at": "string",
  "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "current_version": {
    "change": {},
    "created_at": "string",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "files": [
      {
        "path": "notes/todo.txt",
        "size": 0
      }
    ],
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "vars": [
      "string"
    ],
    "version": 0
  },
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "is_default": false,
  "name": "staging",
  "safe_for_third_parties": false,
  "updated_at": "string"
}
```

## Remove a variable

`DELETE /v1/environments/{environment_id}/vars/{key}`

- **API key:** `Authorization: Bearer vmy_…` with preset `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner or Admin.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `environment_id` | path | `string (uuid)` | Yes |  |
| `key` | path | `string` | 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 |
| --- | --- | --- |
| `200` | A new version was written | [`EnvironmentDto`](/docs/api/schemas#environmentdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Unknown environment or `variable_not_found` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | Not available on this server. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X DELETE "$VMYARD_API_URL/v1/environments/$ENVIRONMENT_ID/vars/$KEY" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "created_at": "string",
  "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "current_version": {
    "change": {},
    "created_at": "string",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "files": [
      {
        "path": "notes/todo.txt",
        "size": 0
      }
    ],
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "vars": [
      "string"
    ],
    "version": 0
  },
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "is_default": false,
  "name": "staging",
  "safe_for_third_parties": false,
  "updated_at": "string"
}
```

## Set a secret file

`PUT /v1/environments/{environment_id}/files`

- **API key:** `Authorization: Bearer vmy_…` with preset `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner or Admin.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `environment_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. |

**Request body** (`application/json`, [`SecretFileInput`](/docs/api/schemas#secretfileinput))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `contents` | `string` | Yes |  |
| `path` | `string` | Yes | Relative to `/work`: no leading `/`, `~`, `.`, `..`, or empty components, and not under `.vmyard`. |
| `encoding` | [`FileEncodingDto`](/docs/api/schemas#fileencodingdto) | No |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | A new version was written | [`EnvironmentDto`](/docs/api/schemas#environmentdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `413` | The request body is too large (`body_too_large`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | Not available on this server. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X PUT "$VMYARD_API_URL/v1/environments/$ENVIRONMENT_ID/files" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "path": "secrets/token.txt",
  "contents": "s3cr3t\n"
}'
```

```json title="Response 200"
{
  "created_at": "string",
  "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "current_version": {
    "change": {},
    "created_at": "string",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "files": [
      {
        "path": "notes/todo.txt",
        "size": 0
      }
    ],
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "vars": [
      "string"
    ],
    "version": 0
  },
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "is_default": false,
  "name": "staging",
  "safe_for_third_parties": false,
  "updated_at": "string"
}
```

## Remove a secret file

`DELETE /v1/environments/{environment_id}/files`

- **API key:** `Authorization: Bearer vmy_…` with preset `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner or Admin.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `environment_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. |

**Request body** (`application/json`, [`RemoveFileRequest`](/docs/api/schemas#removefilerequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `path` | `string` | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | A new version was written | [`EnvironmentDto`](/docs/api/schemas#environmentdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Unknown environment or `file_not_found` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | Not available on this server. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X DELETE "$VMYARD_API_URL/v1/environments/$ENVIRONMENT_ID/files" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "path": "secrets/token.txt"
}'
```

```json title="Response 200"
{
  "created_at": "string",
  "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "current_version": {
    "change": {},
    "created_at": "string",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "files": [
      {
        "path": "notes/todo.txt",
        "size": 0
      }
    ],
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "vars": [
      "string"
    ],
    "version": 0
  },
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "is_default": false,
  "name": "staging",
  "safe_for_third_parties": false,
  "updated_at": "string"
}
```

## List versions

`GET /v1/environments/{environment_id}/versions`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `environment_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 |
| --- | --- | --- |
| `200` | — | [`EnvironmentVersionList`](/docs/api/schemas#environmentversionlist) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/environments/$ENVIRONMENT_ID/versions" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "items": [
    {
      "change": {},
      "created_at": "string",
      "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "files": [
        {
          "path": "notes/todo.txt",
          "size": 0
        }
      ],
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "vars": [
        "string"
      ],
      "version": 0
    }
  ]
}
```

## Reveal values

`POST /v1/environments/{environment_id}/reveal`

- **API key:** `Authorization: Bearer vmy_…` with preset `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner or Admin.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `environment_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. |

**Request body** (`application/json`, [`RevealRequest`](/docs/api/schemas#revealrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version_id` | `string (uuid) \| null` | No | A version of this environment; omitted reveals the current version. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | Values and file contents; audited as `environment.revealed` | [`RevealedEnvironmentDto`](/docs/api/schemas#revealedenvironmentdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | A role other than owner/admin, or an API key without full_access | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | Not available on this server. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/environments/$ENVIRONMENT_ID/reveal" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```json title="Response 200"
{
  "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "files": [
    {
      "contents": "string",
      "encoding": "text",
      "path": "notes/todo.txt"
    }
  ],
  "vars": {},
  "version": {
    "change": {},
    "created_at": "string",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "files": [
      {
        "path": "notes/todo.txt",
        "size": 0
      }
    ],
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "vars": [
      "string"
    ],
    "version": 0
  }
}
```

## Upgrade machines

`POST /v1/environments/{environment_id}/upgrade`

- **API key:** `Authorization: Bearer vmy_…` with preset `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner, Admin, or Operator.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `environment_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. |

**Request body** (`application/json`, [`UpgradeEnvironmentRequest`](/docs/api/schemas#upgradeenvironmentrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `machine_ids` | `string (uuid)[] \| null` | No | Machines to upgrade; omitted upgrades every running machine created with this environment. At most 100. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `202` | One apply operation per upgraded machine; repeating the request replays them | [`UpgradeEnvironmentResponse`](/docs/api/schemas#upgradeenvironmentresponse) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `environment_upgrade_conflict`: a machine changed meanwhile; retry | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | A machine is not one created with this environment | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/environments/$ENVIRONMENT_ID/upgrade" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "machine_ids": [
    "0b6f6c55-2f1d-4f0e-9a51-6f0f4cba7a10"
  ]
}'
```

```json title="Response 202"
{
  "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operations": [
    {
      "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
    }
  ],
  "skipped": [
    {
      "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "reason": "not_running"
    }
  ],
  "version": 0,
  "version_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

---

<!-- Source: /docs/api/catalog.md -->

# Catalog API

> The plans, images, and regions a machine is created from, each selected by ID and exact version.

- [List plans](#list-plans): `GET /v1/plans`
- [List images](#list-images): `GET /v1/images`
- [List regions](#list-regions): `GET /v1/regions`

## List plans

`GET /v1/plans`

Seeded plans report their `size`; pick the one whose `backend` matches the region. See [Sizes and prices](/docs/guides/sizes-and-prices).

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

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

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`PlanPage`](/docs/api/schemas#planpage) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `500` | Internal error (`internal_error`); quote the `correlation_id`. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/plans" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "items": [
    {
      "backend": "mock",
      "cpu": 0,
      "disk_gib": 0,
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "memory_mib": 0,
      "name": "small",
      "network_access": {
        "egress_options": [
          "none"
        ],
        "interactive_access": "managed_terminal",
        "public_ingress": "disabled",
        "ssh_key_selection": "unavailable"
      },
      "price": {
        "currency": "USD",
        "effective_from": "2026-01-01T00:00:00.000000Z",
        "hourly": "0.012500",
        "monthly": "9.125000"
      },
      "size": "string",
      "version": 0
    }
  ],
  "next_cursor": "string"
}
```

## List images

`GET /v1/images`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | `integer` | No |  |
| `cursor` | query | `string` | No |  |
| `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 |
| --- | --- | --- |
| `200` | — | [`ImagePage`](/docs/api/schemas#imagepage) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/images" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "items": [
    {
      "digest": "sha256:3f5a…",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "name": "ubuntu-24.04",
      "version": 0
    }
  ],
  "next_cursor": "string"
}
```

## List regions

`GET /v1/regions`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | `integer` | No |  |
| `cursor` | query | `string` | No |  |
| `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 |
| --- | --- | --- |
| `200` | — | [`RegionPage`](/docs/api/schemas#regionpage) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/regions" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "items": [
    {
      "backend": "mock",
      "capacity_status": "available",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "name": "eu-central",
      "version": 0
    }
  ],
  "next_cursor": "string"
}
```

---

<!-- Source: /docs/api/billing.md -->

# Billing and usage API

> Balances, limits, metered usage, invoice preview, and billing management.

- [Get billing](#get-billing): `GET /v1/billing`
- [Change billing settings](#change-billing-settings): `PATCH /v1/billing`
- [Start a checkout](#start-a-checkout): `POST /v1/billing/checkout`
- [Open the payment portal](#open-the-payment-portal): `POST /v1/billing/portal`
- [Verify a card for the trial](#verify-a-card-for-the-trial): `POST /v1/billing/card-check`
- [Cancel the plan at period end](#cancel-the-plan-at-period-end): `POST /v1/billing/subscription/cancel`
- [Resume a cancelled plan](#resume-a-cancelled-plan): `POST /v1/billing/subscription/resume`
- [End the trial early](#end-the-trial-early): `POST /v1/billing/trial/end`
- [Get automatic refill](#get-automatic-refill): `GET /v1/billing/auto-refill`
- [Change automatic refill](#change-automatic-refill): `PUT /v1/billing/auto-refill`
- [Preview the invoice](#preview-the-invoice): `GET /v1/billing/invoice-preview`
- [Get limits](#get-limits): `GET /v1/limits`
- [Get organization usage](#get-organization-usage): `GET /v1/usage`
- [Get machine usage](#get-machine-usage): `GET /v1/machines/{machine_id}/usage`
- [Receive a Stripe event](#receive-a-stripe-event): `POST /v1/billing/stripe/webhook`
- [Grant credits or time (operators)](#grant-credits-or-time-operators): `POST /v1/operator/billing/grants`
- [List wallet movements](#list-wallet-movements): `GET /v1/billing/ledger`
- [Grant credits from VMYard (operators)](#grant-credits-from-vmyard-operators): `POST /v1/operator/billing/credits`

## Get billing

`GET /v1/billing`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `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 |
| --- | --- | --- |
| `200` | — | [`BillingDto`](/docs/api/schemas#billingdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/billing" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "balances": {
    "credit_micros": 0,
    "plan_micros": 0,
    "spendable_micros": 0,
    "trial_micros": 0
  },
  "card_check": {
    "required": false,
    "verified_at": "string"
  },
  "credit_spent_this_month_micros": 0,
  "currency": "USD",
  "exhausted_since": "string",
  "limits": {
    "concurrent_machines": {
      "limit": 0,
      "used": 0
    },
    "starts": [
      {
        "limit": 0,
        "used": 0,
        "window": "hour"
      }
    ],
    "status": "trial",
    "tier": "pro"
  },
  "minimum_balance_micros": 0,
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "payment_customer_linked": false,
  "payments_available": false,
  "plan": {
    "active": false,
    "cancel_at_period_end": false,
    "included_micros": 0,
    "included_seconds": 0,
    "period_end": "string",
    "period_start": "string",
    "price_micros": 0,
    "renews": false,
    "tier": "pro"
  },
  "spend_cap_micros": 0,
  "status": "trial",
  "trial": {
    "active": false,
    "concurrent_machines": 0,
    "ended_at": "string",
    "max_hourly_micros": 0,
    "remaining_micros": 0,
    "remaining_seconds": 0,
    "total_micros": 0
  }
}
```

## Change billing settings

`PATCH /v1/billing`

- **API key:** `Authorization: Bearer vmy_…` with preset `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner or Billing.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `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. |

**Request body** (`application/json`, [`UpdateBillingRequest`](/docs/api/schemas#updatebillingrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `minimum_balance_micros` | `integer \| null` | No |  |
| `spend_cap_micros` | `integer \| null` | No | Monthly credit spend cap in micros, or `null` to remove it. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`BillingDto`](/docs/api/schemas#billingdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X PATCH "$VMYARD_API_URL/v1/billing" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "spend_cap_micros": 100000000,
  "minimum_balance_micros": 0
}'
```

```json title="Response 200"
{
  "balances": {
    "credit_micros": 0,
    "plan_micros": 0,
    "spendable_micros": 0,
    "trial_micros": 0
  },
  "card_check": {
    "required": false,
    "verified_at": "string"
  },
  "credit_spent_this_month_micros": 0,
  "currency": "USD",
  "exhausted_since": "string",
  "limits": {
    "concurrent_machines": {
      "limit": 0,
      "used": 0
    },
    "starts": [
      {
        "limit": 0,
        "used": 0,
        "window": "hour"
      }
    ],
    "status": "trial",
    "tier": "pro"
  },
  "minimum_balance_micros": 0,
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "payment_customer_linked": false,
  "payments_available": false,
  "plan": {
    "active": false,
    "cancel_at_period_end": false,
    "included_micros": 0,
    "included_seconds": 0,
    "period_end": "string",
    "period_start": "string",
    "price_micros": 0,
    "renews": false,
    "tier": "pro"
  },
  "spend_cap_micros": 0,
  "status": "trial",
  "trial": {
    "active": false,
    "concurrent_machines": 0,
    "ended_at": "string",
    "max_hourly_micros": 0,
    "remaining_micros": 0,
    "remaining_seconds": 0,
    "total_micros": 0
  }
}
```

## Start a checkout

`POST /v1/billing/checkout`

- **API key:** `Authorization: Bearer vmy_…` with preset `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner or Billing.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `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. |

**Request body** (`application/json`, [`CheckoutRequestDto`](/docs/api/schemas#checkoutrequestdto))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `credit_packs` | `integer \| null` | No | Buy this many $20 credit packs (1-50). |
| `end_trial` | `boolean` | No | With `plan`: forfeit the remaining trial once the plan's first payment is confirmed, so the plan's allowance is used right away. |
| `plan` | `string \| null` | No | Subscribe to `starter`, `pro`, `team`, or `scale`. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `201` | — | [`CheckoutDto`](/docs/api/schemas#checkoutdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `501` | `billing_unavailable`: payments are not configured | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `502` | `payment_provider_error` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/billing/checkout" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "credit_packs": 2
}'
```

```json title="Response 201"
{
  "checkout_url": "string",
  "session_id": "string"
}
```

## Open the payment portal

`POST /v1/billing/portal`

- **API key:** `Authorization: Bearer vmy_…` with preset `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner or Billing.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `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` | — | [`PortalDto`](/docs/api/schemas#portaldto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `billing_customer_missing`: no purchase has linked a payment customer yet | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `501` | `billing_unavailable`: payments are not configured | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `502` | `payment_provider_error` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/billing/portal" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 201"
{
  "url": "https://hooks.example.com/vmyard"
}
```

## Verify a card for the trial

`POST /v1/billing/card-check`

Start a card check: a hosted setup page where a billing manager enters a
card, which the provider verifies (and screens for fraud) without
charging it. The signed `checkout.session.completed` webhook records the
verification; until then a trial cannot start machines when the service
requires a card (`402 card_verification_required`).

Opens the payment provider's page where a card is checked, not charged. When `card_check.required` is `true` on `GET /v1/billing`, a trial can't create, start, or restart machines (`402 card_verification_required`) until the check completes. See [Usage, billing, and limits](/docs/guides/billing#card-check).

- **API key:** `Authorization: Bearer vmy_…` with preset `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner or Billing.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `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` | — | [`CardCheckSessionDto`](/docs/api/schemas#cardchecksessiondto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `501` | `billing_unavailable`: payments are not configured | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `502` | `payment_provider_error` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/billing/card-check" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 201"
{
  "checkout_url": "string",
  "session_id": "string"
}
```

## Cancel the plan at period end

`POST /v1/billing/subscription/cancel`

The plan keeps its allowance until `plan.period_end`, then ends. See [Cancel a plan or end the trial](/docs/guides/plans-and-trial).

- **API key:** `Authorization: Bearer vmy_…` with preset `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner or Billing.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `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 |
| --- | --- | --- |
| `200` | The plan stays active until `plan.period_end`, then ends | [`BillingDto`](/docs/api/schemas#billingdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `subscription_missing`: no renewing subscription is linked | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `501` | `billing_unavailable` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `502` | `payment_provider_error` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/billing/subscription/cancel" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "balances": {
    "credit_micros": 0,
    "plan_micros": 0,
    "spendable_micros": 0,
    "trial_micros": 0
  },
  "card_check": {
    "required": false,
    "verified_at": "string"
  },
  "credit_spent_this_month_micros": 0,
  "currency": "USD",
  "exhausted_since": "string",
  "limits": {
    "concurrent_machines": {
      "limit": 0,
      "used": 0
    },
    "starts": [
      {
        "limit": 0,
        "used": 0,
        "window": "hour"
      }
    ],
    "status": "trial",
    "tier": "pro"
  },
  "minimum_balance_micros": 0,
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "payment_customer_linked": false,
  "payments_available": false,
  "plan": {
    "active": false,
    "cancel_at_period_end": false,
    "included_micros": 0,
    "included_seconds": 0,
    "period_end": "string",
    "period_start": "string",
    "price_micros": 0,
    "renews": false,
    "tier": "pro"
  },
  "spend_cap_micros": 0,
  "status": "trial",
  "trial": {
    "active": false,
    "concurrent_machines": 0,
    "ended_at": "string",
    "max_hourly_micros": 0,
    "remaining_micros": 0,
    "remaining_seconds": 0,
    "total_micros": 0
  }
}
```

## Resume a cancelled plan

`POST /v1/billing/subscription/resume`

- **API key:** `Authorization: Bearer vmy_…` with preset `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner or Billing.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `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 |
| --- | --- | --- |
| `200` | The plan renews again at `plan.period_end` | [`BillingDto`](/docs/api/schemas#billingdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `subscription_missing`: the subscription already ended | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `501` | `billing_unavailable` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `502` | `payment_provider_error` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/billing/subscription/resume" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "balances": {
    "credit_micros": 0,
    "plan_micros": 0,
    "spendable_micros": 0,
    "trial_micros": 0
  },
  "card_check": {
    "required": false,
    "verified_at": "string"
  },
  "credit_spent_this_month_micros": 0,
  "currency": "USD",
  "exhausted_since": "string",
  "limits": {
    "concurrent_machines": {
      "limit": 0,
      "used": 0
    },
    "starts": [
      {
        "limit": 0,
        "used": 0,
        "window": "hour"
      }
    ],
    "status": "trial",
    "tier": "pro"
  },
  "minimum_balance_micros": 0,
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "payment_customer_linked": false,
  "payments_available": false,
  "plan": {
    "active": false,
    "cancel_at_period_end": false,
    "included_micros": 0,
    "included_seconds": 0,
    "period_end": "string",
    "period_start": "string",
    "price_micros": 0,
    "renews": false,
    "tier": "pro"
  },
  "spend_cap_micros": 0,
  "status": "trial",
  "trial": {
    "active": false,
    "concurrent_machines": 0,
    "ended_at": "string",
    "max_hourly_micros": 0,
    "remaining_micros": 0,
    "remaining_seconds": 0,
    "total_micros": 0
  }
}
```

## End the trial early

`POST /v1/billing/trial/end`

End the trial now: its remaining balance is forfeited (a
`trial_forfeit` ledger row) and cannot be restored. Trial rules (two
machines, small/default sizes) still apply until the first payment.
Ending an ended trial changes nothing.

Forfeits the remaining trial balance for good; trial rules apply until the first payment. See [Cancel a plan or end the trial](/docs/guides/plans-and-trial).

- **API key:** `Authorization: Bearer vmy_…` with preset `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner or Billing.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `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 |
| --- | --- | --- |
| `200` | — | [`BillingDto`](/docs/api/schemas#billingdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/billing/trial/end" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "balances": {
    "credit_micros": 0,
    "plan_micros": 0,
    "spendable_micros": 0,
    "trial_micros": 0
  },
  "card_check": {
    "required": false,
    "verified_at": "string"
  },
  "credit_spent_this_month_micros": 0,
  "currency": "USD",
  "exhausted_since": "string",
  "limits": {
    "concurrent_machines": {
      "limit": 0,
      "used": 0
    },
    "starts": [
      {
        "limit": 0,
        "used": 0,
        "window": "hour"
      }
    ],
    "status": "trial",
    "tier": "pro"
  },
  "minimum_balance_micros": 0,
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "payment_customer_linked": false,
  "payments_available": false,
  "plan": {
    "active": false,
    "cancel_at_period_end": false,
    "included_micros": 0,
    "included_seconds": 0,
    "period_end": "string",
    "period_start": "string",
    "price_micros": 0,
    "renews": false,
    "tier": "pro"
  },
  "spend_cap_micros": 0,
  "status": "trial",
  "trial": {
    "active": false,
    "concurrent_machines": 0,
    "ended_at": "string",
    "max_hourly_micros": 0,
    "remaining_micros": 0,
    "remaining_seconds": 0,
    "total_micros": 0
  }
}
```

## Get automatic refill

`GET /v1/billing/auto-refill`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `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 |
| --- | --- | --- |
| `200` | — | [`AutoRefillDto`](/docs/api/schemas#autorefilldto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/billing/auto-refill" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "amount_micros": 0,
  "charged_this_month_micros": 0,
  "consecutive_failures": 0,
  "credit_packs": 0,
  "disabled_reason": "string",
  "enabled": false,
  "last_charge": {
    "amount_micros": 0,
    "created_at": "string",
    "credit_packs": 0,
    "failure_code": "string",
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "status": "string"
  },
  "monthly_cap_micros": 0,
  "threshold_micros": 0
}
```

## Change automatic refill

`PUT /v1/billing/auto-refill`

Configure automatic refill. Enabling needs online payments, a linked
customer, and a default payment method at the provider; it also clears
the failure count of a refill that turned itself off.

All four fields are required. Enabling needs a linked customer and a default card at the payment provider. See [Automatic refill](/docs/guides/automatic-refill).

- **API key:** `Authorization: Bearer vmy_…` with preset `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner or Billing.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `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. |

**Request body** (`application/json`, [`UpdateAutoRefillRequest`](/docs/api/schemas#updateautorefillrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `credit_packs` | `integer` | Yes | 1-50 packs of $20. 1–50. |
| `enabled` | `boolean` | Yes |  |
| `monthly_cap_micros` | `integer` | Yes | At least one refill's amount. |
| `threshold_micros` | `integer` | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`AutoRefillDto`](/docs/api/schemas#autorefilldto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `billing_customer_missing` or `payment_method_missing` (set a default card in the portal) | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `501` | `billing_unavailable` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `502` | `payment_provider_error` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X PUT "$VMYARD_API_URL/v1/billing/auto-refill" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "credit_packs": 1,
  "enabled": false,
  "monthly_cap_micros": 0,
  "threshold_micros": 0
}'
```

```json title="Response 200"
{
  "amount_micros": 0,
  "charged_this_month_micros": 0,
  "consecutive_failures": 0,
  "credit_packs": 0,
  "disabled_reason": "string",
  "enabled": false,
  "last_charge": {
    "amount_micros": 0,
    "created_at": "string",
    "credit_packs": 0,
    "failure_code": "string",
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "status": "string"
  },
  "monthly_cap_micros": 0,
  "threshold_micros": 0
}
```

## Preview the invoice

`GET /v1/billing/invoice-preview`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `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 |
| --- | --- | --- |
| `200` | — | [`InvoicePreviewDto`](/docs/api/schemas#invoicepreviewdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/billing/invoice-preview" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "applied": {
    "credit_micros": 0,
    "plan_micros": 0,
    "trial_micros": 0
  },
  "credit_balance_micros": 0,
  "currency": "USD",
  "lines": [
    {
      "amount_micros": 0,
      "description": "default · machine time",
      "hourly_micros": 0,
      "multiplier": 0.5,
      "plan_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "plan_version": 0,
      "seconds": 0
    }
  ],
  "next_charge_micros": 0,
  "period_end": "string",
  "period_start": "string",
  "plan": {
    "active": false,
    "cancel_at_period_end": false,
    "included_micros": 0,
    "included_seconds": 0,
    "period_end": "string",
    "period_start": "string",
    "price_micros": 0,
    "renews": false,
    "tier": "pro"
  },
  "unbilled_micros": 0,
  "usage_micros": 0
}
```

## Get limits

`GET /v1/limits`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `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 |
| --- | --- | --- |
| `200` | — | [`LimitsDto`](/docs/api/schemas#limitsdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/limits" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "concurrent_machines": {
    "limit": 0,
    "used": 0
  },
  "starts": [
    {
      "limit": 0,
      "used": 0,
      "window": "hour"
    }
  ],
  "status": "trial",
  "tier": "pro"
}
```

## Get organization usage

`GET /v1/usage`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `since` | query | `string` | No | RFC 3339 start (inclusive). Defaults to the current plan period's start, or the UTC month's start without a plan; for one machine, to its first run. |
| `until` | query | `string` | No | RFC 3339 end (exclusive). Defaults to now. |
| `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 |
| --- | --- | --- |
| `200` | — | [`UsageDto`](/docs/api/schemas#usagedto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/usage" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "cost_micros": 0,
  "machines": [
    {
      "cost_micros": 0,
      "hourly_micros": 0,
      "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "multiplier": 0.5,
      "running": false,
      "seconds": 0
    }
  ],
  "seconds": 0,
  "since": "string",
  "until": "string"
}
```

## Get machine usage

`GET /v1/machines/{machine_id}/usage`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `machine_id` | path | `string (uuid)` | Yes |  |
| `since` | query | `string` | No | RFC 3339 start (inclusive). Defaults to the current plan period's start, or the UTC month's start without a plan; for one machine, to its first run. |
| `until` | query | `string` | No | RFC 3339 end (exclusive). Defaults to now. |
| `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 |
| --- | --- | --- |
| `200` | — | [`MachineUsageDto`](/docs/api/schemas#machineusagedto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/usage" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "cost_micros": 0,
  "hourly_micros": 0,
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "multiplier": 0.5,
  "running": false,
  "seconds": 0
}
```

## Receive a Stripe event

`POST /v1/billing/stripe/webhook`

Stripe calls this with signed events. It needs no session or API key:
the signature over the exact body is the authentication.

- **Authentication:** none on this route.
- **Who:** Stripe (signed request).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Stripe-Signature` | header | `string` | Yes | t=<unix seconds>,v1=<hex HMAC-SHA256> |

**Request body** (`application/json`)

No fields.

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`WebhookAckDto`](/docs/api/schemas#webhookackdto) |
| `400` | `invalid_signature` or `invalid_event` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `501` | `billing_unavailable` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/billing/stripe/webhook" \
  -H "Stripe-Signature: $STRIPE_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '"string"'
```

```json title="Response 200"
{
  "outcome": "applied",
  "received": false
}
```

## Grant credits or time (operators)

`POST /v1/operator/billing/grants`

Operators grant credits, trial time, or plan periods by hand (support,
invoices paid offline, or a deployment without online payments). The
caller presents the operator token configured for the service; members
of an organization, however privileged, cannot reach it.

- **Authentication:** none on this route.
- **Who:** Service operators (operator token).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `X-VMYard-Operator-Token` | header | `string` | Yes | Operator token from the service configuration |

**Request body** (`application/json`, [`OperatorGrantRequest`](/docs/api/schemas#operatorgrantrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `idempotency_key` | `string` | Yes | Replaying the same key applies the grant once. |
| `kind` | [`GrantKindDto`](/docs/api/schemas#grantkinddto) | Yes |  |
| `organization_id` | `string (uuid)` | Yes |  |
| `reason` | `string` | Yes | Why the grant was made; recorded in the audit log. |
| `amount_micros` | `integer \| null` | No | Micros for `credits` and `trial`. |
| `period_days` | `integer \| null` | No | Period length for `plan_period`, starting now (1-366, default 30). |
| `tier` | `string \| null` | No | Tier for `plan_period`. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`GrantResultDto`](/docs/api/schemas#grantresultdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | operator grants are not configured or the organization is unknown | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/operator/billing/grants" \
  -H "X-VMYard-Operator-Token: $X_VMYARD_OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "organization_id": "2a7d4c1e-8b3f-4f6a-9c5d-0e1f2a3b4c5d",
  "kind": "credits",
  "amount_micros": 20000000,
  "reason": "Invoice 1042 paid by bank transfer",
  "idempotency_key": "grant-invoice-1042"
}'
```

```json title="Response 200"
{
  "outcome": "applied"
}
```

## List wallet movements

`GET /v1/billing/ledger`

The wallet's movements other than usage (grants, credits from VMYard,
purchases, expiries), newest first. Usage is reported by `/v1/usage`.

Grants, credits from VMYard, purchases, and expiries, newest first. Usage is in `GET /v1/usage`.

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | `integer` | No | 1-100, default 50. |
| `before` | query | `integer` | No | Entries before this one (`next_before` of the previous page). |
| `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 |
| --- | --- | --- |
| `200` | — | [`LedgerPage`](/docs/api/schemas#ledgerpage) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/billing/ledger" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "items": [
    {
      "amount_micros": 0,
      "at": "string",
      "bucket": "string",
      "id": 0,
      "kind": "trial_grant",
      "label": "k7f2mq3x9a1b",
      "plan_tier": "string"
    }
  ],
  "next_before": 0
}
```

## Grant credits from VMYard (operators)

`POST /v1/operator/billing/credits`

Grant credits from VMYard to an organization, or claw them back. They
are a gift, not a payment: the organization's status (and trial rules)
do not change. The organization sees each as "Credit from VMYard" in
`GET /v1/billing/ledger`.

- **Authentication:** none on this route.
- **Who:** Service operators (operator token).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `X-VMYard-Operator-Token` | header | `string` | Yes | Operator token from the service configuration |

**Request body** (`application/json`, [`OperatorCreditRequest`](/docs/api/schemas#operatorcreditrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micros` | `integer` | Yes | Positive micros (1 USD = 1000000). at least 1. |
| `idempotency_key` | `string` | Yes | Replaying the same key applies the change once. |
| `kind` | [`CreditKindDto`](/docs/api/schemas#creditkinddto) | Yes |  |
| `operator` | `string` | Yes | The individual operator acting, 1-200 characters. |
| `organization_id` | `string (uuid)` | Yes |  |
| `reason` | `string` | Yes | Why, 1-500 characters; kept on the ledger row and in the audit log, never shown to the organization. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`OperatorCreditDto`](/docs/api/schemas#operatorcreditdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | operator access is not configured or the organization is unknown | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `insufficient_credit`: a claw-back larger than the credit balance | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/operator/billing/credits" \
  -H "X-VMYard-Operator-Token: $X_VMYARD_OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amount_micros": 1,
  "idempotency_key": "string",
  "kind": "grant",
  "operator": "string",
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "reason": "string"
}'
```

```json title="Response 200"
{
  "credit_balance_micros": 0,
  "outcome": "string"
}
```

---

<!-- Source: /docs/api/webhooks.md -->

# Webhooks API

> Register HTTPS endpoints for signed lifecycle events and inspect their deliveries.

- [List webhooks](#list-webhooks): `GET /v1/webhooks`
- [Create a webhook](#create-a-webhook): `POST /v1/webhooks`
- [Get a webhook](#get-a-webhook): `GET /v1/webhooks/{webhook_id}`
- [Change a webhook](#change-a-webhook): `PATCH /v1/webhooks/{webhook_id}`
- [Delete a webhook](#delete-a-webhook): `DELETE /v1/webhooks/{webhook_id}`
- [Rotate a webhook secret](#rotate-a-webhook-secret): `POST /v1/webhooks/{webhook_id}/rotate-secret`
- [List webhook deliveries](#list-webhook-deliveries): `GET /v1/webhooks/{webhook_id}/deliveries`

## List webhooks

`GET /v1/webhooks`

- **API key:** `Authorization: Bearer vmy_…` with preset `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Owner or Admin.

**Parameters**

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

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`WebhookPage`](/docs/api/schemas#webhookpage) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | A role other than owner/admin, or an API key without full_access | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/webhooks" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "items": [
    {
      "created_at": "2026-10-12T05:51:01Z",
      "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "enabled": false,
      "events": [
        "machine.ready"
      ],
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "name": "ci",
      "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "secret_rotated_at": "2026-10-12T05:51:01Z",
      "updated_at": "2026-10-12T05:51:01Z",
      "url": "https://hooks.example.com/vmyard"
    }
  ],
  "next_cursor": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## Create a webhook

`POST /v1/webhooks`

- **API key:** `Authorization: Bearer vmy_…` with preset `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner or Admin.

**Parameters**

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

**Request body** (`application/json`, [`CreateWebhookRequest`](/docs/api/schemas#createwebhookrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `events` | [`WebhookEventDto[]`](/docs/api/schemas#webhookeventdto) | Yes | at least 1 items. |
| `name` | `string` | Yes | 1–64 characters. |
| `url` | `string` | Yes | `https` on port 443, without credentials or a fragment, naming a public host. Redirects are never followed. at most 2048 characters. |
| `enabled` | `boolean` | No | default `true`. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `201` | The signing secret is returned only in this response | [`WebhookSecretDto`](/docs/api/schemas#webhooksecretdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | CSRF failure, a role other than owner/admin, or an API key without full_access | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | The organization already has 10 endpoints | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | `webhooks_unavailable`: no secret keys are configured, and secrets are never stored in plaintext | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/webhooks" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "ci",
  "url": "https://hooks.example.com/vmyard",
  "events": [
    "machine.ready",
    "machine.error"
  ]
}'
```

```json title="Response 201"
{
  "secret": "whsec_…",
  "webhook": {
    "created_at": "2026-10-12T05:51:01Z",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "enabled": false,
    "events": [
      "machine.ready"
    ],
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "name": "ci",
    "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "secret_rotated_at": "2026-10-12T05:51:01Z",
    "updated_at": "2026-10-12T05:51:01Z",
    "url": "https://hooks.example.com/vmyard"
  }
}
```

## Get a webhook

`GET /v1/webhooks/{webhook_id}`

- **API key:** `Authorization: Bearer vmy_…` with preset `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Owner or Admin.

**Parameters**

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

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`WebhookDto`](/docs/api/schemas#webhookdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | A role other than owner/admin, or an API key without full_access | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "created_at": "2026-10-12T05:51:01Z",
  "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "enabled": false,
  "events": [
    "machine.ready"
  ],
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "name": "ci",
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "secret_rotated_at": "2026-10-12T05:51:01Z",
  "updated_at": "2026-10-12T05:51:01Z",
  "url": "https://hooks.example.com/vmyard"
}
```

## Change a webhook

`PATCH /v1/webhooks/{webhook_id}`

- **API key:** `Authorization: Bearer vmy_…` with preset `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner or Admin.

**Parameters**

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

**Request body** (`application/json`, [`UpdateWebhookRequest`](/docs/api/schemas#updatewebhookrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | `boolean \| null` | No |  |
| `events` | [`WebhookEventDto[] \| null`](/docs/api/schemas#webhookeventdto) | No | at least 1 items. |
| `name` | `string \| null` | No | 1–64 characters. |
| `url` | `string \| null` | No | at most 2048 characters. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | Queued deliveries of a disabled endpoint wait until it is enabled again | [`WebhookDto`](/docs/api/schemas#webhookdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | CSRF failure, a role other than owner/admin, or an API key without full_access | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X PATCH "$VMYARD_API_URL/v1/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": false
}'
```

```json title="Response 200"
{
  "created_at": "2026-10-12T05:51:01Z",
  "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "enabled": false,
  "events": [
    "machine.ready"
  ],
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "name": "ci",
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "secret_rotated_at": "2026-10-12T05:51:01Z",
  "updated_at": "2026-10-12T05:51:01Z",
  "url": "https://hooks.example.com/vmyard"
}
```

## Delete a webhook

`DELETE /v1/webhooks/{webhook_id}`

- **API key:** `Authorization: Bearer vmy_…` with preset `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner or Admin.

**Parameters**

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

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `204` | Deleted together with its queued and past deliveries | — |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | CSRF failure, a role other than owner/admin, or an API key without full_access | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X DELETE "$VMYARD_API_URL/v1/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

## Rotate a webhook secret

`POST /v1/webhooks/{webhook_id}/rotate-secret`

- **API key:** `Authorization: Bearer vmy_…` with preset `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner or Admin.

**Parameters**

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

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | The old secret stops signing immediately, including retries of queued deliveries | [`WebhookSecretDto`](/docs/api/schemas#webhooksecretdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | CSRF failure, a role other than owner/admin, or an API key without full_access | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | `webhooks_unavailable`: no secret keys are configured | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/webhooks/$WEBHOOK_ID/rotate-secret" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "secret": "whsec_…",
  "webhook": {
    "created_at": "2026-10-12T05:51:01Z",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "enabled": false,
    "events": [
      "machine.ready"
    ],
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "name": "ci",
    "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "secret_rotated_at": "2026-10-12T05:51:01Z",
    "updated_at": "2026-10-12T05:51:01Z",
    "url": "https://hooks.example.com/vmyard"
  }
}
```

## List webhook deliveries

`GET /v1/webhooks/{webhook_id}/deliveries`

- **API key:** `Authorization: Bearer vmy_…` with preset `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Owner or Admin.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | `integer` | No | 1-100, default 50; newest first. |
| `webhook_id` | path | `string (uuid)` | Yes |  |
| `X-Organization-ID` | header | `string (uuid)` | No | Organization context. Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | Recent deliveries to this endpoint, newest first, with their last attempt | [`WebhookDeliveryPage`](/docs/api/schemas#webhookdeliverypage) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | A role other than owner/admin, or an API key without full_access | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/webhooks/$WEBHOOK_ID/deliveries" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "items": [
    {
      "attempt_count": 0,
      "created_at": "2026-10-12T05:51:01Z",
      "delivered_at": "2026-10-12T05:51:01Z",
      "event_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "event_type": "machine.ready",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "last_attempt_at": "2026-10-12T05:51:01Z",
      "last_error": "string",
      "last_status_code": 0,
      "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "next_attempt_at": "2026-10-12T05:51:01Z",
      "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "status": "pending"
    }
  ]
}
```

---

<!-- Source: /docs/api/notifications.md -->

# Email alerts API

> Read and change your email alert preferences, and the unsubscribe link every alert email carries.

- [Get alert preferences](#get-alert-preferences): `GET /v1/notifications/preferences`
- [Change alert preferences](#change-alert-preferences): `PUT /v1/notifications/preferences`
- [Show the unsubscribe confirmation](#show-the-unsubscribe-confirmation): `GET /v1/notifications/unsubscribe`
- [Unsubscribe from one alert type](#unsubscribe-from-one-alert-type): `POST /v1/notifications/unsubscribe`

## Get alert preferences

`GET /v1/notifications/preferences`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member, for their own preferences.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `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 |
| --- | --- | --- |
| `200` | — | [`NotificationPreferencesDto`](/docs/api/schemas#notificationpreferencesdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/notifications/preferences" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "alerts": [
    {
      "available": false,
      "customized": false,
      "default_enabled": false,
      "description": "A machine could not be stopped.",
      "enabled": false,
      "type": "machine_stop_failed"
    }
  ],
  "email": "ada@example.com",
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "user_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## Change alert preferences

`PUT /v1/notifications/preferences`

- **API key:** `Authorization: Bearer vmy_…` with preset `full_access`.
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Any member, for their own preferences.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `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. |

**Request body** (`application/json`, [`UpdateNotificationPreferencesRequest`](/docs/api/schemas#updatenotificationpreferencesrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `alerts` | `map of string` | Yes | Alert type to on (`true`) or off (`false`); unlisted types keep their current setting. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`NotificationPreferencesDto`](/docs/api/schemas#notificationpreferencesdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X PUT "$VMYARD_API_URL/v1/notifications/preferences" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "alerts": {
    "operation_failed": true,
    "auto_stop": false
  }
}'
```

```json title="Response 200"
{
  "alerts": [
    {
      "available": false,
      "customized": false,
      "default_enabled": false,
      "description": "A machine could not be stopped.",
      "enabled": false,
      "type": "machine_stop_failed"
    }
  ],
  "email": "ada@example.com",
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "user_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## Show the unsubscribe confirmation

`GET /v1/notifications/unsubscribe`

Shows a confirmation page and changes nothing, so link scanners are harmless.

- **Authentication:** none on this route.
- **Who:** Anyone with an alert email's link.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `token` | query | `string` | Yes | The token from the alert email's unsubscribe link. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | A confirmation page whose button POSTs the same URL; nothing changes on GET | `text/html` |
| `400` | Bad request. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/notifications/unsubscribe?token=token"
```

## Unsubscribe from one alert type

`POST /v1/notifications/unsubscribe`

Turns off the one alert type the token names for its member. One-click unsubscribe (RFC 8058) posts here.

- **Authentication:** none on this route.
- **Who:** Anyone with an alert email's link.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `token` | query | `string` | Yes | The token from the alert email's unsubscribe link. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | The alert is off for that member. One-click (RFC 8058) and form posts need no session; `Accept: text/html` answers with a page. | [`UnsubscribedDto`](/docs/api/schemas#unsubscribeddto) |
| `400` | Bad request. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/notifications/unsubscribe?token=token"
```

```json title="Response 200"
{
  "enabled": false,
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "type": "operation_failed"
}
```

---

<!-- Source: /docs/api/organizations.md -->

# Organizations API

> List, read, create, and rename the organizations the caller belongs to.

- [List organizations](#list-organizations): `GET /v1/organizations`
- [Create an organization](#create-an-organization): `POST /v1/organizations`
- [Get an organization](#get-an-organization): `GET /v1/organizations/{organization_id}`
- [Rename an organization](#rename-an-organization): `PATCH /v1/organizations/{organization_id}`

## List organizations

`GET /v1/organizations`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`OrganizationList`](/docs/api/schemas#organizationlist) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/organizations" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "items": [
    {
      "created_at": "2026-10-12T05:51:01Z",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "name": "dev",
      "role": "owner",
      "suspended_at": "2026-10-12T05:51:01Z"
    }
  ]
}
```

## Create an organization

`POST /v1/organizations`

- **API key:** not accepted (`403 session_required`).
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Any signed-in user.

**Request body** (`application/json`, [`CreateOrganizationRequest`](/docs/api/schemas#createorganizationrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | 1-64 characters without control characters or surrounding whitespace; unique (case-insensitively) among the caller's own organizations. 1–64 characters. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `201` | Created with the caller as owner and a trial wallet | [`OrganizationDto`](/docs/api/schemas#organizationdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | CSRF failure or bearer authentication (`session_required`) | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `organization_name_taken`: the caller already created one with this name | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `429` | `rate_limited`: 5 creations per user per 24 hours, counting the personal organization created at sign-in | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/organizations" \
  -b "vmyard_session=$VMYARD_SESSION" \
  -H "x-csrf-token: $VMYARD_CSRF" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "dev"
}'
```

```json title="Response 201"
{
  "created_at": "2026-10-12T05:51:01Z",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "name": "dev",
  "role": "owner",
  "suspended_at": "2026-10-12T05:51:01Z"
}
```

## Get an organization

`GET /v1/organizations/{organization_id}`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `organization_id` | path | `string (uuid)` | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`OrganizationDto`](/docs/api/schemas#organizationdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not a member, or another organization than the API key's | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/organizations/$ORGANIZATION_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "created_at": "2026-10-12T05:51:01Z",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "name": "dev",
  "role": "owner",
  "suspended_at": "2026-10-12T05:51:01Z"
}
```

## Rename an organization

`PATCH /v1/organizations/{organization_id}`

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

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `organization_id` | path | `string (uuid)` | Yes |  |

**Request body** (`application/json`, [`UpdateOrganizationRequest`](/docs/api/schemas#updateorganizationrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | 1–64 characters. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`OrganizationDto`](/docs/api/schemas#organizationdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | CSRF failure, bearer authentication (`session_required`), or neither owner nor admin | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `organization_name_taken`: its creator already has an organization with this name | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X PATCH "$VMYARD_API_URL/v1/organizations/$ORGANIZATION_ID" \
  -b "vmyard_session=$VMYARD_SESSION" \
  -H "x-csrf-token: $VMYARD_CSRF" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "dev"
}'
```

```json title="Response 200"
{
  "created_at": "2026-10-12T05:51:01Z",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "name": "dev",
  "role": "owner",
  "suspended_at": "2026-10-12T05:51:01Z"
}
```

---

<!-- Source: /docs/api/waitlist.md -->

# Waitlist and access API

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

- [Receive a waitlist sign-up](#receive-a-waitlist-sign-up): `POST /v1/waitlist/tally`
- [List waitlist entries (operators)](#list-waitlist-entries-operators): `GET /v1/operator/waitlist`
- [Approve a waitlist entry (operators)](#approve-a-waitlist-entry-operators): `POST /v1/operator/waitlist/{entry_id}/approve`
- [Reject a waitlist entry (operators)](#reject-a-waitlist-entry-operators): `POST /v1/operator/waitlist/{entry_id}/reject`
- [Revoke a waitlist entry (operators)](#revoke-a-waitlist-entry-operators): `POST /v1/operator/waitlist/{entry_id}/revoke`
- [List access grants (operators)](#list-access-grants-operators): `GET /v1/operator/access-grants`
- [Grant access (operators)](#grant-access-operators): `POST /v1/operator/access-grants`
- [Revoke an access grant (operators)](#revoke-an-access-grant-operators): `POST /v1/operator/access-grants/{grant_id}/revoke`

## Receive a waitlist sign-up

`POST /v1/waitlist/tally`

Accept a waitlist sign-up from the form service (Tally). The raw body
must carry a valid `Tally-Signature` (base64 HMAC-SHA256 under the
configured signing secret); unsigned or mis-signed requests are refused.
Events other than `FORM_RESPONSE` are acknowledged and ignored. A second
sign-up from the same address refreshes its answers.

- **Authentication:** none on this route.
- **Who:** The form service (signed request).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Tally-Signature` | header | `string` | Yes | Base64 HMAC-SHA256 of the raw body under the waitlist signing secret |

**Request body** (`application/json`)

No fields.

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`WaitlistAckDto`](/docs/api/schemas#waitlistackdto) |
| `401` | `invalid_signature`: missing or wrong signature | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | the waitlist webhook is not configured | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | the event has no valid email answer | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/waitlist/tally" \
  -H "Tally-Signature: $TALLY_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '"string"'
```

```json title="Response 200"
{
  "received": false
}
```

## List waitlist entries (operators)

`GET /v1/operator/waitlist`

Waitlist entries, newest first.

- **Authentication:** none on this route.
- **Who:** Service operators (operator token).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `status` | query | [`WaitlistFilterDto`](/docs/api/schemas#waitlistfilterdto) | No | `pending` (default), `approved`, `rejected`, `revoked`, or `all`. |
| `limit` | query | `integer` | No | 1-500, default 100; newest first. |
| `X-VMYard-Operator-Token` | header | `string` | Yes | Operator token from the service configuration |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`WaitlistPage`](/docs/api/schemas#waitlistpage) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | operator access is not configured | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/operator/waitlist" \
  -H "X-VMYard-Operator-Token: $X_VMYARD_OPERATOR_TOKEN"
```

```json title="Response 200"
{
  "items": [
    {
      "access_grant_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "company": "string",
      "created_at": "string",
      "decided_at": "string",
      "decided_by": "string",
      "decision_reason": "string",
      "email": "ada@example.com",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "name": "dev",
      "raw_answers": {},
      "status": "pending",
      "updated_at": "string",
      "use_case": "string"
    }
  ]
}
```

## Approve a waitlist entry (operators)

`POST /v1/operator/waitlist/{entry_id}/approve`

Approve an entry: its email gets an access grant (with the initial
credit), and the "you're in" email is sent. Approving an approved entry
changes nothing; a rejected or revoked entry may be approved again.

- **Authentication:** none on this route.
- **Who:** Service operators (operator token).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `entry_id` | path | `string (uuid)` | Yes |  |
| `X-VMYard-Operator-Token` | header | `string` | Yes | Operator token from the service configuration |

**Request body** (`application/json`, [`ApproveWaitlistRequest`](/docs/api/schemas#approvewaitlistrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `operator` | `string` | Yes | The individual operator acting, 1-200 characters. |
| `initial_credit_micros` | `integer \| null` | No | Credits from VMYard granted once to the person's own organization (now if they already signed in, else at their first sign-in). Defaults to the service's `access.initial_credit_micros`; 0 grants none. |
| `notify` | `boolean \| null` | No | Send the "you're in" email (default true). |
| `reason` | `string \| null` | No | Why, 1-500 characters; optional. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`WaitlistDecisionDto`](/docs/api/schemas#waitlistdecisiondto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | operator access is not configured or the entry is unknown | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/operator/waitlist/$ENTRY_ID/approve" \
  -H "X-VMYard-Operator-Token: $X_VMYARD_OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "operator": "string"
}'
```

```json title="Response 200"
{
  "changed": false,
  "entry": {
    "access_grant_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "company": "string",
    "created_at": "string",
    "decided_at": "string",
    "decided_by": "string",
    "decision_reason": "string",
    "email": "ada@example.com",
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "name": "dev",
    "raw_answers": {},
    "status": "pending",
    "updated_at": "string",
    "use_case": "string"
  },
  "grant": {
    "created_at": "string",
    "credited_at": "string",
    "credited_organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "email": "ada@example.com",
    "granted_by": "string",
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "initial_credit_micros": 0,
    "provider": "github",
    "reason": "string",
    "revoke_reason": "string",
    "revoked_at": "string",
    "revoked_by": "string",
    "subject": "string"
  },
  "notification": "sent"
}
```

## Reject a waitlist entry (operators)

`POST /v1/operator/waitlist/{entry_id}/reject`

Reject a pending entry. Rejecting a rejected entry changes nothing; an
approved entry is revoked instead (`409 waitlist_decision_conflict`).

- **Authentication:** none on this route.
- **Who:** Service operators (operator token).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `entry_id` | path | `string (uuid)` | Yes |  |
| `X-VMYard-Operator-Token` | header | `string` | Yes | Operator token from the service configuration |

**Request body** (`application/json`, [`WaitlistDecisionRequest`](/docs/api/schemas#waitlistdecisionrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `operator` | `string` | Yes | The individual operator acting, 1-200 characters. |
| `reason` | `string` | Yes | Why, 1-500 characters. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`WaitlistDecisionDto`](/docs/api/schemas#waitlistdecisiondto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | operator access is not configured or the entry is unknown | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `waitlist_decision_conflict` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/operator/waitlist/$ENTRY_ID/reject" \
  -H "X-VMYard-Operator-Token: $X_VMYARD_OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "operator": "string",
  "reason": "string"
}'
```

```json title="Response 200"
{
  "changed": false,
  "entry": {
    "access_grant_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "company": "string",
    "created_at": "string",
    "decided_at": "string",
    "decided_by": "string",
    "decision_reason": "string",
    "email": "ada@example.com",
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "name": "dev",
    "raw_answers": {},
    "status": "pending",
    "updated_at": "string",
    "use_case": "string"
  },
  "grant": {
    "created_at": "string",
    "credited_at": "string",
    "credited_organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "email": "ada@example.com",
    "granted_by": "string",
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "initial_credit_micros": 0,
    "provider": "github",
    "reason": "string",
    "revoke_reason": "string",
    "revoked_at": "string",
    "revoked_by": "string",
    "subject": "string"
  },
  "notification": "sent"
}
```

## Revoke a waitlist entry (operators)

`POST /v1/operator/waitlist/{entry_id}/revoke`

Revoke an approved entry: its grant is revoked, so the person (and the
organizations only they approve) can no longer create organizations,
machines, or API keys. Running machines keep running; suspend the
organization to stop them.

- **Authentication:** none on this route.
- **Who:** Service operators (operator token).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `entry_id` | path | `string (uuid)` | Yes |  |
| `X-VMYard-Operator-Token` | header | `string` | Yes | Operator token from the service configuration |

**Request body** (`application/json`, [`WaitlistDecisionRequest`](/docs/api/schemas#waitlistdecisionrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `operator` | `string` | Yes | The individual operator acting, 1-200 characters. |
| `reason` | `string` | Yes | Why, 1-500 characters. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`WaitlistDecisionDto`](/docs/api/schemas#waitlistdecisiondto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | operator access is not configured or the entry is unknown | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `waitlist_decision_conflict`: the entry is not approved | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/operator/waitlist/$ENTRY_ID/revoke" \
  -H "X-VMYard-Operator-Token: $X_VMYARD_OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "operator": "string",
  "reason": "string"
}'
```

```json title="Response 200"
{
  "changed": false,
  "entry": {
    "access_grant_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "company": "string",
    "created_at": "string",
    "decided_at": "string",
    "decided_by": "string",
    "decision_reason": "string",
    "email": "ada@example.com",
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "name": "dev",
    "raw_answers": {},
    "status": "pending",
    "updated_at": "string",
    "use_case": "string"
  },
  "grant": {
    "created_at": "string",
    "credited_at": "string",
    "credited_organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "email": "ada@example.com",
    "granted_by": "string",
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "initial_credit_micros": 0,
    "provider": "github",
    "reason": "string",
    "revoke_reason": "string",
    "revoked_at": "string",
    "revoked_by": "string",
    "subject": "string"
  },
  "notification": "sent"
}
```

## List access grants (operators)

`GET /v1/operator/access-grants`

Access grants, newest first.

- **Authentication:** none on this route.
- **Who:** Service operators (operator token).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `include_revoked` | query | `boolean` | No | Include revoked grants (default false). |
| `limit` | query | `integer` | No | 1-500, default 100; newest first. |
| `X-VMYard-Operator-Token` | header | `string` | Yes | Operator token from the service configuration |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`AccessGrantPage`](/docs/api/schemas#accessgrantpage) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | operator access is not configured | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/operator/access-grants" \
  -H "X-VMYard-Operator-Token: $X_VMYARD_OPERATOR_TOKEN"
```

```json title="Response 200"
{
  "items": [
    {
      "created_at": "string",
      "credited_at": "string",
      "credited_organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "email": "ada@example.com",
      "granted_by": "string",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "initial_credit_micros": 0,
      "provider": "github",
      "reason": "string",
      "revoke_reason": "string",
      "revoked_at": "string",
      "revoked_by": "string",
      "subject": "string"
    }
  ]
}
```

## Grant access (operators)

`POST /v1/operator/access-grants`

Grant access without a waitlist entry: a verified login email, or one
sign-in identity (`provider` and `subject`, such as an ERP.AI account's
OIDC subject). No email is sent.

- **Authentication:** none on this route.
- **Who:** Service operators (operator token).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `X-VMYard-Operator-Token` | header | `string` | Yes | Operator token from the service configuration |

**Request body** (`application/json`, [`CreateAccessGrantRequest`](/docs/api/schemas#createaccessgrantrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `operator` | `string` | Yes | The individual operator acting, 1-200 characters. |
| `email` | `string \| null` | No | Grant a verified login email; or name `provider` and `subject`. |
| `initial_credit_micros` | `integer \| null` | No | As on approval; defaults to the service's initial credit, 0 for none. |
| `provider` | `string \| null` | No | A configured sign-in provider such as `erpai`. |
| `reason` | `string \| null` | No |  |
| `subject` | `string \| null` | No | The provider's subject (`sub`) for the account, 1-255 characters. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | An active grant already named this person | [`AccessGrantCreatedDto`](/docs/api/schemas#accessgrantcreateddto) |
| `201` | — | [`AccessGrantCreatedDto`](/docs/api/schemas#accessgrantcreateddto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | operator access is not configured | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/operator/access-grants" \
  -H "X-VMYard-Operator-Token: $X_VMYARD_OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "operator": "string"
}'
```

```json title="Response 200"
{
  "created": false,
  "grant": {
    "created_at": "string",
    "credited_at": "string",
    "credited_organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "email": "ada@example.com",
    "granted_by": "string",
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "initial_credit_micros": 0,
    "provider": "github",
    "reason": "string",
    "revoke_reason": "string",
    "revoked_at": "string",
    "revoked_by": "string",
    "subject": "string"
  }
}
```

## Revoke an access grant (operators)

`POST /v1/operator/access-grants/{grant_id}/revoke`

Revoke a grant; a waitlist entry approved through it becomes revoked.
Revoking a revoked grant changes nothing.

- **Authentication:** none on this route.
- **Who:** Service operators (operator token).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `grant_id` | path | `string (uuid)` | Yes |  |
| `X-VMYard-Operator-Token` | header | `string` | Yes | Operator token from the service configuration |

**Request body** (`application/json`, [`WaitlistDecisionRequest`](/docs/api/schemas#waitlistdecisionrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `operator` | `string` | Yes | The individual operator acting, 1-200 characters. |
| `reason` | `string` | Yes | Why, 1-500 characters. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`AccessGrantDto`](/docs/api/schemas#accessgrantdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | operator access is not configured or the grant is unknown | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/operator/access-grants/$GRANT_ID/revoke" \
  -H "X-VMYard-Operator-Token: $X_VMYARD_OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "operator": "string",
  "reason": "string"
}'
```

```json title="Response 200"
{
  "created_at": "string",
  "credited_at": "string",
  "credited_organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "email": "ada@example.com",
  "granted_by": "string",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "initial_credit_micros": 0,
  "provider": "github",
  "reason": "string",
  "revoke_reason": "string",
  "revoked_at": "string",
  "revoked_by": "string",
  "subject": "string"
}
```

---

<!-- Source: /docs/api/members.md -->

# Members and invitations API

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

- [List members](#list-members): `GET /v1/organizations/{organization_id}/members`
- [Change a member's role](#change-a-members-role): `PATCH /v1/organizations/{organization_id}/members/{user_id}`
- [Remove a member](#remove-a-member): `DELETE /v1/organizations/{organization_id}/members/{user_id}`
- [List pending invitations](#list-pending-invitations): `GET /v1/organizations/{organization_id}/invitations`
- [Invite a member by email](#invite-a-member-by-email): `POST /v1/organizations/{organization_id}/invitations`
- [Revoke an invitation](#revoke-an-invitation): `DELETE /v1/organizations/{organization_id}/invitations/{invitation_id}`
- [Preview an invitation](#preview-an-invitation): `GET /v1/invitations`
- [Accept an invitation](#accept-an-invitation): `POST /v1/invitations/accept`
- [Transfer ownership](#transfer-ownership): `POST /v1/organizations/{organization_id}/transfer`
- [Delete an organization](#delete-an-organization): `DELETE /v1/organizations/{organization_id}`
- [Choose the active organization](#choose-the-active-organization): `PUT /v1/me/active-organization`

## List members

`GET /v1/organizations/{organization_id}/members`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `organization_id` | path | `string (uuid)` | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`MemberList`](/docs/api/schemas#memberlist) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not a member, or another organization than the API key's | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/organizations/$ORGANIZATION_ID/members" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "items": [
    {
      "email": "ada@example.com",
      "joined_at": "2026-10-12T05:51:01Z",
      "max_running_machines": 0,
      "role": "owner",
      "running_machines": 0,
      "usage_this_month": {
        "cost_micros": 0,
        "seconds": 0
      },
      "user_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
    }
  ]
}
```

## Change a member's role

`PATCH /v1/organizations/{organization_id}/members/{user_id}`

An admin can't change an owner or make anyone an owner, and the only owner can't be demoted (`409 last_owner`).

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

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `organization_id` | path | `string (uuid)` | Yes |  |
| `user_id` | path | `string (uuid)` | Yes |  |

**Request body** (`application/json`, [`UpdateMemberRequest`](/docs/api/schemas#updatememberrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `max_running_machines` | `integer \| null` | No | 0-10000, or `null` to remove the member's cap; absent leaves it. at most 10000. |
| `role` | [`null \| RoleDto`](/docs/api/schemas#roledto) | No |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | The member after the change; `usage_this_month` is zero here, read it from the list | [`MemberDto`](/docs/api/schemas#memberdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | CSRF failure, `session_required`, or `forbidden`: neither owner nor admin, or an admin changing an owner or granting the owner role | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `last_owner`: the organization's only owner cannot be demoted | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X PATCH "$VMYARD_API_URL/v1/organizations/$ORGANIZATION_ID/members/$USER_ID" \
  -b "vmyard_session=$VMYARD_SESSION" \
  -H "x-csrf-token: $VMYARD_CSRF" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```json title="Response 200"
{
  "email": "ada@example.com",
  "joined_at": "2026-10-12T05:51:01Z",
  "max_running_machines": 0,
  "role": "owner",
  "running_machines": 0,
  "usage_this_month": {
    "cost_micros": 0,
    "seconds": 0
  },
  "user_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## Remove a member

`DELETE /v1/organizations/{organization_id}/members/{user_id}`

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

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `organization_id` | path | `string (uuid)` | Yes |  |
| `user_id` | path | `string (uuid)` | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`MemberRemovedDto`](/docs/api/schemas#memberremoveddto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | CSRF failure, `session_required`, or `forbidden`: neither owner nor admin (anyone may remove themselves), or an admin removing an owner | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `last_owner` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X DELETE "$VMYARD_API_URL/v1/organizations/$ORGANIZATION_ID/members/$USER_ID" \
  -b "vmyard_session=$VMYARD_SESSION" \
  -H "x-csrf-token: $VMYARD_CSRF"
```

```json title="Response 200"
{
  "api_keys_revoked": 0,
  "channels_revoked": 0,
  "tickets_revoked": 0,
  "user_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## List pending invitations

`GET /v1/organizations/{organization_id}/invitations`

- **API key:** not accepted (`403 session_required`).
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Owner or Admin.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `organization_id` | path | `string (uuid)` | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`InvitationList`](/docs/api/schemas#invitationlist) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Neither owner nor admin, or an API key (`session_required`) | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/organizations/$ORGANIZATION_ID/invitations" \
  -b "vmyard_session=$VMYARD_SESSION"
```

```json title="Response 200"
{
  "items": [
    {
      "created_at": "2026-10-12T05:51:01Z",
      "email": "ada@example.com",
      "expires_at": "2026-10-12T05:51:01Z",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "invited_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "role": "owner"
    }
  ]
}
```

## Invite a member by email

`POST /v1/organizations/{organization_id}/invitations`

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

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `organization_id` | path | `string (uuid)` | Yes |  |

**Request body** (`application/json`, [`CreateInvitationRequest`](/docs/api/schemas#createinvitationrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `string` | Yes |  |
| `role` | [`RoleDto`](/docs/api/schemas#roledto) | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `201` | Emailed with a single-use link valid 7 days; an open invitation to the same address is revoked | [`InvitationDto`](/docs/api/schemas#invitationdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | CSRF failure, `session_required`, or `forbidden` (neither owner nor admin, or an admin inviting an owner) | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `already_member` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `429` | `rate_limited`: 50 invitations per organization per 24 hours | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `502` | `email_unavailable`: the email could not be sent; the invitation was revoked | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | `invitations_unavailable`: email or `ui_base_url` is not configured | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/organizations/$ORGANIZATION_ID/invitations" \
  -b "vmyard_session=$VMYARD_SESSION" \
  -H "x-csrf-token: $VMYARD_CSRF" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ada@example.com",
  "role": "owner"
}'
```

```json title="Response 201"
{
  "created_at": "2026-10-12T05:51:01Z",
  "email": "ada@example.com",
  "expires_at": "2026-10-12T05:51:01Z",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "invited_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "role": "owner"
}
```

## Revoke an invitation

`DELETE /v1/organizations/{organization_id}/invitations/{invitation_id}`

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

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `organization_id` | path | `string (uuid)` | Yes |  |
| `invitation_id` | path | `string (uuid)` | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `204` | Revoked (revoking a revoked invitation changes nothing) | — |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `410` | `invitation_closed`: already accepted | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X DELETE "$VMYARD_API_URL/v1/organizations/$ORGANIZATION_ID/invitations/$INVITATION_ID" \
  -b "vmyard_session=$VMYARD_SESSION" \
  -H "x-csrf-token: $VMYARD_CSRF"
```

## Preview an invitation

`GET /v1/invitations`

- **API key:** not accepted (`403 session_required`).
- **Browser session:** the `vmyard_session` cookie.
- **Who:** The signed-in user.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `token` | query | `string` | Yes | The token from the invitation email. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`InvitationPreviewDto`](/docs/api/schemas#invitationpreviewdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | No invitation has this token | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/invitations?token=token" \
  -b "vmyard_session=$VMYARD_SESSION"
```

```json title="Response 200"
{
  "email": "ada@example.com",
  "expires_at": "2026-10-12T05:51:01Z",
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "organization_name": "string",
  "role": "owner",
  "state": "open"
}
```

## Accept an invitation

`POST /v1/invitations/accept`

- **API key:** not accepted (`403 session_required`).
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** The signed-in user.

**Request body** (`application/json`, [`AcceptInvitationRequest`](/docs/api/schemas#acceptinvitationrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | `string` | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | The caller is a member with the invited role, and it is their active organization | [`InvitationAcceptedDto`](/docs/api/schemas#invitationaccepteddto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | CSRF failure, `session_required`, or `invitation_email_mismatch`: the caller's sign-in addresses do not include the invited one | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `already_member` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `410` | `invitation_closed`: accepted, revoked, or expired | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/invitations/accept" \
  -b "vmyard_session=$VMYARD_SESSION" \
  -H "x-csrf-token: $VMYARD_CSRF" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "string"
}'
```

```json title="Response 200"
{
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "role": "owner"
}
```

## Transfer ownership

`POST /v1/organizations/{organization_id}/transfer`

- **API key:** not accepted (`403 session_required`).
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `organization_id` | path | `string (uuid)` | Yes |  |

**Request body** (`application/json`, [`TransferOwnershipRequest`](/docs/api/schemas#transferownershiprequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `user_id` | `string (uuid)` | Yes | A member who becomes the owner; the caller becomes an admin. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `204` | The member is an owner and the caller an admin | — |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | CSRF failure, `session_required`, or not the owner | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | The caller or the new owner is not a member | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/organizations/$ORGANIZATION_ID/transfer" \
  -b "vmyard_session=$VMYARD_SESSION" \
  -H "x-csrf-token: $VMYARD_CSRF" \
  -H "Content-Type: application/json" \
  -d '{
  "user_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}'
```

## Delete an organization

`DELETE /v1/organizations/{organization_id}`

Needs a sign-in within the last 15 minutes (`403 recent_auth_required`). Its machines are stopped (`stop_reason: organization_deleted`).

- **API key:** not accepted (`403 session_required`).
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Owner.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `organization_id` | path | `string (uuid)` | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`OrganizationDeletedDto`](/docs/api/schemas#organizationdeleteddto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | CSRF failure, `session_required`, `recent_auth_required` (sign in again within 15 minutes), or not the owner | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `subscription_active`: cancel the renewing plan first | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X DELETE "$VMYARD_API_URL/v1/organizations/$ORGANIZATION_ID" \
  -b "vmyard_session=$VMYARD_SESSION" \
  -H "x-csrf-token: $VMYARD_CSRF"
```

```json title="Response 200"
{
  "api_keys_revoked": 0,
  "channels_revoked": 0,
  "machines_stopping": 0,
  "members_removed": 0,
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "tickets_revoked": 0
}
```

## Choose the active organization

`PUT /v1/me/active-organization`

- **API key:** not accepted (`403 session_required`).
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** The signed-in user.

**Request body** (`application/json`, [`ActiveOrganizationRequest`](/docs/api/schemas#activeorganizationrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `organization_id` | `string (uuid) \| null` | No | An organization the caller belongs to, or `null` to clear it. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`ActiveOrganizationDto`](/docs/api/schemas#activeorganizationdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | CSRF failure or `session_required` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not a member of that organization | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X PUT "$VMYARD_API_URL/v1/me/active-organization" \
  -b "vmyard_session=$VMYARD_SESSION" \
  -H "x-csrf-token: $VMYARD_CSRF" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```json title="Response 200"
{
  "active_organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

---

<!-- Source: /docs/api/capacity.md -->

# Capacity (operators) API

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

- [List capacity decisions (operators)](#list-capacity-decisions-operators): `GET /v1/operator/capacity/decisions`
- [Read the capacity budget (operators)](#read-the-capacity-budget-operators): `GET /v1/operator/capacity/budget`
- [List purchases waiting for approval (operators)](#list-purchases-waiting-for-approval-operators): `GET /v1/operator/capacity/approvals`
- [Approve a server purchase (operators)](#approve-a-server-purchase-operators): `POST /v1/operator/capacity/approvals/{purchase_id}/approve`
- [Reject a server purchase (operators)](#reject-a-server-purchase-operators): `POST /v1/operator/capacity/approvals/{purchase_id}/reject`

## List capacity decisions (operators)

`GET /v1/operator/capacity/decisions`

The capacity loop's decisions, newest first.

- **Authentication:** none on this route.
- **Who:** Service operators (operator token).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | `integer` | No | 1-200, default 50. |
| `before` | query | `integer` | No | Only decisions older than this ID. |
| `X-VMYard-Operator-Token` | header | `string` | Yes | Operator token from the service configuration |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`CapacityDecisionPage`](/docs/api/schemas#capacitydecisionpage) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | operator routes are not configured | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/operator/capacity/decisions" \
  -H "X-VMYard-Operator-Token: $X_VMYARD_OPERATOR_TOKEN"
```

```json title="Response 200"
{
  "decisions": [
    {
      "action": "string",
      "at": "string",
      "dry_run": false,
      "facts": {},
      "id": 0,
      "outcome": "string",
      "reason": "string",
      "region": "string",
      "server_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
    }
  ],
  "next_before": 0
}
```

## Read the capacity budget (operators)

`GET /v1/operator/capacity/budget`

What the budget guard allows now.

- **Authentication:** none on this route.
- **Who:** Service operators (operator token).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `X-VMYard-Operator-Token` | header | `string` | Yes | Operator token from the service configuration |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`CapacityBudgetDto`](/docs/api/schemas#capacitybudgetdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | operator routes or the capacity loop are not configured | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/operator/capacity/budget" \
  -H "X-VMYard-Operator-Token: $X_VMYARD_OPERATOR_TOKEN"
```

```json title="Response 200"
{
  "allowance_micros": 0,
  "approval_threshold_micros": 0,
  "ceiling_micros": 0,
  "committed_monthly_micros": 0,
  "launch_floor_micros": 0,
  "revenue_30d_micros": 0,
  "revenue_share_bps": 0,
  "spend_30d_micros": 0
}
```

## List purchases waiting for approval (operators)

`GET /v1/operator/capacity/approvals`

Purchases waiting for an operator's approval, oldest first.

- **Authentication:** none on this route.
- **Who:** Service operators (operator token).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `X-VMYard-Operator-Token` | header | `string` | Yes | Operator token from the service configuration |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`CapacityApprovalList`](/docs/api/schemas#capacityapprovallist) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | operator routes are not configured | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/operator/capacity/approvals" \
  -H "X-VMYard-Operator-Token: $X_VMYARD_OPERATOR_TOKEN"
```

```json title="Response 200"
{
  "approvals": [
    {
      "billing": "string",
      "decided_by": "string",
      "host_id": "string",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "monthly_cost_micros": 0,
      "note": "string",
      "provider": "github",
      "reason": "string",
      "region": "string",
      "requested_at": "string",
      "setup_cost_micros": 0,
      "slots": 0,
      "state": "string"
    }
  ]
}
```

## Approve a server purchase (operators)

`POST /v1/operator/capacity/approvals/{purchase_id}/approve`

Approve a waiting purchase; the capacity loop orders it on its next
pass if the budget rules still allow it.

- **Authentication:** none on this route.
- **Who:** Service operators (operator token).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `purchase_id` | path | `string (uuid)` | Yes |  |
| `X-VMYard-Operator-Token` | header | `string` | Yes | Operator token from the service configuration |

**Request body** (`application/json`, [`CapacityApprovalRequest`](/docs/api/schemas#capacityapprovalrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `operator` | `string` | Yes | The operator deciding, recorded with the decision (1-100 characters). |
| `note` | `string \| null` | No | Optional note recorded with the decision (at most 500 characters). |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`CapacityPurchaseDto`](/docs/api/schemas#capacitypurchasedto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | operator routes are not configured or the purchase is unknown | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | the purchase is no longer waiting for approval | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/operator/capacity/approvals/$PURCHASE_ID/approve" \
  -H "X-VMYard-Operator-Token: $X_VMYARD_OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "operator": "string"
}'
```

```json title="Response 200"
{
  "billing": "string",
  "decided_by": "string",
  "host_id": "string",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "monthly_cost_micros": 0,
  "note": "string",
  "provider": "github",
  "reason": "string",
  "region": "string",
  "requested_at": "string",
  "setup_cost_micros": 0,
  "slots": 0,
  "state": "string"
}
```

## Reject a server purchase (operators)

`POST /v1/operator/capacity/approvals/{purchase_id}/reject`

Reject a waiting purchase; nothing is bought.

- **Authentication:** none on this route.
- **Who:** Service operators (operator token).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `purchase_id` | path | `string (uuid)` | Yes |  |
| `X-VMYard-Operator-Token` | header | `string` | Yes | Operator token from the service configuration |

**Request body** (`application/json`, [`CapacityApprovalRequest`](/docs/api/schemas#capacityapprovalrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `operator` | `string` | Yes | The operator deciding, recorded with the decision (1-100 characters). |
| `note` | `string \| null` | No | Optional note recorded with the decision (at most 500 characters). |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`CapacityPurchaseDto`](/docs/api/schemas#capacitypurchasedto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | operator routes are not configured or the purchase is unknown | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | the purchase is no longer waiting for approval | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/operator/capacity/approvals/$PURCHASE_ID/reject" \
  -H "X-VMYard-Operator-Token: $X_VMYARD_OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "operator": "string"
}'
```

```json title="Response 200"
{
  "billing": "string",
  "decided_by": "string",
  "host_id": "string",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "monthly_cost_micros": 0,
  "note": "string",
  "provider": "github",
  "reason": "string",
  "region": "string",
  "requested_at": "string",
  "setup_cost_micros": 0,
  "slots": 0,
  "state": "string"
}
```

---

<!-- Source: /docs/api/api-keys.md -->

# API keys API

> Create, list, rotate, and revoke organization API keys. These routes need a browser session.

- [List API keys](#list-api-keys): `GET /v1/api-keys`
- [Create an API key](#create-an-api-key): `POST /v1/api-keys`
- [Revoke an API key](#revoke-an-api-key): `DELETE /v1/api-keys/{api_key_id}`
- [Rotate an API key](#rotate-an-api-key): `POST /v1/api-keys/{api_key_id}/rotate`

## List API keys

`GET /v1/api-keys`

- **API key:** not accepted (`403 session_required`).
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member (owners and admins see all).

**Parameters**

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

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | Owners and admins see every organization key; other members see their own | [`ApiKeyPage`](/docs/api/schemas#apikeypage) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Bearer authentication (key management requires a session) | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/api-keys" \
  -b "vmyard_session=$VMYARD_SESSION" \
  -H "X-Organization-ID: $VMYARD_ORGANIZATION_ID"
```

```json title="Response 200"
{
  "items": [
    {
      "created_at": "2026-10-12T05:51:01Z",
      "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "expires_at": "2026-10-12T05:51:01Z",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "last_four": "x9Q2",
      "last_used_at": "2026-10-12T05:51:01Z",
      "name": "ci-runner",
      "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "prefix": "vmy_AbCdEfGh",
      "preset": "read_only",
      "revoked_at": "2026-10-12T05:51:01Z"
    }
  ],
  "next_cursor": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## Create an API key

`POST /v1/api-keys`

- **API key:** not accepted (`403 session_required`).
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Any member.

**Parameters**

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

**Request body** (`application/json`, [`CreateApiKeyRequest`](/docs/api/schemas#createapikeyrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | 1–64 characters. |
| `preset` | [`ApiKeyPresetDto`](/docs/api/schemas#apikeypresetdto) | Yes |  |
| `expires_in_days` | `integer` | No | 1–365. default `90`. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `201` | The secret is returned only in this response | [`ApiKeySecretDto`](/docs/api/schemas#apikeysecretdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | CSRF failure or bearer authentication (key management requires a session) | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/api-keys" \
  -b "vmyard_session=$VMYARD_SESSION" \
  -H "x-csrf-token: $VMYARD_CSRF" \
  -H "X-Organization-ID: $VMYARD_ORGANIZATION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "ci-runner",
  "preset": "use_existing",
  "expires_in_days": 30
}'
```

```json title="Response 201"
{
  "api_key": {
    "created_at": "2026-10-12T05:51:01Z",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "expires_at": "2026-10-12T05:51:01Z",
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "last_four": "x9Q2",
    "last_used_at": "2026-10-12T05:51:01Z",
    "name": "ci-runner",
    "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "prefix": "vmy_AbCdEfGh",
    "preset": "read_only",
    "revoked_at": "2026-10-12T05:51:01Z"
  },
  "secret": "vmy_…"
}
```

## Revoke an API key

`DELETE /v1/api-keys/{api_key_id}`

- **API key:** not accepted (`403 session_required`).
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** The key's creator, Owner, or Admin.

**Parameters**

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

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `204` | Revoked; repeating the request is a no-op | — |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | CSRF failure, bearer authentication, or neither the key's creator nor an owner/admin | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X DELETE "$VMYARD_API_URL/v1/api-keys/$API_KEY_ID" \
  -b "vmyard_session=$VMYARD_SESSION" \
  -H "x-csrf-token: $VMYARD_CSRF" \
  -H "X-Organization-ID: $VMYARD_ORGANIZATION_ID"
```

## Rotate an API key

`POST /v1/api-keys/{api_key_id}/rotate`

- **API key:** not accepted (`403 session_required`).
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** The key's creator, Owner, or Admin.

**Parameters**

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

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `201` | Replacement key with the same name, preset, and lifetime; the old key is revoked | [`ApiKeySecretDto`](/docs/api/schemas#apikeysecretdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | CSRF failure, bearer authentication, or neither the key's creator nor an owner/admin | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Unknown or already revoked key | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/api-keys/$API_KEY_ID/rotate" \
  -b "vmyard_session=$VMYARD_SESSION" \
  -H "x-csrf-token: $VMYARD_CSRF" \
  -H "X-Organization-ID: $VMYARD_ORGANIZATION_ID"
```

```json title="Response 201"
{
  "api_key": {
    "created_at": "2026-10-12T05:51:01Z",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "expires_at": "2026-10-12T05:51:01Z",
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "last_four": "x9Q2",
    "last_used_at": "2026-10-12T05:51:01Z",
    "name": "ci-runner",
    "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "prefix": "vmy_AbCdEfGh",
    "preset": "read_only",
    "revoked_at": "2026-10-12T05:51:01Z"
  },
  "secret": "vmy_…"
}
```

---

<!-- Source: /docs/api/identity.md -->

# Identity API

> The signed-in user or API key caller and their memberships.

- [Get the caller](#get-the-caller): `GET /v1/me`

## Get the caller

`GET /v1/me`

With an API key, the caller is the key's creator scoped to the key's organization.

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`MeDto`](/docs/api/schemas#medto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/me" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "access": "approved",
  "active_organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "email": "ada@example.com",
  "login_method_details": [
    {
      "created_at": "2026-10-12T05:51:01Z",
      "email": "ada@example.com",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "last_used_at": "2026-10-12T05:51:01Z",
      "provider": "github"
    }
  ],
  "login_methods": [
    "string"
  ],
  "memberships": [
    {
      "access": "approved",
      "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "organization_name": "string",
      "role": "owner"
    }
  ],
  "name": "dev",
  "recent_auth": false,
  "user_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "waitlist_url": "string"
}
```

---

<!-- Source: /docs/api/sign-in.md -->

# Sign-in API

> Browser sign-in with a configured provider, and sign-out.

- [List sign-in methods](#list-sign-in-methods): `GET /v1/auth/providers`
- [Start browser sign-in](#start-browser-sign-in): `GET /v1/auth/login`
- [Complete browser sign-in](#complete-browser-sign-in): `GET /v1/auth/callback`
- [Sign out](#sign-out): `POST /v1/auth/logout`

## List sign-in methods

`GET /v1/auth/providers`

The sign-in methods this service offers and its access mode, for the
sign-in page. Unauthenticated.

- **Authentication:** none on this route.
- **Who:** No authentication.

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`SignInProvidersDto`](/docs/api/schemas#signinprovidersdto) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/auth/providers"
```

```json title="Response 200"
{
  "access": "open",
  "providers": [
    {
      "default": false,
      "display_name": "string",
      "kind": "oidc",
      "name": "dev"
    }
  ],
  "waitlist_url": "string"
}
```

## Start browser sign-in

`GET /v1/auth/login`

- **Authentication:** none on this route.
- **Who:** No authentication.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `provider` | query | `string` | No | Configured sign-in method such as `google` or `github`; omitted selects the default provider. |
| `return_to` | query | `string` | No | Same-origin UI path (single leading `/`, at most 2048 bytes) to open after sign-in; invalid values become `/`. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `303` | Redirect to `<ui>/sign-in?error=unsupported_provider\|oidc_unavailable\|oidc_failed` | — |
| `307` | Redirect to the selected OIDC provider | — |

```sh title="Request"
curl "$VMYARD_API_URL/v1/auth/login"
```

## Complete browser sign-in

`GET /v1/auth/callback`

- **Authentication:** none on this route.
- **Who:** No authentication.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `code` | query | `string` | No |  |
| `state` | query | `string` | No |  |
| `error` | query | `string` | No | OAuth error from the provider; `access_denied` maps to the `access_denied` sign-in error. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `303` | Signed in (or, for a linking attempt, identity linked): redirect to the stored `return_to` on the UI origin. Failure: redirect to `<ui>/sign-in?error=access_denied\|identity_in_use\|oidc_failed\|oidc_unavailable\|session_expired\|unsupported_provider` | — |
| `500` | Internal error (`internal_error`); quote the `correlation_id`. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/auth/callback"
```

## Sign out

`POST /v1/auth/logout`

Ends the browser session. API keys cannot sign out; revoke the key instead.

- **API key:** not accepted (`403 session_required`).
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** The signed-in user.

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `204` | Session revoked | — |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Missing or invalid CSRF token, or a bearer API key (`session_required`) | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/auth/logout" \
  -b "vmyard_session=$VMYARD_SESSION" \
  -H "x-csrf-token: $VMYARD_CSRF"
```

---

<!-- Source: /docs/api/email-sign-in.md -->

# Email sign-in API

> Sign in with an emailed 6-digit code or magic link.

- [Send a sign-in code](#send-a-sign-in-code): `POST /v1/auth/email/start`
- [Verify a code](#verify-a-code): `POST /v1/auth/email/verify`
- [Complete a magic link](#complete-a-magic-link): `GET /v1/auth/email/callback`

## Send a sign-in code

`POST /v1/auth/email/start`

- **Authentication:** none on this route.
- **Who:** No authentication.

**Request body** (`application/json`, [`EmailStartRequest`](/docs/api/schemas#emailstartrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `string` | Yes |  |
| `return_to` | `string \| null` | No | Same-origin UI path to open after sign-in; invalid values become `/`. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `202` | Sent if the address can receive email; the answer never depends on whether an account exists | [`EmailStarted`](/docs/api/schemas#emailstarted) |
| `404` | `unsupported_provider`: email sign-in is not configured | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `429` | `rate_limited` per address or client IP, with Retry-After | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | `email_unavailable` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/auth/email/start" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ada@example.com",
  "return_to": "/"
}'
```

```json title="Response 202"
{
  "message": "If the address can receive email, a code is on its way."
}
```

## Verify a code

`POST /v1/auth/email/verify`

Signs in with an emailed code, creating the user on the first verified
sign-in. A code requested through `POST /v1/auth/link/email` instead
links the address to the signed-in user and needs that session's cookie
and CSRF token.

- **Authentication:** none on this route.
- **Who:** No authentication.

**Request body** (`application/json`, [`EmailVerifyRequest`](/docs/api/schemas#emailverifyrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | `string` | Yes | The 6-digit code from the email. |
| `email` | `string` | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | Signed in (session and CSRF cookies set) or address linked | [`EmailVerified`](/docs/api/schemas#emailverified) |
| `400` | `invalid_code`: wrong, expired, used, or superseded | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `401` | A linking code without a session | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | A linking code with another user's session, a missing CSRF token, or an API key | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | `unsupported_provider` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `identity_in_use`: the address is another user's sign-in method | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `429` | Too many requests; wait for `Retry-After`. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/auth/email/verify" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ada@example.com",
  "code": "123456"
}'
```

```json title="Response 200"
{
  "return_to": "string"
}
```

## Complete a magic link

`GET /v1/auth/email/callback`

Completes a magic link. It works once, within ten minutes, and only in
the browser that requested it (`vmyard_email_state`); on another device
type the code instead. A linking link also needs the requesting user's session.

- **Authentication:** none on this route.
- **Who:** No authentication.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `token` | query | `string` | No | The magic-link token from the email. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `303` | Success: redirect to the stored `return_to` on the UI origin. Failure: redirect to `<ui>/sign-in?error=session_expired\|identity_in_use\|unsupported_provider` | — |

```sh title="Request"
curl "$VMYARD_API_URL/v1/auth/email/callback"
```

---

<!-- Source: /docs/api/sign-in-methods.md -->

# Sign-in methods API

> Link another sign-in method to the signed-in user, or remove one.

- [Link a sign-in method](#link-a-sign-in-method): `POST /v1/auth/link/{provider}`
- [Remove a sign-in method](#remove-a-sign-in-method): `DELETE /v1/auth/login-methods/{login_method_id}`

## Link a sign-in method

`POST /v1/auth/link/{provider}`

Starts linking `provider` to the signed-in user. For a redirect provider
the response carries the authorization URL and a browser-bound state
cookie; for `email` a code and link are sent to the address and
`POST /v1/auth/email/verify` (with this session) completes the link.

- **API key:** not accepted (`403 session_required`).
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** The signed-in user.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `provider` | path | `string` | Yes | Configured provider such as `github`, `google`, or `email` |

**Request body** (`application/json`, [`LinkRequest`](/docs/api/schemas#linkrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `string \| null` | No | Required for `email`, refused for other providers. |
| `return_to` | `string \| null` | No | Same-origin UI path to open when the provider flow completes; invalid values become `/`. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | Navigate to `authorization_url` | [`LinkStarted`](/docs/api/schemas#linkstarted) |
| `202` | Email linking: a code was sent if the address can receive email | [`EmailStarted`](/docs/api/schemas#emailstarted) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | `csrf_invalid`, `session_required` (API key), or `recent_auth_required` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | `unsupported_provider` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `429` | Too many requests; wait for `Retry-After`. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | Not available on this server. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/auth/link/$PROVIDER" \
  -b "vmyard_session=$VMYARD_SESSION" \
  -H "x-csrf-token: $VMYARD_CSRF" \
  -H "Content-Type: application/json" \
  -d '{
  "return_to": "/"
}'
```

```json title="Response 200"
{
  "authorization_url": "string"
}
```

## Remove a sign-in method

`DELETE /v1/auth/login-methods/{login_method_id}`

Removes one of the signed-in user's sign-in methods. The last method
cannot be removed. Existing sessions stay valid.

- **API key:** not accepted (`403 session_required`).
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** The signed-in user.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `login_method_id` | path | `string (uuid)` | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `204` | Removed | — |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | `csrf_invalid`, `session_required` (API key), or `recent_auth_required` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not one of this user's methods | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `last_login_method` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X DELETE "$VMYARD_API_URL/v1/auth/login-methods/$LOGIN_METHOD_ID" \
  -b "vmyard_session=$VMYARD_SESSION" \
  -H "x-csrf-token: $VMYARD_CSRF"
```

---

<!-- Source: /docs/api/operator.md -->

# Operator API

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

- [Suspend an organization (operators)](#suspend-an-organization-operators): `POST /v1/operator/organizations/{organization_id}/suspend`
- [Lift a suspension (operators)](#lift-a-suspension-operators): `POST /v1/operator/organizations/{organization_id}/resume`
- [List abuse flags (operators)](#list-abuse-flags-operators): `GET /v1/operator/abuse-flags`
- [Resolve an abuse flag (operators)](#resolve-an-abuse-flag-operators): `POST /v1/operator/abuse-flags/{flag_id}/resolve`

## Suspend an organization (operators)

`POST /v1/operator/organizations/{organization_id}/suspend`

Suspend an organization (the kill switch): its machines are stopped, new
creates, starts, and restarts are refused, nothing may run commands or
open terminals or desktops in it (`403 organization_suspended`), and its
open terminal and desktop tickets and channels are revoked. Its data is
kept. Suspending a suspended organization changes nothing.

- **Authentication:** none on this route.
- **Who:** Service operators (operator token).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `organization_id` | path | `string (uuid)` | Yes |  |
| `X-VMYard-Operator-Token` | header | `string` | Yes | Operator token from the service configuration |

**Request body** (`application/json`, [`OperatorActionRequest`](/docs/api/schemas#operatoractionrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `operator` | `string` | Yes | The individual operator acting (a name or work email), recorded in the audit log; 1-200 characters. |
| `reason` | `string` | Yes | Why; recorded in the audit log, 1-500 characters. A suspension's reason is shown to operators only. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`SuspensionDto`](/docs/api/schemas#suspensiondto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | operator access is not configured or the organization is unknown | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/operator/organizations/$ORGANIZATION_ID/suspend" \
  -H "X-VMYard-Operator-Token: $X_VMYARD_OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "operator": "string",
  "reason": "string"
}'
```

```json title="Response 200"
{
  "already_suspended": false,
  "channels_revoked": 0,
  "machines_stopping": 0,
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "reason": "string",
  "suspended_at": "string",
  "tickets_revoked": 0
}
```

## Lift a suspension (operators)

`POST /v1/operator/organizations/{organization_id}/resume`

Lift a suspension. Machines it stopped stay stopped until members start
them.

- **Authentication:** none on this route.
- **Who:** Service operators (operator token).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `organization_id` | path | `string (uuid)` | Yes |  |
| `X-VMYard-Operator-Token` | header | `string` | Yes | Operator token from the service configuration |

**Request body** (`application/json`, [`OperatorActionRequest`](/docs/api/schemas#operatoractionrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `operator` | `string` | Yes | The individual operator acting (a name or work email), recorded in the audit log; 1-200 characters. |
| `reason` | `string` | Yes | Why; recorded in the audit log, 1-500 characters. A suspension's reason is shown to operators only. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`ResumeDto`](/docs/api/schemas#resumedto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | operator access is not configured or the organization is unknown | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/operator/organizations/$ORGANIZATION_ID/resume" \
  -H "X-VMYard-Operator-Token: $X_VMYARD_OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "operator": "string",
  "reason": "string"
}'
```

```json title="Response 200"
{
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "resumed": false
}
```

## List abuse flags (operators)

`GET /v1/operator/abuse-flags`

The sustained-CPU guard's flags, newest first, for review.

- **Authentication:** none on this route.
- **Who:** Service operators (operator token).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `status` | query | [`AbuseFlagStatusDto`](/docs/api/schemas#abuseflagstatusdto) | No | `open` (default) or `all`. |
| `limit` | query | `integer` | No | 1-500, default 100; newest first. |
| `X-VMYard-Operator-Token` | header | `string` | Yes | Operator token from the service configuration |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`AbuseFlagPage`](/docs/api/schemas#abuseflagpage) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | operator access is not configured | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/operator/abuse-flags" \
  -H "X-VMYard-Operator-Token: $X_VMYARD_OPERATOR_TOKEN"
```

```json title="Response 200"
{
  "items": [
    {
      "action": "string",
      "created_at": "string",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "kind": "string",
      "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "min_cpu_permille": 0,
      "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "resolution": "string",
      "resolution_note": "string",
      "resolved_at": "string",
      "stop_operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "window_seconds": 0,
      "window_start": "string"
    }
  ]
}
```

## Resolve an abuse flag (operators)

`POST /v1/operator/abuse-flags/{flag_id}/resolve`

Resolve a flag after review. A resolved flag stays resolved; a second
resolution changes nothing and returns it as it is.

- **Authentication:** none on this route.
- **Who:** Service operators (operator token).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `flag_id` | path | `string (uuid)` | Yes |  |
| `X-VMYard-Operator-Token` | header | `string` | Yes | Operator token from the service configuration |

**Request body** (`application/json`, [`ResolveAbuseFlagRequest`](/docs/api/schemas#resolveabuseflagrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `note` | `string` | Yes | What the review found, 1-500 characters. |
| `operator` | `string` | Yes | The individual operator acting, 1-200 characters. |
| `resolution` | [`FlagResolutionDto`](/docs/api/schemas#flagresolutiondto) | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`AbuseFlagDto`](/docs/api/schemas#abuseflagdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | operator access is not configured or the flag is unknown | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/operator/abuse-flags/$FLAG_ID/resolve" \
  -H "X-VMYard-Operator-Token: $X_VMYARD_OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "note": "string",
  "operator": "string",
  "resolution": "dismissed"
}'
```

```json title="Response 200"
{
  "action": "string",
  "created_at": "string",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "kind": "string",
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "min_cpu_permille": 0,
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "resolution": "string",
  "resolution_note": "string",
  "resolved_at": "string",
  "stop_operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "window_seconds": 0,
  "window_start": "string"
}
```

---

<!-- Source: /docs/api/device-authorization.md -->

# Device authorization API

> The RFC 8628 device grant that vy login uses to receive an API key.

- [Request a device code](#request-a-device-code): `POST /v1/auth/device/code`
- [Poll for the API key](#poll-for-the-api-key): `POST /v1/auth/device/token`
- [Look up a device request](#look-up-a-device-request): `GET /v1/auth/device`
- [Approve a device](#approve-a-device): `POST /v1/auth/device/approve`
- [Deny a device](#deny-a-device): `POST /v1/auth/device/deny`

## Request a device code

`POST /v1/auth/device/code`

- **Authentication:** none on this route.
- **Who:** No authentication.

**Request body** (`application/json`, [`DeviceCodeRequest`](/docs/api/schemas#devicecoderequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `client_name` | `string \| null` | No | Shown to the approving user, such as `vy on build-host`; 1–64 characters. Defaults to `vy CLI`. |
| `scope` | [`null \| ApiKeyPresetDto`](/docs/api/schemas#apikeypresetdto) | No | The preset the CLI asks for; the approving user may choose another. Defaults to `create_and_use`. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | Show `user_code` and `verification_uri`, then poll `/v1/auth/device/token` every `interval` seconds | [`DeviceCodeResponse`](/docs/api/schemas#devicecoderesponse) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `429` | Too many requests; wait for `Retry-After`. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/auth/device/code" \
  -H "Content-Type: application/json" \
  -d '{
  "client_name": "vy on build-host",
  "scope": "use_existing"
}'
```

```json title="Response 200"
{
  "device_code": "string",
  "expires_in": 0,
  "interval": 0,
  "user_code": "BCDF-GHJK",
  "verification_uri": "https://console.example.com/device",
  "verification_uri_complete": "https://console.example.com/device?user_code=BCDF-GHJK"
}
```

## Poll for the API key

`POST /v1/auth/device/token`

Polls for the API key. Errors use the RFC 8628 shape, not problem details.

- **Authentication:** none on this route.
- **Who:** No authentication.

**Request body** (`application/json`, [`DeviceTokenRequest`](/docs/api/schemas#devicetokenrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `device_code` | `string` | Yes |  |
| `grant_type` | `string` | Yes | `urn:ietf:params:oauth:grant-type:device_code` |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | Approved: the new API key, returned exactly once | [`DeviceTokenResponse`](/docs/api/schemas#devicetokenresponse) |
| `400` | `authorization_pending`, `slow_down` (add 5 s to the interval), `access_denied`, `expired_token`, `invalid_grant`, `invalid_request`, or `unsupported_grant_type` | [`DeviceTokenError`](/docs/api/schemas#devicetokenerror) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/auth/device/token" \
  -H "Content-Type: application/json" \
  -d '{
  "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
  "device_code": "<device_code>"
}'
```

```json title="Response 200"
{
  "access_token": "vmy_…",
  "api_key": {
    "created_at": "2026-10-12T05:51:01Z",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "expires_at": "2026-10-12T05:51:01Z",
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "last_four": "x9Q2",
    "last_used_at": "2026-10-12T05:51:01Z",
    "name": "ci-runner",
    "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "prefix": "vmy_AbCdEfGh",
    "preset": "read_only",
    "revoked_at": "2026-10-12T05:51:01Z"
  },
  "expires_in": 0,
  "scope": "read_only",
  "token_type": "Bearer"
}
```

## Look up a device request

`GET /v1/auth/device`

Shows a pending request so the user can check the device name and
requested scope before approving.

- **API key:** not accepted (`403 session_required`).
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any signed-in user.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `user_code` | query | `string` | Yes | The code the user typed; case, spaces, and dashes are ignored. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`DeviceAuthorizationDto`](/docs/api/schemas#deviceauthorizationdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | `session_required` for API keys | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Unknown, expired, or already decided code | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `429` | Too many requests; wait for `Retry-After`. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/auth/device?user_code=BCDF-GHJK" \
  -b "vmyard_session=$VMYARD_SESSION"
```

```json title="Response 200"
{
  "client_name": "vy on build-host",
  "expires_at": "2026-10-12T05:51:01Z",
  "requested_scope": "read_only",
  "user_code": "BCDF-GHJK"
}
```

## Approve a device

`POST /v1/auth/device/approve`

Approves a pending device for the `X-Organization-ID` organization. The
key is minted for this user when the device next polls, so it is bound by
the user's role there like any other key.

- **API key:** not accepted (`403 session_required`).
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Any member of the chosen organization.

**Parameters**

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

**Request body** (`application/json`, [`DeviceApproveRequest`](/docs/api/schemas#deviceapproverequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `user_code` | `string` | Yes |  |
| `expires_in_days` | `integer \| null` | No | Key lifetime, 1–90 days; defaults to 90. 1–90. default `90`. |
| `name` | `string \| null` | No | Key name, 1–64 characters; defaults to `vy: <client_name>`. |
| `preset` | [`null \| ApiKeyPresetDto`](/docs/api/schemas#apikeypresetdto) | No | The key's preset; defaults to the requested scope. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`DeviceApproved`](/docs/api/schemas#deviceapproved) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | CSRF failure or an API key (`session_required`) | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Unknown, expired, or already decided code, or not a member of the organization | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | Invalid request (`invalid_request`); `field_errors` names the fields. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `429` | Too many requests; wait for `Retry-After`. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/auth/device/approve" \
  -b "vmyard_session=$VMYARD_SESSION" \
  -H "x-csrf-token: $VMYARD_CSRF" \
  -H "X-Organization-ID: $VMYARD_ORGANIZATION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "user_code": "BCDF-GHJK",
  "preset": "use_existing",
  "expires_in_days": 30,
  "name": "vy: build-host"
}'
```

```json title="Response 200"
{
  "expires_in_days": 0,
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "preset": "read_only",
  "user_code": "BCDF-GHJK"
}
```

## Deny a device

`POST /v1/auth/device/deny`

- **API key:** not accepted (`403 session_required`).
- **Browser session:** the `vmyard_session` cookie and the `x-csrf-token` header.
- **Who:** Any signed-in user.

**Parameters**

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

**Request body** (`application/json`, [`DeviceDecisionRequest`](/docs/api/schemas#devicedecisionrequest))

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `user_code` | `string` | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `204` | Denied; the device's next poll gets `access_denied` | — |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `403` | Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `429` | Too many requests; wait for `Retry-After`. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl -X POST "$VMYARD_API_URL/v1/auth/device/deny" \
  -b "vmyard_session=$VMYARD_SESSION" \
  -H "x-csrf-token: $VMYARD_CSRF" \
  -H "X-Organization-ID: $VMYARD_ORGANIZATION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "user_code": "BCDF-GHJK"
}'
```

---

<!-- Source: /docs/api/schemas.md -->

# Schemas

> Every request and response body, with field types and constraints.

Every request and response body in the API, generated from the OpenAPI document. Fields marked required are always present in responses and must be sent in requests.

## AbuseFlagDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `action` | `string` | Yes | `stopped` (a trial machine) or `flagged` (a paid machine, still running). |
| `created_at` | `string` | Yes |  |
| `id` | `string (uuid)` | Yes |  |
| `kind` | `string` | Yes | `sustained_cpu`: every vCPU at full load for the whole window. |
| `machine_id` | `string (uuid)` | Yes |  |
| `min_cpu_permille` | `integer` | Yes | Lowest per-minute CPU use in the window, in thousandths of the machine's vCPU limit (1000 = every vCPU fully used). |
| `organization_id` | `string (uuid)` | Yes |  |
| `window_seconds` | `integer` | Yes |  |
| `window_start` | `string` | Yes |  |
| `resolution` | `string \| null` | No |  |
| `resolution_note` | `string \| null` | No |  |
| `resolved_at` | `string \| null` | No |  |
| `stop_operation_id` | `string (uuid) \| null` | No |  |

```json title="Example"
{
  "action": "string",
  "created_at": "string",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "kind": "string",
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "min_cpu_permille": 0,
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "resolution": "string",
  "resolution_note": "string",
  "resolved_at": "string",
  "stop_operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "window_seconds": 0,
  "window_start": "string"
}
```

## AbuseFlagPage

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [`AbuseFlagDto[]`](/docs/api/schemas#abuseflagdto) | Yes |  |

```json title="Example"
{
  "items": [
    {
      "action": "string",
      "created_at": "string",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "kind": "string",
      "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "min_cpu_permille": 0,
      "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "resolution": "string",
      "resolution_note": "string",
      "resolved_at": "string",
      "stop_operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "window_seconds": 0,
      "window_start": "string"
    }
  ]
}
```

## AbuseFlagStatusDto

One of: `open`, `all`.

## AcceptInvitationRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | `string` | Yes |  |

```json title="Example"
{
  "token": "string"
}
```

## AccessDto

Whether an account (or an organization) may spend money while the service is invite-only. With open access everything is `approved`.

One of: `approved`, `waitlisted`.

## AccessGrantCreatedDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created` | `boolean` | Yes | False when an active grant already named this person (returned as it is). |
| `grant` | [`AccessGrantDto`](/docs/api/schemas#accessgrantdto) | Yes |  |

```json title="Example"
{
  "created": false,
  "grant": {
    "created_at": "string",
    "credited_at": "string",
    "credited_organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "email": "ada@example.com",
    "granted_by": "string",
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "initial_credit_micros": 0,
    "provider": "github",
    "reason": "string",
    "revoke_reason": "string",
    "revoked_at": "string",
    "revoked_by": "string",
    "subject": "string"
  }
}
```

## AccessGrantDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | `string` | Yes |  |
| `granted_by` | `string` | Yes |  |
| `id` | `string (uuid)` | Yes |  |
| `credited_at` | `string \| null` | No |  |
| `credited_organization_id` | `string (uuid) \| null` | No | Where the initial credit went, once credited. |
| `email` | `string \| null` | No | Set for a grant by verified email. |
| `initial_credit_micros` | `integer \| null` | No |  |
| `provider` | `string \| null` | No | Set (with `subject`) for a grant of one sign-in identity. |
| `reason` | `string \| null` | No |  |
| `revoke_reason` | `string \| null` | No |  |
| `revoked_at` | `string \| null` | No |  |
| `revoked_by` | `string \| null` | No |  |
| `subject` | `string \| null` | No |  |

```json title="Example"
{
  "created_at": "string",
  "credited_at": "string",
  "credited_organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "email": "ada@example.com",
  "granted_by": "string",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "initial_credit_micros": 0,
  "provider": "github",
  "reason": "string",
  "revoke_reason": "string",
  "revoked_at": "string",
  "revoked_by": "string",
  "subject": "string"
}
```

## AccessGrantPage

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [`AccessGrantDto[]`](/docs/api/schemas#accessgrantdto) | Yes |  |

```json title="Example"
{
  "items": [
    {
      "created_at": "string",
      "credited_at": "string",
      "credited_organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "email": "ada@example.com",
      "granted_by": "string",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "initial_credit_micros": 0,
      "provider": "github",
      "reason": "string",
      "revoke_reason": "string",
      "revoked_at": "string",
      "revoked_by": "string",
      "subject": "string"
    }
  ]
}
```

## AccessModeDto

One of: `open`, `invite_only`.

## ActiveOrganizationDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `active_organization_id` | `string (uuid) \| null` | No |  |

```json title="Example"
{
  "active_organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## ActiveOrganizationRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `organization_id` | `string (uuid) \| null` | No | An organization the caller belongs to, or `null` to clear it. |

```json title="Example"
{
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## AgentAttachmentRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `content_base64` | `string` | Yes | The file's bytes (standard base64), at most 8 MiB decoded. |
| `name` | `string` | Yes | The file name the agent sees: 1-128 bytes, one path component. |
| `media_type` | `string \| null` | No | `type/subtype`; `image/*` attachments are also passed to the agent as images where it accepts them. |

```json title="Example"
{
  "content_base64": "string",
  "media_type": "string",
  "name": "dev"
}
```

## AgentConversationDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | `string (date-time)` | Yes |  |
| `events_url` | `string` | Yes |  |
| `id` | `string (uuid)` | Yes |  |
| `machine_id` | `string (uuid)` | Yes |  |
| `provider` | [`AgentProviderDto`](/docs/api/schemas#agentproviderdto) | Yes |  |
| `status` | [`AgentConversationStatusDto`](/docs/api/schemas#agentconversationstatusdto) | Yes |  |
| `turn_count` | `integer` | Yes |  |
| `updated_at` | `string (date-time)` | Yes |  |
| `latest_turn` | [`null \| AgentTurnDto`](/docs/api/schemas#agentturndto) | No |  |

```json title="Example"
{
  "created_at": "2026-10-12T05:51:01Z",
  "events_url": "string",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "latest_turn": {
    "conversation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "created_at": "2026-10-12T05:51:01Z",
    "error_code": "string",
    "events_url": "string",
    "exit_code": 0,
    "finished_at": "2026-10-12T05:51:01Z",
    "interrupt_requested": false,
    "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "model": "string",
    "provider": "claude",
    "reasoning_effort": "minimal",
    "resume": false,
    "started_at": "2026-10-12T05:51:01Z",
    "status": "starting",
    "turn_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
  },
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "provider": "claude",
  "status": "idle",
  "turn_count": 0,
  "updated_at": "2026-10-12T05:51:01Z"
}
```

## AgentConversationListDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `conversations` | [`AgentConversationDto[]`](/docs/api/schemas#agentconversationdto) | Yes | Newest first. |
| `next_cursor` | `string (uuid) \| null` | No | Pass as `cursor` for the next page; absent on the last page. |

```json title="Example"
{
  "conversations": [
    {
      "created_at": "2026-10-12T05:51:01Z",
      "events_url": "string",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "latest_turn": {
        "conversation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "created_at": "2026-10-12T05:51:01Z",
        "error_code": "string",
        "events_url": "string",
        "exit_code": 0,
        "finished_at": "2026-10-12T05:51:01Z",
        "interrupt_requested": false,
        "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "model": "string",
        "provider": "claude",
        "reasoning_effort": "minimal",
        "resume": false,
        "started_at": "2026-10-12T05:51:01Z",
        "status": "starting",
        "turn_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
      },
      "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "provider": "claude",
      "status": "idle",
      "turn_count": 0,
      "updated_at": "2026-10-12T05:51:01Z"
    }
  ],
  "next_cursor": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## AgentConversationStatusDto

One of: `idle`, `running`.

## AgentEventDto

One event, as the runner normalised it from the agent. Guest data: fields hold what code in the machine wrote, bounded (text fields at most 16 KiB, events at most 64 KiB) and with credential values redacted by the runner.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seq` | `integer` | Yes | 1, 2, ... across the conversation's turns. |
| `time_ms` | `integer` | Yes | When the runner wrote it (milliseconds since the Unix epoch). |
| `turn_id` | `string` | Yes |  |
| `type` | [`AgentEventTypeDto`](/docs/api/schemas#agenteventtypedto) | Yes |  |
| `code` | `string \| null` | No |  |
| `id` | `string \| null` | No |  |
| `input` | `string \| null` | No |  |
| `input_id` | `string \| null` | No |  |
| `is_error` | `boolean \| null` | No |  |
| `kind` | [`null \| AgentInputEventKindDto`](/docs/api/schemas#agentinputeventkinddto) | No |  |
| `message` | `string \| null` | No |  |
| `model` | `string \| null` | No |  |
| `name` | `string \| null` | No |  |
| `outcome` | [`null \| AgentTurnOutcomeDto`](/docs/api/schemas#agentturnoutcomedto) | No |  |
| `output` | `string \| null` | No |  |
| `provider` | [`null \| AgentProviderDto`](/docs/api/schemas#agentproviderdto) | No |  |
| `reasoning_effort` | [`null \| ReasoningEffortDto`](/docs/api/schemas#reasoningeffortdto) | No |  |
| `restarted` | `boolean \| null` | No |  |
| `result` | `string \| null` | No |  |
| `resumed` | `boolean \| null` | No |  |
| `session_id` | `string \| null` | No |  |
| `text` | `string \| null` | No |  |
| `usage` | [`null \| AgentUsageDto`](/docs/api/schemas#agentusagedto) | No |  |

```json title="Example"
{
  "code": "string",
  "id": "string",
  "input": "string",
  "input_id": "string",
  "is_error": false,
  "kind": "prompt",
  "message": "string",
  "model": "string",
  "name": "dev",
  "outcome": "completed",
  "output": "string",
  "provider": "claude",
  "reasoning_effort": "minimal",
  "restarted": false,
  "result": "string",
  "resumed": false,
  "seq": 0,
  "session_id": "string",
  "text": "string",
  "time_ms": 0,
  "turn_id": "string",
  "type": "turn_started",
  "usage": {
    "cached_input_tokens": 0,
    "cost_micro_usd": 0,
    "input_tokens": 0,
    "output_tokens": 0
  }
}
```

## AgentEventsDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `active` | `boolean` | Yes | A turn is starting or running: more events are coming. |
| `conversation_id` | `string (uuid)` | Yes |  |
| `cursor` | `integer` | Yes | Pass back as `cursor` to continue after these events. |
| `events` | [`AgentEventDto[]`](/docs/api/schemas#agenteventdto) | Yes |  |
| `latest_turn` | [`null \| AgentTurnDto`](/docs/api/schemas#agentturndto) | No | The conversation's latest turn, as last observed. |

```json title="Example"
{
  "active": false,
  "conversation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "cursor": 0,
  "events": [
    {
      "code": "string",
      "id": "string",
      "input": "string",
      "input_id": "string",
      "is_error": false,
      "kind": "prompt",
      "message": "string",
      "model": "string",
      "name": "dev",
      "outcome": "completed",
      "output": "string",
      "provider": "claude",
      "reasoning_effort": "minimal",
      "restarted": false,
      "result": "string",
      "resumed": false,
      "seq": 0,
      "session_id": "string",
      "text": "string",
      "time_ms": 0,
      "turn_id": "string",
      "type": "turn_started",
      "usage": {
        "cached_input_tokens": 0,
        "cost_micro_usd": 0,
        "input_tokens": 0,
        "output_tokens": 0
      }
    }
  ],
  "latest_turn": {
    "conversation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "created_at": "2026-10-12T05:51:01Z",
    "error_code": "string",
    "events_url": "string",
    "exit_code": 0,
    "finished_at": "2026-10-12T05:51:01Z",
    "interrupt_requested": false,
    "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "model": "string",
    "provider": "claude",
    "reasoning_effort": "minimal",
    "resume": false,
    "started_at": "2026-10-12T05:51:01Z",
    "status": "starting",
    "turn_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
  }
}
```

## AgentEventTypeDto

One of: `turn_started`, `session`, `input_accepted`, `text_delta`, `thinking_delta`, `message`, `tool_call`, `tool_result`, `usage`, `error`, `turn_end`.

## AgentInputAccepted

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `conversation_id` | `string (uuid)` | Yes |  |
| `input_id` | `string (uuid)` | Yes | The input's ID; the agent confirms it with an `input_accepted` event carrying this `input_id`. |
| `kind` | [`AgentInputKindDto`](/docs/api/schemas#agentinputkinddto) | Yes |  |
| `turn_id` | `string (uuid)` | Yes |  |
| `stopped` | `boolean \| null` | No | A forced interrupt killed the runner (`false` when it had already ended); absent otherwise. |

```json title="Example"
{
  "conversation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "input_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "kind": "steer",
  "stopped": false,
  "turn_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## AgentInputEventKindDto

One of: `prompt`, `steer`, `interrupt`.

## AgentInputKindDto

One of: `steer`, `interrupt`.

## AgentInterruptRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `conversation_id` | `string (uuid)` | Yes |  |
| `force` | `boolean` | No | Also kill the runner and the agent at once instead of letting the agent stop on its own (it gets 10 s, then SIGTERM, then SIGKILL). |

```json title="Example"
{
  "conversation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "force": false
}
```

## AgentModelsDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `models` | [`ProviderModelDto[]`](/docs/api/schemas#providermodeldto) | Yes | Newest first; an empty list means the agent's own default. |
| `provider` | [`AgentProviderDto`](/docs/api/schemas#agentproviderdto) | Yes |  |
| `reasoning_efforts` | [`ReasoningEffortDto[]`](/docs/api/schemas#reasoningeffortdto) | Yes |  |

```json title="Example"
{
  "models": [
    {
      "attachments": false,
      "context_tokens": 0,
      "id": "string",
      "name": "dev",
      "provider": "anthropic",
      "reasoning": false,
      "release_date": "string"
    }
  ],
  "provider": "claude",
  "reasoning_efforts": [
    "minimal"
  ]
}
```

## AgentPromptRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `attachments` | [`AgentAttachmentRequest[]`](/docs/api/schemas#agentattachmentrequest) | No | At most 16 files, 16 MiB together, written to the machine for the agent to read. |
| `conversation_id` | `string (uuid) \| null` | No | Continue this conversation; omit to start a new one. |
| `model` | `string \| null` | No | A model the agent accepts (see `GET /v1/provider-models`); the agent's default when omitted. Pi takes `provider/model`. |
| `provider` | [`null \| AgentProviderDto`](/docs/api/schemas#agentproviderdto) | No | Required for a new conversation; a conversation keeps its provider. |
| `reasoning_effort` | [`null \| ReasoningEffortDto`](/docs/api/schemas#reasoningeffortdto) | No |  |
| `text` | `string` | No | The prompt, at most 256 KiB. A prompt needs text or an attachment. |

```json title="Example"
{
  "attachments": [
    {
      "content_base64": "string",
      "media_type": "string",
      "name": "dev"
    }
  ],
  "conversation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "model": "string",
  "provider": "claude",
  "reasoning_effort": "minimal",
  "text": "Add a health check endpoint and run the tests."
}
```

## AgentProviderDto

One of: `claude`, `codex`, `pi`.

## AgentSteerRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `conversation_id` | `string (uuid)` | Yes |  |
| `text` | `string` | Yes | More instructions for the running turn, at most 256 KiB. |

```json title="Example"
{
  "conversation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "text": "string"
}
```

## AgentTurnDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `conversation_id` | `string (uuid)` | Yes |  |
| `created_at` | `string (date-time)` | Yes |  |
| `events_url` | `string` | Yes | Follow the conversation's events. |
| `interrupt_requested` | `boolean` | Yes |  |
| `machine_id` | `string (uuid)` | Yes |  |
| `provider` | [`AgentProviderDto`](/docs/api/schemas#agentproviderdto) | Yes |  |
| `resume` | `boolean` | Yes | The turn continues the conversation's earlier turns. |
| `status` | [`AgentTurnStatusDto`](/docs/api/schemas#agentturnstatusdto) | Yes |  |
| `turn_id` | `string (uuid)` | Yes |  |
| `error_code` | `string \| null` | No | Why a failed turn failed: `agent_failed`, `invalid_turn`, `runner_failed`, `runner_killed`, `turn_lost`, `machine_stopped`, or `agents_unavailable`. |
| `exit_code` | `integer \| null` | No | The runner's exit status, once it exited. |
| `finished_at` | `string (date-time) \| null` | No |  |
| `model` | `string \| null` | No |  |
| `reasoning_effort` | [`null \| ReasoningEffortDto`](/docs/api/schemas#reasoningeffortdto) | No |  |
| `started_at` | `string (date-time) \| null` | No |  |

```json title="Example"
{
  "conversation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "created_at": "2026-10-12T05:51:01Z",
  "error_code": "string",
  "events_url": "string",
  "exit_code": 0,
  "finished_at": "2026-10-12T05:51:01Z",
  "interrupt_requested": false,
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "model": "string",
  "provider": "claude",
  "reasoning_effort": "minimal",
  "resume": false,
  "started_at": "2026-10-12T05:51:01Z",
  "status": "starting",
  "turn_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## AgentTurnOutcomeDto

One of: `completed`, `failed`, `interrupted`.

## AgentTurnStatusDto

One of: `starting`, `running`, `completed`, `failed`, `interrupted`.

## AgentUsageDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cached_input_tokens` | `integer \| null` | No |  |
| `cost_micro_usd` | `integer \| null` | No | The agent's own cost estimate, in millionths of a US dollar. |
| `input_tokens` | `integer \| null` | No |  |
| `output_tokens` | `integer \| null` | No |  |

```json title="Example"
{
  "cached_input_tokens": 0,
  "cost_micro_usd": 0,
  "input_tokens": 0,
  "output_tokens": 0
}
```

## AlertPreferenceDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `available` | `boolean` | Yes | Whether the control plane raises this alert today (every type but `product_announcements`, which people send). |
| `customized` | `boolean` | Yes | The member chose `enabled` instead of the role default. |
| `default_enabled` | `boolean` | Yes | What the member's role receives without a choice. |
| `description` | `string` | Yes |  |
| `enabled` | `boolean` | Yes | Whether this member receives the alert. |
| `type` | `string` | Yes | `balance_exhausted`, `auto_refill_failed`, `machine_unresponsive`, `machine_stop_failed`, `snapshot_failed`, `disk_almost_full`, `disk_full`, `operation_failed`, `auto_stop`, `billing_stop`, `idle_sleep`, `capacity`, or `product_announcements`. |

```json title="Example"
{
  "available": false,
  "customized": false,
  "default_enabled": false,
  "description": "A machine could not be stopped.",
  "enabled": false,
  "type": "machine_stop_failed"
}
```

## ApiKeyDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | `string (date-time)` | Yes |  |
| `created_by` | `string (uuid)` | Yes |  |
| `expires_at` | `string (date-time)` | Yes |  |
| `id` | `string (uuid)` | Yes |  |
| `last_four` | `string` | Yes |  |
| `name` | `string` | Yes |  |
| `organization_id` | `string (uuid)` | Yes |  |
| `prefix` | `string` | Yes | The first 12 characters of the secret, for identification only. |
| `preset` | [`ApiKeyPresetDto`](/docs/api/schemas#apikeypresetdto) | Yes |  |
| `last_used_at` | `string (date-time) \| null` | No |  |
| `revoked_at` | `string (date-time) \| null` | No |  |

```json title="Example"
{
  "created_at": "2026-10-12T05:51:01Z",
  "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "expires_at": "2026-10-12T05:51:01Z",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "last_four": "x9Q2",
  "last_used_at": "2026-10-12T05:51:01Z",
  "name": "ci-runner",
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "prefix": "vmy_AbCdEfGh",
  "preset": "read_only",
  "revoked_at": "2026-10-12T05:51:01Z"
}
```

## ApiKeyPage

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [`ApiKeyDto[]`](/docs/api/schemas#apikeydto) | Yes |  |
| `next_cursor` | `string (uuid) \| null` | No |  |

```json title="Example"
{
  "items": [
    {
      "created_at": "2026-10-12T05:51:01Z",
      "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "expires_at": "2026-10-12T05:51:01Z",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "last_four": "x9Q2",
      "last_used_at": "2026-10-12T05:51:01Z",
      "name": "ci-runner",
      "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "prefix": "vmy_AbCdEfGh",
      "preset": "read_only",
      "revoked_at": "2026-10-12T05:51:01Z"
    }
  ],
  "next_cursor": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## ApiKeyPresetDto

One of: `read_only`, `use_existing`, `create_and_use`, `full_access`.

## ApiKeySecretDto

Returned once on creation or rotation; the secret is never retrievable again.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `api_key` | [`ApiKeyDto`](/docs/api/schemas#apikeydto) | Yes |  |
| `secret` | `string` | Yes |  |

```json title="Example"
{
  "api_key": {
    "created_at": "2026-10-12T05:51:01Z",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "expires_at": "2026-10-12T05:51:01Z",
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "last_four": "x9Q2",
    "last_used_at": "2026-10-12T05:51:01Z",
    "name": "ci-runner",
    "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "prefix": "vmy_AbCdEfGh",
    "preset": "read_only",
    "revoked_at": "2026-10-12T05:51:01Z"
  },
  "secret": "vmy_…"
}
```

## AppliedDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `credit_micros` | `integer` | Yes |  |
| `plan_micros` | `integer` | Yes |  |
| `trial_micros` | `integer` | Yes |  |

```json title="Example"
{
  "credit_micros": 0,
  "plan_micros": 0,
  "trial_micros": 0
}
```

## ApproveWaitlistRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `operator` | `string` | Yes | The individual operator acting, 1-200 characters. |
| `initial_credit_micros` | `integer \| null` | No | Credits from VMYard granted once to the person's own organization (now if they already signed in, else at their first sign-in). Defaults to the service's `access.initial_credit_micros`; 0 grants none. |
| `notify` | `boolean \| null` | No | Send the "you're in" email (default true). |
| `reason` | `string \| null` | No | Why, 1-500 characters; optional. |

```json title="Example"
{
  "initial_credit_micros": 0,
  "notify": false,
  "operator": "string",
  "reason": "string"
}
```

## AutoRefillChargeDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micros` | `integer` | Yes |  |
| `created_at` | `string` | Yes |  |
| `credit_packs` | `integer` | Yes |  |
| `id` | `string (uuid)` | Yes |  |
| `status` | `string` | Yes | `pending`, `submitted` (waiting for the provider's confirmation), `succeeded`, or `failed`. |
| `failure_code` | `string \| null` | No | Provider decline code such as `insufficient_funds`, `authentication_required`, or `no_payment_method`. |

```json title="Example"
{
  "amount_micros": 0,
  "created_at": "string",
  "credit_packs": 0,
  "failure_code": "string",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "status": "string"
}
```

## AutoRefillDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micros` | `integer` | Yes |  |
| `charged_this_month_micros` | `integer` | Yes |  |
| `consecutive_failures` | `integer` | Yes | Failed charges since the last success; refill turns off at 3. |
| `credit_packs` | `integer` | Yes | $20 packs bought per refill. |
| `enabled` | `boolean` | Yes |  |
| `monthly_cap_micros` | `integer` | Yes | Most refill charges per UTC calendar month. |
| `threshold_micros` | `integer` | Yes | Refill when the balance (trial + plan + credits) drops below this. |
| `disabled_reason` | `string \| null` | No | `payment_failures` when refill turned itself off. |
| `last_charge` | [`null \| AutoRefillChargeDto`](/docs/api/schemas#autorefillchargedto) | No |  |

```json title="Example"
{
  "amount_micros": 0,
  "charged_this_month_micros": 0,
  "consecutive_failures": 0,
  "credit_packs": 0,
  "disabled_reason": "string",
  "enabled": false,
  "last_charge": {
    "amount_micros": 0,
    "created_at": "string",
    "credit_packs": 0,
    "failure_code": "string",
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "status": "string"
  },
  "monthly_cap_micros": 0,
  "threshold_micros": 0
}
```

## BackendDto

One of: `mock`, `docker`, `kvm`.

## BalancesDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `credit_micros` | `integer` | Yes | Non-expiring credits; negative only by usage metered after exhaustion. |
| `plan_micros` | `integer` | Yes | Unused allowance of the current plan period. |
| `spendable_micros` | `integer` | Yes | What can still be spent, with credits bounded by the spend cap. |
| `trial_micros` | `integer` | Yes |  |

```json title="Example"
{
  "credit_micros": 0,
  "plan_micros": 0,
  "spendable_micros": 0,
  "trial_micros": 0
}
```

## BillingDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `balances` | [`BalancesDto`](/docs/api/schemas#balancesdto) | Yes |  |
| `card_check` | [`CardCheckDto`](/docs/api/schemas#cardcheckdto) | Yes |  |
| `credit_spent_this_month_micros` | `integer` | Yes |  |
| `currency` | `string` | Yes |  |
| `limits` | [`LimitsDto`](/docs/api/schemas#limitsdto) | Yes |  |
| `minimum_balance_micros` | `integer` | Yes | Creates and starts need more than this spendable balance. |
| `organization_id` | `string (uuid)` | Yes |  |
| `payment_customer_linked` | `boolean` | Yes |  |
| `payments_available` | `boolean` | Yes | Whether checkout and the payment portal are configured. |
| `status` | `string` | Yes | `trial`, `pay_as_you_go`, or `subscribed`. |
| `trial` | [`TrialDto`](/docs/api/schemas#trialdto) | Yes |  |
| `exhausted_since` | `string \| null` | No | When the spendable balance reached zero; running machines are stopped after the grace period. |
| `plan` | [`null \| PlanSubscriptionDto`](/docs/api/schemas#plansubscriptiondto) | No |  |
| `spend_cap_micros` | `integer \| null` | No | Most credit spend allowed per UTC calendar month; `null` is no cap. |

```json title="Example"
{
  "balances": {
    "credit_micros": 0,
    "plan_micros": 0,
    "spendable_micros": 0,
    "trial_micros": 0
  },
  "card_check": {
    "required": false,
    "verified_at": "string"
  },
  "credit_spent_this_month_micros": 0,
  "currency": "USD",
  "exhausted_since": "string",
  "limits": {
    "concurrent_machines": {
      "limit": 0,
      "used": 0
    },
    "starts": [
      {
        "limit": 0,
        "used": 0,
        "window": "hour"
      }
    ],
    "status": "trial",
    "tier": "pro"
  },
  "minimum_balance_micros": 0,
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "payment_customer_linked": false,
  "payments_available": false,
  "plan": {
    "active": false,
    "cancel_at_period_end": false,
    "included_micros": 0,
    "included_seconds": 0,
    "period_end": "string",
    "period_start": "string",
    "price_micros": 0,
    "renews": false,
    "tier": "pro"
  },
  "spend_cap_micros": 0,
  "status": "trial",
  "trial": {
    "active": false,
    "concurrent_machines": 0,
    "ended_at": "string",
    "max_hourly_micros": 0,
    "remaining_micros": 0,
    "remaining_seconds": 0,
    "total_micros": 0
  }
}
```

## BulkDeleteSnapshotsRequest

Delete several snapshots by ID.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `snapshot_ids` | `string (uuid)[]` | Yes | 1-100 snapshot IDs; duplicates are reported once. |

```json title="Example"
{
  "snapshot_ids": [
    "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
  ]
}
```

## CapacityApprovalList

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `approvals` | [`CapacityPurchaseDto[]`](/docs/api/schemas#capacitypurchasedto) | Yes |  |

```json title="Example"
{
  "approvals": [
    {
      "billing": "string",
      "decided_by": "string",
      "host_id": "string",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "monthly_cost_micros": 0,
      "note": "string",
      "provider": "github",
      "reason": "string",
      "region": "string",
      "requested_at": "string",
      "setup_cost_micros": 0,
      "slots": 0,
      "state": "string"
    }
  ]
}
```

## CapacityApprovalRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `operator` | `string` | Yes | The operator deciding, recorded with the decision (1-100 characters). |
| `note` | `string \| null` | No | Optional note recorded with the decision (at most 500 characters). |

```json title="Example"
{
  "note": "string",
  "operator": "string"
}
```

## CapacityBudgetDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `allowance_micros` | `integer` | Yes | What the revenue allows: the revenue share, at least the launch floor. |
| `approval_threshold_micros` | `integer` | Yes | Purchases whose first month costs more wait for an approval. |
| `ceiling_micros` | `integer` | Yes |  |
| `committed_monthly_micros` | `integer` | Yes | Monthly spend of every server bought or kept now. |
| `launch_floor_micros` | `integer` | Yes |  |
| `revenue_30d_micros` | `integer` | Yes | Stripe revenue of the last 30 days, USD micros. |
| `revenue_share_bps` | `integer` | Yes | Share of revenue servers may cost, basis points. |
| `spend_30d_micros` | `integer` | Yes | Provider charges recorded in the last 30 days. |

```json title="Example"
{
  "allowance_micros": 0,
  "approval_threshold_micros": 0,
  "ceiling_micros": 0,
  "committed_monthly_micros": 0,
  "launch_floor_micros": 0,
  "revenue_30d_micros": 0,
  "revenue_share_bps": 0,
  "spend_30d_micros": 0
}
```

## CapacityDecisionDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `action` | `string` | Yes | `start_overflow`, `order_monthly`, `order`, `deliver`, `join`, `drain`, `release`, `cancel_at_term_end`, `retire`, or `approval`. |
| `at` | `string` | Yes | When it was decided (UTC RFC 3339). |
| `dry_run` | `boolean` | Yes | Recorded in dry run: nothing was bought or changed. |
| `facts` | `object` | Yes | The numbers behind the decision. |
| `id` | `integer` | Yes |  |
| `outcome` | `string` | Yes | What happened, such as `ordering`, `placed`, `refused`, `awaiting_approval`, `approved`, `dry_run`, or `failed`. |
| `reason` | `string` | Yes | Why, in plain words. |
| `region` | `string` | Yes |  |
| `server_id` | `string (uuid) \| null` | No |  |

```json title="Example"
{
  "action": "string",
  "at": "string",
  "dry_run": false,
  "facts": {},
  "id": 0,
  "outcome": "string",
  "reason": "string",
  "region": "string",
  "server_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## CapacityDecisionPage

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `decisions` | [`CapacityDecisionDto[]`](/docs/api/schemas#capacitydecisiondto) | Yes |  |
| `next_before` | `integer \| null` | No | Pass as `before` for older decisions; absent on the last page. |

```json title="Example"
{
  "decisions": [
    {
      "action": "string",
      "at": "string",
      "dry_run": false,
      "facts": {},
      "id": 0,
      "outcome": "string",
      "reason": "string",
      "region": "string",
      "server_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
    }
  ],
  "next_before": 0
}
```

## CapacityPurchaseDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `billing` | `string` | Yes | `monthly` or `hourly`. |
| `host_id` | `string` | Yes | The fleet host ID it will enroll as. |
| `id` | `string (uuid)` | Yes |  |
| `monthly_cost_micros` | `integer` | Yes | What it adds to the monthly server spend, USD micros (an hourly server counts at its full-month price). |
| `provider` | `string` | Yes | `ovh` or `scaleway`. |
| `reason` | `string` | Yes | Why the capacity loop wants it. |
| `region` | `string` | Yes |  |
| `requested_at` | `string` | Yes |  |
| `setup_cost_micros` | `integer` | Yes |  |
| `slots` | `integer` | Yes |  |
| `state` | `string` | Yes | `awaiting_approval`, `ordering`, `rejected`, `expired`, ... |
| `decided_by` | `string \| null` | No |  |
| `note` | `string \| null` | No |  |

```json title="Example"
{
  "billing": "string",
  "decided_by": "string",
  "host_id": "string",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "monthly_cost_micros": 0,
  "note": "string",
  "provider": "github",
  "reason": "string",
  "region": "string",
  "requested_at": "string",
  "setup_cost_micros": 0,
  "slots": 0,
  "state": "string"
}
```

## CapacityShortageDto

Why a start is waiting.

One of: `no_host_in_region`, `full`, `held_for_paid`.

## CardCheckDto

The card check a trial needs before it may start machines.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `required` | `boolean` | Yes | Whether this service requires a verified card before a trial starts machines (paid organizations never need one). |
| `verified_at` | `string \| null` | No | When a card was verified with the payment provider, if ever. |

```json title="Example"
{
  "required": false,
  "verified_at": "string"
}
```

## CardCheckSessionDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `checkout_url` | `string` | Yes | The provider's hosted page; the card is verified, not charged. |
| `session_id` | `string` | Yes |  |

```json title="Example"
{
  "checkout_url": "string",
  "session_id": "string"
}
```

## CheckoutDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `checkout_url` | `string` | Yes | Hosted checkout page; card details stay with the payment provider. |
| `session_id` | `string` | Yes |  |

```json title="Example"
{
  "checkout_url": "string",
  "session_id": "string"
}
```

## CheckoutRequestDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `credit_packs` | `integer \| null` | No | Buy this many $20 credit packs (1-50). |
| `end_trial` | `boolean` | No | With `plan`: forfeit the remaining trial once the plan's first payment is confirmed, so the plan's allowance is used right away. |
| `plan` | `string \| null` | No | Subscribe to `starter`, `pro`, `team`, or `scale`. |

```json title="Example"
{
  "credit_packs": 0,
  "end_trial": false,
  "plan": "string"
}
```

## CommandAccepted

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `command_id` | `string (uuid)` | Yes | The command ID; it equals the ID of the operation that starts it. |
| `command_url` | `string` | Yes |  |
| `machine_id` | `string (uuid)` | Yes |  |
| `operation_id` | `string (uuid)` | Yes |  |
| `operation_url` | `string` | Yes |  |
| `status` | `string` | Yes |  |

```json title="Example"
{
  "command_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "command_url": "/v1/machines/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f/commands/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "status": "pending"
}
```

## CommandDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `command_id` | `string (uuid)` | Yes |  |
| `machine_id` | `string (uuid)` | Yes |  |
| `status` | [`CommandStatusDto`](/docs/api/schemas#commandstatusdto) | Yes |  |
| `error_code` | `string \| null` | No |  |
| `exit_code` | `integer \| null` | No | Exit status recorded by the guest agent when `status` is `exited`. |
| `log` | [`null \| CommandLogDto`](/docs/api/schemas#commandlogdto) | No | Combined stdout and stderr, from `log_offset`. |
| `signal` | `integer \| null` | No | Signal that ended the command when `status` is `killed` and known. |

```json title="Example"
{
  "command_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "error_code": "string",
  "exit_code": 0,
  "log": {
    "data_base64": "string",
    "next_offset": 0,
    "offset": 0,
    "size": 0
  },
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "signal": 0,
  "status": "starting"
}
```

## CommandHistoryEntryDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `argv` | `string[]` | Yes |  |
| `cancelled` | `boolean` | Yes |  |
| `command` | `string` | Yes | The shell command of `/bin/sh -c <command>`, otherwise the arguments joined by spaces. Search matches this text. |
| `created_at` | `string` | Yes | When the command was requested (UTC RFC 3339). |
| `logs_url` | `string` | Yes |  |
| `machine_id` | `string (uuid)` | Yes |  |
| `mode` | [`CommandModeDto`](/docs/api/schemas#commandmodedto) | Yes |  |
| `operation_id` | `string (uuid)` | Yes | The exec operation; for a detached command it is also the `command_id`. |
| `output_purged` | `boolean` | Yes | Retention removed the stored output; the sizes stay. |
| `status` | [`OperationStatusDto`](/docs/api/schemas#operationstatusdto) | Yes |  |
| `timed_out` | `boolean` | Yes |  |
| `truncated` | `boolean` | Yes | The runtime capped the captured output. |
| `duration_ms` | `integer \| null` | No | `finished_at - started_at`, across retries. |
| `error_code` | `string \| null` | No |  |
| `exit_code` | `integer \| null` | No | Exit status of a finished foreground command. |
| `finished_at` | `string \| null` | No |  |
| `started_at` | `string \| null` | No | The first time a worker claimed it; absent for history recorded before migration 0023. |
| `stderr_bytes` | `integer \| null` | No |  |
| `stdout_bytes` | `integer \| null` | No |  |

```json title="Example"
{
  "argv": [
    "string"
  ],
  "cancelled": false,
  "command": "npm test",
  "created_at": "string",
  "duration_ms": 0,
  "error_code": "string",
  "exit_code": 0,
  "finished_at": "string",
  "logs_url": "/v1/machines/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f/commands/history/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f/logs",
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "mode": "sync",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "output_purged": false,
  "started_at": "string",
  "status": "pending",
  "stderr_bytes": 0,
  "stdout_bytes": 0,
  "timed_out": false,
  "truncated": false
}
```

## CommandHistoryPage

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [`CommandHistoryEntryDto[]`](/docs/api/schemas#commandhistoryentrydto) | Yes |  |
| `next_cursor` | `string \| null` | No | Pass as `cursor` for the next (older) page; absent on the last page. |

```json title="Example"
{
  "items": [
    {
      "argv": [
        "string"
      ],
      "cancelled": false,
      "command": "npm test",
      "created_at": "string",
      "duration_ms": 0,
      "error_code": "string",
      "exit_code": 0,
      "finished_at": "string",
      "logs_url": "/v1/machines/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f/commands/history/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f/logs",
      "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "mode": "sync",
      "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "output_purged": false,
      "started_at": "string",
      "status": "pending",
      "stderr_bytes": 0,
      "stdout_bytes": 0,
      "timed_out": false,
      "truncated": false
    }
  ],
  "next_cursor": "string"
}
```

## CommandLogChunkDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `complete` | `boolean` | Yes | The command finished and its output is final. While a streamed command runs, output arrives as it is relayed and `size` grows. |
| `data_base64` | `string` | Yes |  |
| `next_offset` | `integer` | Yes |  |
| `offset` | `integer` | Yes |  |
| `operation_id` | `string (uuid)` | Yes |  |
| `size` | `integer` | Yes | Bytes of this stream stored so far. |
| `stream` | [`OutputStreamDto`](/docs/api/schemas#outputstreamdto) | Yes |  |
| `truncated` | `boolean` | Yes |  |

```json title="Example"
{
  "complete": false,
  "data_base64": "UEFTUyAgc3JjL2FwcC50ZXN0LnRzCg==",
  "next_offset": 0,
  "offset": 0,
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "size": 0,
  "stream": "stdout",
  "truncated": false
}
```

## CommandLogDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data_base64` | `string` | Yes |  |
| `next_offset` | `integer` | Yes |  |
| `offset` | `integer` | Yes |  |
| `size` | `integer` | Yes | Current log size reported by the guest. |

```json title="Example"
{
  "data_base64": "string",
  "next_offset": 0,
  "offset": 0,
  "size": 0
}
```

## CommandModeDto

One of: `sync`, `detached`.

## CommandStatusDto

One of: `starting`, `failed_to_start`, `running`, `exited`, `killed`, `unknown`.

## CreateAccessGrantRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `operator` | `string` | Yes | The individual operator acting, 1-200 characters. |
| `email` | `string \| null` | No | Grant a verified login email; or name `provider` and `subject`. |
| `initial_credit_micros` | `integer \| null` | No | As on approval; defaults to the service's initial credit, 0 for none. |
| `provider` | `string \| null` | No | A configured sign-in provider such as `erpai`. |
| `reason` | `string \| null` | No |  |
| `subject` | `string \| null` | No | The provider's subject (`sub`) for the account, 1-255 characters. |

```json title="Example"
{
  "email": "ada@example.com",
  "initial_credit_micros": 0,
  "operator": "string",
  "provider": "github",
  "reason": "string",
  "subject": "string"
}
```

## CreateApiKeyRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | 1–64 characters. |
| `preset` | [`ApiKeyPresetDto`](/docs/api/schemas#apikeypresetdto) | Yes |  |
| `expires_in_days` | `integer` | No | 1–365. default `90`. |

```json title="Example"
{
  "expires_in_days": 90,
  "name": "dev",
  "preset": "read_only"
}
```

## CreateEnvironmentRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `files` | [`SecretFileInput[]`](/docs/api/schemas#secretfileinput) | No |  |
| `is_default` | `boolean \| null` | No | Defaults to `true` when the organization has no default environment. |
| `name` | `string \| null` | No | Lowercase DNS label, unique in the organization. Defaults to `base`. |
| `safe_for_third_parties` | `boolean` | No |  |
| `vars` | `map of string` | No | Variable names (`^[A-Za-z_][A-Za-z0-9_]{0,127}$`) to values. |

```json title="Example"
{
  "files": [
    {
      "contents": "string",
      "encoding": "text",
      "path": "notes/todo.txt"
    }
  ],
  "is_default": false,
  "name": "dev",
  "safe_for_third_parties": false,
  "vars": {}
}
```

## CreateInvitationRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `string` | Yes |  |
| `role` | [`RoleDto`](/docs/api/schemas#roledto) | Yes |  |

```json title="Example"
{
  "email": "ada@example.com",
  "role": "owner"
}
```

## CreateMachineRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `auto_stop_after_seconds` | `integer \| null` | No | Seconds the machine may run after it becomes running before the control plane stops it, 60 to 2592000. Omitted means 3600; `null` means never. 60–2592000. |
| `backend` | [`null \| BackendDto`](/docs/api/schemas#backenddto) | No |  |
| `environment` | `string \| null` | No | Environment to apply, by name (alternative to `environment_id`). |
| `environment_id` | `string (uuid) \| null` | No | Environment to apply once the machine is first ready, by ID. Omitting `environment_id`, `environment`, and `no_env` selects the organization's default environment, if it has one. |
| `idle_sleep_after_seconds` | `integer \| null` | No | Seconds the running machine may stay idle (no operation, terminal, or resource activity) before the control plane puts it to sleep, 300 to 86400. Omitted or `null` leaves idle sleep off. 300–86400. |
| `image` | [`null \| VersionedSelectionDto`](/docs/api/schemas#versionedselectiondto) | No |  |
| `name` | `string \| null` | No | Display name, following the `tenant_alias` rules. Defaults to the tenant alias. Unlike the alias it can be changed later. |
| `network` | [`null \| NetworkRequest`](/docs/api/schemas#networkrequest) | No | The machine's egress policy. Omitted, the host's default applies (internet egress unless the operator configured otherwise). Not with `template`: a restored machine keeps its host's policy. Change it later with `PUT /v1/machines/{machine_id}/network`. |
| `never_auto_stop` | `boolean` | No | `true` disables auto-stop. It cannot be combined with `auto_stop_after_seconds`. |
| `no_env` | `boolean` | No | `true` creates the machine without any environment, not even the default (for example, for a machine shared with third parties). |
| `plan` | [`null \| VersionedSelectionDto`](/docs/api/schemas#versionedselectiondto) | No | Required without `template`; with one, the template's exact plan, image, region, resources, and backend are used and these may be omitted (if sent, they must match). |
| `region` | [`null \| VersionedSelectionDto`](/docs/api/schemas#versionedselectiondto) | No |  |
| `resources` | [`null \| ResourcesDto`](/docs/api/schemas#resourcesdto) | No |  |
| `setup_script` | `string \| null` | No | Shell script run once as `/bin/sh -c <script>` after the machine is first ready, at most 65527 bytes without NUL. It is its own exec operation (see `setup_operation_id`) with the runtime's maximum timeout; its failure does not stop the machine. |
| `template` | `string \| null` | No | Create the machine from a ready template (name or ID): a warm restore with its own identity, woken at once. The chosen environment (or the default, or `no_env`) is applied after the restore. |
| `tenant_alias` | `string \| null` | No | Required without `template`. With one, it is the template's (the runtime scopes stored snapshots to their tenant) and may be omitted. |

```json title="Example"
{
  "auto_stop_after_seconds": 60,
  "backend": "mock",
  "environment": "string",
  "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "idle_sleep_after_seconds": 300,
  "image": {
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "version": 0
  },
  "name": "dev",
  "network": {
    "egress": "none"
  },
  "never_auto_stop": false,
  "no_env": false,
  "plan": {
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "version": 0
  },
  "region": {
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "version": 0
  },
  "resources": {
    "cpu": 0,
    "disk_gib": 0,
    "memory_mib": 0
  },
  "setup_script": "string",
  "template": "string",
  "tenant_alias": "dev"
}
```

## CreateOrganizationRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | 1-64 characters without control characters or surrounding whitespace; unique (case-insensitively) among the caller's own organizations. 1–64 characters. |

```json title="Example"
{
  "name": "dev"
}
```

## CreateSnapshotRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tier` | [`null \| SnapshotTierDto`](/docs/api/schemas#snapshottierdto) | No | Default `warm`. |

```json title="Example"
{
  "tier": "warm"
}
```

## CreateTemplateRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `machine_id` | `string (uuid)` | Yes | A stopped machine to save as the template. |
| `name` | `string` | Yes | `[a-z0-9]` then up to 63 of `[a-z0-9._-]`; unique among the organization's templates. |

```json title="Example"
{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "name": "dev"
}
```

## CreateWebhookRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `events` | [`WebhookEventDto[]`](/docs/api/schemas#webhookeventdto) | Yes | at least 1 items. |
| `name` | `string` | Yes | 1–64 characters. |
| `url` | `string` | Yes | `https` on port 443, without credentials or a fragment, naming a public host. Redirects are never followed. at most 2048 characters. |
| `enabled` | `boolean` | No | default `true`. |

```json title="Example"
{
  "enabled": true,
  "events": [
    "machine.ready"
  ],
  "name": "dev",
  "url": "https://hooks.example.com/vmyard"
}
```

## CreditKindDto

One of: `grant`, `claw_back`.

## DesiredStateDto

One of: `running`, `stopped`, `deleted`.

## DesktopClientMessage

A JSON text message from the client.

One of:

- `type: "resize"`

```json title="Example"
{
  "type": "resize"
}
```

## DesktopModeDto

What a viewer shows.

One of: `desktop`, `browser`.

## DesktopServerMessage

A JSON text message to the client. `closed` is always the last one; the WebSocket closes after it.

One of:

- `type: "opened"` with `height`, `mode`, `width`
- `type: "error"` with `code`
- `type: "closed"` with `reason`

```json title="Example"
{
  "height": 0,
  "mode": "desktop",
  "type": "opened",
  "width": 0
}
```

## DesktopTicketDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `expires_at` | `string` | Yes |  |
| `ticket` | `string` | Yes | Single-use credential for one desktop WebSocket of this machine, valid for 30 seconds, only with the session that minted it. |

```json title="Example"
{
  "expires_at": "string",
  "ticket": "string"
}
```

## DeviceApproved

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `expires_in_days` | `integer` | Yes |  |
| `organization_id` | `string (uuid)` | Yes |  |
| `preset` | [`ApiKeyPresetDto`](/docs/api/schemas#apikeypresetdto) | Yes |  |
| `user_code` | `string` | Yes |  |

```json title="Example"
{
  "expires_in_days": 0,
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "preset": "read_only",
  "user_code": "BCDF-GHJK"
}
```

## DeviceApproveRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `user_code` | `string` | Yes |  |
| `expires_in_days` | `integer \| null` | No | Key lifetime, 1–90 days; defaults to 90. 1–90. default `90`. |
| `name` | `string \| null` | No | Key name, 1–64 characters; defaults to `vy: <client_name>`. |
| `preset` | [`null \| ApiKeyPresetDto`](/docs/api/schemas#apikeypresetdto) | No | The key's preset; defaults to the requested scope. |

```json title="Example"
{
  "expires_in_days": 90,
  "name": "dev",
  "preset": "read_only",
  "user_code": "BCDF-GHJK"
}
```

## DeviceAuthorizationDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `client_name` | `string` | Yes | Untrusted text supplied by the device; display it as plain text. |
| `expires_at` | `string (date-time)` | Yes |  |
| `requested_scope` | [`ApiKeyPresetDto`](/docs/api/schemas#apikeypresetdto) | Yes |  |
| `user_code` | `string` | Yes |  |

```json title="Example"
{
  "client_name": "vy on build-host",
  "expires_at": "2026-10-12T05:51:01Z",
  "requested_scope": "read_only",
  "user_code": "BCDF-GHJK"
}
```

## DeviceCodeRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `client_name` | `string \| null` | No | Shown to the approving user, such as `vy on build-host`; 1–64 characters. Defaults to `vy CLI`. |
| `scope` | [`null \| ApiKeyPresetDto`](/docs/api/schemas#apikeypresetdto) | No | The preset the CLI asks for; the approving user may choose another. Defaults to `create_and_use`. |

```json title="Example"
{
  "client_name": "vy on build-host",
  "scope": "read_only"
}
```

## DeviceCodeResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `device_code` | `string` | Yes | Secret polling credential; keep it on the device. |
| `expires_in` | `integer` | Yes |  |
| `interval` | `integer` | Yes | Minimum seconds between polls. |
| `user_code` | `string` | Yes | Short code the user confirms in the browser, `XXXX-XXXX`. |
| `verification_uri` | `string` | Yes |  |
| `verification_uri_complete` | `string` | Yes |  |

```json title="Example"
{
  "device_code": "string",
  "expires_in": 0,
  "interval": 0,
  "user_code": "BCDF-GHJK",
  "verification_uri": "https://console.example.com/device",
  "verification_uri_complete": "https://console.example.com/device?user_code=BCDF-GHJK"
}
```

## DeviceDecisionRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `user_code` | `string` | Yes |  |

```json title="Example"
{
  "user_code": "BCDF-GHJK"
}
```

## DeviceTokenError

RFC 8628 §3.5 error: `authorization_pending`, `slow_down`, `access_denied`, `expired_token`, `invalid_grant`, `invalid_request`, or `unsupported_grant_type`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | `string` | Yes |  |
| `error_description` | `string` | Yes |  |

```json title="Example"
{
  "error": "string",
  "error_description": "string"
}
```

## DeviceTokenRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `device_code` | `string` | Yes |  |
| `grant_type` | `string` | Yes | `urn:ietf:params:oauth:grant-type:device_code` |

```json title="Example"
{
  "device_code": "string",
  "grant_type": "string"
}
```

## DeviceTokenResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `access_token` | `string` | Yes | The new API key secret (`vmy_…`), returned only once. |
| `api_key` | [`ApiKeyDto`](/docs/api/schemas#apikeydto) | Yes |  |
| `expires_in` | `integer` | Yes | Seconds until the API key expires. |
| `scope` | [`ApiKeyPresetDto`](/docs/api/schemas#apikeypresetdto) | Yes | The key's preset. |
| `token_type` | `string` | Yes | Always `Bearer`. |

```json title="Example"
{
  "access_token": "vmy_…",
  "api_key": {
    "created_at": "2026-10-12T05:51:01Z",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "expires_at": "2026-10-12T05:51:01Z",
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "last_four": "x9Q2",
    "last_used_at": "2026-10-12T05:51:01Z",
    "name": "ci-runner",
    "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "prefix": "vmy_AbCdEfGh",
    "preset": "read_only",
    "revoked_at": "2026-10-12T05:51:01Z"
  },
  "expires_in": 0,
  "scope": "read_only",
  "token_type": "Bearer"
}
```

## EgressDto

What a machine's guest may reach: `none` (only the host's egress allowlist) or `internet` (the public internet as well, within the host's limits; private, metadata, and other machines' networks stay unreachable and SMTP is blocked).

One of: `none`, `internet`.

## EmailStarted

The same answer for every well-formed address.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | `string` | Yes |  |

```json title="Example"
{
  "message": "If the address can receive email, a code is on its way."
}
```

## EmailStartRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `string` | Yes |  |
| `return_to` | `string \| null` | No | Same-origin UI path to open after sign-in; invalid values become `/`. |

```json title="Example"
{
  "email": "ada@example.com",
  "return_to": "string"
}
```

## EmailVerified

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `return_to` | `string` | Yes | The UI path stored when the code was requested. |

```json title="Example"
{
  "return_to": "string"
}
```

## EmailVerifyRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | `string` | Yes | The 6-digit code from the email. |
| `email` | `string` | Yes |  |

```json title="Example"
{
  "code": "string",
  "email": "ada@example.com"
}
```

## EmptyAction

No fields.

```json title="Example"
{}
```

## EnvironmentApplyStatusDto

One of: `pending`, `applied`, `failed`.

## EnvironmentDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | `string` | Yes |  |
| `current_version` | [`EnvironmentVersionDto`](/docs/api/schemas#environmentversiondto) | Yes |  |
| `id` | `string (uuid)` | Yes |  |
| `is_default` | `boolean` | Yes | Machines created without `environment_id`, `environment`, or `no_env` get the default environment. |
| `name` | `string` | Yes |  |
| `safe_for_third_parties` | `boolean` | Yes | Marks an environment whose contents may be exposed to third parties. |
| `updated_at` | `string` | Yes |  |
| `created_by` | `string (uuid) \| null` | No |  |

```json title="Example"
{
  "created_at": "string",
  "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "current_version": {
    "change": {},
    "created_at": "string",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "files": [
      {
        "path": "notes/todo.txt",
        "size": 0
      }
    ],
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "vars": [
      "string"
    ],
    "version": 0
  },
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "is_default": false,
  "name": "staging",
  "safe_for_third_parties": false,
  "updated_at": "string"
}
```

## EnvironmentFileDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `path` | `string` | Yes | Path relative to `/work`. |
| `size` | `integer` | Yes |  |

```json title="Example"
{
  "path": "notes/todo.txt",
  "size": 0
}
```

## EnvironmentList

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [`EnvironmentDto[]`](/docs/api/schemas#environmentdto) | Yes |  |

```json title="Example"
{
  "items": [
    {
      "created_at": "string",
      "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "current_version": {
        "change": {},
        "created_at": "string",
        "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "files": [
          {
            "path": "notes/todo.txt",
            "size": 0
          }
        ],
        "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "vars": [
          "string"
        ],
        "version": 0
      },
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "is_default": false,
      "name": "staging",
      "safe_for_third_parties": false,
      "updated_at": "string"
    }
  ]
}
```

## EnvironmentVersionDto

One immutable version. Values are never included.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `change` | `object` | Yes | What this version changed, without values, for example `{"action": "set_variable", "name": "API_TOKEN", "size": 40}`. |
| `created_at` | `string` | Yes |  |
| `environment_id` | `string (uuid)` | Yes |  |
| `files` | [`EnvironmentFileDto[]`](/docs/api/schemas#environmentfiledto) | Yes |  |
| `id` | `string (uuid)` | Yes |  |
| `vars` | `string[]` | Yes | Variable names, sorted. |
| `version` | `integer` | Yes | 1 for the first version, then one more per change. |
| `created_by` | `string (uuid) \| null` | No |  |

```json title="Example"
{
  "change": {},
  "created_at": "string",
  "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "files": [
    {
      "path": "notes/todo.txt",
      "size": 0
    }
  ],
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "vars": [
    "string"
  ],
  "version": 0
}
```

## EnvironmentVersionList

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [`EnvironmentVersionDto[]`](/docs/api/schemas#environmentversiondto) | Yes | Newest first. |

```json title="Example"
{
  "items": [
    {
      "change": {},
      "created_at": "string",
      "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "files": [
        {
          "path": "notes/todo.txt",
          "size": 0
        }
      ],
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "vars": [
        "string"
      ],
      "version": 0
    }
  ]
}
```

## ExecRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `argv` | `string[] \| null` | No | Program and arguments, executed directly. Exactly one of `argv` or `command`. |
| `command` | `string \| null` | No | Shell command run as `/bin/sh -c <command>`, at most 8192 bytes. |
| `stream` | `boolean` | No | Respond with `application/x-ndjson` frames as output arrives instead of `202 Accepted`. |
| `timeout_ms` | `integer \| null` | No | Foreground limit in milliseconds, 1 to the runtime maximum (600000). Defaults to the maximum; the effective value is persisted with the operation. |

```json title="Example"
{
  "argv": [
    "string"
  ],
  "command": "string",
  "stream": false,
  "timeout_ms": 0
}
```

## ExecResultDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cancelled` | `boolean` | Yes |  |
| `stderr_base64` | `string` | Yes |  |
| `stdout_base64` | `string` | Yes |  |
| `timed_out` | `boolean` | Yes |  |
| `truncated` | `boolean` | Yes |  |
| `exit_code` | `integer \| null` | No |  |

```json title="Example"
{
  "cancelled": false,
  "exit_code": 0,
  "stderr_base64": "string",
  "stdout_base64": "string",
  "timed_out": false,
  "truncated": false
}
```

## ExecStreamFrame

One line of a streamed exec response. `stdout`/`stderr` frames carry untrusted guest bytes; the `exit` frame is the authoritative result.

One of:

- `type: "started"` with `operation_id`, `operation_url`
- `type: "stdout"` with `data_base64`
- `type: "stderr"` with `data_base64`
- `type: "exit"` with `cancelled`, `error_code`, `exit_code`, `operation_id`, `status`, `timed_out`, `truncated`
- `type: "error"` with `code`, `message`, `operation_id`, `status`

```json title="Example"
{
  "cancelled": false,
  "error_code": "string",
  "exit_code": 0,
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "status": "succeeded",
  "timed_out": false,
  "truncated": false,
  "type": "exit"
}
```

## ExposePortRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `port` | `integer` | Yes | Guest TCP port, 1-65535 except 22 (use the SSH key for SSH) and the desktop's 5907 and 5908 (open the desktop instead). |
| `localhost` | `boolean` | No | Relay the guest's addresses to a service bound to `127.0.0.1`/`[::1]`. |
| `public` | `boolean` | No | Reachable without a token. Private ports (the default) need a token from `POST /v1/machines/{machine_id}/ports/{port}/token`. |

```json title="Example"
{
  "localhost": false,
  "port": 0,
  "public": false
}
```

## FileContentDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `content` | `string` | Yes |  |
| `encoding` | [`FileEncodingDto`](/docs/api/schemas#fileencodingdto) | Yes |  |
| `path` | `string` | Yes | Path relative to /work. |
| `size` | `integer` | Yes |  |

```json title="Example"
{
  "content": "string",
  "encoding": "text",
  "path": "notes/todo.txt",
  "size": 0
}
```

## FileEncodingDto

One of: `text`, `base64`.

## FileEntryTypeDto

One of: `file`, `dir`, `symlink`.

## FileRangeDto

One range of a completed read, as persisted by the worker. Data is untrusted guest content.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data_base64` | `string` | Yes |  |
| `missing` | `boolean` | Yes |  |
| `offset` | `integer` | Yes |  |
| `path` | `string` | Yes |  |
| `size` | `integer` | Yes |  |

```json title="Example"
{
  "data_base64": "string",
  "missing": false,
  "offset": 0,
  "path": "notes/todo.txt",
  "size": 0
}
```

## FileTreeDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `entries` | [`FileTreeEntryDto[]`](/docs/api/schemas#filetreeentrydto) | Yes |  |
| `file_count` | `integer` | Yes | Non-directory entries under it at any depth. |
| `path` | `string` | Yes | The listed directory, normalized. |
| `total_bytes` | `integer` | Yes | The directory's recursive apparent size (`du -sb`). |
| `truncated` | `boolean` | Yes | The listing stopped at 5,000 entries (deeper levels go first). |

```json title="Example"
{
  "entries": [
    {
      "children": [],
      "modified_at": "2026-10-12T05:51:01Z",
      "name": "dev",
      "path": "notes/todo.txt",
      "size_bytes": 0,
      "type": "file"
    }
  ],
  "file_count": 0,
  "path": "notes/todo.txt",
  "total_bytes": 0,
  "truncated": false
}
```

## FileTreeEntryDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | The last path component. Guest data: bytes that are not UTF-8 are replaced by U+FFFD. |
| `path` | `string` | Yes | The absolute guest path. |
| `size_bytes` | `integer` | Yes | A file's size; a symlink's target length; a directory's recursive apparent size, its own entries included (`du -b`). |
| `type` | [`FileEntryTypeDto`](/docs/api/schemas#fileentrytypedto) | Yes |  |
| `children` | [`FileTreeEntryDto[] \| null`](/docs/api/schemas#filetreeentrydto) | No | A directory's entries, sorted by name, only within the requested depth; absent for files, symlinks, and directories at the depth. |
| `modified_at` | `string (date-time) \| null` | No | Last modification (UTC RFC 3339), when the guest reported one. |

```json title="Example"
{
  "children": [],
  "modified_at": "2026-10-12T05:51:01Z",
  "name": "dev",
  "path": "notes/todo.txt",
  "size_bytes": 0,
  "type": "file"
}
```

## FlagResolutionDto

One of: `dismissed`, `confirmed`.

## ForkMachineRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `keep_ssh_keys` | `boolean` | No | Keep the login user's SSH `authorized_keys` in the copy (default `false`). The SSH gateway port is never inherited. |
| `live` | `boolean \| null` | No | Run the copy at once with the source's processes (default `true`); `false` creates it stopped. |
| `name` | `string \| null` | No | The copy's display name (default: the tenant alias it shares with the source). |

```json title="Example"
{
  "keep_ssh_keys": false,
  "live": false,
  "name": "dev"
}
```

## GrantKindDto

One of: `credits`, `trial`, `plan_period`.

## GrantResultDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `outcome` | `string` | Yes | `applied`, `duplicate`, or `stale`. |

```json title="Example"
{
  "outcome": "applied"
}
```

## GuestReportedDto

Values the guest agent reports about itself. Code in the guest can alter them: they are shown for information and never billed or enforced on.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filesystem_available_bytes` | `integer` | Yes |  |
| `filesystem_total_bytes` | `integer` | Yes |  |
| `memory_available_bytes` | `integer` | Yes |  |
| `memory_total_bytes` | `integer` | Yes |  |
| `reported_at` | `string (date-time) \| null` | No | When the guest reported them (UTC RFC 3339). |

```json title="Example"
{
  "filesystem_available_bytes": 0,
  "filesystem_total_bytes": 0,
  "memory_available_bytes": 0,
  "memory_total_bytes": 0,
  "reported_at": "2026-10-12T05:51:01Z"
}
```

## ImageDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `digest` | `string` | Yes |  |
| `id` | `string (uuid)` | Yes |  |
| `name` | `string` | Yes |  |
| `version` | `integer` | Yes |  |

```json title="Example"
{
  "digest": "sha256:3f5a…",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "name": "ubuntu-24.04",
  "version": 0
}
```

## ImagePage

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [`ImageDto[]`](/docs/api/schemas#imagedto) | Yes |  |
| `next_cursor` | `string \| null` | No |  |

```json title="Example"
{
  "items": [
    {
      "digest": "sha256:3f5a…",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "name": "ubuntu-24.04",
      "version": 0
    }
  ],
  "next_cursor": "string"
}
```

## InteractiveAccessDto

One of: `managed_terminal`.

## InvitationAcceptedDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `organization_id` | `string (uuid)` | Yes |  |
| `role` | [`RoleDto`](/docs/api/schemas#roledto) | Yes |  |

```json title="Example"
{
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "role": "owner"
}
```

## InvitationDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | `string (date-time)` | Yes |  |
| `email` | `string` | Yes |  |
| `expires_at` | `string (date-time)` | Yes |  |
| `id` | `string (uuid)` | Yes |  |
| `organization_id` | `string (uuid)` | Yes |  |
| `role` | [`RoleDto`](/docs/api/schemas#roledto) | Yes |  |
| `invited_by` | `string (uuid) \| null` | No |  |

```json title="Example"
{
  "created_at": "2026-10-12T05:51:01Z",
  "email": "ada@example.com",
  "expires_at": "2026-10-12T05:51:01Z",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "invited_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "role": "owner"
}
```

## InvitationList

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [`InvitationDto[]`](/docs/api/schemas#invitationdto) | Yes | Open invitations, newest first. |

```json title="Example"
{
  "items": [
    {
      "created_at": "2026-10-12T05:51:01Z",
      "email": "ada@example.com",
      "expires_at": "2026-10-12T05:51:01Z",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "invited_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "role": "owner"
    }
  ]
}
```

## InvitationPreviewDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `string` | Yes |  |
| `expires_at` | `string (date-time)` | Yes |  |
| `organization_id` | `string (uuid)` | Yes |  |
| `organization_name` | `string` | Yes |  |
| `role` | [`RoleDto`](/docs/api/schemas#roledto) | Yes |  |
| `state` | [`InvitationStateDto`](/docs/api/schemas#invitationstatedto) | Yes |  |

```json title="Example"
{
  "email": "ada@example.com",
  "expires_at": "2026-10-12T05:51:01Z",
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "organization_name": "string",
  "role": "owner",
  "state": "open"
}
```

## InvitationStateDto

One of: `open`, `accepted`, `revoked`, `expired`.

## InvoiceLineDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micros` | `integer` | Yes |  |
| `description` | `string` | Yes |  |
| `hourly_micros` | `integer` | Yes |  |
| `multiplier` | `number` | Yes |  |
| `plan_id` | `string (uuid)` | Yes |  |
| `plan_version` | `integer` | Yes |  |
| `seconds` | `integer` | Yes |  |

```json title="Example"
{
  "amount_micros": 0,
  "description": "default · machine time",
  "hourly_micros": 0,
  "multiplier": 0.5,
  "plan_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "plan_version": 0,
  "seconds": 0
}
```

## InvoicePreviewDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `applied` | [`AppliedDto`](/docs/api/schemas#applieddto) | Yes | How the charged part was paid. |
| `credit_balance_micros` | `integer` | Yes |  |
| `currency` | `string` | Yes |  |
| `lines` | [`InvoiceLineDto[]`](/docs/api/schemas#invoicelinedto) | Yes | Machine time in the period so far, by size. |
| `next_charge_micros` | `integer` | Yes | What renews at `period_end` (the plan price), or 0. Usage is prepaid, so nothing else is charged automatically. |
| `period_end` | `string` | Yes |  |
| `period_start` | `string` | Yes |  |
| `unbilled_micros` | `integer` | Yes | Accrued by running machines but not yet charged by the meter. |
| `usage_micros` | `integer` | Yes |  |
| `plan` | [`null \| PlanSubscriptionDto`](/docs/api/schemas#plansubscriptiondto) | No |  |

```json title="Example"
{
  "applied": {
    "credit_micros": 0,
    "plan_micros": 0,
    "trial_micros": 0
  },
  "credit_balance_micros": 0,
  "currency": "USD",
  "lines": [
    {
      "amount_micros": 0,
      "description": "default · machine time",
      "hourly_micros": 0,
      "multiplier": 0.5,
      "plan_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "plan_version": 0,
      "seconds": 0
    }
  ],
  "next_charge_micros": 0,
  "period_end": "string",
  "period_start": "string",
  "plan": {
    "active": false,
    "cancel_at_period_end": false,
    "included_micros": 0,
    "included_seconds": 0,
    "period_end": "string",
    "period_start": "string",
    "price_micros": 0,
    "renews": false,
    "tier": "pro"
  },
  "unbilled_micros": 0,
  "usage_micros": 0
}
```

## LatestSnapshotDto

A machine's newest live snapshot (templates and failed pushes excluded), for showing freshness in machine lists.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | `string (date-time)` | Yes | When the snapshot was requested (UTC RFC 3339): the instant a capture or push copies. |
| `id` | `string (uuid)` | Yes |  |
| `source` | [`SnapshotSourceDto`](/docs/api/schemas#snapshotsourcedto) | Yes |  |
| `status` | [`SnapshotStatusDto`](/docs/api/schemas#snapshotstatusdto) | Yes | `pending` or `ready`. |
| `tier` | [`SnapshotTierDto`](/docs/api/schemas#snapshottierdto) | Yes |  |
| `completed_at` | `string (date-time) \| null` | No | When it became ready; `null` while `pending`. |

```json title="Example"
{
  "completed_at": "2026-10-12T05:51:01Z",
  "created_at": "2026-10-12T05:51:01Z",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "source": "api",
  "status": "pending",
  "tier": "warm"
}
```

## LedgerEntryDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micros` | `integer` | Yes | Positive adds to the balance, negative takes from it. |
| `at` | `string` | Yes |  |
| `bucket` | `string` | Yes | `trial`, `plan`, or `credit`. |
| `id` | `integer` | Yes |  |
| `kind` | [`LedgerKindDto`](/docs/api/schemas#ledgerkinddto) | Yes |  |
| `label` | `string` | Yes | What to show, such as "Credit from VMYard". |
| `plan_tier` | `string \| null` | No |  |

```json title="Example"
{
  "amount_micros": 0,
  "at": "string",
  "bucket": "string",
  "id": 0,
  "kind": "trial_grant",
  "label": "k7f2mq3x9a1b",
  "plan_tier": "string"
}
```

## LedgerKindDto

One of: `trial_grant`, `trial_forfeit`, `plan_grant`, `plan_expire`, `credit_grant`, `vmyard_credit`, `vmyard_clawback`.

## LedgerPage

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [`LedgerEntryDto[]`](/docs/api/schemas#ledgerentrydto) | Yes |  |
| `next_before` | `integer \| null` | No | Pass as `before` for the next page; absent on the last page. |

```json title="Example"
{
  "items": [
    {
      "amount_micros": 0,
      "at": "string",
      "bucket": "string",
      "id": 0,
      "kind": "trial_grant",
      "label": "k7f2mq3x9a1b",
      "plan_tier": "string"
    }
  ],
  "next_before": 0
}
```

## LimitDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | `integer` | Yes |  |
| `used` | `integer` | Yes |  |

```json title="Example"
{
  "limit": 0,
  "used": 0
}
```

## LimitsDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `concurrent_machines` | [`LimitDto`](/docs/api/schemas#limitdto) | Yes | Machines that want to run, pending creates included. |
| `starts` | [`StartLimitDto[]`](/docs/api/schemas#startlimitdto) | Yes | Creates, starts, and restarts in each rolling window. |
| `status` | `string` | Yes | `trial`, `pay_as_you_go`, or `subscribed`. |
| `tier` | `string \| null` | No |  |

```json title="Example"
{
  "concurrent_machines": {
    "limit": 0,
    "used": 0
  },
  "starts": [
    {
      "limit": 0,
      "used": 0,
      "window": "hour"
    }
  ],
  "status": "trial",
  "tier": "pro"
}
```

## LinkRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `string \| null` | No | Required for `email`, refused for other providers. |
| `return_to` | `string \| null` | No | Same-origin UI path to open when the provider flow completes; invalid values become `/`. |

```json title="Example"
{
  "email": "ada@example.com",
  "return_to": "string"
}
```

## LinkStarted

Open `authorization_url` as a top-level navigation; the provider returns to `/v1/auth/callback`, which attaches the identity to this user.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `authorization_url` | `string` | Yes |  |

```json title="Example"
{
  "authorization_url": "string"
}
```

## LoginMethodDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | `string (date-time)` | Yes |  |
| `id` | `string (uuid)` | Yes |  |
| `last_used_at` | `string (date-time)` | Yes |  |
| `provider` | `string` | Yes | Provider name such as `github`, `google`, or `email`. |
| `email` | `string \| null` | No | The address the provider vouched for at the last sign-in, when known. |

```json title="Example"
{
  "created_at": "2026-10-12T05:51:01Z",
  "email": "ada@example.com",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "last_used_at": "2026-10-12T05:51:01Z",
  "provider": "github"
}
```

## MachineDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `backend` | [`BackendDto`](/docs/api/schemas#backenddto) | Yes |  |
| `created_at` | `string (date-time)` | Yes | When the machine was requested (UTC RFC 3339). |
| `desired_state` | [`DesiredStateDto`](/docs/api/schemas#desiredstatedto) | Yes |  |
| `id` | `string (uuid)` | Yes |  |
| `image` | [`VersionedSelectionDto`](/docs/api/schemas#versionedselectiondto) | Yes |  |
| `name` | `string` | Yes | Display name; the tenant alias unless renamed. |
| `observed_state` | [`ObservedStateDto`](/docs/api/schemas#observedstatedto) | Yes |  |
| `organization_id` | `string (uuid)` | Yes |  |
| `plan` | [`VersionedSelectionDto`](/docs/api/schemas#versionedselectiondto) | Yes |  |
| `region` | [`VersionedSelectionDto`](/docs/api/schemas#versionedselectiondto) | Yes |  |
| `resources` | [`ResourcesDto`](/docs/api/schemas#resourcesdto) | Yes |  |
| `tenant_alias` | `string` | Yes |  |
| `auto_stop_after_seconds` | `integer \| null` | No | Configured auto-stop duration in seconds; `null` means never. |
| `auto_stop_at` | `string \| null` | No | When the control plane will stop the running machine (UTC RFC 3339); `null` when it is not running toward a deadline. |
| `environment` | [`null \| MachineEnvironmentDto`](/docs/api/schemas#machineenvironmentdto) | No | The machine's environment; `null` when it was created without one. |
| `forked_from_machine_id` | `string (uuid) \| null` | No | The machine this one was forked from (`POST .../fork`). |
| `idle_since` | `string \| null` | No | Start of the running machine's current unbroken idle window (UTC RFC 3339); `null` while it is active, its metrics are unknown, or idle sleep is off. |
| `idle_sleep_after_seconds` | `integer \| null` | No | Configured idle-sleep window in seconds; `null` means idle sleep is off (the default). |
| `idle_sleep_at` | `string \| null` | No | When the machine will be put to sleep if it stays idle: `idle_since` plus the window (UTC RFC 3339). |
| `last_active_at` | `string \| null` | No | The last activity the idle-sleep scan observed (UTC RFC 3339); `null` until a scan saw any. |
| `latest_snapshot` | [`null \| LatestSnapshotDto`](/docs/api/schemas#latestsnapshotdto) | No | The machine's newest live snapshot (pending or ready; templates and failed pushes excluded), for freshness; `null` when it has none. |
| `metrics` | [`null \| MachineMetricsSummaryDto`](/docs/api/schemas#machinemetricssummarydto) | No | The latest metrics the poller recorded; `null` until the machine has been sampled. Values stay after the machine stops being reported, with `stale` set. |
| `network` | [`null \| MachineNetworkDto`](/docs/api/schemas#machinenetworkdto) | No | The network policy and public address the machine's host last reported applying; `null` until a host reported one (hosts without guest networking never do). |
| `restored_from_snapshot_id` | `string (uuid) \| null` | No | The snapshot or template this machine was restored from. |
| `setup_operation_id` | `string (uuid) \| null` | No | The setup script's exec operation, when one was requested. |
| `ssh` | [`null \| SshAccessDto`](/docs/api/schemas#sshaccessdto) | No | How to reach the machine over SSH, present while it has an SSH key (`PUT /v1/machines/{machine_id}/ssh-key`). |
| `starting_soon` | [`null \| StartingSoonDto`](/docs/api/schemas#startingsoondto) | No | Set while the machine's create or start waits for a server to have room ("starting soon"); `null` otherwise. |

```json title="Example"
{
  "auto_stop_after_seconds": 0,
  "auto_stop_at": "2026-10-12T06:51:01Z",
  "backend": "mock",
  "created_at": "2026-10-12T05:51:01Z",
  "desired_state": "running",
  "environment": {
    "applied_version_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "error_code": "string",
    "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "status": "pending",
    "version": 0,
    "version_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
  },
  "forked_from_machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "idle_since": "2026-10-12T05:36:01Z",
  "idle_sleep_after_seconds": 900,
  "idle_sleep_at": "2026-10-12T05:51:01Z",
  "image": {
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "version": 0
  },
  "last_active_at": "2026-10-12T05:36:01Z",
  "latest_snapshot": {
    "completed_at": "2026-10-12T05:51:01Z",
    "created_at": "2026-10-12T05:51:01Z",
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "source": "api",
    "status": "pending",
    "tier": "warm"
  },
  "metrics": {
    "cpu_limit_millis": 0,
    "cpu_millis": 0,
    "cpu_percent": 0.5,
    "disk_percent": 0.5,
    "disk_size_bytes": 0,
    "disk_used_bytes": 0,
    "flags": [
      "disk_almost_full"
    ],
    "io_read_bps": 0,
    "io_write_bps": 0,
    "memory_bytes": 0,
    "memory_limit_bytes": 0,
    "memory_percent": 0.5,
    "net_rx_bps": 0,
    "net_tx_bps": 0,
    "sampled_at": "2026-10-12T05:51:01Z",
    "stale": false,
    "stale_reason": "host_unreachable",
    "state": "string"
  },
  "name": "dev",
  "network": {
    "egress": "none",
    "ipv6_address": "string"
  },
  "observed_state": {
    "boot_id": "string",
    "state": "running"
  },
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "plan": {
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "version": 0
  },
  "region": {
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "version": 0
  },
  "resources": {
    "cpu": 0,
    "disk_gib": 0,
    "memory_mib": 0
  },
  "restored_from_snapshot_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "setup_operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "ssh": {
    "host": "ssh.eu.example.com",
    "port": 0,
    "user": "vmyard"
  },
  "starting_soon": {
    "expires_at": "2026-10-12T05:51:01Z",
    "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "position": 0,
    "priority": "paid",
    "queued_at": "2026-10-12T05:51:01Z",
    "reason": "no_host_in_region"
  },
  "tenant_alias": "dev"
}
```

## MachineEnvironmentDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `environment_id` | `string (uuid)` | Yes |  |
| `operation_id` | `string (uuid)` | Yes | The apply operation for `version_id`. |
| `status` | [`EnvironmentApplyStatusDto`](/docs/api/schemas#environmentapplystatusdto) | Yes |  |
| `version` | `integer` | Yes |  |
| `version_id` | `string (uuid)` | Yes | The version the machine should have: the one it was created with, until an upgrade. |
| `applied_version_id` | `string (uuid) \| null` | No | The version last installed in the guest, if any. |
| `error_code` | `string \| null` | No |  |

```json title="Example"
{
  "applied_version_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "error_code": "string",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "status": "pending",
  "version": 0,
  "version_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## MachineMetricsDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cpu_limit_millis` | `integer` | Yes |  |
| `interval_ms` | `integer` | Yes | Time between points: the host's sampling interval for `live`, 60000 for `1m`. |
| `machine_id` | `string (uuid)` | Yes |  |
| `memory_limit_bytes` | `integer` | Yes |  |
| `points` | [`MetricsPointDto[]`](/docs/api/schemas#metricspointdto) | Yes | Oldest first. |
| `resolution` | [`MetricsResolutionDto`](/docs/api/schemas#metricsresolutiondto) | Yes |  |
| `guest_reported` | [`null \| GuestReportedDto`](/docs/api/schemas#guestreporteddto) | No | The guest's own report, when there is one. |
| `next_since` | `string \| null` | No | More `1m` points follow: ask again with this as `since`. |

```json title="Example"
{
  "cpu_limit_millis": 0,
  "guest_reported": {
    "filesystem_available_bytes": 0,
    "filesystem_total_bytes": 0,
    "memory_available_bytes": 0,
    "memory_total_bytes": 0,
    "reported_at": "2026-10-12T05:51:01Z"
  },
  "interval_ms": 0,
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "memory_limit_bytes": 0,
  "next_since": "string",
  "points": [
    {
      "cpu_millis": 0,
      "cpu_millis_max": 0,
      "cpu_percent": 0.5,
      "disk_percent": 0.5,
      "disk_used_bytes": 0,
      "io_read_bps": 0,
      "io_write_bps": 0,
      "memory_bytes": 0,
      "memory_bytes_max": 0,
      "memory_percent": 0.5,
      "net_rx_bps": 0,
      "net_tx_bps": 0,
      "t": "2026-10-12T05:51:01Z"
    }
  ],
  "resolution": "live"
}
```

## MachineMetricsSummaryDto

The machine's latest values as the last metrics poll recorded them. Percentages are of the machine's limits; absent values were not measured (for example CPU and memory while asleep).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cpu_limit_millis` | `integer` | Yes |  |
| `flags` | [`MetricFlagDto[]`](/docs/api/schemas#metricflagdto) | Yes |  |
| `memory_limit_bytes` | `integer` | Yes |  |
| `stale` | `boolean` | Yes | The values are from an earlier poll and may no longer be current; they are the last known values, not zero. |
| `state` | `string` | Yes | The runtime state when sampled: `running` or `sleeping`. |
| `cpu_millis` | `integer \| null` | No | Millicores used over the last sampling interval (1000 = one core). |
| `cpu_percent` | `number \| null` | No | CPU used over the host's last sampling interval, as a share of the machine's CPU limit. |
| `disk_percent` | `number \| null` | No | Disk blocks the machine's image holds, as a share of its size. An upper bound: blocks the guest freed stay allocated. |
| `disk_size_bytes` | `integer \| null` | No |  |
| `disk_used_bytes` | `integer \| null` | No |  |
| `io_read_bps` | `integer \| null` | No | Bytes per second over the host's last sampling interval. |
| `io_write_bps` | `integer \| null` | No |  |
| `memory_bytes` | `integer \| null` | No |  |
| `memory_percent` | `number \| null` | No | Memory charged to the machine (guest RAM in use, page cache, and the VMM), as a share of its limit. |
| `net_rx_bps` | `integer \| null` | No | Bytes per second seen from the guest (`rx` = received by it). |
| `net_tx_bps` | `integer \| null` | No |  |
| `sampled_at` | `string (date-time) \| null` | No | When the host sampled these values (UTC RFC 3339). |
| `stale_reason` | [`null \| StaleReasonDto`](/docs/api/schemas#stalereasondto) | No |  |

```json title="Example"
{
  "cpu_limit_millis": 0,
  "cpu_millis": 0,
  "cpu_percent": 0.5,
  "disk_percent": 0.5,
  "disk_size_bytes": 0,
  "disk_used_bytes": 0,
  "flags": [
    "disk_almost_full"
  ],
  "io_read_bps": 0,
  "io_write_bps": 0,
  "memory_bytes": 0,
  "memory_limit_bytes": 0,
  "memory_percent": 0.5,
  "net_rx_bps": 0,
  "net_tx_bps": 0,
  "sampled_at": "2026-10-12T05:51:01Z",
  "stale": false,
  "stale_reason": "host_unreachable",
  "state": "string"
}
```

## MachineNetworkDto

The machine's network as its host last reported applying it.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `egress` | [`EgressDto`](/docs/api/schemas#egressdto) | Yes |  |
| `ipv6_address` | `string \| null` | No | The machine's public IPv6 address, when its host routes a global prefix to its machines; `null` otherwise. Inbound traffic still reaches only exposed ports. |

```json title="Example"
{
  "egress": "none",
  "ipv6_address": "string"
}
```

## MachinePage

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [`MachineDto[]`](/docs/api/schemas#machinedto) | Yes |  |
| `next_cursor` | `string \| null` | No | Opaque; pass it as `cursor` with the same `sort` and `order`. |

```json title="Example"
{
  "items": [
    {
      "auto_stop_after_seconds": 0,
      "auto_stop_at": "2026-10-12T06:51:01Z",
      "backend": "mock",
      "created_at": "2026-10-12T05:51:01Z",
      "desired_state": "running",
      "environment": {
        "applied_version_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "error_code": "string",
        "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "status": "pending",
        "version": 0,
        "version_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
      },
      "forked_from_machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "idle_since": "2026-10-12T05:36:01Z",
      "idle_sleep_after_seconds": 900,
      "idle_sleep_at": "2026-10-12T05:51:01Z",
      "image": {
        "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "version": 0
      },
      "last_active_at": "2026-10-12T05:36:01Z",
      "latest_snapshot": {
        "completed_at": "2026-10-12T05:51:01Z",
        "created_at": "2026-10-12T05:51:01Z",
        "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "source": "api",
        "status": "pending",
        "tier": "warm"
      },
      "metrics": {
        "cpu_limit_millis": 0,
        "cpu_millis": 0,
        "cpu_percent": 0.5,
        "disk_percent": 0.5,
        "disk_size_bytes": 0,
        "disk_used_bytes": 0,
        "flags": [
          "disk_almost_full"
        ],
        "io_read_bps": 0,
        "io_write_bps": 0,
        "memory_bytes": 0,
        "memory_limit_bytes": 0,
        "memory_percent": 0.5,
        "net_rx_bps": 0,
        "net_tx_bps": 0,
        "sampled_at": "2026-10-12T05:51:01Z",
        "stale": false,
        "stale_reason": "host_unreachable",
        "state": "string"
      },
      "name": "dev",
      "network": {
        "egress": "none",
        "ipv6_address": "string"
      },
      "observed_state": {
        "boot_id": "string",
        "state": "running"
      },
      "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "plan": {
        "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "version": 0
      },
      "region": {
        "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "version": 0
      },
      "resources": {
        "cpu": 0,
        "disk_gib": 0,
        "memory_mib": 0
      },
      "restored_from_snapshot_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "setup_operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "ssh": {
        "host": "ssh.eu.example.com",
        "port": 0,
        "user": "vmyard"
      },
      "starting_soon": {
        "expires_at": "2026-10-12T05:51:01Z",
        "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "position": 0,
        "priority": "paid",
        "queued_at": "2026-10-12T05:51:01Z",
        "reason": "no_host_in_region"
      },
      "tenant_alias": "dev"
    }
  ],
  "next_cursor": "string"
}
```

## MachineUsageDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cost_micros` | `integer` | Yes |  |
| `hourly_micros` | `integer` | Yes |  |
| `machine_id` | `string (uuid)` | Yes |  |
| `multiplier` | `number` | Yes | Size multiplier relative to `default` (small 0.5, large 2). |
| `running` | `boolean` | Yes | Whether a metered run is open now. |
| `seconds` | `integer` | Yes | Whole seconds observed running inside the window. |

```json title="Example"
{
  "cost_micros": 0,
  "hourly_micros": 0,
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "multiplier": 0.5,
  "running": false,
  "seconds": 0
}
```

## MeDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `access` | [`AccessDto`](/docs/api/schemas#accessdto) | Yes | `waitlisted` while the service is invite-only and this account holds no access grant: it may sign in and read, and work in organizations an approved owner invited it to, but not create organizations. |
| `email` | `string` | Yes |  |
| `login_method_details` | [`LoginMethodDto[]`](/docs/api/schemas#loginmethoddto) | Yes | Each linked sign-in identity, oldest first; `id` is what `DELETE /v1/auth/login-methods/{id}` takes. |
| `login_methods` | `string[]` | Yes | Sign-in provider names linked to this user, sorted. |
| `memberships` | [`MembershipDto[]`](/docs/api/schemas#membershipdto) | Yes | Every organization the user belongs to (with an API key, only the key's). Signing in gives a user who belongs to none their personal organization, unless the deployment disables `auto_personal_organization`. |
| `recent_auth` | `boolean` | Yes |  |
| `user_id` | `string (uuid)` | Yes |  |
| `active_organization_id` | `string (uuid) \| null` | No | The organization the user last switched to (`PUT /v1/me/active-organization`) or joined, while they are still a member; the console sends it as `X-Organization-ID`. With an API key, the key's organization. |
| `name` | `string \| null` | No | Display name from the identity provider's `name` claim, when it supplied one. |
| `waitlist_url` | `string \| null` | No | Where to join the waitlist, while the service is invite-only. |

```json title="Example"
{
  "access": "approved",
  "active_organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "email": "ada@example.com",
  "login_method_details": [
    {
      "created_at": "2026-10-12T05:51:01Z",
      "email": "ada@example.com",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "last_used_at": "2026-10-12T05:51:01Z",
      "provider": "github"
    }
  ],
  "login_methods": [
    "string"
  ],
  "memberships": [
    {
      "access": "approved",
      "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "organization_name": "string",
      "role": "owner"
    }
  ],
  "name": "dev",
  "recent_auth": false,
  "user_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "waitlist_url": "string"
}
```

## MemberDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `string` | Yes |  |
| `joined_at` | `string (date-time)` | Yes |  |
| `role` | [`RoleDto`](/docs/api/schemas#roledto) | Yes |  |
| `running_machines` | `integer` | Yes | Machines the member last asked to run that still want to run; the cap counts these. |
| `usage_this_month` | [`MemberUsageDto`](/docs/api/schemas#memberusagedto) | Yes |  |
| `user_id` | `string (uuid)` | Yes |  |
| `max_running_machines` | `integer \| null` | No | The member's own running-at-once cap; `null` is no cap beyond the organization's plan limits. |

```json title="Example"
{
  "email": "ada@example.com",
  "joined_at": "2026-10-12T05:51:01Z",
  "max_running_machines": 0,
  "role": "owner",
  "running_machines": 0,
  "usage_this_month": {
    "cost_micros": 0,
    "seconds": 0
  },
  "user_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## MemberList

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [`MemberDto[]`](/docs/api/schemas#memberdto) | Yes | Owners first, then by email. |

```json title="Example"
{
  "items": [
    {
      "email": "ada@example.com",
      "joined_at": "2026-10-12T05:51:01Z",
      "max_running_machines": 0,
      "role": "owner",
      "running_machines": 0,
      "usage_this_month": {
        "cost_micros": 0,
        "seconds": 0
      },
      "user_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
    }
  ]
}
```

## MemberRemovedDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `api_keys_revoked` | `integer` | Yes | The member's API keys of this organization, now revoked. |
| `channels_revoked` | `integer` | Yes | Open terminals and desktops revoked; each ends at its relay's next heartbeat (at most 15 s) with reason `revoked`. |
| `tickets_revoked` | `integer` | Yes | Unredeemed terminal and desktop tickets deleted. |
| `user_id` | `string (uuid)` | Yes |  |

```json title="Example"
{
  "api_keys_revoked": 0,
  "channels_revoked": 0,
  "tickets_revoked": 0,
  "user_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## MembershipDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `access` | [`AccessDto`](/docs/api/schemas#accessdto) | Yes | `approved` while one of the organization's owners is approved: its members may then create and start machines and create API keys. |
| `organization_id` | `string (uuid)` | Yes |  |
| `organization_name` | `string` | Yes |  |
| `role` | `string` | Yes |  |

```json title="Example"
{
  "access": "approved",
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "organization_name": "string",
  "role": "owner"
}
```

## MemberUsageDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cost_micros` | `integer` | Yes |  |
| `seconds` | `integer` | Yes | Machine seconds of the runs the member started this UTC month. |

```json title="Example"
{
  "cost_micros": 0,
  "seconds": 0
}
```

## MetricFlagDto

One of: `disk_almost_full`, `disk_full`, `host_disk_low`.

## MetricsPointDto

One chart point. `live` points are the host's samples; `1m` points average the minute's samples, with its maxima and counter-based rates.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `t` | `string (date-time)` | Yes | The sample time, or the minute's start (UTC RFC 3339). |
| `cpu_millis` | `integer \| null` | No |  |
| `cpu_millis_max` | `integer \| null` | No | The minute's highest sample (`1m` only). |
| `cpu_percent` | `number \| null` | No |  |
| `disk_percent` | `number \| null` | No |  |
| `disk_used_bytes` | `integer \| null` | No |  |
| `io_read_bps` | `integer \| null` | No |  |
| `io_write_bps` | `integer \| null` | No |  |
| `memory_bytes` | `integer \| null` | No |  |
| `memory_bytes_max` | `integer \| null` | No | The minute's highest sample (`1m` only). |
| `memory_percent` | `number \| null` | No |  |
| `net_rx_bps` | `integer \| null` | No |  |
| `net_tx_bps` | `integer \| null` | No |  |

```json title="Example"
{
  "cpu_millis": 0,
  "cpu_millis_max": 0,
  "cpu_percent": 0.5,
  "disk_percent": 0.5,
  "disk_used_bytes": 0,
  "io_read_bps": 0,
  "io_write_bps": 0,
  "memory_bytes": 0,
  "memory_bytes_max": 0,
  "memory_percent": 0.5,
  "net_rx_bps": 0,
  "net_tx_bps": 0,
  "t": "2026-10-12T05:51:01Z"
}
```

## MetricsResolutionDto

One of: `live`, `1m`.

## NetworkAccessPolicyDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `egress_options` | [`EgressDto[]`](/docs/api/schemas#egressdto) | Yes | The egress policies a machine of the plan may request at create or change later (`PUT /v1/machines/{machine_id}/network`). Any member who may create machines may choose either; the host's operator can still refuse `internet` with its kill switch. |
| `interactive_access` | [`InteractiveAccessDto`](/docs/api/schemas#interactiveaccessdto) | Yes |  |
| `public_ingress` | [`PublicIngressDto`](/docs/api/schemas#publicingressdto) | Yes |  |
| `ssh_key_selection` | [`SshKeySelectionDto`](/docs/api/schemas#sshkeyselectiondto) | Yes |  |

```json title="Example"
{
  "egress_options": [
    "none"
  ],
  "interactive_access": "managed_terminal",
  "public_ingress": "disabled",
  "ssh_key_selection": "unavailable"
}
```

## NetworkRequest

A requested network policy.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `egress` | [`EgressDto`](/docs/api/schemas#egressdto) | Yes |  |

```json title="Example"
{
  "egress": "none"
}
```

## NotificationDto

Whether the "you're in" email went out.

One of: `sent`, `failed`, `not_configured`, `skipped`.

## NotificationPreferencesDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `alerts` | [`AlertPreferenceDto[]`](/docs/api/schemas#alertpreferencedto) | Yes |  |
| `email` | `string` | Yes | Where alerts are sent: the account's email address. |
| `organization_id` | `string (uuid)` | Yes |  |
| `user_id` | `string (uuid)` | Yes |  |

```json title="Example"
{
  "alerts": [
    {
      "available": false,
      "customized": false,
      "default_enabled": false,
      "description": "A machine could not be stopped.",
      "enabled": false,
      "type": "machine_stop_failed"
    }
  ],
  "email": "ada@example.com",
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "user_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## ObservedStateDto

One of:

- `state: "absent"`
- `state: "provisioning"`
- `state: "running"` with `boot_id`
- `state: "stopped"`
- `state: "degraded"`
- `state: "unknown"`

```json title="Example"
{
  "boot_id": "string",
  "state": "running"
}
```

## OperationAccepted

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `machine_id` | `string (uuid)` | Yes |  |
| `operation_id` | `string (uuid)` | Yes |  |
| `operation_url` | `string` | Yes |  |
| `requested_action` | `string` | Yes |  |
| `status` | `string` | Yes |  |

```json title="Example"
{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "requested_action": "string",
  "status": "pending"
}
```

## OperationDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `attempt_count` | `integer` | Yes |  |
| `completed_but_unchanged` | `boolean` | Yes |  |
| `id` | `string (uuid)` | Yes |  |
| `kind` | `string` | Yes |  |
| `machine_id` | `string (uuid)` | Yes |  |
| `status` | [`OperationStatusDto`](/docs/api/schemas#operationstatusdto) | Yes |  |
| `error_code` | `string \| null` | No |  |
| `exec_result` | [`null \| ExecResultDto`](/docs/api/schemas#execresultdto) | No |  |
| `file_ranges` | [`FileRangeDto[] \| null`](/docs/api/schemas#filerangedto) | No | For a succeeded `file_read`: the ranges read, as untrusted guest data. |
| `starting_soon` | [`null \| StartingSoonDto`](/docs/api/schemas#startingsoondto) | No | For a pending `create` or `start` the fleet has no room for yet: why it waits and until when ("starting soon"); `null` otherwise. |
| `stop_reason` | [`null \| StopReasonDto`](/docs/api/schemas#stopreasondto) | No | For a `stop`: who asked for it; `null` for other kinds. |

```json title="Example"
{
  "attempt_count": 0,
  "completed_but_unchanged": false,
  "error_code": "string",
  "exec_result": {
    "cancelled": false,
    "exit_code": 0,
    "stderr_base64": "string",
    "stdout_base64": "string",
    "timed_out": false,
    "truncated": false
  },
  "file_ranges": [
    {
      "data_base64": "string",
      "missing": false,
      "offset": 0,
      "path": "notes/todo.txt",
      "size": 0
    }
  ],
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "kind": "stop",
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "starting_soon": {
    "expires_at": "2026-10-12T05:51:01Z",
    "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "position": 0,
    "priority": "paid",
    "queued_at": "2026-10-12T05:51:01Z",
    "reason": "no_host_in_region"
  },
  "status": "pending",
  "stop_reason": "idle_sleep"
}
```

## OperationEventDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | `string` | Yes |  |
| `stage` | `string` | Yes |  |
| `timestamp` | `string` | Yes |  |

```json title="Example"
{
  "message": "string",
  "stage": "accepted",
  "timestamp": "string"
}
```

## OperationStatusDto

One of: `pending`, `running`, `succeeded`, `failed`, `uncertain`, `correlation_miss`.

## OperatorActionRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `operator` | `string` | Yes | The individual operator acting (a name or work email), recorded in the audit log; 1-200 characters. |
| `reason` | `string` | Yes | Why; recorded in the audit log, 1-500 characters. A suspension's reason is shown to operators only. |

```json title="Example"
{
  "operator": "string",
  "reason": "string"
}
```

## OperatorCreditDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `outcome` | `string` | Yes | `applied` or `duplicate`. |
| `credit_balance_micros` | `integer \| null` | No | The credit balance after an applied change. |

```json title="Example"
{
  "credit_balance_micros": 0,
  "outcome": "string"
}
```

## OperatorCreditRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micros` | `integer` | Yes | Positive micros (1 USD = 1000000). at least 1. |
| `idempotency_key` | `string` | Yes | Replaying the same key applies the change once. |
| `kind` | [`CreditKindDto`](/docs/api/schemas#creditkinddto) | Yes |  |
| `operator` | `string` | Yes | The individual operator acting, 1-200 characters. |
| `organization_id` | `string (uuid)` | Yes |  |
| `reason` | `string` | Yes | Why, 1-500 characters; kept on the ledger row and in the audit log, never shown to the organization. |

```json title="Example"
{
  "amount_micros": 1,
  "idempotency_key": "string",
  "kind": "grant",
  "operator": "string",
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "reason": "string"
}
```

## OperatorGrantRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `idempotency_key` | `string` | Yes | Replaying the same key applies the grant once. |
| `kind` | [`GrantKindDto`](/docs/api/schemas#grantkinddto) | Yes |  |
| `organization_id` | `string (uuid)` | Yes |  |
| `reason` | `string` | Yes | Why the grant was made; recorded in the audit log. |
| `amount_micros` | `integer \| null` | No | Micros for `credits` and `trial`. |
| `period_days` | `integer \| null` | No | Period length for `plan_period`, starting now (1-366, default 30). |
| `tier` | `string \| null` | No | Tier for `plan_period`. |

```json title="Example"
{
  "amount_micros": 0,
  "idempotency_key": "string",
  "kind": "credits",
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "period_days": 0,
  "reason": "string",
  "tier": "pro"
}
```

## OrganizationDeletedDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `api_keys_revoked` | `integer` | Yes |  |
| `channels_revoked` | `integer` | Yes |  |
| `machines_stopping` | `integer` | Yes | Machines that wanted to run; each gets a durable stop (`stop_reason: organization_deleted`) within about a second. |
| `members_removed` | `integer` | Yes |  |
| `organization_id` | `string (uuid)` | Yes |  |
| `tickets_revoked` | `integer` | Yes |  |

```json title="Example"
{
  "api_keys_revoked": 0,
  "channels_revoked": 0,
  "machines_stopping": 0,
  "members_removed": 0,
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "tickets_revoked": 0
}
```

## OrganizationDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | `string (date-time)` | Yes |  |
| `id` | `string (uuid)` | Yes |  |
| `name` | `string` | Yes |  |
| `role` | `string` | Yes | The caller's role in the organization. |
| `suspended_at` | `string (date-time) \| null` | No | When an operator suspended the organization; `null` unless it is suspended. While suspended its machines are stopped and nothing may create, start, or reach into one (`403 organization_suspended`); reads, billing, keys, and settings still work. |

```json title="Example"
{
  "created_at": "2026-10-12T05:51:01Z",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "name": "dev",
  "role": "owner",
  "suspended_at": "2026-10-12T05:51:01Z"
}
```

## OrganizationList

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [`OrganizationDto[]`](/docs/api/schemas#organizationdto) | Yes | Every organization the caller belongs to, by name. With an API key, only the key's organization. |

```json title="Example"
{
  "items": [
    {
      "created_at": "2026-10-12T05:51:01Z",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "name": "dev",
      "role": "owner",
      "suspended_at": "2026-10-12T05:51:01Z"
    }
  ]
}
```

## OutputStreamDto

One of: `stdout`, `stderr`.

## PlanDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `backend` | [`BackendDto`](/docs/api/schemas#backenddto) | Yes |  |
| `cpu` | `integer` | Yes |  |
| `disk_gib` | `integer` | Yes |  |
| `id` | `string (uuid)` | Yes |  |
| `memory_mib` | `integer` | Yes |  |
| `name` | `string` | Yes |  |
| `network_access` | [`NetworkAccessPolicyDto`](/docs/api/schemas#networkaccesspolicydto) | Yes |  |
| `price` | [`PlanPriceDto`](/docs/api/schemas#planpricedto) | Yes |  |
| `version` | `integer` | Yes |  |
| `size` | `string \| null` | No | `small`, `default`, `large`, or `xlarge` for the seeded size plans; `null` for other plans. |

```json title="Example"
{
  "backend": "mock",
  "cpu": 0,
  "disk_gib": 0,
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "memory_mib": 0,
  "name": "small",
  "network_access": {
    "egress_options": [
      "none"
    ],
    "interactive_access": "managed_terminal",
    "public_ingress": "disabled",
    "ssh_key_selection": "unavailable"
  },
  "price": {
    "currency": "USD",
    "effective_from": "2026-01-01T00:00:00.000000Z",
    "hourly": "0.012500",
    "monthly": "9.125000"
  },
  "size": "string",
  "version": 0
}
```

## PlanPage

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [`PlanDto[]`](/docs/api/schemas#plandto) | Yes |  |
| `next_cursor` | `string \| null` | No |  |

```json title="Example"
{
  "items": [
    {
      "backend": "mock",
      "cpu": 0,
      "disk_gib": 0,
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "memory_mib": 0,
      "name": "small",
      "network_access": {
        "egress_options": [
          "none"
        ],
        "interactive_access": "managed_terminal",
        "public_ingress": "disabled",
        "ssh_key_selection": "unavailable"
      },
      "price": {
        "currency": "USD",
        "effective_from": "2026-01-01T00:00:00.000000Z",
        "hourly": "0.012500",
        "monthly": "9.125000"
      },
      "size": "string",
      "version": 0
    }
  ],
  "next_cursor": "string"
}
```

## PlanPriceDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `currency` | `string` | Yes | pattern `^[A-Z]{3}$`. |
| `effective_from` | `string (date-time)` | Yes |  |
| `hourly` | `string` | Yes | pattern `^(0\|[1-9][0-9]*)\.[0-9]{6}$`. |
| `monthly` | `string` | Yes | pattern `^(0\|[1-9][0-9]*)\.[0-9]{6}$`. |

```json title="Example"
{
  "currency": "USD",
  "effective_from": "2026-01-01T00:00:00.000000Z",
  "hourly": "0.012500",
  "monthly": "9.125000"
}
```

## PlanSubscriptionDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `active` | `boolean` | Yes | Whether the period covers now. |
| `cancel_at_period_end` | `boolean` | Yes | The linked subscription was cancelled: the plan ends at `period_end` unless resumed before then. |
| `included_micros` | `integer` | Yes | Usage included each period, in micros. It expires at `period_end`. |
| `included_seconds` | `integer` | Yes | The allowance as `default`-size seconds. |
| `period_end` | `string` | Yes |  |
| `period_start` | `string` | Yes |  |
| `price_micros` | `integer` | Yes |  |
| `renews` | `boolean` | Yes |  |
| `tier` | `string` | Yes | `starter` ($20), `pro` ($100), `team` ($500), or `scale` ($2000). |

```json title="Example"
{
  "active": false,
  "cancel_at_period_end": false,
  "included_micros": 0,
  "included_seconds": 0,
  "period_end": "string",
  "period_start": "string",
  "price_micros": 0,
  "renews": false,
  "tier": "pro"
}
```

## PortalDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | `string` | Yes |  |

```json title="Example"
{
  "url": "https://hooks.example.com/vmyard"
}
```

## PortDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `localhost` | `boolean` | Yes |  |
| `port` | `integer` | Yes |  |
| `public` | `boolean` | Yes |  |
| `url` | `string` | Yes | `https://<label>-<port>.<edge domain>`. |

```json title="Example"
{
  "localhost": false,
  "port": 0,
  "public": false,
  "url": "https://hooks.example.com/vmyard"
}
```

## PortListDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [`PortDto[]`](/docs/api/schemas#portdto) | Yes | Exposed ports as the machine's host last confirmed them, by port. |
| `label` | `string \| null` | No | The machine's name in port URLs; `null` until a port was first exposed. |

```json title="Example"
{
  "items": [
    {
      "localhost": false,
      "port": 0,
      "public": false,
      "url": "https://hooks.example.com/vmyard"
    }
  ],
  "label": "k7f2mq3x9a1b"
}
```

## PortTokenDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `expires_at` | `string` | Yes | When the token stops working (UTC RFC 3339). |
| `header_token` | `string` | Yes | For API clients: send it as `X-Vmyard-Token`. A version 2 edge token bound to this route host and the host sandbox the machine runs in now; it stops working once the machine runs in another sandbox. |
| `url` | `string` | Yes | The port URL without a token. |
| `url_with_token` | `string` | Yes | Opens the port in a browser: the edge answers `302` to `url` and sets a host-scoped cookie, removing the token from the address bar. |

```json title="Example"
{
  "expires_at": "string",
  "header_token": "string",
  "url": "https://hooks.example.com/vmyard",
  "url_with_token": "string"
}
```

## PortTokenRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ttl_seconds` | `integer \| null` | No | Token lifetime, 1-3600 seconds; default 900. 1–3600. |

```json title="Example"
{
  "ttl_seconds": 1
}
```

## ProblemDetails

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | `string` | Yes |  |
| `correlation_id` | `string (uuid)` | Yes |  |
| `field_errors` | `map of string` | Yes |  |
| `message` | `string` | Yes |  |
| `remediation` | `string` | Yes |  |
| `status` | `integer` | Yes |  |
| `title` | `string` | Yes |  |
| `type` | `string` | Yes |  |
| `retry_after_seconds` | `integer \| null` | No |  |
| `waitlist_url` | `string \| null` | No | With `waitlisted`: where to join the waitlist. |

```json title="Example"
{
  "code": "string",
  "correlation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "field_errors": {},
  "message": "string",
  "remediation": "string",
  "retry_after_seconds": 0,
  "status": 0,
  "title": "string",
  "type": "string",
  "waitlist_url": "string"
}
```

## ProviderModelDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | Yes | What to send as `model` in a prompt. |
| `name` | `string` | Yes |  |
| `attachments` | `boolean \| null` | No | Accepts image or file input. |
| `context_tokens` | `integer \| null` | No |  |
| `provider` | `string \| null` | No | The catalog provider that serves it (`anthropic`, `openai`, ...). |
| `reasoning` | `boolean \| null` | No |  |
| `release_date` | `string \| null` | No | `YYYY-MM-DD`, as the catalog states it. |

```json title="Example"
{
  "attachments": false,
  "context_tokens": 0,
  "id": "string",
  "name": "dev",
  "provider": "anthropic",
  "reasoning": false,
  "release_date": "string"
}
```

## ProviderModelsDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `providers` | [`AgentModelsDto[]`](/docs/api/schemas#agentmodelsdto) | Yes |  |
| `source` | [`ProviderModelsSourceDto`](/docs/api/schemas#providermodelssourcedto) | Yes |  |

```json title="Example"
{
  "providers": [
    {
      "models": [
        {
          "attachments": false,
          "context_tokens": 0,
          "id": "string",
          "name": "dev",
          "provider": "anthropic",
          "reasoning": false,
          "release_date": "string"
        }
      ],
      "provider": "claude",
      "reasoning_efforts": [
        "minimal"
      ]
    }
  ],
  "source": "live"
}
```

## ProviderModelsSourceDto

One of: `live`, `builtin`.

## PublicIngressDto

One of: `disabled`.

## ReadySnapshotDto

A machine's newest ready snapshot, for the Files view's snapshot section.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | `string (date-time)` | Yes | When the snapshot was requested (UTC RFC 3339): the instant it copies. |
| `id` | `string (uuid)` | Yes |  |
| `source` | [`SnapshotSourceDto`](/docs/api/schemas#snapshotsourcedto) | Yes |  |
| `tier` | [`SnapshotTierDto`](/docs/api/schemas#snapshottierdto) | Yes |  |
| `completed_at` | `string (date-time) \| null` | No | When it became ready. |
| `size_bytes` | `integer \| null` | No | Plaintext bytes of the snapshot's files. |

```json title="Example"
{
  "completed_at": "2026-10-12T05:51:01Z",
  "created_at": "2026-10-12T05:51:01Z",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "size_bytes": 0,
  "source": "api",
  "tier": "warm"
}
```

## ReasoningEffortDto

One of: `minimal`, `low`, `medium`, `high`, `xhigh`.

## RegionDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `backend` | [`BackendDto`](/docs/api/schemas#backenddto) | Yes |  |
| `capacity_status` | `string` | Yes |  |
| `id` | `string (uuid)` | Yes |  |
| `name` | `string` | Yes |  |
| `version` | `integer` | Yes |  |

```json title="Example"
{
  "backend": "mock",
  "capacity_status": "available",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "name": "eu-central",
  "version": 0
}
```

## RegionPage

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [`RegionDto[]`](/docs/api/schemas#regiondto) | Yes |  |
| `next_cursor` | `string \| null` | No |  |

```json title="Example"
{
  "items": [
    {
      "backend": "mock",
      "capacity_status": "available",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "name": "eu-central",
      "version": 0
    }
  ],
  "next_cursor": "string"
}
```

## RemoveFileRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `path` | `string` | Yes |  |

```json title="Example"
{
  "path": "notes/todo.txt"
}
```

## ResolveAbuseFlagRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `note` | `string` | Yes | What the review found, 1-500 characters. |
| `operator` | `string` | Yes | The individual operator acting, 1-200 characters. |
| `resolution` | [`FlagResolutionDto`](/docs/api/schemas#flagresolutiondto) | Yes |  |

```json title="Example"
{
  "note": "string",
  "operator": "string",
  "resolution": "dismissed"
}
```

## ResourcesDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cpu` | `integer` | Yes |  |
| `disk_gib` | `integer` | Yes |  |
| `memory_mib` | `integer` | Yes |  |

```json title="Example"
{
  "cpu": 0,
  "disk_gib": 0,
  "memory_mib": 0
}
```

## RestoreMachineRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `snapshot_id` | `string (uuid)` | Yes | A ready snapshot of this machine. |
| `keep_ssh_keys` | `boolean` | No | Keep the login user's SSH `authorized_keys` (default `false`). |
| `name` | `string \| null` | No | The new machine's display name. |
| `wake` | `boolean \| null` | No | Wake the new machine at once (default `true`); `false` creates it stopped. |

```json title="Example"
{
  "keep_ssh_keys": false,
  "name": "dev",
  "snapshot_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "wake": false
}
```

## ResumeDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `organization_id` | `string (uuid)` | Yes |  |
| `resumed` | `boolean` | Yes | False when the organization was not suspended. |

```json title="Example"
{
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "resumed": false
}
```

## RevealedEnvironmentDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `environment_id` | `string (uuid)` | Yes |  |
| `files` | [`RevealedFileDto[]`](/docs/api/schemas#revealedfiledto) | Yes |  |
| `vars` | `map of string` | Yes |  |
| `version` | [`EnvironmentVersionDto`](/docs/api/schemas#environmentversiondto) | Yes |  |

```json title="Example"
{
  "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "files": [
    {
      "contents": "string",
      "encoding": "text",
      "path": "notes/todo.txt"
    }
  ],
  "vars": {},
  "version": {
    "change": {},
    "created_at": "string",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "files": [
      {
        "path": "notes/todo.txt",
        "size": 0
      }
    ],
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "vars": [
      "string"
    ],
    "version": 0
  }
}
```

## RevealedFileDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `contents` | `string` | Yes |  |
| `encoding` | [`FileEncodingDto`](/docs/api/schemas#fileencodingdto) | Yes | Always `base64`, so the exact bytes come back. |
| `path` | `string` | Yes |  |

```json title="Example"
{
  "contents": "string",
  "encoding": "text",
  "path": "notes/todo.txt"
}
```

## RevealRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version_id` | `string (uuid) \| null` | No | A version of this environment; omitted reveals the current version. |

```json title="Example"
{
  "version_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## RoleDto

One of: `owner`, `admin`, `operator`, `billing`, `viewer`.

## SecretFileInput

A secret file. `contents` is UTF-8 text unless `encoding` is `base64`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `contents` | `string` | Yes |  |
| `path` | `string` | Yes | Relative to `/work`: no leading `/`, `~`, `.`, `..`, or empty components, and not under `.vmyard`. |
| `encoding` | [`FileEncodingDto`](/docs/api/schemas#fileencodingdto) | No |  |

```json title="Example"
{
  "contents": "string",
  "encoding": "text",
  "path": "notes/todo.txt"
}
```

## SetSshKeyRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `public_key` | `string` | Yes | One OpenSSH public key line: `ssh-ed25519`, `ecdsa-sha2-nistp256/384/521`, or `ssh-rsa` of at least 3072 bits, with an optional comment, without a trailing newline. |

```json title="Example"
{
  "public_key": "string"
}
```

## SetVariableRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `string` | Yes | At most 32 KiB without NUL. |

```json title="Example"
{
  "value": "string"
}
```

## SignInProviderDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `default` | `boolean` | Yes | Used when `/v1/auth/login` names no provider. |
| `display_name` | `string` | Yes | The button label, such as "ERP.AI" ("Continue with ERP.AI"). |
| `kind` | [`SignInProviderKindDto`](/docs/api/schemas#signinproviderkinddto) | Yes |  |
| `name` | `string` | Yes | What `provider` takes, such as `erpai`, `github`, or `email`. |

```json title="Example"
{
  "default": false,
  "display_name": "string",
  "kind": "oidc",
  "name": "dev"
}
```

## SignInProviderKindDto

One of: `oidc`, `github`, `email`.

## SignInProvidersDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `access` | [`AccessModeDto`](/docs/api/schemas#accessmodedto) | Yes | `invite_only`: anyone may sign in, but only approved accounts may create organizations, machines, and API keys. |
| `providers` | [`SignInProviderDto[]`](/docs/api/schemas#signinproviderdto) | Yes | Sorted by name. |
| `waitlist_url` | `string \| null` | No | Where to join the waitlist, while invite-only. |

```json title="Example"
{
  "access": "open",
  "providers": [
    {
      "default": false,
      "display_name": "string",
      "kind": "oidc",
      "name": "dev"
    }
  ],
  "waitlist_url": "string"
}
```

## SnapshotAccepted

A push or template save was accepted.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `machine_id` | `string (uuid)` | Yes |  |
| `operation_id` | `string (uuid)` | Yes |  |
| `operation_url` | `string` | Yes |  |
| `snapshot_id` | `string (uuid)` | Yes |  |
| `snapshot_url` | `string` | Yes |  |
| `status` | `string` | Yes |  |

```json title="Example"
{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "snapshot_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "snapshot_url": "string",
  "status": "string"
}
```

## SnapshotDeleteItemDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `result` | [`SnapshotDeleteResultDto`](/docs/api/schemas#snapshotdeleteresultdto) | Yes |  |
| `snapshot_id` | `string (uuid)` | Yes |  |

```json title="Example"
{
  "result": "deleted",
  "snapshot_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## SnapshotDeleteResultDto

What happened to one requested snapshot.

One of: `deleted`, `not_found`, `pending`, `template`.

## SnapshotDeleteResults

Per-snapshot results of a bulk delete, in request order (oldest first for a machine's snapshots). The request succeeds even when some items were not deleted.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deleted` | `integer` | Yes | How many were deleted. |
| `results` | [`SnapshotDeleteItemDto[]`](/docs/api/schemas#snapshotdeleteitemdto) | Yes |  |

```json title="Example"
{
  "deleted": 0,
  "results": [
    {
      "result": "deleted",
      "snapshot_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
    }
  ]
}
```

## SnapshotDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | `string (date-time)` | Yes |  |
| `id` | `string (uuid)` | Yes |  |
| `machine_id` | `string (uuid)` | Yes | The machine the snapshot was taken from. |
| `operation_id` | `string (uuid)` | Yes | The push operation. |
| `source` | [`SnapshotSourceDto`](/docs/api/schemas#snapshotsourcedto) | Yes |  |
| `status` | [`SnapshotStatusDto`](/docs/api/schemas#snapshotstatusdto) | Yes |  |
| `tier` | [`SnapshotTierDto`](/docs/api/schemas#snapshottierdto) | Yes |  |
| `completed_at` | `string (date-time) \| null` | No |  |
| `disk_synced` | `boolean \| null` | No | The guest flushed its filesystems before the snapshot. |
| `error_code` | `string \| null` | No |  |
| `generation` | `integer \| null` | No | 1 for a machine's first push, then one more than its parent's. |
| `manifest` | `string \| null` | No | The stored manifest (64 hex digits) once ready. |
| `name` | `string \| null` | No | The template name, for a template. |
| `parent_manifest` | `string \| null` | No | The manifest the machine last was or came from. |
| `size_bytes` | `integer \| null` | No | Plaintext bytes of the snapshot's files. |
| `uploaded_bytes` | `integer \| null` | No | Compressed bytes this push uploaded (chunks already stored are reused). |

```json title="Example"
{
  "completed_at": "2026-10-12T05:51:01Z",
  "created_at": "2026-10-12T05:51:01Z",
  "disk_synced": false,
  "error_code": "string",
  "generation": 0,
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "manifest": "string",
  "name": "dev",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "parent_manifest": "string",
  "size_bytes": 0,
  "source": "api",
  "status": "pending",
  "tier": "warm",
  "uploaded_bytes": 0
}
```

## SnapshotPage

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [`SnapshotDto[]`](/docs/api/schemas#snapshotdto) | Yes |  |
| `next_cursor` | `string (uuid) \| null` | No |  |

```json title="Example"
{
  "items": [
    {
      "completed_at": "2026-10-12T05:51:01Z",
      "created_at": "2026-10-12T05:51:01Z",
      "disk_synced": false,
      "error_code": "string",
      "generation": 0,
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "manifest": "string",
      "name": "dev",
      "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "parent_manifest": "string",
      "size_bytes": 0,
      "source": "api",
      "status": "pending",
      "tier": "warm",
      "uploaded_bytes": 0
    }
  ],
  "next_cursor": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## SnapshotSourceDto

Who took a snapshot.

One of: `api`, `tier_policy`, `automatic`.

## SnapshotStatusDto

One of: `pending`, `ready`, `failed`.

## SnapshotTierDto

One of: `warm`, `cold`.

## SshAccessDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `port` | `integer` | Yes | The gateway port allocated to the machine. |
| `user` | `string` | Yes |  |
| `host` | `string \| null` | No | The SSH gateway for the machine's host or region; `null` when none is configured. |

```json title="Example"
{
  "host": "ssh.eu.example.com",
  "port": 0,
  "user": "vmyard"
}
```

## SshKeySelectionDto

One of: `unavailable`.

## StaleReasonDto

One of: `host_unreachable`, `not_reported`, `poll_overdue`.

## StartCommandRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `argv` | `string[] \| null` | No | Program and arguments. Exactly one of `argv` or `command`. |
| `command` | `string \| null` | No | Shell command run as `/bin/sh -c <command>`, at most 8192 bytes. |

```json title="Example"
{
  "argv": [
    "string"
  ],
  "command": "string"
}
```

## StartingSoonDto

A create or start waiting for capacity. Its operation stays `pending` and is tried again every few seconds; it begins as soon as a server has room, or fails as `capacity_unavailable` at `expires_at`. Nothing is billed while it waits.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `expires_at` | `string (date-time)` | Yes | When it fails if no room appears (UTC RFC 3339). |
| `operation_id` | `string (uuid)` | Yes | The waiting `create` or `start` operation. |
| `position` | `integer` | Yes | Its place in line among the region's waiting starts (1 is next; paid starts are ahead of every trial start). |
| `priority` | [`StartPriorityDto`](/docs/api/schemas#startprioritydto) | Yes |  |
| `queued_at` | `string (date-time)` | Yes | When it began waiting (UTC RFC 3339). |
| `reason` | [`CapacityShortageDto`](/docs/api/schemas#capacityshortagedto) | Yes |  |

```json title="Example"
{
  "expires_at": "2026-10-12T05:51:01Z",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "position": 0,
  "priority": "paid",
  "queued_at": "2026-10-12T05:51:01Z",
  "reason": "no_host_in_region"
}
```

## StartLimitDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | `integer` | Yes |  |
| `used` | `integer` | Yes |  |
| `window` | `string` | Yes | Rolling window: `minute`, `hour`, or `day`. |

```json title="Example"
{
  "limit": 0,
  "used": 0,
  "window": "hour"
}
```

## StartPriorityDto

Paid starts leave the queue before trial starts.

One of: `paid`, `trial`.

## StopReasonDto

Who asked for a stop: a caller through the API, or the control plane itself (an auto-stop deadline, an exhausted balance, idle sleep, an operator's suspension of the organization, the sustained-CPU abuse guard, or the organization's deletion).

One of: `api`, `auto_stop`, `billing`, `idle_sleep`, `suspension`, `abuse`, `organization_deleted`.

## SuspensionDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `already_suspended` | `boolean` | Yes | The organization was already suspended: nothing changed, and the original suspension is returned. |
| `channels_revoked` | `integer` | Yes | Open terminals and desktops revoked; each ends at its relay's next heartbeat (at most 15 s) with reason `revoked`. |
| `machines_stopping` | `integer` | Yes | Machines that wanted to run; the worker persists a stop for each (`stop_reason: suspension`) within about a second. |
| `organization_id` | `string (uuid)` | Yes |  |
| `reason` | `string` | Yes |  |
| `suspended_at` | `string` | Yes |  |
| `tickets_revoked` | `integer` | Yes | Unredeemed terminal and desktop tickets deleted. |

```json title="Example"
{
  "already_suspended": false,
  "channels_revoked": 0,
  "machines_stopping": 0,
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "reason": "string",
  "suspended_at": "string",
  "tickets_revoked": 0
}
```

## TerminalClientMessage

A JSON text message from the browser.

One of:

- `type: "resize"` with `cols`, `rows`
- `type: "signal"` with `signal`
- `type: "close"`

```json title="Example"
{
  "cols": 0,
  "rows": 0,
  "type": "resize"
}
```

## TerminalServerMessage

A JSON text message to the browser. `exit` and `closed` are final; the WebSocket closes after them.

One of:

- `type: "opened"` with `terminal_id`, `user`
- `type: "exit"` with `exit_code`, `signal`
- `type: "closed"` with `reason`

```json title="Example"
{
  "terminal_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "type": "opened",
  "user": "vmyard"
}
```

## TerminalTicketDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `expires_at` | `string` | Yes |  |
| `ticket` | `string` | Yes | Single-use credential for one terminal WebSocket of this machine, valid for 30 seconds, only with the session that minted it. |
| `url` | `string` | Yes | The WebSocket path with the ticket; add `cols` and `rows`. |

```json title="Example"
{
  "expires_at": "string",
  "ticket": "string",
  "url": "https://hooks.example.com/vmyard"
}
```

## TransferOwnershipRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `user_id` | `string (uuid)` | Yes | A member who becomes the owner; the caller becomes an admin. |

```json title="Example"
{
  "user_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## TrialDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `active` | `boolean` | Yes | Whether trial rules (two machines, small/default only) apply. |
| `concurrent_machines` | `integer` | Yes |  |
| `max_hourly_micros` | `integer` | Yes | Sizes priced above this hourly rate are refused during the trial. |
| `remaining_micros` | `integer` | Yes |  |
| `remaining_seconds` | `integer` | Yes | Remaining trial time as `default`-size seconds. |
| `total_micros` | `integer` | Yes |  |
| `ended_at` | `string \| null` | No | When the trial was ended early and its remaining balance forfeited. Trial rules still apply until the first payment. |

```json title="Example"
{
  "active": false,
  "concurrent_machines": 0,
  "ended_at": "string",
  "max_hourly_micros": 0,
  "remaining_micros": 0,
  "remaining_seconds": 0,
  "total_micros": 0
}
```

## UnsubscribedDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | `boolean` | Yes |  |
| `organization_id` | `string (uuid)` | Yes |  |
| `type` | `string` | Yes |  |

```json title="Example"
{
  "enabled": false,
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "type": "operation_failed"
}
```

## UpdateAutoRefillRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `credit_packs` | `integer` | Yes | 1-50 packs of $20. 1–50. |
| `enabled` | `boolean` | Yes |  |
| `monthly_cap_micros` | `integer` | Yes | At least one refill's amount. |
| `threshold_micros` | `integer` | Yes |  |

```json title="Example"
{
  "credit_packs": 1,
  "enabled": false,
  "monthly_cap_micros": 0,
  "threshold_micros": 0
}
```

## UpdateBillingRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `minimum_balance_micros` | `integer \| null` | No |  |
| `spend_cap_micros` | `integer \| null` | No | Monthly credit spend cap in micros, or `null` to remove it. |

```json title="Example"
{
  "minimum_balance_micros": 0,
  "spend_cap_micros": 0
}
```

## UpdateEnvironmentRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `is_default` | `boolean \| null` | No | `true` makes this the default; `false` leaves the organization without one. |
| `name` | `string \| null` | No |  |
| `safe_for_third_parties` | `boolean \| null` | No |  |

```json title="Example"
{
  "is_default": false,
  "name": "dev",
  "safe_for_third_parties": false
}
```

## UpdateMachineRequest

A partial settings change. At least one setting is required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `auto_stop_after_seconds` | `integer \| null` | No | New auto-stop duration, 60 to 2592000 seconds, or `null` for never. The deadline of a running machine restarts from now. 60–2592000. |
| `idle_sleep_after_seconds` | `integer \| null` | No | New idle-sleep window, 300 to 86400 seconds, or `null` to turn idle sleep off. The idle window restarts. 300–86400. |
| `name` | `string \| null` | No | New display name, following the `tenant_alias` rules. The tenant alias itself is immutable. |
| `never_auto_stop` | `boolean` | No | `true` disables auto-stop. It cannot be combined with `auto_stop_after_seconds`. |

```json title="Example"
{
  "auto_stop_after_seconds": 60,
  "idle_sleep_after_seconds": 300,
  "name": "dev",
  "never_auto_stop": false
}
```

## UpdateMemberRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `max_running_machines` | `integer \| null` | No | 0-10000, or `null` to remove the member's cap; absent leaves it. at most 10000. |
| `role` | [`null \| RoleDto`](/docs/api/schemas#roledto) | No |  |

```json title="Example"
{
  "max_running_machines": 0,
  "role": "owner"
}
```

## UpdateNotificationPreferencesRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `alerts` | `map of string` | Yes | Alert type to on (`true`) or off (`false`); unlisted types keep their current setting. |

```json title="Example"
{
  "alerts": {}
}
```

## UpdateOrganizationRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | 1–64 characters. |

```json title="Example"
{
  "name": "dev"
}
```

## UpdateWebhookRequest

Omitted fields keep their value; at least one field is required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | `boolean \| null` | No |  |
| `events` | [`WebhookEventDto[] \| null`](/docs/api/schemas#webhookeventdto) | No | at least 1 items. |
| `name` | `string \| null` | No | 1–64 characters. |
| `url` | `string \| null` | No | at most 2048 characters. |

```json title="Example"
{
  "enabled": false,
  "events": [
    "machine.ready"
  ],
  "name": "dev",
  "url": "https://hooks.example.com/vmyard"
}
```

## UpgradeEnvironmentRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `machine_ids` | `string (uuid)[] \| null` | No | Machines to upgrade; omitted upgrades every running machine created with this environment. At most 100. |

```json title="Example"
{
  "machine_ids": [
    "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
  ]
}
```

## UpgradeEnvironmentResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `environment_id` | `string (uuid)` | Yes |  |
| `operations` | [`UpgradeOperationDto[]`](/docs/api/schemas#upgradeoperationdto) | Yes | One `apply_environment` operation per upgraded machine. |
| `skipped` | [`UpgradeSkippedDto[]`](/docs/api/schemas#upgradeskippeddto) | Yes |  |
| `version` | `integer` | Yes |  |
| `version_id` | `string (uuid)` | Yes |  |

```json title="Example"
{
  "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operations": [
    {
      "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
    }
  ],
  "skipped": [
    {
      "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "reason": "not_running"
    }
  ],
  "version": 0,
  "version_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## UpgradeOperationDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `machine_id` | `string (uuid)` | Yes |  |
| `operation_id` | `string (uuid)` | Yes |  |
| `operation_url` | `string` | Yes |  |

```json title="Example"
{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## UpgradeSkippedDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `machine_id` | `string (uuid)` | Yes |  |
| `reason` | `string` | Yes | `already_current` or `not_running` (start it, then upgrade again). |

```json title="Example"
{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "reason": "not_running"
}
```

## UsageDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cost_micros` | `integer` | Yes |  |
| `machines` | [`MachineUsageDto[]`](/docs/api/schemas#machineusagedto) | Yes |  |
| `seconds` | `integer` | Yes |  |
| `since` | `string` | Yes |  |
| `until` | `string` | Yes |  |

```json title="Example"
{
  "cost_micros": 0,
  "machines": [
    {
      "cost_micros": 0,
      "hourly_micros": 0,
      "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "multiplier": 0.5,
      "running": false,
      "seconds": 0
    }
  ],
  "seconds": 0,
  "since": "string",
  "until": "string"
}
```

## VersionedSelectionDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string (uuid)` | Yes |  |
| `version` | `integer` | Yes |  |

```json title="Example"
{
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "version": 0
}
```

## WaitlistAckDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `received` | `boolean` | Yes |  |

```json title="Example"
{
  "received": false
}
```

## WaitlistDecisionDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `changed` | `boolean` | Yes | False when the entry already had this decision. |
| `entry` | [`WaitlistEntryDto`](/docs/api/schemas#waitlistentrydto) | Yes |  |
| `notification` | [`NotificationDto`](/docs/api/schemas#notificationdto) | Yes |  |
| `grant` | [`null \| AccessGrantDto`](/docs/api/schemas#accessgrantdto) | No | The access grant behind an approved or revoked entry. |

```json title="Example"
{
  "changed": false,
  "entry": {
    "access_grant_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "company": "string",
    "created_at": "string",
    "decided_at": "string",
    "decided_by": "string",
    "decision_reason": "string",
    "email": "ada@example.com",
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "name": "dev",
    "raw_answers": {},
    "status": "pending",
    "updated_at": "string",
    "use_case": "string"
  },
  "grant": {
    "created_at": "string",
    "credited_at": "string",
    "credited_organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "email": "ada@example.com",
    "granted_by": "string",
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "initial_credit_micros": 0,
    "provider": "github",
    "reason": "string",
    "revoke_reason": "string",
    "revoked_at": "string",
    "revoked_by": "string",
    "subject": "string"
  },
  "notification": "sent"
}
```

## WaitlistDecisionRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `operator` | `string` | Yes | The individual operator acting, 1-200 characters. |
| `reason` | `string` | Yes | Why, 1-500 characters. |

```json title="Example"
{
  "operator": "string",
  "reason": "string"
}
```

## WaitlistEntryDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | `string` | Yes |  |
| `email` | `string` | Yes |  |
| `id` | `string (uuid)` | Yes |  |
| `raw_answers` | `object` | Yes | The form's answers as received. |
| `status` | [`WaitlistStatusDto`](/docs/api/schemas#waitliststatusdto) | Yes |  |
| `updated_at` | `string` | Yes |  |
| `access_grant_id` | `string (uuid) \| null` | No |  |
| `company` | `string \| null` | No |  |
| `decided_at` | `string \| null` | No |  |
| `decided_by` | `string \| null` | No |  |
| `decision_reason` | `string \| null` | No |  |
| `name` | `string \| null` | No |  |
| `use_case` | `string \| null` | No |  |

```json title="Example"
{
  "access_grant_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "company": "string",
  "created_at": "string",
  "decided_at": "string",
  "decided_by": "string",
  "decision_reason": "string",
  "email": "ada@example.com",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "name": "dev",
  "raw_answers": {},
  "status": "pending",
  "updated_at": "string",
  "use_case": "string"
}
```

## WaitlistFilterDto

One of: `pending`, `approved`, `rejected`, `revoked`, `all`.

## WaitlistPage

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [`WaitlistEntryDto[]`](/docs/api/schemas#waitlistentrydto) | Yes |  |

```json title="Example"
{
  "items": [
    {
      "access_grant_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "company": "string",
      "created_at": "string",
      "decided_at": "string",
      "decided_by": "string",
      "decision_reason": "string",
      "email": "ada@example.com",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "name": "dev",
      "raw_answers": {},
      "status": "pending",
      "updated_at": "string",
      "use_case": "string"
    }
  ]
}
```

## WaitlistStatusDto

One of: `pending`, `approved`, `rejected`, `revoked`.

## WebhookAckDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `outcome` | `string` | Yes | `applied`, `duplicate`, `stale`, or `ignored`. |
| `received` | `boolean` | Yes |  |

```json title="Example"
{
  "outcome": "applied",
  "received": false
}
```

## WebhookDeliveryDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `attempt_count` | `integer` | Yes |  |
| `created_at` | `string (date-time)` | Yes |  |
| `event_id` | `string (uuid)` | Yes | Shared by every endpoint's delivery of the same event and sent as `X-VMYard-Event-Id`; deduplicate on it. |
| `event_type` | [`WebhookEventDto`](/docs/api/schemas#webhookeventdto) | Yes |  |
| `id` | `string (uuid)` | Yes |  |
| `machine_id` | `string (uuid)` | Yes |  |
| `operation_id` | `string (uuid)` | Yes |  |
| `status` | [`WebhookDeliveryStatusDto`](/docs/api/schemas#webhookdeliverystatusdto) | Yes |  |
| `delivered_at` | `string (date-time) \| null` | No |  |
| `last_attempt_at` | `string (date-time) \| null` | No |  |
| `last_error` | `string \| null` | No | Why the last attempt failed, when it did. |
| `last_status_code` | `integer \| null` | No | HTTP status of the last attempt; null when no response arrived. |
| `next_attempt_at` | `string (date-time) \| null` | No | When the next attempt is due; set only while pending. |

```json title="Example"
{
  "attempt_count": 0,
  "created_at": "2026-10-12T05:51:01Z",
  "delivered_at": "2026-10-12T05:51:01Z",
  "event_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "event_type": "machine.ready",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "last_attempt_at": "2026-10-12T05:51:01Z",
  "last_error": "string",
  "last_status_code": 0,
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "next_attempt_at": "2026-10-12T05:51:01Z",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "status": "pending"
}
```

## WebhookDeliveryPage

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [`WebhookDeliveryDto[]`](/docs/api/schemas#webhookdeliverydto) | Yes |  |

```json title="Example"
{
  "items": [
    {
      "attempt_count": 0,
      "created_at": "2026-10-12T05:51:01Z",
      "delivered_at": "2026-10-12T05:51:01Z",
      "event_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "event_type": "machine.ready",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "last_attempt_at": "2026-10-12T05:51:01Z",
      "last_error": "string",
      "last_status_code": 0,
      "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "next_attempt_at": "2026-10-12T05:51:01Z",
      "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "status": "pending"
    }
  ]
}
```

## WebhookDeliveryStatusDto

One of: `pending`, `delivering`, `succeeded`, `dead`.

## WebhookDto

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | `string (date-time)` | Yes |  |
| `enabled` | `boolean` | Yes |  |
| `events` | [`WebhookEventDto[]`](/docs/api/schemas#webhookeventdto) | Yes |  |
| `id` | `string (uuid)` | Yes |  |
| `name` | `string` | Yes |  |
| `organization_id` | `string (uuid)` | Yes |  |
| `secret_rotated_at` | `string (date-time)` | Yes |  |
| `updated_at` | `string (date-time)` | Yes |  |
| `url` | `string` | Yes |  |
| `created_by` | `string (uuid) \| null` | No | The member who created the endpoint; null once that user is deleted. |

```json title="Example"
{
  "created_at": "2026-10-12T05:51:01Z",
  "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "enabled": false,
  "events": [
    "machine.ready"
  ],
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "name": "ci",
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "secret_rotated_at": "2026-10-12T05:51:01Z",
  "updated_at": "2026-10-12T05:51:01Z",
  "url": "https://hooks.example.com/vmyard"
}
```

## WebhookEventDto

A lifecycle event an endpoint subscribes to.

One of: `machine.ready`, `machine.started`, `machine.stopped`, `machine.deleted`, `machine.error`, `operation.failed`, `snapshot.ready`, `template.ready`.

## WebhookPage

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [`WebhookDto[]`](/docs/api/schemas#webhookdto) | Yes |  |
| `next_cursor` | `string (uuid) \| null` | No |  |

```json title="Example"
{
  "items": [
    {
      "created_at": "2026-10-12T05:51:01Z",
      "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "enabled": false,
      "events": [
        "machine.ready"
      ],
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "name": "ci",
      "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "secret_rotated_at": "2026-10-12T05:51:01Z",
      "updated_at": "2026-10-12T05:51:01Z",
      "url": "https://hooks.example.com/vmyard"
    }
  ],
  "next_cursor": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
```

## WebhookSecretDto

Returned on creation and secret rotation; the secret is never shown again.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `secret` | `string` | Yes | `whsec_` plus 43 base64url characters. The whole string is the HMAC-SHA256 key for `X-VMYard-Signature`. |
| `webhook` | [`WebhookDto`](/docs/api/schemas#webhookdto) | Yes |  |

```json title="Example"
{
  "secret": "whsec_…",
  "webhook": {
    "created_at": "2026-10-12T05:51:01Z",
    "created_by": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "enabled": false,
    "events": [
      "machine.ready"
    ],
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "name": "ci",
    "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "secret_rotated_at": "2026-10-12T05:51:01Z",
    "updated_at": "2026-10-12T05:51:01Z",
    "url": "https://hooks.example.com/vmyard"
  }
}
```

## WriteFileRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `content` | `string` | Yes |  |
| `encoding` | [`FileEncodingDto`](/docs/api/schemas#fileencodingdto) | Yes |  |

```json title="Example"
{
  "content": "string",
  "encoding": "text"
}
```

---

<!-- Source: /docs/status.md -->

# Status page

> Where to check whether VMYard is up, what each state means, recent check history, and the machine-readable status JSON.

VMYard publishes service status in two places. Neither needs a sign-in.

| Page                    | Where                                                                                                                        | Keeps history                      | Up when the console is down |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | --------------------------- |
| Console status          | [/status](/status) on the console                                                                                            | No, current state only             | No                          |
| Independent status page | Its own address, such as `status.<your domain>`; the console footer's **Status** link opens it when your deployment runs one | Yes, the recent checks it has made | Yes                         |

If the console doesn't load, open the independent status page. Your VMYard operator gives you its address, and the console's footer and **Support** page link to it.

## States

| State       | Meaning                                                                                                                               |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Operational | The component answered normally.                                                                                                      |
| Degraded    | It answers, but isn't ready for every request; some requests may be slow or fail.                                                     |
| Outage      | It answers with server errors, or doesn't answer at all.                                                                              |
| Unknown     | It couldn't be checked: the first check hasn't finished, the check is misconfigured, or the status host itself has no network access. |

The overall state is the worst component's state. An active incident raises it: a minor-impact incident to at least Degraded, a major-impact one to Outage.

## What the independent page checks

It runs on a separate host from the console and the API, and checks each public health endpoint from outside, by default every 30 seconds. It sends no credentials and shows only component names and fixed descriptions, never addresses or error messages.

For each component it shows the result of each of the most recent checks it has made, newest on the right, with a count such as "Operational in 118 of the last 120 checks", and a **Recent changes** list of state changes with times. It keeps only the checks it has observed itself (120 by default), so history starts when the page was first deployed and has no gaps filled in later.

Current incidents, scheduled maintenance, and incidents from the last 7 days appear on both pages when your deployment publishes them.

## Status JSON

The independent page serves the same data at `status.json` next to the page, for scripts and monitors. It allows cross-origin reads.

```json
{
  "observed": true,
  "overall": "degraded",
  "checked_at": "2026-10-12T12:00:00.000Z",
  "components": [
    {
      "name": "API",
      "state": "degraded",
      "summary": "Answering, but not ready for every request"
    },
    {
      "name": "Console",
      "state": "operational",
      "summary": "Answering normally"
    }
  ],
  "incidents": { "active": [], "upcoming": [], "recent": [] },
  "history": [
    {
      "at": "2026-10-12T12:00:00.000Z",
      "overall": "degraded",
      "components": { "API": "degraded", "Console": "operational" }
    }
  ]
}
```

| Field                           | Notes                                                                                                                                              |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `observed`                      | `false` until the first check after the page starts; `checked_at` is then `null` and every component is `unknown`.                                 |
| `overall`, `components[].state` | `operational`, `degraded`, `outage`, or `unknown`.                                                                                                 |
| `incidents`                     | `null` when the deployment publishes no incidents, `"unavailable"` when they couldn't be read, otherwise `active`, `upcoming`, and `recent` lists. |
| `history`                       | The kept checks, oldest first.                                                                                                                     |

## Getting help

Open **Support** in the console sidebar, or [/support](/support), for your deployment's support contacts and copyable diagnostic info. The independent status page also lists the support contacts in its footer.

---

<!-- Source: /docs/faq.md -->

# FAQ

> Short answers to common questions about machines, billing, access, and what VMYard does not do.

## How do I sign up?

Sign in to the console with GitHub, Google, or an email code; your first sign-in creates your user. Organizations are set up by your VMYard operator, so ask them to add you if the console says you have none.

## What is the API's base URL?

It depends on your deployment. Set `VMYARD_API_URL` to the origin you were given. The CLI and SDKs have no default, so they never send a key to a guessed host.

## Am I billed while a machine is stopped?

No. Billing is per second, only while VMYard observes the machine running. See [Usage, billing, and limits](/docs/guides/billing).

## Why did my machine stop on its own?

[Auto-stop](/docs/concepts/auto-stop) reached its deadline (new machines stop after 1 hour by default), [idle sleep](/docs/concepts/idle-sleep) found it idle for its window (only when you turned it on), or the organization's balance ran out and stayed empty past the grace period. All emit `machine.stopped`, and the stop operation's `stop_reason` says which: `auto_stop`, `idle_sleep`, `billing`, or `api` for a stop someone asked for. Activity inside the machine doesn't extend auto-stop.

## Are my files kept when a machine stops?

Yes, files in `/work` are kept until the machine is deleted. Don't count on running processes or in-memory state surviving a stop.

## Can a machine sleep when idle and wake on the next request?

It can sleep when idle: turn on [idle sleep](/docs/concepts/idle-sleep) and VMYard stops the machine once it has shown no activity for the window you chose. It is off by default.

It does not wake on the next request: start a sleeping machine to wake it. See [Sleep and wake](/docs/concepts/sleep-and-wake).

## Can I snapshot, fork, or template a machine?

Yes, from the console, the CLI (`vy snapshot`, `vy templates save`, `vy fork`, `vy restore`), the SDKs, or the HTTP API. Push a stopped machine as a warm or cold [snapshot](/docs/guides/snapshots), save it as a [template](/docs/guides/templates) to create machines from, or [fork](/docs/guides/fork-and-restore) a running machine. Every copy is a new machine with its own ID and identity.

## My command exited non-zero. Why did the operation fail?

An exec operation succeeds only when the command exits with code 0. A non-zero exit ends it `failed` with `exec_nonzero`; the output is still in `exec_result`. See [Running commands](/docs/guides/commands#the-result).

## How long can a command run?

A foreground command can run up to 10 minutes (`timeout_ms` up to 600,000). Use a [background command](/docs/guides/background-commands) for anything longer.

## I retried a request. Did it run twice?

Not if you sent the same `Idempotency-Key` and body: VMYard returns the original operation. See [Operations and idempotency](/docs/concepts/operations).

## Why does my API key get `403 insufficient_scope`?

Its preset doesn't include that route. Reading files and command status counts as using a machine and needs `use_existing`; webhooks need `full_access`. See [API keys and presets](/docs/guides/api-keys#presets).

## Why can't I manage API keys with an API key?

Key management needs a signed-in browser session so a leaked key can't mint more keys. Use the console, or `vy login` to get a new key.

## Does `vy logout` revoke my key?

No. It deletes the key from your computer. Revoke it in the console under **API keys**.

## How do I share a running service?

[Expose the port](/docs/guides/ports). Keep it private and hand out short-lived tokens, or make it public.

## Can I connect over SSH?

Yes, with your own public key through VMYard's SSH gateway. See [SSH](/docs/guides/ssh); `vy ssh <machine>` installs your key if needed and connects.

## Status and support

Open [/status](/status), no sign-in needed. It shows whether the API, the dashboard, and the docs are operational, degraded, down, or unknown, and when they were last checked. It also lists current incidents and scheduled maintenance when your deployment publishes them. It shows current state only, with no uptime history.

When the console itself is down, use your deployment's independent status page: it runs on a separate host, so it stays up, and it keeps its recent check history. The console's footer links to it when your deployment runs one. See [Status page](/docs/status).

For help, open **Support** in the console sidebar, or [/support](/support). It shows your deployment's support contacts. **Copy diagnostic info** copies your user ID, organization ID, recent operation IDs, and the console version, so support can find your requests. It never includes your session, CSRF token, or API keys.

## Where are the docs as Markdown?

Add `.md` to any docs URL, or use **Copy page**. [/llms.txt](/llms.txt) lists every page and [/llms-full.txt](/llms-full.txt) has them all in one file.

---

<!-- Source: /docs/changelog.md -->

# Changelog

> Notable changes to the VMYard API, CLI, SDKs, and console.

VMYard is in private beta. Entries appear here as changes ship; the API reference always reflects the current OpenAPI document (version 1.0.0).

## October 2026

### Files

- The console's **Files** tab is now a live [file browser](/docs/guides/files#browse-files-in-the-console) for `/work`: a tree with sizes and each entry's share of the total, fuzzy search, Name / Size sorting, keyboard navigation, and actions to open, download (files, or folders as `.tar.gz`), upload into a folder, create a file, and copy a path. The latest snapshot shows above the tree with a download. Writing, reading, and uploading by path still work underneath.

### Desktop

- **Send keys** adds a [Workspaces](/docs/guides/desktop#in-the-console) group: switch to workspace 1-4, next or previous workspace, and open the launcher, for shortcuts the browser or your computer doesn't pass through.
- The [desktop](/docs/guides/desktop#full-page-in-its-own-tab) opens full page in a new browser tab, from **Open in new tab** on the Desktop tab, the machine overview, or the Machines row menu. It connects on arrival, scales to fit, and keeps its controls on a collapsible handle at the left edge.
- [Browser mode](/docs/guides/desktop#browser-mode) shows only the machine's web browser, where the host supports it.
- The Machines row menu adds **Desktop**, **Browser**, **Terminal**, **Files**, and **Copy SSH**; Desktop and Browser say "(Machine is not up)" while a machine is stopped.
- [Desktop](/docs/guides/desktop): a machine's graphical desktop over VNC in the console's new **Desktop** tab, with view-only, scale-to-fit or 1:1, resize-to-window, full screen, Send keys (Ctrl+Alt+Del and more), clipboard in both directions, and automatic reconnects. Single-use tickets authorize it; there is no VNC password, and the console records nothing. Machines whose image has no desktop yet say so.

### Documentation

- Published these docs: quickstart, concepts, guides, SDK and CLI references, a generated API reference, `/llms.txt`, `/llms-full.txt`, and a Markdown version of every page.

### Available in the beta

- Machines: create, list, rename, start, stop, restart, and delete, with auto-stop and setup scripts.
- Commands with streamed output, background commands with logs, and file transfer up to 32 MiB.
- Ports as public or token-protected HTTPS URLs, and SSH through a gateway.
- An interactive [web terminal](/docs/guides/web-terminal) in the console, also reachable over a WebSocket with an API key.
- API keys with presets, browser sign-in (GitHub, Google, email codes), and CLI device login.
- Environments: encrypted, versioned variables and secret files applied to machines, with upgrades and audited reveals.
- Signed lifecycle webhooks.
- [Command history](/docs/guides/command-history) with search and stored stdout and stderr, and [email alerts](/docs/guides/email-alerts) with per-member preferences.
- Per-second metering, prepaid trial, plans, and credits, with spend caps and limits.
- The `vy` CLI and the TypeScript and Python SDKs (not yet published to npm or PyPI).

### Machine metrics

- [Machine metrics](/docs/guides/machine-metrics): CPU, memory, disk, disk I/O, and network for every machine, in the machine list and as one-minute or live charts on its overview.
- The `disk_almost_full` and `disk_full` [email alerts](/docs/guides/email-alerts) are now sent.

### Snapshots, templates, fork, and organizations

- [Snapshots](/docs/guides/snapshots): push a stopped machine as a warm or cold snapshot; long stops move down the tiers on their own.
- [Templates](/docs/guides/templates): save a stopped machine by name and create machines from it.
- [Fork and restore](/docs/guides/fork-and-restore): copy a running machine at one instant, or restore a snapshot, as a new machine.
- `snapshot.ready` and `template.ready` webhooks.
- Organizations by name: every account gets a personal organization, and signed-in users create and rename their own.
- Machine search, state filter, sort, and order run on the server across the whole organization.

### Billing: sizes, plans, trial, and automatic refill

- [Sizes and prices](/docs/guides/sizes-and-prices): `GET /v1/plans` reports each plan's `size` (`small`, `default`, `large`, `xlarge`). The console's create page picks a size for the chosen region with its resources and hourly price, and shows which sizes a trial can't use.
- [Cancel a plan or end the trial](/docs/guides/plans-and-trial): cancel a plan at the end of its period and keep it again before then (`plan.cancel_at_period_end`), end the trial early (`trial.ended_at`), or end it with a plan checkout (`end_trial`).
- [Automatic refill](/docs/guides/automatic-refill): buy credit packs when the balance drops below a threshold, up to a monthly cap, with the new `auto_refill_failed` [email alert](/docs/guides/email-alerts).

### Automatic snapshots and bulk deletes

- [Automatic snapshots](/docs/guides/automatic-snapshots): running KVM machines are captured every 5 minutes by default, keeping the newest 10; manual snapshots, tier-policy snapshots, and templates are never pruned.
- Machines report `latest_snapshot`, so the machine list and overview show how fresh each machine's copy is.
- [Delete several snapshots](/docs/guides/snapshots#delete-several-snapshots) by ID, or all of a machine's (optionally one source's), with a result for each. The console's Snapshots tab filters by source and selects snapshots to delete.

### Independent status page

- An [independent status page](/docs/status) that runs on its own host, separate from the console and the API, so it stays up when they are down. It checks each component from outside, shows its recent check history and state changes, lists incidents and maintenance, and serves the same data as `status.json`.
- The console's footer and Support page link to it when your deployment runs one.

### Idle sleep

- [Idle sleep](/docs/concepts/idle-sleep): turn it on per machine (`idle_sleep_after_seconds`, 5 minutes to 24 hours; off by default) and VMYard stops a running machine once it has shown no activity for that long. Missing or stale metrics never count as idle.
- Machines report `idle_sleep_after_seconds`, `idle_since`, `idle_sleep_at`, and `last_active_at`. The console counts down to sleep in the machine list and on the overview, and shows when the machine was last active.
- Stop operations and `machine.stopped` webhooks carry `stop_reason` (`api`, `auto_stop`, `billing`, or `idle_sleep`); the console labels it, for example "Stopped: idle".
- The opt-in `idle_sleep` [email alert](/docs/guides/email-alerts).

### Internet access, IPv6, and restarts

- [Internet access and IPv6](/docs/guides/networking): choose a machine's egress policy, `internet` or `none`, when you create it (`network: {egress}`; leave it out for the host's default) and change it later with `PUT /v1/machines/{id}/network`, a `network_set` operation. Machines report `network`, with a public `ipv6_address` on hosts that route IPv6 to their machines. Choosing needs the permission to create machines.
- Internet access is the public internet only: private and metadata ranges, the host, and other machines stay blocked, port 25 is blocked, and each machine has its own rate and bandwidth limits. A host's operator can turn internet access off.
- **Breaking:** the plan catalog's `network_access.network_mode` (`private_only`) is gone; `network_access.egress_options` lists the policies a plan offers.
- [Restart](/docs/concepts/lifecycle#restart) is one operation that reboots the machine in place without stopping it, on Docker hosts too. A host that can't restart machines yet ends it `failed` with `restart_unsupported`, and the machine keeps running.
- The console's create page offers Internet access, the Network tab shows and changes it with the IPv6 address, and Restart is available for Docker machines.