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 actionstringYes stopped (a trial machine) or flagged (a paid machine, still running).created_atstringYes idstring (uuid)Yes kindstringYes sustained_cpu: every vCPU at full load for the whole window.machine_idstring (uuid)Yes min_cpu_permilleintegerYes Lowest per-minute CPU use in the window, in thousandths of the machine's vCPU limit (1000 = every vCPU fully used). organization_idstring (uuid)Yes window_secondsintegerYes window_startstringYes resolutionstring | nullNo resolution_notestring | nullNo resolved_atstring | nullNo stop_operation_idstring (uuid) | nullNo
{
"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 {
"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 tokenstringYes
{
"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 createdbooleanYes False when an active grant already named this person (returned as it is). grantAccessGrantDtoYes
{
"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_atstringYes granted_bystringYes idstring (uuid)Yes credited_atstring | nullNo credited_organization_idstring (uuid) | nullNo Where the initial credit went, once credited. emailstring | nullNo Set for a grant by verified email. initial_credit_microsinteger | nullNo providerstring | nullNo Set (with subject) for a grant of one sign-in identity. reasonstring | nullNo revoke_reasonstring | nullNo revoked_atstring | nullNo revoked_bystring | nullNo subjectstring | nullNo
{
"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 {
"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_idstring (uuid) | nullNo
{
"active_organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}ActiveOrganizationRequest Field Type Required Description organization_idstring (uuid) | nullNo An organization the caller belongs to, or null to clear it.
{
"organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}AgentAttachmentRequest Field Type Required Description content_base64stringYes The file's bytes (standard base64), at most 8 MiB decoded. namestringYes The file name the agent sees: 1-128 bytes, one path component. media_typestring | nullNo type/subtype; image/* attachments are also passed to the agent as images where it accepts them.
{
"content_base64": "string",
"media_type": "string",
"name": "dev"
}AgentConversationDto {
"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 conversationsAgentConversationDto[]Yes Newest first. next_cursorstring (uuid) | nullNo Pass as cursor for the next page; absent on the last page.
{
"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.
{
"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 activebooleanYes A turn is starting or running: more events are coming. conversation_idstring (uuid)Yes cursorintegerYes Pass back as cursor to continue after these events. eventsAgentEventDto[]Yes latest_turnnull | AgentTurnDtoNo The conversation's latest turn, as last observed.
{
"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.
Field Type Required Description conversation_idstring (uuid)Yes input_idstring (uuid)Yes The input's ID; the agent confirms it with an input_accepted event carrying this input_id. kindAgentInputKindDtoYes turn_idstring (uuid)Yes stoppedboolean | nullNo A forced interrupt killed the runner (false when it had already ended); absent otherwise.
{
"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"
}One of: prompt, steer, interrupt.
One of: steer, interrupt.
AgentInterruptRequest Field Type Required Description conversation_idstring (uuid)Yes forcebooleanNo 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).
{
"conversation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
"force": false
}AgentModelsDto {
"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 attachmentsAgentAttachmentRequest[]No At most 16 files, 16 MiB together, written to the machine for the agent to read. conversation_idstring (uuid) | nullNo Continue this conversation; omit to start a new one. modelstring | nullNo A model the agent accepts (see GET /v1/provider-models); the agent's default when omitted. Pi takes provider/model. providernull | AgentProviderDtoNo Required for a new conversation; a conversation keeps its provider. reasoning_effortnull | ReasoningEffortDtoNo textstringNo The prompt, at most 256 KiB. A prompt needs text or an attachment.
{
"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_idstring (uuid)Yes textstringYes More instructions for the running turn, at most 256 KiB.
{
"conversation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
"text": "string"
}AgentTurnDto Field Type Required Description conversation_idstring (uuid)Yes created_atstring (date-time)Yes events_urlstringYes Follow the conversation's events. interrupt_requestedbooleanYes machine_idstring (uuid)Yes providerAgentProviderDtoYes resumebooleanYes The turn continues the conversation's earlier turns. statusAgentTurnStatusDtoYes turn_idstring (uuid)Yes error_codestring | nullNo Why a failed turn failed: agent_failed, invalid_turn, runner_failed, runner_killed, turn_lost, machine_stopped, or agents_unavailable. exit_codeinteger | nullNo The runner's exit status, once it exited. finished_atstring (date-time) | nullNo modelstring | nullNo reasoning_effortnull | ReasoningEffortDtoNo started_atstring (date-time) | nullNo
{
"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_tokensinteger | nullNo cost_micro_usdinteger | nullNo The agent's own cost estimate, in millionths of a US dollar. input_tokensinteger | nullNo output_tokensinteger | nullNo
{
"cached_input_tokens": 0,
"cost_micro_usd": 0,
"input_tokens": 0,
"output_tokens": 0
}AlertPreferenceDto Field Type Required Description availablebooleanYes Whether the control plane raises this alert today (every type but product_announcements, which people send). customizedbooleanYes The member chose enabled instead of the role default. default_enabledbooleanYes What the member's role receives without a choice. descriptionstringYes enabledbooleanYes Whether this member receives the alert. typestringYes 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.
{
"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_atstring (date-time)Yes created_bystring (uuid)Yes expires_atstring (date-time)Yes idstring (uuid)Yes last_fourstringYes namestringYes organization_idstring (uuid)Yes prefixstringYes The first 12 characters of the secret, for identification only. presetApiKeyPresetDtoYes last_used_atstring (date-time) | nullNo revoked_atstring (date-time) | nullNo
{
"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 itemsApiKeyDto[]Yes next_cursorstring (uuid) | nullNo
{
"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_keyApiKeyDtoYes secretstringYes
{
"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_microsintegerYes plan_microsintegerYes trial_microsintegerYes
{
"credit_micros": 0,
"plan_micros": 0,
"trial_micros": 0
}ApproveWaitlistRequest Field Type Required Description operatorstringYes The individual operator acting, 1-200 characters. initial_credit_microsinteger | nullNo 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. notifyboolean | nullNo Send the "you're in" email (default true). reasonstring | nullNo Why, 1-500 characters; optional.
{
"initial_credit_micros": 0,
"notify": false,
"operator": "string",
"reason": "string"
}AutoRefillChargeDto Field Type Required Description amount_microsintegerYes created_atstringYes credit_packsintegerYes idstring (uuid)Yes statusstringYes pending, submitted (waiting for the provider's confirmation), succeeded, or failed.failure_codestring | nullNo Provider decline code such as insufficient_funds, authentication_required, or no_payment_method.
{
"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_microsintegerYes charged_this_month_microsintegerYes consecutive_failuresintegerYes Failed charges since the last success; refill turns off at 3. credit_packsintegerYes $20 packs bought per refill. enabledbooleanYes monthly_cap_microsintegerYes Most refill charges per UTC calendar month. threshold_microsintegerYes Refill when the balance (trial + plan + credits) drops below this. disabled_reasonstring | nullNo payment_failures when refill turned itself off.last_chargenull | AutoRefillChargeDtoNo
{
"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_microsintegerYes Non-expiring credits; negative only by usage metered after exhaustion. plan_microsintegerYes Unused allowance of the current plan period. spendable_microsintegerYes What can still be spent, with credits bounded by the spend cap. trial_microsintegerYes
{
"credit_micros": 0,
"plan_micros": 0,
"spendable_micros": 0,
"trial_micros": 0
}BillingDto Field Type Required Description balancesBalancesDtoYes card_checkCardCheckDtoYes credit_spent_this_month_microsintegerYes currencystringYes limitsLimitsDtoYes minimum_balance_microsintegerYes Creates and starts need more than this spendable balance. organization_idstring (uuid)Yes payment_customer_linkedbooleanYes payments_availablebooleanYes Whether checkout and the payment portal are configured. statusstringYes trial, pay_as_you_go, or subscribed.trialTrialDtoYes exhausted_sincestring | nullNo When the spendable balance reached zero; running machines are stopped after the grace period. plannull | PlanSubscriptionDtoNo spend_cap_microsinteger | nullNo Most credit spend allowed per UTC calendar month; null is no cap.
{
"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_idsstring (uuid)[]Yes 1-100 snapshot IDs; duplicates are reported once.
{
"snapshot_ids": [
"6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
]
}CapacityApprovalList {
"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 operatorstringYes The operator deciding, recorded with the decision (1-100 characters). notestring | nullNo Optional note recorded with the decision (at most 500 characters).
{
"note": "string",
"operator": "string"
}CapacityBudgetDto Field Type Required Description allowance_microsintegerYes What the revenue allows: the revenue share, at least the launch floor. approval_threshold_microsintegerYes Purchases whose first month costs more wait for an approval. ceiling_microsintegerYes committed_monthly_microsintegerYes Monthly spend of every server bought or kept now. launch_floor_microsintegerYes revenue_30d_microsintegerYes Stripe revenue of the last 30 days, USD micros. revenue_share_bpsintegerYes Share of revenue servers may cost, basis points. spend_30d_microsintegerYes Provider charges recorded in the last 30 days.
{
"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 actionstringYes start_overflow, order_monthly, order, deliver, join, drain, release, cancel_at_term_end, retire, or approval.atstringYes When it was decided (UTC RFC 3339). dry_runbooleanYes Recorded in dry run: nothing was bought or changed. factsobjectYes The numbers behind the decision. idintegerYes outcomestringYes What happened, such as ordering, placed, refused, awaiting_approval, approved, dry_run, or failed. reasonstringYes Why, in plain words. regionstringYes server_idstring (uuid) | nullNo
{
"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 decisionsCapacityDecisionDto[]Yes next_beforeinteger | nullNo Pass as before for older decisions; absent on the last page.
{
"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 billingstringYes monthly or hourly.host_idstringYes The fleet host ID it will enroll as. idstring (uuid)Yes monthly_cost_microsintegerYes What it adds to the monthly server spend, USD micros (an hourly server counts at its full-month price). providerstringYes ovh or scaleway.reasonstringYes Why the capacity loop wants it. regionstringYes requested_atstringYes setup_cost_microsintegerYes slotsintegerYes statestringYes awaiting_approval, ordering, rejected, expired, ...decided_bystring | nullNo notestring | nullNo
{
"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 requiredbooleanYes Whether this service requires a verified card before a trial starts machines (paid organizations never need one). verified_atstring | nullNo When a card was verified with the payment provider, if ever.
{
"required": false,
"verified_at": "string"
}CardCheckSessionDto Field Type Required Description checkout_urlstringYes The provider's hosted page; the card is verified, not charged. session_idstringYes
{
"checkout_url": "string",
"session_id": "string"
}CheckoutDto Field Type Required Description checkout_urlstringYes Hosted checkout page; card details stay with the payment provider. session_idstringYes
{
"checkout_url": "string",
"session_id": "string"
}CheckoutRequestDto Field Type Required Description credit_packsinteger | nullNo Buy this many $20 credit packs (1-50). end_trialbooleanNo With plan: forfeit the remaining trial once the plan's first payment is confirmed, so the plan's allowance is used right away. planstring | nullNo Subscribe to starter, pro, team, or scale.
{
"credit_packs": 0,
"end_trial": false,
"plan": "string"
}CommandAccepted Field Type Required Description command_idstring (uuid)Yes The command ID; it equals the ID of the operation that starts it. command_urlstringYes machine_idstring (uuid)Yes operation_idstring (uuid)Yes operation_urlstringYes statusstringYes
{
"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_idstring (uuid)Yes machine_idstring (uuid)Yes statusCommandStatusDtoYes error_codestring | nullNo exit_codeinteger | nullNo Exit status recorded by the guest agent when status is exited. lognull | CommandLogDtoNo Combined stdout and stderr, from log_offset. signalinteger | nullNo Signal that ended the command when status is killed and known.
{
"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 argvstring[]Yes cancelledbooleanYes commandstringYes The shell command of /bin/sh -c <command>, otherwise the arguments joined by spaces. Search matches this text. created_atstringYes When the command was requested (UTC RFC 3339). logs_urlstringYes machine_idstring (uuid)Yes modeCommandModeDtoYes operation_idstring (uuid)Yes The exec operation; for a detached command it is also the command_id. output_purgedbooleanYes Retention removed the stored output; the sizes stay. statusOperationStatusDtoYes timed_outbooleanYes truncatedbooleanYes The runtime capped the captured output. duration_msinteger | nullNo finished_at - started_at, across retries.error_codestring | nullNo exit_codeinteger | nullNo Exit status of a finished foreground command. finished_atstring | nullNo started_atstring | nullNo The first time a worker claimed it; absent for history recorded before migration 0023. stderr_bytesinteger | nullNo stdout_bytesinteger | nullNo
{
"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 itemsCommandHistoryEntryDto[]Yes next_cursorstring | nullNo Pass as cursor for the next (older) page; absent on the last page.
{
"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 completebooleanYes The command finished and its output is final. While a streamed command runs, output arrives as it is relayed and size grows. data_base64stringYes next_offsetintegerYes offsetintegerYes operation_idstring (uuid)Yes sizeintegerYes Bytes of this stream stored so far. streamOutputStreamDtoYes truncatedbooleanYes
{
"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_base64stringYes next_offsetintegerYes offsetintegerYes sizeintegerYes Current log size reported by the guest.
{
"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 operatorstringYes The individual operator acting, 1-200 characters. emailstring | nullNo Grant a verified login email; or name provider and subject. initial_credit_microsinteger | nullNo As on approval; defaults to the service's initial credit, 0 for none. providerstring | nullNo A configured sign-in provider such as erpai. reasonstring | nullNo subjectstring | nullNo The provider's subject (sub) for the account, 1-255 characters.
{
"email": "ada@example.com",
"initial_credit_micros": 0,
"operator": "string",
"provider": "github",
"reason": "string",
"subject": "string"
}CreateApiKeyRequest Field Type Required Description namestringYes 1–64 characters. presetApiKeyPresetDtoYes expires_in_daysintegerNo 1–365. default 90.
{
"expires_in_days": 90,
"name": "dev",
"preset": "read_only"
}CreateEnvironmentRequest Field Type Required Description filesSecretFileInput[]No is_defaultboolean | nullNo Defaults to true when the organization has no default environment. namestring | nullNo Lowercase DNS label, unique in the organization. Defaults to base. safe_for_third_partiesbooleanNo varsmap of stringNo Variable names (^[A-Za-z_][A-Za-z0-9_]{0,127}$) to values.
{
"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 emailstringYes roleRoleDtoYes
{
"email": "ada@example.com",
"role": "owner"
}CreateMachineRequest Field Type Required Description auto_stop_after_secondsinteger | nullNo 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. backendnull | BackendDtoNo environmentstring | nullNo Environment to apply, by name (alternative to environment_id). environment_idstring (uuid) | nullNo 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_secondsinteger | nullNo 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. imagenull | VersionedSelectionDtoNo namestring | nullNo Display name, following the tenant_alias rules. Defaults to the tenant alias. Unlike the alias it can be changed later. networknull | NetworkRequestNo 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_stopbooleanNo true disables auto-stop. It cannot be combined with auto_stop_after_seconds.no_envbooleanNo true creates the machine without any environment, not even the default (for example, for a machine shared with third parties).plannull | VersionedSelectionDtoNo 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). regionnull | VersionedSelectionDtoNo resourcesnull | ResourcesDtoNo setup_scriptstring | nullNo 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. templatestring | nullNo 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_aliasstring | nullNo Required without template. With one, it is the template's (the runtime scopes stored snapshots to their tenant) and may be omitted.
{
"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 namestringYes 1-64 characters without control characters or surrounding whitespace; unique (case-insensitively) among the caller's own organizations. 1–64 characters.
{
"name": "dev"
}CreateSnapshotRequest {
"tier": "warm"
}CreateTemplateRequest Field Type Required Description machine_idstring (uuid)Yes A stopped machine to save as the template. namestringYes [a-z0-9] then up to 63 of [a-z0-9._-]; unique among the organization's templates.
{
"machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
"name": "dev"
}CreateWebhookRequest Field Type Required Description eventsWebhookEventDto[]Yes at least 1 items. namestringYes 1–64 characters. urlstringYes https on port 443, without credentials or a fragment, naming a public host. Redirects are never followed. at most 2048 characters.enabledbooleanNo default true.
{
"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"
}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, widthtype: "error" with codetype: "closed" with reason{
"height": 0,
"mode": "desktop",
"type": "opened",
"width": 0
}DesktopTicketDto Field Type Required Description expires_atstringYes ticketstringYes Single-use credential for one desktop WebSocket of this machine, valid for 30 seconds, only with the session that minted it.
{
"expires_at": "string",
"ticket": "string"
}DeviceApproved Field Type Required Description expires_in_daysintegerYes organization_idstring (uuid)Yes presetApiKeyPresetDtoYes user_codestringYes
{
"expires_in_days": 0,
"organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
"preset": "read_only",
"user_code": "BCDF-GHJK"
}DeviceApproveRequest Field Type Required Description user_codestringYes expires_in_daysinteger | nullNo Key lifetime, 1–90 days; defaults to 90. 1–90. default 90. namestring | nullNo Key name, 1–64 characters; defaults to vy: <client_name>. presetnull | ApiKeyPresetDtoNo The key's preset; defaults to the requested scope.
{
"expires_in_days": 90,
"name": "dev",
"preset": "read_only",
"user_code": "BCDF-GHJK"
}DeviceAuthorizationDto Field Type Required Description client_namestringYes Untrusted text supplied by the device; display it as plain text. expires_atstring (date-time)Yes requested_scopeApiKeyPresetDtoYes user_codestringYes
{
"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_namestring | nullNo Shown to the approving user, such as vy on build-host; 1–64 characters. Defaults to vy CLI. scopenull | ApiKeyPresetDtoNo The preset the CLI asks for; the approving user may choose another. Defaults to create_and_use.
{
"client_name": "vy on build-host",
"scope": "read_only"
}DeviceCodeResponse Field Type Required Description device_codestringYes Secret polling credential; keep it on the device. expires_inintegerYes intervalintegerYes Minimum seconds between polls. user_codestringYes Short code the user confirms in the browser, XXXX-XXXX. verification_uristringYes verification_uri_completestringYes
{
"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_codestringYes
{
"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 errorstringYes error_descriptionstringYes
{
"error": "string",
"error_description": "string"
}DeviceTokenRequest Field Type Required Description device_codestringYes grant_typestringYes urn:ietf:params:oauth:grant-type:device_code
{
"device_code": "string",
"grant_type": "string"
}DeviceTokenResponse Field Type Required Description access_tokenstringYes The new API key secret (vmy_…), returned only once. api_keyApiKeyDtoYes expires_inintegerYes Seconds until the API key expires. scopeApiKeyPresetDtoYes The key's preset. token_typestringYes Always Bearer.
{
"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 messagestringYes
{
"message": "If the address can receive email, a code is on its way."
}EmailStartRequest Field Type Required Description emailstringYes return_tostring | nullNo Same-origin UI path to open after sign-in; invalid values become /.
{
"email": "ada@example.com",
"return_to": "string"
}EmailVerified Field Type Required Description return_tostringYes The UI path stored when the code was requested.
{
"return_to": "string"
}EmailVerifyRequest Field Type Required Description codestringYes The 6-digit code from the email. emailstringYes
{
"code": "string",
"email": "ada@example.com"
}EmptyAction No fields.
{}EnvironmentApplyStatusDto One of: pending, applied, failed.
EnvironmentDto Field Type Required Description created_atstringYes current_versionEnvironmentVersionDtoYes idstring (uuid)Yes is_defaultbooleanYes Machines created without environment_id, environment, or no_env get the default environment. namestringYes safe_for_third_partiesbooleanYes Marks an environment whose contents may be exposed to third parties. updated_atstringYes created_bystring (uuid) | nullNo
{
"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 pathstringYes Path relative to /work. sizeintegerYes
{
"path": "notes/todo.txt",
"size": 0
}EnvironmentList {
"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 changeobjectYes What this version changed, without values, for example {"action": "set_variable", "name": "API_TOKEN", "size": 40}. created_atstringYes environment_idstring (uuid)Yes filesEnvironmentFileDto[]Yes idstring (uuid)Yes varsstring[]Yes Variable names, sorted. versionintegerYes 1 for the first version, then one more per change. created_bystring (uuid) | nullNo
{
"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 {
"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 argvstring[] | nullNo Program and arguments, executed directly. Exactly one of argv or command. commandstring | nullNo Shell command run as /bin/sh -c <command>, at most 8192 bytes. streambooleanNo Respond with application/x-ndjson frames as output arrives instead of 202 Accepted. timeout_msinteger | nullNo Foreground limit in milliseconds, 1 to the runtime maximum (600000). Defaults to the maximum; the effective value is persisted with the operation.
{
"argv": [
"string"
],
"command": "string",
"stream": false,
"timeout_ms": 0
}ExecResultDto Field Type Required Description cancelledbooleanYes stderr_base64stringYes stdout_base64stringYes timed_outbooleanYes truncatedbooleanYes exit_codeinteger | nullNo
{
"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_urltype: "stdout" with data_base64type: "stderr" with data_base64type: "exit" with cancelled, error_code, exit_code, operation_id, status, timed_out, truncatedtype: "error" with code, message, operation_id, status{
"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 portintegerYes Guest TCP port, 1-65535 except 22 (use the SSH key for SSH) and the desktop's 5907 and 5908 (open the desktop instead). localhostbooleanNo Relay the guest's addresses to a service bound to 127.0.0.1/[::1]. publicbooleanNo Reachable without a token. Private ports (the default) need a token from POST /v1/machines/{machine_id}/ports/{port}/token.
{
"localhost": false,
"port": 0,
"public": false
}FileContentDto Field Type Required Description contentstringYes encodingFileEncodingDtoYes pathstringYes Path relative to /work. sizeintegerYes
{
"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_base64stringYes missingbooleanYes offsetintegerYes pathstringYes sizeintegerYes
{
"data_base64": "string",
"missing": false,
"offset": 0,
"path": "notes/todo.txt",
"size": 0
}FileTreeDto Field Type Required Description entriesFileTreeEntryDto[]Yes file_countintegerYes Non-directory entries under it at any depth. pathstringYes The listed directory, normalized. total_bytesintegerYes The directory's recursive apparent size (du -sb). truncatedbooleanYes The listing stopped at 5,000 entries (deeper levels go first).
{
"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 namestringYes The last path component. Guest data: bytes that are not UTF-8 are replaced by U+FFFD. pathstringYes The absolute guest path. size_bytesintegerYes A file's size; a symlink's target length; a directory's recursive apparent size, its own entries included (du -b). typeFileEntryTypeDtoYes childrenFileTreeEntryDto[] | nullNo A directory's entries, sorted by name, only within the requested depth; absent for files, symlinks, and directories at the depth. modified_atstring (date-time) | nullNo Last modification (UTC RFC 3339), when the guest reported one.
{
"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_keysbooleanNo Keep the login user's SSH authorized_keys in the copy (default false). The SSH gateway port is never inherited. liveboolean | nullNo Run the copy at once with the source's processes (default true); false creates it stopped. namestring | nullNo The copy's display name (default: the tenant alias it shares with the source).
{
"keep_ssh_keys": false,
"live": false,
"name": "dev"
}GrantKindDto One of: credits, trial, plan_period.
GrantResultDto Field Type Required Description outcomestringYes applied, duplicate, or stale.
{
"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_bytesintegerYes filesystem_total_bytesintegerYes memory_available_bytesintegerYes memory_total_bytesintegerYes reported_atstring (date-time) | nullNo When the guest reported them (UTC RFC 3339).
{
"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 digeststringYes idstring (uuid)Yes namestringYes versionintegerYes
{
"digest": "sha256:3f5a…",
"id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
"name": "ubuntu-24.04",
"version": 0
}ImagePage Field Type Required Description itemsImageDto[]Yes next_cursorstring | nullNo
{
"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_idstring (uuid)Yes roleRoleDtoYes
{
"organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
"role": "owner"
}InvitationDto Field Type Required Description created_atstring (date-time)Yes emailstringYes expires_atstring (date-time)Yes idstring (uuid)Yes organization_idstring (uuid)Yes roleRoleDtoYes invited_bystring (uuid) | nullNo
{
"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 itemsInvitationDto[]Yes Open invitations, newest first.
{
"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 emailstringYes expires_atstring (date-time)Yes organization_idstring (uuid)Yes organization_namestringYes roleRoleDtoYes stateInvitationStateDtoYes
{
"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_microsintegerYes descriptionstringYes hourly_microsintegerYes multipliernumberYes plan_idstring (uuid)Yes plan_versionintegerYes secondsintegerYes
{
"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 appliedAppliedDtoYes How the charged part was paid. credit_balance_microsintegerYes currencystringYes linesInvoiceLineDto[]Yes Machine time in the period so far, by size. next_charge_microsintegerYes What renews at period_end (the plan price), or 0. Usage is prepaid, so nothing else is charged automatically. period_endstringYes period_startstringYes unbilled_microsintegerYes Accrued by running machines but not yet charged by the meter. usage_microsintegerYes plannull | PlanSubscriptionDtoNo
{
"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_atstring (date-time)Yes When the snapshot was requested (UTC RFC 3339): the instant a capture or push copies. idstring (uuid)Yes sourceSnapshotSourceDtoYes statusSnapshotStatusDtoYes pending or ready.tierSnapshotTierDtoYes completed_atstring (date-time) | nullNo When it became ready; null while pending.
{
"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_microsintegerYes Positive adds to the balance, negative takes from it. atstringYes bucketstringYes trial, plan, or credit.idintegerYes kindLedgerKindDtoYes labelstringYes What to show, such as "Credit from VMYard". plan_tierstring | nullNo
{
"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 itemsLedgerEntryDto[]Yes next_beforeinteger | nullNo Pass as before for the next page; absent on the last page.
{
"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 limitintegerYes usedintegerYes
{
"limit": 0,
"used": 0
}LimitsDto Field Type Required Description concurrent_machinesLimitDtoYes Machines that want to run, pending creates included. startsStartLimitDto[]Yes Creates, starts, and restarts in each rolling window. statusstringYes trial, pay_as_you_go, or subscribed.tierstring | nullNo
{
"concurrent_machines": {
"limit": 0,
"used": 0
},
"starts": [
{
"limit": 0,
"used": 0,
"window": "hour"
}
],
"status": "trial",
"tier": "pro"
}LinkRequest Field Type Required Description emailstring | nullNo Required for email, refused for other providers. return_tostring | nullNo Same-origin UI path to open when the provider flow completes; invalid values become /.
{
"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_urlstringYes
{
"authorization_url": "string"
}LoginMethodDto Field Type Required Description created_atstring (date-time)Yes idstring (uuid)Yes last_used_atstring (date-time)Yes providerstringYes Provider name such as github, google, or email. emailstring | nullNo The address the provider vouched for at the last sign-in, when known.
{
"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 backendBackendDtoYes created_atstring (date-time)Yes When the machine was requested (UTC RFC 3339). desired_stateDesiredStateDtoYes idstring (uuid)Yes imageVersionedSelectionDtoYes namestringYes Display name; the tenant alias unless renamed. observed_stateObservedStateDtoYes organization_idstring (uuid)Yes planVersionedSelectionDtoYes regionVersionedSelectionDtoYes resourcesResourcesDtoYes tenant_aliasstringYes auto_stop_after_secondsinteger | nullNo Configured auto-stop duration in seconds; null means never. auto_stop_atstring | nullNo When the control plane will stop the running machine (UTC RFC 3339); null when it is not running toward a deadline. environmentnull | MachineEnvironmentDtoNo The machine's environment; null when it was created without one. forked_from_machine_idstring (uuid) | nullNo The machine this one was forked from (POST .../fork). idle_sincestring | nullNo 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_secondsinteger | nullNo Configured idle-sleep window in seconds; null means idle sleep is off (the default). idle_sleep_atstring | nullNo When the machine will be put to sleep if it stays idle: idle_since plus the window (UTC RFC 3339). last_active_atstring | nullNo The last activity the idle-sleep scan observed (UTC RFC 3339); null until a scan saw any. latest_snapshotnull | LatestSnapshotDtoNo The machine's newest live snapshot (pending or ready; templates and failed pushes excluded), for freshness; null when it has none. metricsnull | MachineMetricsSummaryDtoNo The latest metrics the poller recorded; null until the machine has been sampled. Values stay after the machine stops being reported, with stale set. networknull | MachineNetworkDtoNo 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_idstring (uuid) | nullNo The snapshot or template this machine was restored from. setup_operation_idstring (uuid) | nullNo The setup script's exec operation, when one was requested. sshnull | SshAccessDtoNo How to reach the machine over SSH, present while it has an SSH key (PUT /v1/machines/{machine_id}/ssh-key). starting_soonnull | StartingSoonDtoNo Set while the machine's create or start waits for a server to have room ("starting soon"); null otherwise.
{
"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_idstring (uuid)Yes operation_idstring (uuid)Yes The apply operation for version_id. statusEnvironmentApplyStatusDtoYes versionintegerYes version_idstring (uuid)Yes The version the machine should have: the one it was created with, until an upgrade. applied_version_idstring (uuid) | nullNo The version last installed in the guest, if any. error_codestring | nullNo
{
"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_millisintegerYes interval_msintegerYes Time between points: the host's sampling interval for live, 60000 for 1m. machine_idstring (uuid)Yes memory_limit_bytesintegerYes pointsMetricsPointDto[]Yes Oldest first. resolutionMetricsResolutionDtoYes guest_reportednull | GuestReportedDtoNo The guest's own report, when there is one. next_sincestring | nullNo More 1m points follow: ask again with this as since.
{
"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_millisintegerYes flagsMetricFlagDto[]Yes memory_limit_bytesintegerYes stalebooleanYes The values are from an earlier poll and may no longer be current; they are the last known values, not zero. statestringYes The runtime state when sampled: running or sleeping. cpu_millisinteger | nullNo Millicores used over the last sampling interval (1000 = one core). cpu_percentnumber | nullNo CPU used over the host's last sampling interval, as a share of the machine's CPU limit. disk_percentnumber | nullNo Disk blocks the machine's image holds, as a share of its size. An upper bound: blocks the guest freed stay allocated. disk_size_bytesinteger | nullNo disk_used_bytesinteger | nullNo io_read_bpsinteger | nullNo Bytes per second over the host's last sampling interval. io_write_bpsinteger | nullNo memory_bytesinteger | nullNo memory_percentnumber | nullNo Memory charged to the machine (guest RAM in use, page cache, and the VMM), as a share of its limit. net_rx_bpsinteger | nullNo Bytes per second seen from the guest (rx = received by it). net_tx_bpsinteger | nullNo sampled_atstring (date-time) | nullNo When the host sampled these values (UTC RFC 3339). stale_reasonnull | StaleReasonDtoNo
{
"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 egressEgressDtoYes ipv6_addressstring | nullNo 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.
{
"egress": "none",
"ipv6_address": "string"
}MachinePage Field Type Required Description itemsMachineDto[]Yes next_cursorstring | nullNo Opaque; pass it as cursor with the same sort and order.
{
"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_microsintegerYes hourly_microsintegerYes machine_idstring (uuid)Yes multipliernumberYes Size multiplier relative to default (small 0.5, large 2). runningbooleanYes Whether a metered run is open now. secondsintegerYes Whole seconds observed running inside the window.
{
"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 accessAccessDtoYes 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.emailstringYes login_method_detailsLoginMethodDto[]Yes Each linked sign-in identity, oldest first; id is what DELETE /v1/auth/login-methods/{id} takes. login_methodsstring[]Yes Sign-in provider names linked to this user, sorted. membershipsMembershipDto[]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_authbooleanYes user_idstring (uuid)Yes active_organization_idstring (uuid) | nullNo 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. namestring | nullNo Display name from the identity provider's name claim, when it supplied one. waitlist_urlstring | nullNo Where to join the waitlist, while the service is invite-only.
{
"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 emailstringYes joined_atstring (date-time)Yes roleRoleDtoYes running_machinesintegerYes Machines the member last asked to run that still want to run; the cap counts these. usage_this_monthMemberUsageDtoYes user_idstring (uuid)Yes max_running_machinesinteger | nullNo The member's own running-at-once cap; null is no cap beyond the organization's plan limits.
{
"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 itemsMemberDto[]Yes Owners first, then by email.
{
"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_revokedintegerYes The member's API keys of this organization, now revoked. channels_revokedintegerYes Open terminals and desktops revoked; each ends at its relay's next heartbeat (at most 15 s) with reason revoked. tickets_revokedintegerYes Unredeemed terminal and desktop tickets deleted. user_idstring (uuid)Yes
{
"api_keys_revoked": 0,
"channels_revoked": 0,
"tickets_revoked": 0,
"user_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}MembershipDto Field Type Required Description accessAccessDtoYes approved while one of the organization's owners is approved: its members may then create and start machines and create API keys.organization_idstring (uuid)Yes organization_namestringYes rolestringYes
{
"access": "approved",
"organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
"organization_name": "string",
"role": "owner"
}MemberUsageDto Field Type Required Description cost_microsintegerYes secondsintegerYes Machine seconds of the runs the member started this UTC month.
{
"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 tstring (date-time)Yes The sample time, or the minute's start (UTC RFC 3339). cpu_millisinteger | nullNo cpu_millis_maxinteger | nullNo The minute's highest sample (1m only). cpu_percentnumber | nullNo disk_percentnumber | nullNo disk_used_bytesinteger | nullNo io_read_bpsinteger | nullNo io_write_bpsinteger | nullNo memory_bytesinteger | nullNo memory_bytes_maxinteger | nullNo The minute's highest sample (1m only). memory_percentnumber | nullNo net_rx_bpsinteger | nullNo net_tx_bpsinteger | nullNo
{
"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_optionsEgressDto[]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_accessInteractiveAccessDtoYes public_ingressPublicIngressDtoYes ssh_key_selectionSshKeySelectionDtoYes
{
"egress_options": [
"none"
],
"interactive_access": "managed_terminal",
"public_ingress": "disabled",
"ssh_key_selection": "unavailable"
}NetworkRequest A requested network policy.
Field Type Required Description egressEgressDtoYes
{
"egress": "none"
}NotificationDto Whether the "you're in" email went out.
One of: sent, failed, not_configured, skipped.
NotificationPreferencesDto Field Type Required Description alertsAlertPreferenceDto[]Yes emailstringYes Where alerts are sent: the account's email address. organization_idstring (uuid)Yes user_idstring (uuid)Yes
{
"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_idstate: "stopped"state: "degraded"state: "unknown"{
"boot_id": "string",
"state": "running"
}OperationAccepted Field Type Required Description machine_idstring (uuid)Yes operation_idstring (uuid)Yes operation_urlstringYes requested_actionstringYes statusstringYes
{
"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_countintegerYes completed_but_unchangedbooleanYes idstring (uuid)Yes kindstringYes machine_idstring (uuid)Yes statusOperationStatusDtoYes error_codestring | nullNo exec_resultnull | ExecResultDtoNo file_rangesFileRangeDto[] | nullNo For a succeeded file_read: the ranges read, as untrusted guest data. starting_soonnull | StartingSoonDtoNo For a pending create or start the fleet has no room for yet: why it waits and until when ("starting soon"); null otherwise. stop_reasonnull | StopReasonDtoNo For a stop: who asked for it; null for other kinds.
{
"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 messagestringYes stagestringYes timestampstringYes
{
"message": "string",
"stage": "accepted",
"timestamp": "string"
}OperationStatusDto One of: pending, running, succeeded, failed, uncertain, correlation_miss.
OperatorActionRequest Field Type Required Description operatorstringYes The individual operator acting (a name or work email), recorded in the audit log; 1-200 characters. reasonstringYes Why; recorded in the audit log, 1-500 characters. A suspension's reason is shown to operators only.
{
"operator": "string",
"reason": "string"
}OperatorCreditDto Field Type Required Description outcomestringYes applied or duplicate.credit_balance_microsinteger | nullNo The credit balance after an applied change.
{
"credit_balance_micros": 0,
"outcome": "string"
}OperatorCreditRequest Field Type Required Description amount_microsintegerYes Positive micros (1 USD = 1000000). at least 1. idempotency_keystringYes Replaying the same key applies the change once. kindCreditKindDtoYes operatorstringYes The individual operator acting, 1-200 characters. organization_idstring (uuid)Yes reasonstringYes Why, 1-500 characters; kept on the ledger row and in the audit log, never shown to the organization.
{
"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_keystringYes Replaying the same key applies the grant once. kindGrantKindDtoYes organization_idstring (uuid)Yes reasonstringYes Why the grant was made; recorded in the audit log. amount_microsinteger | nullNo Micros for credits and trial. period_daysinteger | nullNo Period length for plan_period, starting now (1-366, default 30). tierstring | nullNo Tier for plan_period.
{
"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_revokedintegerYes channels_revokedintegerYes machines_stoppingintegerYes Machines that wanted to run; each gets a durable stop (stop_reason: organization_deleted) within about a second. members_removedintegerYes organization_idstring (uuid)Yes tickets_revokedintegerYes
{
"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_atstring (date-time)Yes idstring (uuid)Yes namestringYes rolestringYes The caller's role in the organization. suspended_atstring (date-time) | nullNo 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.
{
"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 itemsOrganizationDto[]Yes Every organization the caller belongs to, by name. With an API key, only the key's organization.
{
"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 backendBackendDtoYes cpuintegerYes disk_gibintegerYes idstring (uuid)Yes memory_mibintegerYes namestringYes network_accessNetworkAccessPolicyDtoYes pricePlanPriceDtoYes versionintegerYes sizestring | nullNo small, default, large, or xlarge for the seeded size plans; null for other plans.
{
"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 itemsPlanDto[]Yes next_cursorstring | nullNo
{
"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 currencystringYes pattern ^[A-Z]{3}$. effective_fromstring (date-time)Yes hourlystringYes pattern ^(0|[1-9][0-9]*)\.[0-9]{6}$. monthlystringYes pattern ^(0|[1-9][0-9]*)\.[0-9]{6}$.
{
"currency": "USD",
"effective_from": "2026-01-01T00:00:00.000000Z",
"hourly": "0.012500",
"monthly": "9.125000"
}PlanSubscriptionDto Field Type Required Description activebooleanYes Whether the period covers now. cancel_at_period_endbooleanYes The linked subscription was cancelled: the plan ends at period_end unless resumed before then. included_microsintegerYes Usage included each period, in micros. It expires at period_end. included_secondsintegerYes The allowance as default-size seconds. period_endstringYes period_startstringYes price_microsintegerYes renewsbooleanYes tierstringYes starter ($20), pro ($100), team ($500), or scale ($2000).
{
"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 urlstringYes
{
"url": "https://hooks.example.com/vmyard"
}PortDto Field Type Required Description localhostbooleanYes portintegerYes publicbooleanYes urlstringYes https://<label>-<port>.<edge domain>.
{
"localhost": false,
"port": 0,
"public": false,
"url": "https://hooks.example.com/vmyard"
}PortListDto Field Type Required Description itemsPortDto[]Yes Exposed ports as the machine's host last confirmed them, by port. labelstring | nullNo The machine's name in port URLs; null until a port was first exposed.
{
"items": [
{
"localhost": false,
"port": 0,
"public": false,
"url": "https://hooks.example.com/vmyard"
}
],
"label": "k7f2mq3x9a1b"
}PortTokenDto Field Type Required Description expires_atstringYes When the token stops working (UTC RFC 3339). header_tokenstringYes 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. urlstringYes The port URL without a token. url_with_tokenstringYes 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.
{
"expires_at": "string",
"header_token": "string",
"url": "https://hooks.example.com/vmyard",
"url_with_token": "string"
}PortTokenRequest Field Type Required Description ttl_secondsinteger | nullNo Token lifetime, 1-3600 seconds; default 900. 1–3600.
{
"ttl_seconds": 1
}ProblemDetails Field Type Required Description codestringYes correlation_idstring (uuid)Yes field_errorsmap of stringYes messagestringYes remediationstringYes statusintegerYes titlestringYes typestringYes retry_after_secondsinteger | nullNo waitlist_urlstring | nullNo With waitlisted: where to join the waitlist.
{
"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 idstringYes What to send as model in a prompt. namestringYes attachmentsboolean | nullNo Accepts image or file input. context_tokensinteger | nullNo providerstring | nullNo The catalog provider that serves it (anthropic, openai, ...). reasoningboolean | nullNo release_datestring | nullNo YYYY-MM-DD, as the catalog states it.
{
"attachments": false,
"context_tokens": 0,
"id": "string",
"name": "dev",
"provider": "anthropic",
"reasoning": false,
"release_date": "string"
}ProviderModelsDto {
"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_atstring (date-time)Yes When the snapshot was requested (UTC RFC 3339): the instant it copies. idstring (uuid)Yes sourceSnapshotSourceDtoYes tierSnapshotTierDtoYes completed_atstring (date-time) | nullNo When it became ready. size_bytesinteger | nullNo Plaintext bytes of the snapshot's files.
{
"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 backendBackendDtoYes capacity_statusstringYes idstring (uuid)Yes namestringYes versionintegerYes
{
"backend": "mock",
"capacity_status": "available",
"id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
"name": "eu-central",
"version": 0
}RegionPage Field Type Required Description itemsRegionDto[]Yes next_cursorstring | nullNo
{
"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 pathstringYes
{
"path": "notes/todo.txt"
}ResolveAbuseFlagRequest Field Type Required Description notestringYes What the review found, 1-500 characters. operatorstringYes The individual operator acting, 1-200 characters. resolutionFlagResolutionDtoYes
{
"note": "string",
"operator": "string",
"resolution": "dismissed"
}ResourcesDto Field Type Required Description cpuintegerYes disk_gibintegerYes memory_mibintegerYes
{
"cpu": 0,
"disk_gib": 0,
"memory_mib": 0
}RestoreMachineRequest Field Type Required Description snapshot_idstring (uuid)Yes A ready snapshot of this machine. keep_ssh_keysbooleanNo Keep the login user's SSH authorized_keys (default false). namestring | nullNo The new machine's display name. wakeboolean | nullNo Wake the new machine at once (default true); false creates it stopped.
{
"keep_ssh_keys": false,
"name": "dev",
"snapshot_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
"wake": false
}ResumeDto Field Type Required Description organization_idstring (uuid)Yes resumedbooleanYes False when the organization was not suspended.
{
"organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
"resumed": false
}RevealedEnvironmentDto {
"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 contentsstringYes encodingFileEncodingDtoYes Always base64, so the exact bytes come back. pathstringYes
{
"contents": "string",
"encoding": "text",
"path": "notes/todo.txt"
}RevealRequest Field Type Required Description version_idstring (uuid) | nullNo A version of this environment; omitted reveals the current version.
{
"version_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}RoleDto One of: owner, admin, operator, billing, viewer.
A secret file. contents is UTF-8 text unless encoding is base64.
Field Type Required Description contentsstringYes pathstringYes Relative to /work: no leading /, ~, ., .., or empty components, and not under .vmyard. encodingFileEncodingDtoNo
{
"contents": "string",
"encoding": "text",
"path": "notes/todo.txt"
}SetSshKeyRequest Field Type Required Description public_keystringYes 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.
{
"public_key": "string"
}SetVariableRequest Field Type Required Description valuestringYes At most 32 KiB without NUL.
{
"value": "string"
}SignInProviderDto Field Type Required Description defaultbooleanYes Used when /v1/auth/login names no provider. display_namestringYes The button label, such as "ERP.AI" ("Continue with ERP.AI"). kindSignInProviderKindDtoYes namestringYes What provider takes, such as erpai, github, or email.
{
"default": false,
"display_name": "string",
"kind": "oidc",
"name": "dev"
}SignInProviderKindDto One of: oidc, github, email.
SignInProvidersDto Field Type Required Description accessAccessModeDtoYes invite_only: anyone may sign in, but only approved accounts may create organizations, machines, and API keys.providersSignInProviderDto[]Yes Sorted by name. waitlist_urlstring | nullNo Where to join the waitlist, while invite-only.
{
"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_idstring (uuid)Yes operation_idstring (uuid)Yes operation_urlstringYes snapshot_idstring (uuid)Yes snapshot_urlstringYes statusstringYes
{
"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 {
"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.
{
"deleted": 0,
"results": [
{
"result": "deleted",
"snapshot_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}
]
}SnapshotDto Field Type Required Description created_atstring (date-time)Yes idstring (uuid)Yes machine_idstring (uuid)Yes The machine the snapshot was taken from. operation_idstring (uuid)Yes The push operation. sourceSnapshotSourceDtoYes statusSnapshotStatusDtoYes tierSnapshotTierDtoYes completed_atstring (date-time) | nullNo disk_syncedboolean | nullNo The guest flushed its filesystems before the snapshot. error_codestring | nullNo generationinteger | nullNo 1 for a machine's first push, then one more than its parent's. manifeststring | nullNo The stored manifest (64 hex digits) once ready. namestring | nullNo The template name, for a template. parent_manifeststring | nullNo The manifest the machine last was or came from. size_bytesinteger | nullNo Plaintext bytes of the snapshot's files. uploaded_bytesinteger | nullNo Compressed bytes this push uploaded (chunks already stored are reused).
{
"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 itemsSnapshotDto[]Yes next_cursorstring (uuid) | nullNo
{
"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 portintegerYes The gateway port allocated to the machine. userstringYes hoststring | nullNo The SSH gateway for the machine's host or region; null when none is configured.
{
"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 argvstring[] | nullNo Program and arguments. Exactly one of argv or command. commandstring | nullNo Shell command run as /bin/sh -c <command>, at most 8192 bytes.
{
"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_atstring (date-time)Yes When it fails if no room appears (UTC RFC 3339). operation_idstring (uuid)Yes The waiting create or start operation. positionintegerYes Its place in line among the region's waiting starts (1 is next; paid starts are ahead of every trial start). priorityStartPriorityDtoYes queued_atstring (date-time)Yes When it began waiting (UTC RFC 3339). reasonCapacityShortageDtoYes
{
"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 limitintegerYes usedintegerYes windowstringYes Rolling window: minute, hour, or day.
{
"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_suspendedbooleanYes The organization was already suspended: nothing changed, and the original suspension is returned. channels_revokedintegerYes Open terminals and desktops revoked; each ends at its relay's next heartbeat (at most 15 s) with reason revoked. machines_stoppingintegerYes Machines that wanted to run; the worker persists a stop for each (stop_reason: suspension) within about a second. organization_idstring (uuid)Yes reasonstringYes suspended_atstringYes tickets_revokedintegerYes Unredeemed terminal and desktop tickets deleted.
{
"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, rowstype: "signal" with signaltype: "close"{
"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, usertype: "exit" with exit_code, signaltype: "closed" with reason{
"terminal_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
"type": "opened",
"user": "vmyard"
}TerminalTicketDto Field Type Required Description expires_atstringYes ticketstringYes Single-use credential for one terminal WebSocket of this machine, valid for 30 seconds, only with the session that minted it. urlstringYes The WebSocket path with the ticket; add cols and rows.
{
"expires_at": "string",
"ticket": "string",
"url": "https://hooks.example.com/vmyard"
}TransferOwnershipRequest Field Type Required Description user_idstring (uuid)Yes A member who becomes the owner; the caller becomes an admin.
{
"user_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}TrialDto Field Type Required Description activebooleanYes Whether trial rules (two machines, small/default only) apply. concurrent_machinesintegerYes max_hourly_microsintegerYes Sizes priced above this hourly rate are refused during the trial. remaining_microsintegerYes remaining_secondsintegerYes Remaining trial time as default-size seconds. total_microsintegerYes ended_atstring | nullNo When the trial was ended early and its remaining balance forfeited. Trial rules still apply until the first payment.
{
"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 enabledbooleanYes organization_idstring (uuid)Yes typestringYes
{
"enabled": false,
"organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
"type": "operation_failed"
}UpdateAutoRefillRequest Field Type Required Description credit_packsintegerYes 1-50 packs of $20. 1–50. enabledbooleanYes monthly_cap_microsintegerYes At least one refill's amount. threshold_microsintegerYes
{
"credit_packs": 1,
"enabled": false,
"monthly_cap_micros": 0,
"threshold_micros": 0
}UpdateBillingRequest Field Type Required Description minimum_balance_microsinteger | nullNo spend_cap_microsinteger | nullNo Monthly credit spend cap in micros, or null to remove it.
{
"minimum_balance_micros": 0,
"spend_cap_micros": 0
}UpdateEnvironmentRequest Field Type Required Description is_defaultboolean | nullNo true makes this the default; false leaves the organization without one.namestring | nullNo safe_for_third_partiesboolean | nullNo
{
"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_secondsinteger | nullNo 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_secondsinteger | nullNo New idle-sleep window, 300 to 86400 seconds, or null to turn idle sleep off. The idle window restarts. 300–86400. namestring | nullNo New display name, following the tenant_alias rules. The tenant alias itself is immutable. never_auto_stopbooleanNo true disables auto-stop. It cannot be combined with auto_stop_after_seconds.
{
"auto_stop_after_seconds": 60,
"idle_sleep_after_seconds": 300,
"name": "dev",
"never_auto_stop": false
}UpdateMemberRequest Field Type Required Description max_running_machinesinteger | nullNo 0-10000, or null to remove the member's cap; absent leaves it. at most 10000. rolenull | RoleDtoNo
{
"max_running_machines": 0,
"role": "owner"
}UpdateNotificationPreferencesRequest Field Type Required Description alertsmap of stringYes Alert type to on (true) or off (false); unlisted types keep their current setting.
{
"alerts": {}
}UpdateOrganizationRequest Field Type Required Description namestringYes 1–64 characters.
{
"name": "dev"
}UpdateWebhookRequest Omitted fields keep their value; at least one field is required.
Field Type Required Description enabledboolean | nullNo eventsWebhookEventDto[] | nullNo at least 1 items. namestring | nullNo 1–64 characters. urlstring | nullNo at most 2048 characters.
{
"enabled": false,
"events": [
"machine.ready"
],
"name": "dev",
"url": "https://hooks.example.com/vmyard"
}UpgradeEnvironmentRequest Field Type Required Description machine_idsstring (uuid)[] | nullNo Machines to upgrade; omitted upgrades every running machine created with this environment. At most 100.
{
"machine_ids": [
"6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
]
}UpgradeEnvironmentResponse Field Type Required Description environment_idstring (uuid)Yes operationsUpgradeOperationDto[]Yes One apply_environment operation per upgraded machine. skippedUpgradeSkippedDto[]Yes versionintegerYes version_idstring (uuid)Yes
{
"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_idstring (uuid)Yes operation_idstring (uuid)Yes operation_urlstringYes
{
"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_idstring (uuid)Yes reasonstringYes already_current or not_running (start it, then upgrade again).
{
"machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
"reason": "not_running"
}UsageDto Field Type Required Description cost_microsintegerYes machinesMachineUsageDto[]Yes secondsintegerYes sincestringYes untilstringYes
{
"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 idstring (uuid)Yes versionintegerYes
{
"id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
"version": 0
}WaitlistAckDto Field Type Required Description receivedbooleanYes
{
"received": false
}WaitlistDecisionDto {
"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 operatorstringYes The individual operator acting, 1-200 characters. reasonstringYes Why, 1-500 characters.
{
"operator": "string",
"reason": "string"
}WaitlistEntryDto Field Type Required Description created_atstringYes emailstringYes idstring (uuid)Yes raw_answersobjectYes The form's answers as received. statusWaitlistStatusDtoYes updated_atstringYes access_grant_idstring (uuid) | nullNo companystring | nullNo decided_atstring | nullNo decided_bystring | nullNo decision_reasonstring | nullNo namestring | nullNo use_casestring | nullNo
{
"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 {
"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 outcomestringYes applied, duplicate, stale, or ignored.receivedbooleanYes
{
"outcome": "applied",
"received": false
}WebhookDeliveryDto Field Type Required Description attempt_countintegerYes created_atstring (date-time)Yes event_idstring (uuid)Yes Shared by every endpoint's delivery of the same event and sent as X-VMYard-Event-Id; deduplicate on it. event_typeWebhookEventDtoYes idstring (uuid)Yes machine_idstring (uuid)Yes operation_idstring (uuid)Yes statusWebhookDeliveryStatusDtoYes delivered_atstring (date-time) | nullNo last_attempt_atstring (date-time) | nullNo last_errorstring | nullNo Why the last attempt failed, when it did. last_status_codeinteger | nullNo HTTP status of the last attempt; null when no response arrived. next_attempt_atstring (date-time) | nullNo When the next attempt is due; set only while pending.
{
"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 {
"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_atstring (date-time)Yes enabledbooleanYes eventsWebhookEventDto[]Yes idstring (uuid)Yes namestringYes organization_idstring (uuid)Yes secret_rotated_atstring (date-time)Yes updated_atstring (date-time)Yes urlstringYes created_bystring (uuid) | nullNo The member who created the endpoint; null once that user is deleted.
{
"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 itemsWebhookDto[]Yes next_cursorstring (uuid) | nullNo
{
"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 secretstringYes whsec_ plus 43 base64url characters. The whole string is the HMAC-SHA256 key for X-VMYard-Signature.webhookWebhookDtoYes
{
"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 {
"content": "string",
"encoding": "text"
}