---
title: "Update Machine"
method: PATCH
path: "/machines/{id}"
tags: ["Machines"]
---

# Update Machine

`PATCH /machines/{id}`

Update machine settings. All parameters are optional; only sent fields are updated.

### Headers

| Name | Type |
| --- | --- |
| Authorization\* | HMAC {key}:{signature}:{nonce}:{timestamp} |
| Content-Type | application/json |

### Path Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `id`\* | Integer | Machine ID |

### Request Body

| Parameter | Type | Description |
| --- | --- | --- |
| `auto_stop_threshold` | Integer | Auto-stop threshold in seconds. Options": `"0"`, `"900"`, `"3600"`, `"10800"`, `"21600"`. `"0"` to disable. |
| `usage_source` | String | `"team_balance"` or `"machine"`. Controls whether usage is drawn from team balance or machine-only balance. |

### Success Response Fields

| Field | Type | Description |
| --- | --- | --- |
| `id` | String | Machine ID |
| `type` | String | Always "machine" |
| `attributes.name` | String | Machine Name |
| `attributes.os` | String | Operating system: `windows` or `linux` |
| `attributes.last_session_start_at` | String | Last session start time (ISO 8601). null if no session |
| `attributes.auto_stop_threshold` | Integer | Auto-stop threshold in seconds |
| `attributes.file_storage_size` | Integer | Vagon Files storage size in GB |
| `attributes.disk_size` | Integer | Machine disk size in GB |
| `attributes.network_credit` | Integer | Available outbound network credits in bytes |
| `attributes.assigned_image_id` | Integer | Assigned image/template ID. null if none |
| `attributes.assigned_image_name` | String | Name of the assigned base image/template. null if none |
| `attributes.region` | String | Machine region |
| `attributes.machine_type` | String | Machine Performance Type |
| `attributes.remaining_usage` | Integer | Remaining usage time in minutes |
| `attributes.deposited_usage` | Integer | Deposited usage time in minutes |
| `attributes.friendly_status` | String | Machine Status |
| `attributes.user` | Object | Assigned User (null if no user) |
| `attributes.user.id` | String | User UUID |
| `attributes.user.type` | String | Always "user" |
| `attributes.user.attributes.email` | String | User email |
| `attributes.user.attributes.name` | String | User name |
| `attributes.permissions` | Object | Machine Permissions |
| `attributes.usage_source` | String | Usage source - "machine" (only assigned usages) or "team_balance" (can use team balance when no additional usage on machine) |
| `attributes.task` | Object | Active task on the machine (null if no task is active) |
| `attributes.task.id` | Integer | Active task ID on the machine |
| `attributes.task.uid` | String | Unique human-readable task name / uid for the machine |
| `attributes.task.created_at` | String | Task creation timestamp to the machine (ISO 8601) |
| `attributes.latest_image_status` | String | Snapshot state of the latest machine image. One of `in_use`, `processing`, `ready`, or `null`. `null` = machine has no user data yet (never started, or reset since); `in_use` = machine is not off; `processing` = a snapshot is being captured; `ready` = machine is off and no snapshot is being captured. |
| `client_code` | Integer | Response code (200 for success) |
| `message` | String | Response message |
| `timestamp` | String | Response timestamp (ISO 8601) |

## Request body

- object
  - `auto_stop_threshold` integer — Auto-stop threshold in seconds. 0 to disable.
  - `usage_source` 'team_balance' | 'machine' — Usage source - team_balance or machine

## Response `200`

Machine updated successfully

- MachineResponse
  - `client_code` integer
  - `message` string
  - `timestamp` string, date-time
  - `id` string
  - `type` string
  - `attributes` MachineAttributes
    - `name` string
    - `region` string, nullable
    - `last_session_start_at` string, date-time, nullable
    - `friendly_status` 'off' | 'creating' | 'turning_on' | 'ready' | 'turning_off' | 'resizing_disk' | 'installing' | 'region_migration' | 'warming_up'
    - `auto_stop_threshold` integer — Auto-stop threshold in seconds
    - `file_storage_size` integer — Vagon Files storage size in bytes
    - `disk_size` integer — Machine disk size in bytes
    - `network_credit` integer — Available outbound network credits in bytes
    - `assigned_image_id` integer, nullable — Assigned base image ID. null if using default image
    - `assigned_image_name` string, nullable — Name of the assigned base image/template. null if none
    - `machine_type` string
    - `remaining_usage` integer — Remaining usage time in seconds
    - `deposited_usage` integer — Deposited usage time in seconds
    - `user` object, nullable — Assigned user (null if no user). When present contains id, type, attributes (email, name)
      - `id` string, uuid
      - `type` string
      - `attributes` object
        - `email` string
        - `name` string
    - `permissions` Permissions — Machine permission settings
      - `public_internet_access` boolean — Allow public internet access from the machine
      - `can_download_from_vagon_workstation` boolean — Allow file downloads from the Vagon workstation
      - `can_upload_to_workstation` boolean — Allow file uploads to the Vagon workstation
      - `analytics_collection_enabled` boolean — Enable analytics data collection
      - `clipboard_enabled` boolean — Enable clipboard sharing between local and remote machine
      - `screen_recording_enabled` boolean — Enable screen recording capability
      - `input_recording_enabled` boolean — Enable input (keyboard/mouse) recording
    - `usage_source` 'machine' | 'team_balance' — "machine" means the computer will only use assigned usages. "team_balance" means the computer can use team balance as a fallback source when there is no additional usage on the machine.
    - `task` object, nullable — Currently active task on the machine. null when no task is active or when the seat's `backup_enabled` flag is off.
      - `id` integer — Task ID. Use this for task API calls (e.g. DELETE /tasks/:id).
      - `uid` string — Human-readable task name (e.g. "Outputs", "Project-Alpha").
      - `created_at` string, date-time — Timestamp when this task was created and assigned to the seat.
    - `latest_image_status` 'in_use' | 'processing' | 'ready', nullable — Combined snapshot state of the machine's latest image. - `null`: machine has no user data yet (never started, or has been reset and not used since). - `in_use`: machine is not off, so no snapshot can be captured right now. - `processing`: a snapshot is currently being captured (pending image, or within the post-stop scheduling window before the pending record exists). - `ready`: machine is off and no snapshot is being captured (latest committed image, if any, reflects the machine's current state).

## Other responses

- `400` — Bad request (e.g. invalid usage_source)
- `404` — Machine not found
- `4710` — Permission required

---

[API](https://skmtc.dev/vagon/apis/vagon-computers-api.md) · [All operations](https://skmtc.dev/vagon/apis/vagon-computers-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/vagon/vagon-computers-api/revisions/2c128e38f47e/schema)