# 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"
}
```