> For the complete documentation index, see [llms.txt](https://docs.vagon.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vagon.io/teams/reference/machines.md).

# Machines

## List Machines

> List all machine(s) with their applied configurations.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### \*\*Query Parameters\*\*\
> \
> \| Parameter | Type | Default | Description |\
> \| --- | --- | --- | --- |\
> \| \`page\` | Integer | 1 | Page number |\
> \| \`per\_page\` | Integer | 20 | Record count per page |\
> \| \`q\` | String | \\- | Search query by user email or machine name |\
> \| \`time\_left\` | Integer | \\- | Filter by remaining usage in minutes. Returns machines with at least this many minutes remaining |\
> \| \`has\_session\_data\` | Boolean | \\- | Filter by whether machine has session data after reset. \`true\` = has session data (sessions after reset), \`false\` = no session data |\
> \| \`assigned\` | Boolean | \\- | Filter by machine assignment. \`true\` = only machines has a user or pending invitation, \`false\` = only machines has no user and no pending invitation |\
> \| \`status\` | String | \\- | Filter by machine status. |\
> \
> \### \*\*Success Response Example\*\*\
> \
> \`\`\` json\
> {\
> &#x20;   "machines": \[\
> &#x20;       {\
> &#x20;           "id": "100",\
> &#x20;           "type": "machine",\
> &#x20;           "attributes": {\
> &#x20;               "name": "Computer #100",\
> &#x20;               "last\_session\_start\_at": "2026-01-23T11:02:41.902Z",\
> &#x20;               "os": "windows",\
> &#x20;               "auto\_stop\_threshold": 900,\
> &#x20;               "file\_storage\_size": 25,\
> &#x20;               "disk\_size": 75,\
> &#x20;               "network\_credit": 10233505675,\
> &#x20;               "assigned\_image\_id": 990,\
> &#x20;               "assigned\_image\_name": "Template #990",\
> &#x20;               "region": "dublin",\
> &#x20;               "machine\_type": "Planet",\
> &#x20;               "remaining\_usage": 0,\
> &#x20;               "deposited\_usage": 0,\
> &#x20;               "friendly\_status": "off",\
> &#x20;               "user": {\
> &#x20;                   "id": "f1592625-edd0-48df-9bc0-de14910ec936",\
> &#x20;                   "type": "user",\
> &#x20;                   "attributes": {\
> &#x20;                       "email": "<user@vagon.io>",\
> &#x20;                       "name": "Computer User"\
> &#x20;                   }\
> &#x20;               },\
> &#x20;               "permissions": {\
> &#x20;                   "public\_internet\_access": true,\
> &#x20;                   "can\_download\_from\_vagon\_workstation": true,\
> &#x20;                   "can\_upload\_to\_workstation": true,\
> &#x20;                   "analytics\_collection\_enabled": true,\
> &#x20;                   "clipboard\_enabled": true,\
> &#x20;                   "screen\_recording\_enabled": true,\
> &#x20;                   "input\_recording\_enabled": true\
> &#x20;               },\
> &#x20;               "usage\_source": "machine",\
> &#x20;               "task": {\
> &#x20;                   "id": 42,\
> &#x20;                   "uid": "Project-Alpha",\
> &#x20;                   "created\_at": "2026-04-20T09:15:00Z"\
> &#x20;               },\
> &#x20;               "latest\_image\_status": "ready"\
> &#x20;           }\
> &#x20;       },\
> &#x20;       {\
> &#x20;           "id": "101",\
> &#x20;           "type": "machine",\
> &#x20;           "attributes": {\
> &#x20;               "name": "Computer #101",\
> &#x20;               "last\_session\_start\_at": "2026-01-23T14:12:18.943Z",\
> &#x20;               "os": "linux",\
> &#x20;               "auto\_stop\_threshold": 900,\
> &#x20;               "file\_storage\_size": 250,\
> &#x20;               "disk\_size": 125,\
> &#x20;               "network\_credit": 10338256517,\
> &#x20;               "assigned\_image\_id": 991,\
> &#x20;               "assigned\_image\_name": "Template #991",\
> &#x20;               "region": "dublin",\
> &#x20;               "machine\_type": "Planet",\
> &#x20;               "remaining\_usage": 2400,\
> &#x20;               "deposited\_usage": 0,\
> &#x20;               "user": null,\
> &#x20;               "permissions": {\
> &#x20;                   "public\_internet\_access": true,\
> &#x20;                   "can\_download\_from\_vagon\_workstation": true,\
> &#x20;                   "can\_upload\_to\_workstation": true,\
> &#x20;                   "analytics\_collection\_enabled": true,\
> &#x20;                   "clipboard\_enabled": true,\
> &#x20;                   "screen\_recording\_enabled": true,\
> &#x20;                   "input\_recording\_enabled": true\
> &#x20;               },\
> &#x20;               "friendly\_status": "off",\
> &#x20;               "usage\_source": "machine",\
> &#x20;               "task": null,\
> &#x20;               "latest\_image\_status": "processing"\
> &#x20;           }\
> &#x20;       }\
> &#x20;   ],\
> &#x20;   "count": 2,\
> &#x20;   "page": 1,\
> &#x20;   "next\_page": null,\
> &#x20;   "client\_code": 200,\
> &#x20;   "message": "OK",\
> &#x20;   "timestamp": "2026-02-05T10:08:09Z"\
> }\
> \
> &#x20;\`\`\`\
> \
> \### \*\*Success Response Fields\*\*\
> \
> \| Field | Type | Description |\
> \| --- | --- | --- |\
> \| \`machines\` | Array | Array of machine objects |\
> \| \`machines\[].id\` | String | Machine ID |\
> \| \`machines\[].type\` | String | Always "machine" |\
> \| \`machines\[].attributes.name\` | String | Machine Name |\
> \| \`machines\[].attributes.os\` | String | Operating system: \`windows\` or \`linux\` |\
> \| \`machines\[].attributes.last\_session\_start\_at\` | String | Last session start time (ISO 8601). null if no session |\
> \| \`machines\[].attributes.auto\_stop\_threshold\` | Integer | Auto-stop threshold in seconds |\
> \| \`machines\[].attributes.file\_storage\_size\` | Integer | Vagon Files storage size in GB |\
> \| \`machines\[].attributes.disk\_size\` | Integer | Machine disk size in GB |\
> \| \`machines\[].attributes.network\_credit\` | Integer | Available outbound network credits in bytes |\
> \| \`machines\[].attributes.assigned\_image\_id\` | Integer | Assigned image/template ID. null if none |\
> \| \`machines\[].attributes.assigned\_image\_name\` | String | Name of the assigned base image/template. null if none |\
> \| \`machines\[].attributes.region\` | String | Machine region |\
> \| \`machines\[].attributes.machine\_type\` | String | Machine Performance Type |\
> \| \`machines\[].attributes.remaining\_usage\` | Integer | Remaining usage time in minutes |\
> \| \`machines\[].attributes.deposited\_usage\` | Integer | Deposited usage time in minutes |\
> \| \`machines\[].attributes.friendly\_status\` | String | Machine Status |\
> \| \`machines\[].attributes.user\` | Object | Assigned User (null if no user) |\
> \| \`machines\[].attributes.user.id\` | String | User UUID |\
> \| \`machines\[].attributes.user.type\` | String | Always "user" |\
> \| \`machines\[].attributes.user.attributes.email\` | String | User email |\
> \| \`machines\[].attributes.user.attributes.name\` | String | User name |\
> \| \`machines\[].attributes.permissions\` | Object | Machine Permissions |\
> \| \`machines\[].attributes.usage\_source\` | String | Usage source - "machine" (only assigned usages) or "team\_balance" (can use team balance when no additional usage on machine) |\
> \| \`machines\[].attributes.task\` | Object | Active task on the machine (null if no task is active) |\
> \| \`machines\[].attributes.task.id\` | Integer | Active task ID on the machine |\
> \| \`machines\[].attributes.task.uid\` | String | Unique human-readable task name / uid for the machine |\
> \| \`machines\[].attributes.task.created\_at\` | String | Task creation timestamp to the machine (ISO 8601) |\
> \| \`machines\[].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. |\
> \| \`count\` | Integer | Total number of machines |\
> \| \`page\` | Integer | Current page number |\
> \| \`next\_page\` | Integer | Next page number. null if last page |\
> \| \`client\_code\` | Integer | Response code (200 for success) |\
> \| \`message\` | String | Response message |\
> \| \`timestamp\` | String | Response timestamp (ISO 8601) |

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/machines":{"get":{"summary":"List Machines","parameters":[{"name":"page","in":"query","description":"(Optional) Page number. Default: 1","schema":{"type":"integer"}},{"name":"per_page","in":"query","description":"(Optional) Records per page. Default: 20","schema":{"type":"integer"}},{"name":"q","in":"query","description":"(Optional) Search by user email or machine name","schema":{"type":"string"}}],"responses":{"200":{"description":"List of machines","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListMachinesResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"480":{"description":"Insufficient funds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error480Response"}}}},"4201":{"description":"Machine is not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4201Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Machines"],"description":"List all machine(s) with their applied configurations.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### **Query Parameters**\n\n| Parameter | Type | Default | Description |\n| --- | --- | --- | --- |\n| `page` | Integer | 1 | Page number |\n| `per_page` | Integer | 20 | Record count per page |\n| `q` | String | \\- | Search query by user email or machine name |\n| `time_left` | Integer | \\- | Filter by remaining usage in minutes. Returns machines with at least this many minutes remaining |\n| `has_session_data` | Boolean | \\- | Filter by whether machine has session data after reset. `true` = has session data (sessions after reset), `false` = no session data |\n| `assigned` | Boolean | \\- | Filter by machine assignment. `true` = only machines has a user or pending invitation, `false` = only machines has no user and no pending invitation |\n| `status` | String | \\- | Filter by machine status. |\n\n### **Success Response Example**\n\n``` json\n{\n    \"machines\": [\n        {\n            \"id\": \"100\",\n            \"type\": \"machine\",\n            \"attributes\": {\n                \"name\": \"Computer #100\",\n                \"last_session_start_at\": \"2026-01-23T11:02:41.902Z\",\n                \"os\": \"windows\",\n                \"auto_stop_threshold\": 900,\n                \"file_storage_size\": 25,\n                \"disk_size\": 75,\n                \"network_credit\": 10233505675,\n                \"assigned_image_id\": 990,\n                \"assigned_image_name\": \"Template #990\",\n                \"region\": \"dublin\",\n                \"machine_type\": \"Planet\",\n                \"remaining_usage\": 0,\n                \"deposited_usage\": 0,\n                \"friendly_status\": \"off\",\n                \"user\": {\n                    \"id\": \"f1592625-edd0-48df-9bc0-de14910ec936\",\n                    \"type\": \"user\",\n                    \"attributes\": {\n                        \"email\": \"user@vagon.io\",\n                        \"name\": \"Computer User\"\n                    }\n                },\n                \"permissions\": {\n                    \"public_internet_access\": true,\n                    \"can_download_from_vagon_workstation\": true,\n                    \"can_upload_to_workstation\": true,\n                    \"analytics_collection_enabled\": true,\n                    \"clipboard_enabled\": true,\n                    \"screen_recording_enabled\": true,\n                    \"input_recording_enabled\": true\n                },\n                \"usage_source\": \"machine\",\n                \"task\": {\n                    \"id\": 42,\n                    \"uid\": \"Project-Alpha\",\n                    \"created_at\": \"2026-04-20T09:15:00Z\"\n                },\n                \"latest_image_status\": \"ready\"\n            }\n        },\n        {\n            \"id\": \"101\",\n            \"type\": \"machine\",\n            \"attributes\": {\n                \"name\": \"Computer #101\",\n                \"last_session_start_at\": \"2026-01-23T14:12:18.943Z\",\n                \"os\": \"linux\",\n                \"auto_stop_threshold\": 900,\n                \"file_storage_size\": 250,\n                \"disk_size\": 125,\n                \"network_credit\": 10338256517,\n                \"assigned_image_id\": 991,\n                \"assigned_image_name\": \"Template #991\",\n                \"region\": \"dublin\",\n                \"machine_type\": \"Planet\",\n                \"remaining_usage\": 2400,\n                \"deposited_usage\": 0,\n                \"user\": null,\n                \"permissions\": {\n                    \"public_internet_access\": true,\n                    \"can_download_from_vagon_workstation\": true,\n                    \"can_upload_to_workstation\": true,\n                    \"analytics_collection_enabled\": true,\n                    \"clipboard_enabled\": true,\n                    \"screen_recording_enabled\": true,\n                    \"input_recording_enabled\": true\n                },\n                \"friendly_status\": \"off\",\n                \"usage_source\": \"machine\",\n                \"task\": null,\n                \"latest_image_status\": \"processing\"\n            }\n        }\n    ],\n    \"count\": 2,\n    \"page\": 1,\n    \"next_page\": null,\n    \"client_code\": 200,\n    \"message\": \"OK\",\n    \"timestamp\": \"2026-02-05T10:08:09Z\"\n}\n\n ```\n\n### **Success Response Fields**\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `machines` | Array | Array of machine objects |\n| `machines[].id` | String | Machine ID |\n| `machines[].type` | String | Always \"machine\" |\n| `machines[].attributes.name` | String | Machine Name |\n| `machines[].attributes.os` | String | Operating system: `windows` or `linux` |\n| `machines[].attributes.last_session_start_at` | String | Last session start time (ISO 8601). null if no session |\n| `machines[].attributes.auto_stop_threshold` | Integer | Auto-stop threshold in seconds |\n| `machines[].attributes.file_storage_size` | Integer | Vagon Files storage size in GB |\n| `machines[].attributes.disk_size` | Integer | Machine disk size in GB |\n| `machines[].attributes.network_credit` | Integer | Available outbound network credits in bytes |\n| `machines[].attributes.assigned_image_id` | Integer | Assigned image/template ID. null if none |\n| `machines[].attributes.assigned_image_name` | String | Name of the assigned base image/template. null if none |\n| `machines[].attributes.region` | String | Machine region |\n| `machines[].attributes.machine_type` | String | Machine Performance Type |\n| `machines[].attributes.remaining_usage` | Integer | Remaining usage time in minutes |\n| `machines[].attributes.deposited_usage` | Integer | Deposited usage time in minutes |\n| `machines[].attributes.friendly_status` | String | Machine Status |\n| `machines[].attributes.user` | Object | Assigned User (null if no user) |\n| `machines[].attributes.user.id` | String | User UUID |\n| `machines[].attributes.user.type` | String | Always \"user\" |\n| `machines[].attributes.user.attributes.email` | String | User email |\n| `machines[].attributes.user.attributes.name` | String | User name |\n| `machines[].attributes.permissions` | Object | Machine Permissions |\n| `machines[].attributes.usage_source` | String | Usage source - \"machine\" (only assigned usages) or \"team_balance\" (can use team balance when no additional usage on machine) |\n| `machines[].attributes.task` | Object | Active task on the machine (null if no task is active) |\n| `machines[].attributes.task.id` | Integer | Active task ID on the machine |\n| `machines[].attributes.task.uid` | String | Unique human-readable task name / uid for the machine |\n| `machines[].attributes.task.created_at` | String | Task creation timestamp to the machine (ISO 8601) |\n| `machines[].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. |\n| `count` | Integer | Total number of machines |\n| `page` | Integer | Current page number |\n| `next_page` | Integer | Next page number. null if last page |\n| `client_code` | Integer | Response code (200 for success) |\n| `message` | String | Response message |\n| `timestamp` | String | Response timestamp (ISO 8601) |"}}},"components":{"schemas":{"ListMachinesResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"machines":{"type":"array","items":{"$ref":"#/components/schemas/Machine"}},"count":{"type":"integer","description":"Total number of machines"},"page":{"type":"integer","description":"Current page number"},"next_page":{"type":"integer","nullable":true,"description":"Next page number (null if no more pages)"}}}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Machine":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"$ref":"#/components/schemas/MachineAttributes"}}},"MachineAttributes":{"type":"object","properties":{"name":{"type":"string"},"region":{"type":"string","nullable":true},"last_session_start_at":{"type":"string","format":"date-time","nullable":true},"friendly_status":{"type":"string","enum":["off","creating","turning_on","ready","turning_off","resizing_disk","installing","region_migration","warming_up","preparing_files","running_scripts"],"description":"`preparing_files` is reported while the machine copies its linked preloaded files to the desktop at session start, and `running_scripts` while it then runs its linked preloaded scripts; Connect is not available until it becomes `ready`."},"auto_stop_threshold":{"type":"integer","description":"Auto-stop threshold in seconds"},"file_storage_size":{"type":"integer","description":"Vagon Files storage size in bytes"},"disk_size":{"type":"integer","description":"Machine disk size in bytes"},"network_credit":{"type":"integer","description":"Available outbound network credits in bytes"},"assigned_image_id":{"type":"integer","nullable":true,"description":"Assigned base image ID. null if using default image"},"assigned_image_name":{"type":"string","nullable":true,"description":"Name of the assigned base image/template. null if none"},"machine_type":{"type":"string"},"remaining_usage":{"type":"integer","description":"Remaining usage time in seconds"},"deposited_usage":{"type":"integer","description":"Deposited usage time in seconds"},"user":{"type":"object","nullable":true,"description":"Assigned user (null if no user). When present contains id, type, attributes (email, name)","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"}}}}},"permissions":{"$ref":"#/components/schemas/Permissions"},"usage_source":{"type":"string","enum":["machine","team_balance"],"description":"\"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":{"type":"object","nullable":true,"description":"Currently active task on the machine. null when no task is active or when the seat's `backup_enabled` flag is off.","properties":{"id":{"type":"integer","description":"Task ID. Use this for task API calls (e.g. DELETE /tasks/:id)."},"uid":{"type":"string","description":"Human-readable task name (e.g. \"Outputs\", \"Project-Alpha\")."},"created_at":{"type":"string","format":"date-time","description":"Timestamp when this task was created and assigned to the seat."}}},"latest_image_status":{"type":"string","nullable":true,"enum":["in_use","processing","ready"],"description":"Combined snapshot state of the machine's latest image.\n  - `null`: machine has no user data yet (never started, or has been reset and not used since).\n  - `in_use`: machine is not off, so no snapshot can be captured right now.\n  - `processing`: a snapshot is currently being captured (pending image, or within the post-stop scheduling window before the pending record exists).\n  - `ready`: machine is off and no snapshot is being captured (latest committed image, if any, reflects the machine's current state).\n"}}},"Permissions":{"type":"object","description":"Machine permission settings","properties":{"public_internet_access":{"type":"boolean","description":"Allow public internet access from the machine"},"can_download_from_vagon_workstation":{"type":"boolean","description":"Allow file downloads from the Vagon workstation"},"can_upload_to_workstation":{"type":"boolean","description":"Allow file uploads to the Vagon workstation"},"analytics_collection_enabled":{"type":"boolean","description":"Enable analytics data collection"},"clipboard_enabled":{"type":"boolean","description":"Enable clipboard sharing between local and remote machine"},"screen_recording_enabled":{"type":"boolean","description":"Enable screen recording capability"},"input_recording_enabled":{"type":"boolean","description":"Enable input (keyboard/mouse) recording"}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error480Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4201Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````

## Create Machines

> Create machine(s) with selected configurations. Associated payments will be processed from organization balance.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### \*\*Body Parameters\*\*\
> \
> \| Parameter | Type | Description |\
> \| --- | --- | --- |\
> \| \`plan\_id\`\\\* | Integer | Plan ID. Determines which plan the machine will use. Defines available machine types, disk size, file storage size, etc. Contact Vagon team to learn Plan ID options. |\
> \| \`quantity\` | Integer | Number of machines to create. Must be greater than 0. Default: 1 |\
> \| \`region\` | String | Region where machine will be created (e.g., "dublin", "frankfurt"). Required if default region is not set for the account, globally. |\
> \| \`os\` | String | Operating system for the created machines: \`windows\` or \`linux\`. Optional. Default: \`windows\`. |\
> \| \`software\_ids\` | Array\\\[Integer\\] | Array of software IDs to pre-install. Use \`GET /software\` to see available software |\
> \| \`base\_image\_id\` | Integer | Base image ID, when it's null uses latest base image. Use \`GET /software\` to see available images |\
> \| \`permissions.public\_internet\_access\` | Boolean | Whether machine has internet access. Default: true |\
> \| \`permissions.can\_download\_from\_vagon\_workstation\` | Boolean | Whether files can be downloaded from Vagon machine. Default: true |\
> \| \`permissions.can\_upload\_to\_workstation\` | Boolean | Whether team member is allowed to upload files to the Vagon workstation. Default: true |\
> \| \`permissions.analytics\_collection\_enabled\` | Boolean | Whether analytics collection is enabled. Default: false |\
> \| \`permissions.clipboard\_enabled\` | Boolean | Whether clipboard sharing is enabled. Default: true |\
> \| \`permissions.screen\_recording\_enabled\` | Boolean | Whether screen recording is enabled. Default: false |\
> \| \`permissions.input\_recording\_enabled\` | Boolean | Whether input recording is enabled. Default: false |\
> \
> \### Request Body\
> \
> \`\`\` json\
> {\
> &#x20; "plan\_id": 1,\
> &#x20; "quantity": 1,\
> &#x20; "region": "dublin",\
> &#x20; "os": "windows",\
> &#x20; "software\_ids": \[],\
> &#x20; "base\_image\_id": 100,\
> &#x20; "permissions": {\
> &#x20;   "public\_internet\_access": true,\
> &#x20;   "can\_download\_from\_vagon\_workstation": true,\
> &#x20;   "can\_upload\_to\_workstation": true,\
> &#x20;   "analytics\_collection\_enabled": false,\
> &#x20;   "clipboard\_enabled": true,\
> &#x20;   "screen\_recording\_enabled": false,\
> &#x20;   "input\_recording\_enabled": false\
> &#x20; }\
> }\
> \
> &#x20;\`\`\`\
> \
> \### \*\*Success Response Example\*\*\
> \
> \`\`\` json\
> {\
> &#x20;   "machines": \[\
> &#x20;       {\
> &#x20;           "id": "100",\
> &#x20;           "type": "machine",\
> &#x20;           "attributes": {\
> &#x20;               "name": "Computer #100",\
> &#x20;               "last\_session\_start\_at": null,\
> &#x20;               "os": "windows",\
> &#x20;               "auto\_stop\_threshold": 900,\
> &#x20;               "file\_storage\_size": 25,\
> &#x20;               "disk\_size": 75,\
> &#x20;               "network\_credit": 10737418240,\
> &#x20;               "assigned\_image\_id": 100,\
> &#x20;               "assigned\_image\_name": "Template #100",\
> &#x20;               "region": "dublin",\
> &#x20;               "machine\_type": "Planet",\
> &#x20;               "remaining\_usage": 0,\
> &#x20;               "deposited\_usage": 0,\
> &#x20;               "user": null,\
> &#x20;               "friendly\_status": "off",\
> &#x20;               "permissions": {\
> &#x20;                   "public\_internet\_access": true,\
> &#x20;                   "can\_download\_from\_vagon\_workstation": true,\
> &#x20;                   "can\_upload\_to\_workstation": true,\
> &#x20;                   "analytics\_collection\_enabled": false,\
> &#x20;                   "clipboard\_enabled": true,\
> &#x20;                   "screen\_recording\_enabled": false,\
> &#x20;                   "input\_recording\_enabled": false\
> &#x20;               },\
> &#x20;               "task": null,\
> &#x20;               "latest\_image\_status": null\
> &#x20;           }\
> &#x20;       }\
> &#x20;   ],\
> &#x20;   "count": 1,\
> &#x20;   "client\_code": 200,\
> &#x20;   "message": "OK",\
> &#x20;   "timestamp": "2026-02-05T10:10:22Z"\
> }\
> \
> &#x20;\`\`\`\
> \
> \### \*\*Success Response Fields\*\*\
> \
> \| Field | Type | Description |\
> \| --- | --- | --- |\
> \| \`machines\` | Array | Array of created machine objects |\
> \| \`machines\[].id\` | String | Machine ID |\
> \| \`machines\[].type\` | String | Always "machine" |\
> \| \`machines\[].attributes.name\` | String | Machine Name |\
> \| \`machines\[].attributes.os\` | String | Operating system: \`windows\` or \`linux\` |\
> \| \`machines\[].attributes.last\_session\_start\_at\` | String | Last session start time (ISO 8601). null if no session |\
> \| \`machines\[].attributes.auto\_stop\_threshold\` | Integer | Auto-stop threshold in seconds |\
> \| \`machines\[].attributes.file\_storage\_size\` | Integer | Vagon Files storage size in GB |\
> \| \`machines\[].attributes.disk\_size\` | Integer | Machine disk size in GB |\
> \| \`machines\[].attributes.network\_credit\` | Integer | Available  network credits in bytes |\
> \| \`machines\[].attributes.assigned\_image\_id\` | Integer | Assigned image/template ID. null if none |\
> \| \`machines\[].attributes.assigned\_image\_name\` | String | Name of the assigned base image/template. null if none |\
> \| \`machines\[].attributes.region\` | String | Machine region |\
> \| \`machines\[].attributes.machine\_type\` | String | Machine Performance Type |\
> \| \`machines\[].attributes.remaining\_usage\` | Integer | Remaining usage time in minutes |\
> \| \`machines\[].attributes.deposited\_usage\` | Integer | Deposited usage time in minutes |\
> \| \`machines\[].attributes.user\` | Object | Assigned User (null if no user) |\
> \| \`machines\[].attributes.friendly\_status\` | String | Machine Status - check documentation for detailed machine states. |\
> \| \`machines\[].attributes.permissions\` | Object | Machine Permissions |\
> \| \`machines\[].attributes.task\` | Object | Active task on the machine (null if no task is active) |\
> \| \`machines\[].attributes.task.id\` | Integer | Active task ID on the machine |\
> \| \`machines\[].attributes.task.uid\` | String | Unique human-readable task name / uid for the machine |\
> \| \`machines\[].attributes.task.created\_at\` | String | Task creation timestamp to the machine (ISO 8601) |\
> \| \`machines\[].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. |\
> \| \`count\` | Integer | Number of machines created |\
> \| \`client\_code\` | Integer | Response code (200 for success) |\
> \| \`message\` | String | Response message |\
> \| \`timestamp\` | String | Response timestamp (ISO 8601) |\
> \
> \### \*\*Error Responses\*\*\
> \
> \| Status | Description |\
> \| --- | --- |\
> \| 400 | Bad request |\
> \| 404 | Plan ID not found |\
> \| 480 | Insufficient balance to create computer |\
> \| 4202 | Region is required |\
> \| 4710 | Permission required |

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/machines":{"post":{"summary":"Create Machines","responses":{"200":{"description":"Machines created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMachinesResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"Plan ID not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"480":{"description":"Insufficient balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error480Response"}}}},"4202":{"description":"Region is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4202Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Machines"],"description":"Create machine(s) with selected configurations. Associated payments will be processed from organization balance.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### **Body Parameters**\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `plan_id`\\* | Integer | Plan ID. Determines which plan the machine will use. Defines available machine types, disk size, file storage size, etc. Contact Vagon team to learn Plan ID options. |\n| `quantity` | Integer | Number of machines to create. Must be greater than 0. Default: 1 |\n| `region` | String | Region where machine will be created (e.g., \"dublin\", \"frankfurt\"). Required if default region is not set for the account, globally. |\n| `os` | String | Operating system for the created machines: `windows` or `linux`. Optional. Default: `windows`. |\n| `software_ids` | Array\\[Integer\\] | Array of software IDs to pre-install. Use `GET /software` to see available software |\n| `base_image_id` | Integer | Base image ID, when it's null uses latest base image. Use `GET /software` to see available images |\n| `permissions.public_internet_access` | Boolean | Whether machine has internet access. Default: true |\n| `permissions.can_download_from_vagon_workstation` | Boolean | Whether files can be downloaded from Vagon machine. Default: true |\n| `permissions.can_upload_to_workstation` | Boolean | Whether team member is allowed to upload files to the Vagon workstation. Default: true |\n| `permissions.analytics_collection_enabled` | Boolean | Whether analytics collection is enabled. Default: false |\n| `permissions.clipboard_enabled` | Boolean | Whether clipboard sharing is enabled. Default: true |\n| `permissions.screen_recording_enabled` | Boolean | Whether screen recording is enabled. Default: false |\n| `permissions.input_recording_enabled` | Boolean | Whether input recording is enabled. Default: false |\n\n### Request Body\n\n``` json\n{\n  \"plan_id\": 1,\n  \"quantity\": 1,\n  \"region\": \"dublin\",\n  \"os\": \"windows\",\n  \"software_ids\": [],\n  \"base_image_id\": 100,\n  \"permissions\": {\n    \"public_internet_access\": true,\n    \"can_download_from_vagon_workstation\": true,\n    \"can_upload_to_workstation\": true,\n    \"analytics_collection_enabled\": false,\n    \"clipboard_enabled\": true,\n    \"screen_recording_enabled\": false,\n    \"input_recording_enabled\": false\n  }\n}\n\n ```\n\n### **Success Response Example**\n\n``` json\n{\n    \"machines\": [\n        {\n            \"id\": \"100\",\n            \"type\": \"machine\",\n            \"attributes\": {\n                \"name\": \"Computer #100\",\n                \"last_session_start_at\": null,\n                \"os\": \"windows\",\n                \"auto_stop_threshold\": 900,\n                \"file_storage_size\": 25,\n                \"disk_size\": 75,\n                \"network_credit\": 10737418240,\n                \"assigned_image_id\": 100,\n                \"assigned_image_name\": \"Template #100\",\n                \"region\": \"dublin\",\n                \"machine_type\": \"Planet\",\n                \"remaining_usage\": 0,\n                \"deposited_usage\": 0,\n                \"user\": null,\n                \"friendly_status\": \"off\",\n                \"permissions\": {\n                    \"public_internet_access\": true,\n                    \"can_download_from_vagon_workstation\": true,\n                    \"can_upload_to_workstation\": true,\n                    \"analytics_collection_enabled\": false,\n                    \"clipboard_enabled\": true,\n                    \"screen_recording_enabled\": false,\n                    \"input_recording_enabled\": false\n                },\n                \"task\": null,\n                \"latest_image_status\": null\n            }\n        }\n    ],\n    \"count\": 1,\n    \"client_code\": 200,\n    \"message\": \"OK\",\n    \"timestamp\": \"2026-02-05T10:10:22Z\"\n}\n\n ```\n\n### **Success Response Fields**\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `machines` | Array | Array of created machine objects |\n| `machines[].id` | String | Machine ID |\n| `machines[].type` | String | Always \"machine\" |\n| `machines[].attributes.name` | String | Machine Name |\n| `machines[].attributes.os` | String | Operating system: `windows` or `linux` |\n| `machines[].attributes.last_session_start_at` | String | Last session start time (ISO 8601). null if no session |\n| `machines[].attributes.auto_stop_threshold` | Integer | Auto-stop threshold in seconds |\n| `machines[].attributes.file_storage_size` | Integer | Vagon Files storage size in GB |\n| `machines[].attributes.disk_size` | Integer | Machine disk size in GB |\n| `machines[].attributes.network_credit` | Integer | Available  network credits in bytes |\n| `machines[].attributes.assigned_image_id` | Integer | Assigned image/template ID. null if none |\n| `machines[].attributes.assigned_image_name` | String | Name of the assigned base image/template. null if none |\n| `machines[].attributes.region` | String | Machine region |\n| `machines[].attributes.machine_type` | String | Machine Performance Type |\n| `machines[].attributes.remaining_usage` | Integer | Remaining usage time in minutes |\n| `machines[].attributes.deposited_usage` | Integer | Deposited usage time in minutes |\n| `machines[].attributes.user` | Object | Assigned User (null if no user) |\n| `machines[].attributes.friendly_status` | String | Machine Status - check documentation for detailed machine states. |\n| `machines[].attributes.permissions` | Object | Machine Permissions |\n| `machines[].attributes.task` | Object | Active task on the machine (null if no task is active) |\n| `machines[].attributes.task.id` | Integer | Active task ID on the machine |\n| `machines[].attributes.task.uid` | String | Unique human-readable task name / uid for the machine |\n| `machines[].attributes.task.created_at` | String | Task creation timestamp to the machine (ISO 8601) |\n| `machines[].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. |\n| `count` | Integer | Number of machines created |\n| `client_code` | Integer | Response code (200 for success) |\n| `message` | String | Response message |\n| `timestamp` | String | Response timestamp (ISO 8601) |\n\n### **Error Responses**\n\n| Status | Description |\n| --- | --- |\n| 400 | Bad request |\n| 404 | Plan ID not found |\n| 480 | Insufficient balance to create computer |\n| 4202 | Region is required |\n| 4710 | Permission required |","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["plan_id","quantity","region"],"properties":{"plan_id":{"type":"integer","description":"Subscription plan ID"},"quantity":{"type":"integer","description":"Number of machines to create"},"region":{"type":"string","description":"Region for the machine (e.g., dublin, frankfurt)"},"os":{"type":"string","enum":["windows","linux"],"default":"windows","description":"Operating system for the created machines. Optional; defaults to windows."},"software_ids":{"type":"array","description":"List of software IDs to pre-install","items":{"type":"integer"}},"base_image_id":{"type":"integer","nullable":true,"description":"Base image ID to use (null for default)"},"permissions":{"type":"object","description":"Machine permission settings","properties":{"public_internet_access":{"type":"boolean","description":"Allow public internet access"},"can_download_from_vagon_workstation":{"type":"boolean","description":"Allow file downloads from workstation"},"can_upload_to_workstation":{"type":"boolean","description":"Allow file uploads to the Vagon workstation"},"analytics_collection_enabled":{"type":"boolean","description":"Enable analytics collection"},"clipboard_enabled":{"type":"boolean","description":"Enable clipboard sharing"},"screen_recording_enabled":{"type":"boolean","description":"Enable screen recording"},"input_recording_enabled":{"type":"boolean","description":"Enable input recording"}}}}}}}}}}},"components":{"schemas":{"CreateMachinesResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"machines":{"type":"array","items":{"$ref":"#/components/schemas/Machine"}},"count":{"type":"integer"}}}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Machine":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"$ref":"#/components/schemas/MachineAttributes"}}},"MachineAttributes":{"type":"object","properties":{"name":{"type":"string"},"region":{"type":"string","nullable":true},"last_session_start_at":{"type":"string","format":"date-time","nullable":true},"friendly_status":{"type":"string","enum":["off","creating","turning_on","ready","turning_off","resizing_disk","installing","region_migration","warming_up","preparing_files","running_scripts"],"description":"`preparing_files` is reported while the machine copies its linked preloaded files to the desktop at session start, and `running_scripts` while it then runs its linked preloaded scripts; Connect is not available until it becomes `ready`."},"auto_stop_threshold":{"type":"integer","description":"Auto-stop threshold in seconds"},"file_storage_size":{"type":"integer","description":"Vagon Files storage size in bytes"},"disk_size":{"type":"integer","description":"Machine disk size in bytes"},"network_credit":{"type":"integer","description":"Available outbound network credits in bytes"},"assigned_image_id":{"type":"integer","nullable":true,"description":"Assigned base image ID. null if using default image"},"assigned_image_name":{"type":"string","nullable":true,"description":"Name of the assigned base image/template. null if none"},"machine_type":{"type":"string"},"remaining_usage":{"type":"integer","description":"Remaining usage time in seconds"},"deposited_usage":{"type":"integer","description":"Deposited usage time in seconds"},"user":{"type":"object","nullable":true,"description":"Assigned user (null if no user). When present contains id, type, attributes (email, name)","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"}}}}},"permissions":{"$ref":"#/components/schemas/Permissions"},"usage_source":{"type":"string","enum":["machine","team_balance"],"description":"\"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":{"type":"object","nullable":true,"description":"Currently active task on the machine. null when no task is active or when the seat's `backup_enabled` flag is off.","properties":{"id":{"type":"integer","description":"Task ID. Use this for task API calls (e.g. DELETE /tasks/:id)."},"uid":{"type":"string","description":"Human-readable task name (e.g. \"Outputs\", \"Project-Alpha\")."},"created_at":{"type":"string","format":"date-time","description":"Timestamp when this task was created and assigned to the seat."}}},"latest_image_status":{"type":"string","nullable":true,"enum":["in_use","processing","ready"],"description":"Combined snapshot state of the machine's latest image.\n  - `null`: machine has no user data yet (never started, or has been reset and not used since).\n  - `in_use`: machine is not off, so no snapshot can be captured right now.\n  - `processing`: a snapshot is currently being captured (pending image, or within the post-stop scheduling window before the pending record exists).\n  - `ready`: machine is off and no snapshot is being captured (latest committed image, if any, reflects the machine's current state).\n"}}},"Permissions":{"type":"object","description":"Machine permission settings","properties":{"public_internet_access":{"type":"boolean","description":"Allow public internet access from the machine"},"can_download_from_vagon_workstation":{"type":"boolean","description":"Allow file downloads from the Vagon workstation"},"can_upload_to_workstation":{"type":"boolean","description":"Allow file uploads to the Vagon workstation"},"analytics_collection_enabled":{"type":"boolean","description":"Enable analytics data collection"},"clipboard_enabled":{"type":"boolean","description":"Enable clipboard sharing between local and remote machine"},"screen_recording_enabled":{"type":"boolean","description":"Enable screen recording capability"},"input_recording_enabled":{"type":"boolean","description":"Enable input (keyboard/mouse) recording"}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error480Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4202Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````

## Update Machine

> 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) |

```json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/machines/{id}":{"patch":{"summary":"Update Machine","responses":{"200":{"description":"Machine updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineResponse"}}}},"400":{"description":"Bad request (e.g. invalid usage_source)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"Machine not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Machines"],"description":"Update machine settings. All parameters are optional; only sent fields are updated.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### Path Parameters\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `id`\\* | Integer | Machine ID |\n\n### Request Body\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `auto_stop_threshold` | Integer | Auto-stop threshold in seconds. Options\": `\"0\"`, `\"900\"`, `\"3600\"`, `\"10800\"`, `\"21600\"`. `\"0\"` to disable. |\n| `usage_source` | String | `\"team_balance\"` or `\"machine\"`. Controls whether usage is drawn from team balance or machine-only balance. |\n\n### Success Response Fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `id` | String | Machine ID |\n| `type` | String | Always \"machine\" |\n| `attributes.name` | String | Machine Name |\n| `attributes.os` | String | Operating system: `windows` or `linux` |\n| `attributes.last_session_start_at` | String | Last session start time (ISO 8601). null if no session |\n| `attributes.auto_stop_threshold` | Integer | Auto-stop threshold in seconds |\n| `attributes.file_storage_size` | Integer | Vagon Files storage size in GB |\n| `attributes.disk_size` | Integer | Machine disk size in GB |\n| `attributes.network_credit` | Integer | Available outbound network credits in bytes |\n| `attributes.assigned_image_id` | Integer | Assigned image/template ID. null if none |\n| `attributes.assigned_image_name` | String | Name of the assigned base image/template. null if none |\n| `attributes.region` | String | Machine region |\n| `attributes.machine_type` | String | Machine Performance Type |\n| `attributes.remaining_usage` | Integer | Remaining usage time in minutes |\n| `attributes.deposited_usage` | Integer | Deposited usage time in minutes |\n| `attributes.friendly_status` | String | Machine Status |\n| `attributes.user` | Object | Assigned User (null if no user) |\n| `attributes.user.id` | String | User UUID |\n| `attributes.user.type` | String | Always \"user\" |\n| `attributes.user.attributes.email` | String | User email |\n| `attributes.user.attributes.name` | String | User name |\n| `attributes.permissions` | Object | Machine Permissions |\n| `attributes.usage_source` | String | Usage source - \"machine\" (only assigned usages) or \"team_balance\" (can use team balance when no additional usage on machine) |\n| `attributes.task` | Object | Active task on the machine (null if no task is active) |\n| `attributes.task.id` | Integer | Active task ID on the machine |\n| `attributes.task.uid` | String | Unique human-readable task name / uid for the machine |\n| `attributes.task.created_at` | String | Task creation timestamp to the machine (ISO 8601) |\n| `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. |\n| `client_code` | Integer | Response code (200 for success) |\n| `message` | String | Response message |\n| `timestamp` | String | Response timestamp (ISO 8601) |","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"auto_stop_threshold":{"type":"integer","description":"Auto-stop threshold in seconds. 0 to disable."},"usage_source":{"type":"string","enum":["team_balance","machine"],"description":"Usage source - team_balance or machine"}}}}}}}}},"components":{"schemas":{"MachineResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"$ref":"#/components/schemas/Machine"}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Machine":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"$ref":"#/components/schemas/MachineAttributes"}}},"MachineAttributes":{"type":"object","properties":{"name":{"type":"string"},"region":{"type":"string","nullable":true},"last_session_start_at":{"type":"string","format":"date-time","nullable":true},"friendly_status":{"type":"string","enum":["off","creating","turning_on","ready","turning_off","resizing_disk","installing","region_migration","warming_up","preparing_files","running_scripts"],"description":"`preparing_files` is reported while the machine copies its linked preloaded files to the desktop at session start, and `running_scripts` while it then runs its linked preloaded scripts; Connect is not available until it becomes `ready`."},"auto_stop_threshold":{"type":"integer","description":"Auto-stop threshold in seconds"},"file_storage_size":{"type":"integer","description":"Vagon Files storage size in bytes"},"disk_size":{"type":"integer","description":"Machine disk size in bytes"},"network_credit":{"type":"integer","description":"Available outbound network credits in bytes"},"assigned_image_id":{"type":"integer","nullable":true,"description":"Assigned base image ID. null if using default image"},"assigned_image_name":{"type":"string","nullable":true,"description":"Name of the assigned base image/template. null if none"},"machine_type":{"type":"string"},"remaining_usage":{"type":"integer","description":"Remaining usage time in seconds"},"deposited_usage":{"type":"integer","description":"Deposited usage time in seconds"},"user":{"type":"object","nullable":true,"description":"Assigned user (null if no user). When present contains id, type, attributes (email, name)","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"}}}}},"permissions":{"$ref":"#/components/schemas/Permissions"},"usage_source":{"type":"string","enum":["machine","team_balance"],"description":"\"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":{"type":"object","nullable":true,"description":"Currently active task on the machine. null when no task is active or when the seat's `backup_enabled` flag is off.","properties":{"id":{"type":"integer","description":"Task ID. Use this for task API calls (e.g. DELETE /tasks/:id)."},"uid":{"type":"string","description":"Human-readable task name (e.g. \"Outputs\", \"Project-Alpha\")."},"created_at":{"type":"string","format":"date-time","description":"Timestamp when this task was created and assigned to the seat."}}},"latest_image_status":{"type":"string","nullable":true,"enum":["in_use","processing","ready"],"description":"Combined snapshot state of the machine's latest image.\n  - `null`: machine has no user data yet (never started, or has been reset and not used since).\n  - `in_use`: machine is not off, so no snapshot can be captured right now.\n  - `processing`: a snapshot is currently being captured (pending image, or within the post-stop scheduling window before the pending record exists).\n  - `ready`: machine is off and no snapshot is being captured (latest committed image, if any, reflects the machine's current state).\n"}}},"Permissions":{"type":"object","description":"Machine permission settings","properties":{"public_internet_access":{"type":"boolean","description":"Allow public internet access from the machine"},"can_download_from_vagon_workstation":{"type":"boolean","description":"Allow file downloads from the Vagon workstation"},"can_upload_to_workstation":{"type":"boolean","description":"Allow file uploads to the Vagon workstation"},"analytics_collection_enabled":{"type":"boolean","description":"Enable analytics data collection"},"clipboard_enabled":{"type":"boolean","description":"Enable clipboard sharing between local and remote machine"},"screen_recording_enabled":{"type":"boolean","description":"Enable screen recording capability"},"input_recording_enabled":{"type":"boolean","description":"Enable input (keyboard/mouse) recording"}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
```

## Start Machine

> Start selected machine.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### Path Parameters\
> \
> \| Parameter | Type | Description |\
> \| --- | --- | --- |\
> \| \`id\`\\\* | Integer | Machine ID |\
> \
> \### Success Response\
> \
> \`\`\` json\
> {\
> &#x20;   "client\_code": 200,\
> &#x20;   "message": "OK",\
> &#x20;   "timestamp": "2026-02-05T10:11:54Z"\
> }\
> \
> &#x20;\`\`\`\
> \
> \### Error Responses\
> \
> \| Status | Description |\
> \| --- | --- |\
> \| 400 | Bad request |\
> \| 404 | Machine not found |\
> \| 480 | Insufficient balance |\
> \| 4710 | Permission required |

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/machines/{id}/start":{"post":{"summary":"Start Machine","responses":{"200":{"description":"Machine started successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"Machine not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"480":{"description":"Insufficient balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error480Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Machines"],"description":"Start selected machine.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### Path Parameters\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `id`\\* | Integer | Machine ID |\n\n### Success Response\n\n``` json\n{\n    \"client_code\": 200,\n    \"message\": \"OK\",\n    \"timestamp\": \"2026-02-05T10:11:54Z\"\n}\n\n ```\n\n### Error Responses\n\n| Status | Description |\n| --- | --- |\n| 400 | Bad request |\n| 404 | Machine not found |\n| 480 | Insufficient balance |\n| 4710 | Permission required |"}}},"components":{"schemas":{"SuccessResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error480Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````

## Get Available Machine Performances

> Lists all available machine types for a specific machine based on its plan.\
> \
> Machine types define the hardware specifications (CPU, RAM, GPU) that can be used for the machine.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### Path Parameters\
> \
> \| Parameter | Type | Description |\
> \| --- | --- | --- |\
> \| \`id\` | Integer | Machine ID |\
> \
> \### Response Fields\
> \
> \| Field | Type | Description |\
> \| --- | --- | --- |\
> \| \`machine\_types\` | Array | Array of available machine type objects |\
> \| \`machine\_types\[].id\` | String | Machine type ID (use this in machine\_type\_id parameter) |\
> \| \`machine\_types\[].type\` | String | Always "machine\_type" |\
> \| \`machine\_types\[].attributes.name\` | String | Internal machine type name (e.g., "g4dn.xlarge") |\
> \| \`machine\_types\[].attributes.friendly\_name\` | String | Human-readable machine type name (e.g., "Planet", "Spark") |\
> \| \`machine\_types\[].attributes.cpu\` | Integer | Number of CPU cores |\
> \| \`machine\_types\[].attributes.memory\` | String | RAM size in GB (e.g., "16.0") |\
> \| \`machine\_types\[].attributes.gpu\` | Integer | Number of GPUs (0 = no GPU) |\
> \| \`machine\_types\[].attributes.gpu\_memory\` | String | GPU memory in GB (e.g., "16.0") |\
> \| \`client\_code\` | Integer | Response code (200 for success) |\
> \| \`message\` | String | Response message |\
> \| \`timestamp\` | String | Response timestamp (ISO 8601) |\
> \
> \### Response Example\
> \
> \`\`\` json\
> {\
> &#x20;   "machine\_types": \[\
> &#x20;       {\
> &#x20;           "id": "11",\
> &#x20;           "type": "machine\_type",\
> &#x20;           "attributes": {\
> &#x20;               "name": "g4dn.xlarge",\
> &#x20;               "friendly\_name": "Planet",\
> &#x20;               "cpu": 4,\
> &#x20;               "memory": "16.0",\
> &#x20;               "gpu": 1,\
> &#x20;               "gpu\_memory": "16.0"\
> &#x20;           }\
> &#x20;       },\
> &#x20;       {\
> &#x20;           "id": "15",\
> &#x20;           "type": "machine\_type",\
> &#x20;           "attributes": {\
> &#x20;               "name": "g5.xlarge",\
> &#x20;               "friendly\_name": "Spark",\
> &#x20;               "cpu": 4,\
> &#x20;               "memory": "16.0",\
> &#x20;               "gpu": 1,\
> &#x20;               "gpu\_memory": "24.0"\
> &#x20;           }\
> &#x20;       }\
> &#x20;   ],\
> &#x20;   "client\_code": 200,\
> &#x20;   "message": "OK",\
> &#x20;   "timestamp": "2026-02-04T11:13:07Z"\
> }\
> \
> &#x20;\`\`\`

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/machines/{id}/available-machine-types":{"get":{"summary":"Get Available Machine Performances","responses":{"200":{"description":"List of available machine types","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailableMachineTypesResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"Machine not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Machines"],"description":"Lists all available machine types for a specific machine based on its plan.\n\nMachine types define the hardware specifications (CPU, RAM, GPU) that can be used for the machine.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### Path Parameters\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `id` | Integer | Machine ID |\n\n### Response Fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `machine_types` | Array | Array of available machine type objects |\n| `machine_types[].id` | String | Machine type ID (use this in machine_type_id parameter) |\n| `machine_types[].type` | String | Always \"machine_type\" |\n| `machine_types[].attributes.name` | String | Internal machine type name (e.g., \"g4dn.xlarge\") |\n| `machine_types[].attributes.friendly_name` | String | Human-readable machine type name (e.g., \"Planet\", \"Spark\") |\n| `machine_types[].attributes.cpu` | Integer | Number of CPU cores |\n| `machine_types[].attributes.memory` | String | RAM size in GB (e.g., \"16.0\") |\n| `machine_types[].attributes.gpu` | Integer | Number of GPUs (0 = no GPU) |\n| `machine_types[].attributes.gpu_memory` | String | GPU memory in GB (e.g., \"16.0\") |\n| `client_code` | Integer | Response code (200 for success) |\n| `message` | String | Response message |\n| `timestamp` | String | Response timestamp (ISO 8601) |\n\n### Response Example\n\n``` json\n{\n    \"machine_types\": [\n        {\n            \"id\": \"11\",\n            \"type\": \"machine_type\",\n            \"attributes\": {\n                \"name\": \"g4dn.xlarge\",\n                \"friendly_name\": \"Planet\",\n                \"cpu\": 4,\n                \"memory\": \"16.0\",\n                \"gpu\": 1,\n                \"gpu_memory\": \"16.0\"\n            }\n        },\n        {\n            \"id\": \"15\",\n            \"type\": \"machine_type\",\n            \"attributes\": {\n                \"name\": \"g5.xlarge\",\n                \"friendly_name\": \"Spark\",\n                \"cpu\": 4,\n                \"memory\": \"16.0\",\n                \"gpu\": 1,\n                \"gpu_memory\": \"24.0\"\n            }\n        }\n    ],\n    \"client_code\": 200,\n    \"message\": \"OK\",\n    \"timestamp\": \"2026-02-04T11:13:07Z\"\n}\n\n ```"}}},"components":{"schemas":{"AvailableMachineTypesResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"machine_types":{"type":"array","items":{"$ref":"#/components/schemas/MachineType"}}}}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"MachineType":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"$ref":"#/components/schemas/MachineTypeAttributes"}}},"MachineTypeAttributes":{"type":"object","properties":{"name":{"type":"string","description":"AWS instance type name"},"friendly_name":{"type":"string","description":"User-friendly machine type name"},"cpu":{"type":"integer","description":"Number of CPU cores"},"memory":{"type":"string","description":"RAM in GB"},"gpu":{"type":"integer","description":"Number of GPUs"},"gpu_memory":{"type":"string","description":"GPU memory in GB"}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````

## Set Machine Performance

> Changes the machine performance type. Allows you to change the machine's CPU, RAM, GPU, and GPU memory allocation. The machine must be stopped before changing the type.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### Path Parameters\
> \
> \| Parameter | Type | Description |\
> \| --- | --- | --- |\
> \| \`id\` | Integer | Machine ID |\
> \
> \### Body Parameters\
> \
> \| Parameter | Type | Required | Description |\
> \| --- | --- | --- | --- |\
> \| \`machine\_type\_id\` | Integer | Yes | New machine type ID. Must be one of the types available in the machine's plan. Use \`GET /machines/:id/available-machine-types\` to see available types |\
> \
> \*\*Success Response:\*\*\
> \
> \`\`\` json\
> {\
> &#x20;   "client\_code": 200,\
> &#x20;   "message": "OK",\
> &#x20;   "timestamp": "2026-02-04T11:16:28Z"\
> }\
> \
> &#x20;\`\`\`

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/machines/{id}/machine-type":{"post":{"summary":"Set Machine Performance","responses":{"200":{"description":"Machine type updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"Machine not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4205":{"description":"Machine type is not available for this seat plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4205Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Machines"],"description":"Changes the machine performance type. Allows you to change the machine's CPU, RAM, GPU, and GPU memory allocation. The machine must be stopped before changing the type.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### Path Parameters\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `id` | Integer | Machine ID |\n\n### Body Parameters\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `machine_type_id` | Integer | Yes | New machine type ID. Must be one of the types available in the machine's plan. Use `GET /machines/:id/available-machine-types` to see available types |\n\n**Success Response:**\n\n``` json\n{\n    \"client_code\": 200,\n    \"message\": \"OK\",\n    \"timestamp\": \"2026-02-04T11:16:28Z\"\n}\n\n ```","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"machine_type_id":{"type":"integer"}}}}}}}}},"components":{"schemas":{"SuccessResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4205Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````

## Stop Machine

> Stop the selected running machine.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### Path Parameters\
> \
> \| Parameter | Type | Description |\
> \| --- | --- | --- |\
> \| \`id\`\\\* | Integer | Machine ID |\
> \
> \### Body Parameters\
> \
> \| Parameter | Type | Default | Description |\
> \| --- | --- | --- | --- |\
> \| \`gracefully\` | Boolean | false | \`true\`: Sends graceful shutdown signal, and let system to save logs and recordings. Use to prevent any file interruptions.  \<br>  \<br>\`false\`: Stops machine immediately |\
> \
> \### Error Responses\
> \
> \| Status | Description |\
> \| --- | --- |\
> \| 400 | Bad request |\
> \| 404 | Machine not found |\
> \| 4204 | Machine is not running |\
> \| 4710 | Permission required |\
> \
> \### Success Response\
> \
> \`\`\` json\
> {\
> &#x20;   "client\_code": 200,\
> &#x20;   "message": "OK",\
> &#x20;   "timestamp": "2026-02-04T11:18:42Z"\
> }\
> \
> &#x20;\`\`\`

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/machines/{id}/stop":{"post":{"summary":"Stop Machine","responses":{"200":{"description":"Machine stopped successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"Machine not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4204":{"description":"Machine is not running","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4204Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Machines"],"description":"Stop the selected running machine.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### Path Parameters\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `id`\\* | Integer | Machine ID |\n\n### Body Parameters\n\n| Parameter | Type | Default | Description |\n| --- | --- | --- | --- |\n| `gracefully` | Boolean | false | `true`: Sends graceful shutdown signal, and let system to save logs and recordings. Use to prevent any file interruptions.  <br>  <br>`false`: Stops machine immediately |\n\n### Error Responses\n\n| Status | Description |\n| --- | --- |\n| 400 | Bad request |\n| 404 | Machine not found |\n| 4204 | Machine is not running |\n| 4710 | Permission required |\n\n### Success Response\n\n``` json\n{\n    \"client_code\": 200,\n    \"message\": \"OK\",\n    \"timestamp\": \"2026-02-04T11:18:42Z\"\n}\n\n ```","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"gracefully":{"type":"boolean"}}}}}}}}},"components":{"schemas":{"SuccessResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4204Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````

## Get Access Link for a Machine

> Creates a temporary access token for external access to the machine.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### Path Parameters\
> \
> \| Parameter | Type | Description |\
> \| --- | --- | --- |\
> \| \`id\` | Integer | Machine ID |\
> \
> \### Body Parameters\
> \
> \| Parameter | Type | Description |\
> \| --- | --- | --- |\
> \| \`expires\_in\`\\\* | Integer | Token validity duration in minutes. Minimum: 1 minute. Example: 60 = 1 hour, 1440 = 24 hours |\
> \
> \### Success Response\
> \
> \`\`\` json\
> {\
> &#x20;   "id": "77",\
> &#x20;   "type": "machine\_external\_access",\
> &#x20;   "attributes": {\
> &#x20;       "expires\_at": "2026-02-05T11:12:42.677Z",\
> &#x20;       "connection\_link": "<https://app.vagon.io/team/session/62ba2d60-5ee2-11aa-aa64-957da90ef117"\\>
> &#x20;   },\
> &#x20;   "client\_code": 200,\
> &#x20;   "message": "OK",\
> &#x20;   "timestamp": "2026-02-05T10:12:42Z"\
> }\
> \
> &#x20;\`\`\`\
> \
> \### Response Fields\
> \
> \| Field | Type | Description |\
> \| --- | --- | --- |\
> \| \`id\` | String | Unique identifier for the access token |\
> \| \`type\` | String | Always "machine\_external\_access" |\
> \| \`attributes.expires\_at\` | String | ISO 8601 timestamp when the token expires |\
> \| \`attributes.connection\_link\` | String | Full URL that can be shared with users to access the machine |\
> \| \`client\_code\` | Integer | Response code (200 for success) |\
> \| \`message\` | String | Response message |\
> \| \`timestamp\` | String | Response timestamp (ISO 8601) |

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/machines/{id}/access":{"post":{"summary":"Get Access Link for a Machine","responses":{"200":{"description":"Access link created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineAccessResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"Machine not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Machines"],"description":"Creates a temporary access token for external access to the machine.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### Path Parameters\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `id` | Integer | Machine ID |\n\n### Body Parameters\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `expires_in`\\* | Integer | Token validity duration in minutes. Minimum: 1 minute. Example: 60 = 1 hour, 1440 = 24 hours |\n\n### Success Response\n\n``` json\n{\n    \"id\": \"77\",\n    \"type\": \"machine_external_access\",\n    \"attributes\": {\n        \"expires_at\": \"2026-02-05T11:12:42.677Z\",\n        \"connection_link\": \"https://app.vagon.io/team/session/62ba2d60-5ee2-11aa-aa64-957da90ef117\"\n    },\n    \"client_code\": 200,\n    \"message\": \"OK\",\n    \"timestamp\": \"2026-02-05T10:12:42Z\"\n}\n\n ```\n\n### Response Fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `id` | String | Unique identifier for the access token |\n| `type` | String | Always \"machine_external_access\" |\n| `attributes.expires_at` | String | ISO 8601 timestamp when the token expires |\n| `attributes.connection_link` | String | Full URL that can be shared with users to access the machine |\n| `client_code` | Integer | Response code (200 for success) |\n| `message` | String | Response message |\n| `timestamp` | String | Response timestamp (ISO 8601) |","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"expires_in":{"type":"integer"}}}}}}}}},"components":{"schemas":{"MachineAccessResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"$ref":"#/components/schemas/MachineAccessAttributes"}}}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"MachineAccessAttributes":{"type":"object","description":"Machine external access token attributes","properties":{"expires_at":{"type":"string","format":"date-time","description":"Token expiration timestamp"},"connection_link":{"type":"string","format":"uri","description":"URL to access the machine session"}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````

## Reset Machine to Initial State

> Resets all files and data inside the computer, and revert it to the initial machine image state. This action is irreversible. All data on the machine will be permanently deleted.\
> \
> \### Task Behavior on Reset\
> \
> All non-default tasks are deleted and their Desktop source folders (\`C:\Users\Administrator\Desktop\\{uid}\`) are removed from the machine on the next boot. The default "Outputs" task is preserved and set as active. Task names that were removed by the reset become reusable.\
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### Path Parameters\
> \
> \| Parameter | Type | Description |\
> \| --- | --- | --- |\
> \| \`id\`\\\* | Integer | Machine ID |\
> \
> \### Body Parameters\
> \
> \| Parameter | Type | Required | Description |\
> \| --- | --- | --- | --- |\
> \| \`remove\_files\` | Boolean | No | When \`true\`, the VagonFiles folder (computer files) is also wiped as part of the reset. When \`false\` (default), VagonFiles are preserved. |\
> \
> \### Success Response\
> \
> \`\`\` json\
> {\
> &#x20;   "client\_code": 200,\
> &#x20;   "message": "OK",\
> &#x20;   "timestamp": "2026-02-04T11:31:12Z"\
> }\
> \
> &#x20;\`\`\`\
> \
> \### Error Responses\
> \
> \| Status | Description |\
> \| --- | --- |\
> \| 400 | Bad request |\
> \| 404 | Machine not found |\
> \| 4206 | Machine is running |\
> \| 4710 | Permission required |

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/machines/{id}/reset":{"post":{"summary":"Reset Machine to Initial State","responses":{"200":{"description":"Machine reset successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"Machine not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4206":{"description":"Machine is running","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4206Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Machines"],"description":"Resets all files and data inside the computer, and revert it to the initial machine image state. This action is irreversible. All data on the machine will be permanently deleted.\n\n### Task Behavior on Reset\n\nAll non-default tasks are deleted and their Desktop source folders (`C:\\Users\\Administrator\\Desktop\\{uid}`) are removed from the machine on the next boot. The default \"Outputs\" task is preserved and set as active. Task names that were removed by the reset become reusable.\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### Path Parameters\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `id`\\* | Integer | Machine ID |\n\n### Body Parameters\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `remove_files` | Boolean | No | When `true`, the VagonFiles folder (computer files) is also wiped as part of the reset. When `false` (default), VagonFiles are preserved. |\n\n### Success Response\n\n``` json\n{\n    \"client_code\": 200,\n    \"message\": \"OK\",\n    \"timestamp\": \"2026-02-04T11:31:12Z\"\n}\n\n ```\n\n### Error Responses\n\n| Status | Description |\n| --- | --- |\n| 400 | Bad request |\n| 404 | Machine not found |\n| 4206 | Machine is running |\n| 4710 | Permission required |","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"remove_files":{"type":"boolean","default":false,"description":"When `true`, the VagonFiles folder (computer files) is also wiped as part of the reset. When `false` (default), VagonFiles are preserved."}}}}}}}}},"components":{"schemas":{"SuccessResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4206Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````

## Manage Permissions

> Updates permissions for a specific machine.\
> \
> This endpoint allows you to modify permission settings for a machine's seat. Only permission fields available in the external API can be updated.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### Path Parameters\
> \
> \| Parameter | Type | Description |\
> \| --- | --- | --- |\
> \| \`id\`\\\* | Integer | Machine ID |\
> \
> \### Body Parameters\
> \
> \| Parameter | Type | Required | Description |\
> \| --- | --- | --- | --- |\
> \| \`permissions\`\\\* | Object | Yes | Dictionary of permission field names to boolean values |\
> \| \`permissions.public\_internet\_access\` | Boolean | No | Whether machine has internet access |\
> \| \`permissions.can\_download\_from\_vagon\_workstation\` | Boolean | No | Whether files can be downloaded from the Vagon Computer |\
> \| \`permissions.can\_upload\_to\_workstation\` | Boolean | No | Whether team members are allowed to upload files to the Vagon Computer |\
> \| \`permissions.analytics\_collection\_enabled\` | Boolean | No | Whether analytics collection is enabled |\
> \| \`permissions.clipboard\_enabled\` | Boolean | No | Whether clipboard sharing is enabled |\
> \| \`permissions.screen\_recording\_enabled\` | Boolean | No | Whether screen recording is enabled |\
> \| \`permissions.input\_recording\_enabled\` | Boolean | No | Whether input recording is enabled |\
> \
> \### Request Body\
> \
> \`\`\` json\
> {\
> &#x20; "permissions": {\
> &#x20;   "public\_internet\_access": true,\
> &#x20;   "can\_download\_from\_vagon\_workstation": true,\
> &#x20;   "can\_upload\_to\_workstation": true,\
> &#x20;   "analytics\_collection\_enabled": false,\
> &#x20;   "clipboard\_enabled": true,\
> &#x20;   "screen\_recording\_enabled": false,\
> &#x20;   "input\_recording\_enabled": false\
> &#x20; }\
> }\
> \
> &#x20;\`\`\`\
> \
> \### Success Response\
> \
> \`\`\` json\
> {\
> &#x20;   "client\_code": 200,\
> &#x20;   "message": "OK",\
> &#x20;   "timestamp": "2026-02-04T11:41:34Z"\
> }\
> \
> &#x20;\`\`\`\
> \
> \### Error Responses\
> \
> \| Status | Description |\
> \| --- | --- |\
> \| 400 | Bad request (invalid permissions) |\
> \| 404 | Machine not found |\
> \| 4710 | Permission required |\
> \
> \### Notes\
> \
> \- Only permission fields available in the external API can be updated\
> \- Use \`GET /machines/permission-fields\` to see available permission fields\
> \- Permission changes are logged in user action logs

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/machines/{id}/permissions":{"post":{"summary":"Manage Permissions","responses":{"200":{"description":"Permissions updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"Machine not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Machines"],"description":"Updates permissions for a specific machine.\n\nThis endpoint allows you to modify permission settings for a machine's seat. Only permission fields available in the external API can be updated.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### Path Parameters\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `id`\\* | Integer | Machine ID |\n\n### Body Parameters\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `permissions`\\* | Object | Yes | Dictionary of permission field names to boolean values |\n| `permissions.public_internet_access` | Boolean | No | Whether machine has internet access |\n| `permissions.can_download_from_vagon_workstation` | Boolean | No | Whether files can be downloaded from the Vagon Computer |\n| `permissions.can_upload_to_workstation` | Boolean | No | Whether team members are allowed to upload files to the Vagon Computer |\n| `permissions.analytics_collection_enabled` | Boolean | No | Whether analytics collection is enabled |\n| `permissions.clipboard_enabled` | Boolean | No | Whether clipboard sharing is enabled |\n| `permissions.screen_recording_enabled` | Boolean | No | Whether screen recording is enabled |\n| `permissions.input_recording_enabled` | Boolean | No | Whether input recording is enabled |\n\n### Request Body\n\n``` json\n{\n  \"permissions\": {\n    \"public_internet_access\": true,\n    \"can_download_from_vagon_workstation\": true,\n    \"can_upload_to_workstation\": true,\n    \"analytics_collection_enabled\": false,\n    \"clipboard_enabled\": true,\n    \"screen_recording_enabled\": false,\n    \"input_recording_enabled\": false\n  }\n}\n\n ```\n\n### Success Response\n\n``` json\n{\n    \"client_code\": 200,\n    \"message\": \"OK\",\n    \"timestamp\": \"2026-02-04T11:41:34Z\"\n}\n\n ```\n\n### Error Responses\n\n| Status | Description |\n| --- | --- |\n| 400 | Bad request (invalid permissions) |\n| 404 | Machine not found |\n| 4710 | Permission required |\n\n### Notes\n\n- Only permission fields available in the external API can be updated\n- Use `GET /machines/permission-fields` to see available permission fields\n- Permission changes are logged in user action logs","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["permissions"],"properties":{"permissions":{"type":"object","description":"Permission settings to update","properties":{"public_internet_access":{"type":"boolean","description":"Allow public internet access"},"can_download_from_vagon_workstation":{"type":"boolean","description":"Allow file downloads from workstation"},"can_upload_to_workstation":{"type":"boolean","description":"Allow file uploads to the Vagon workstation"},"analytics_collection_enabled":{"type":"boolean","description":"Enable analytics collection"},"clipboard_enabled":{"type":"boolean","description":"Enable clipboard sharing"},"screen_recording_enabled":{"type":"boolean","description":"Enable screen recording"},"input_recording_enabled":{"type":"boolean","description":"Enable input recording"}}}}}}}}}}},"components":{"schemas":{"SuccessResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````

## Run Remote Script

> Runs a script on a machine and returns its output. The interpreter depends on the machine OS: \*\*Windows\*\* machines run the script via \*\*PowerShell\*\*, \*\*Linux\*\* machines run it as a \*\*bash\*\* script.\
> \
> The script in \`script\_body\` is executed on the machine via the workstation agent. The request waits up to \*\*5 seconds\*\* for the agent to respond. If the agent responds in time, its output is returned in \`result\`. If the call times out (or otherwise fails), \`result\` is an empty string \`""\`.\
> \
> The machine must have been launched at least once (it must have a cloud instance id); otherwise the request returns \`400\`.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### \*\*Path Parameters\*\*\
> \
> \| Parameter | Type | Required | Description |\
> \| --- | --- | --- | --- |\
> \| \`id\` | Integer | Yes | Machine ID |\
> \
> \### \*\*Body Parameters\*\*\
> \
> \| Parameter | Type | Required | Description |\
> \| --- | --- | --- | --- |\
> \| \`script\_body\` | String | Yes | The script to execute on the machine: PowerShell on Windows machines, bash on Linux machines |\
> \
> \### \*\*Error Responses\*\*\
> \
> \| Status | Description |\
> \| --- | --- |\
> \| 400 | Bad request (e.g., missing \`script\_body\` or machine has never been launched) |\
> \| 404 | Machine not found or does not belong to organization |\
> \| 4710 | Permission required |\
> \
> \### \*\*Response Fields\*\*\
> \
> \| Field | Type | Description |\
> \| --- | --- | --- |\
> \| \`result\` | String | The script output, or \`""\` if the call timed out |\
> \| \`client\_code\` | Integer | Response code (200 for success) |\
> \| \`message\` | String | Response message |\
> \| \`timestamp\` | String | Response timestamp (ISO 8601) |\
> \
> \### \*\*Request Body Example (single line)\*\*\
> \
> \`\`\` json\
> {\
> &#x20; "script\_body": "Write-Output \\"PowerShell script is working!\\""\
> }\
> \
> &#x20;\`\`\`\
> \
> \### \*\*Request Body Example (multi line)\*\*\
> \
> Multi-line scripts are sent as a single JSON string with each line separated by an escaped newline (\`\n\`):\
> \
> \`\`\` json\
> {\
> &#x20; "script\_body": "Write-Output \\"OS            : $((Get-CimInstance Win32\_OperatingSystem).Caption)\\"\nWrite-Output \\"PS Version    : $($PSVersionTable.PSVersion)\\"\nWrite-Output \\"Timestamp     : $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')\\""\
> }\
> \
> &#x20;\`\`\`\
> \
> \
> The \`script\_body\` above corresponds to the following PowerShell:\
> \
> \`\`\` powershell\
> Write-Output "OS            : $((Get-CimInstance Win32\_OperatingSystem).Caption)" Write-Output "PS Version    : $($PSVersionTable.PSVersion)" Write-Output "Timestamp     : $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')"\
> \
> &#x20;\`\`\`\
> \
> \
> \### \*\*Request Body Example (Linux / bash)\*\*\
> \
> On Linux machines \`script\_body\` is a bash script:\
> \
> \`\`\` json\
> {\
> &#x20; "script\_body": "echo \\"OS        : $(uname -a)\\"\necho \\"Timestamp : $(date '+%Y-%m-%d %H:%M:%S')\\""\
> }\
> \
> &#x20;\`\`\`\
> \
> \
> ...which corresponds to the following bash:\
> \
> \`\`\` bash\
> echo "OS        : $(uname -a)" echo "Timestamp : $(date '+%Y-%m-%d %H:%M:%S')"\
> \
> &#x20;\`\`\`\
> \
> \### \*\*Response Example\*\*\
> \
> \`\`\` json\
> {\
> &#x20;   "result": "PowerShell script is working!",\
> &#x20;   "client\_code": 200,\
> &#x20;   "message": "OK",\
> &#x20;   "timestamp": "2026-02-04T11:55:10Z"\
> }\
> \
> &#x20;\`\`\`

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/machines/{id}/run-script":{"post":{"summary":"Run Remote Script","responses":{"200":{"description":"Script execution result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunScriptResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"Machine not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Machines"],"description":"Runs a script on a machine and returns its output. The interpreter depends on the machine OS: **Windows** machines run the script via **PowerShell**, **Linux** machines run it as a **bash** script.\n\nThe script in `script_body` is executed on the machine via the workstation agent. The request waits up to **5 seconds** for the agent to respond. If the agent responds in time, its output is returned in `result`. If the call times out (or otherwise fails), `result` is an empty string `\"\"`.\n\nThe machine must have been launched at least once (it must have a cloud instance id); otherwise the request returns `400`.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### **Path Parameters**\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `id` | Integer | Yes | Machine ID |\n\n### **Body Parameters**\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `script_body` | String | Yes | The script to execute on the machine: PowerShell on Windows machines, bash on Linux machines |\n\n### **Error Responses**\n\n| Status | Description |\n| --- | --- |\n| 400 | Bad request (e.g., missing `script_body` or machine has never been launched) |\n| 404 | Machine not found or does not belong to organization |\n| 4710 | Permission required |\n\n### **Response Fields**\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `result` | String | The script output, or `\"\"` if the call timed out |\n| `client_code` | Integer | Response code (200 for success) |\n| `message` | String | Response message |\n| `timestamp` | String | Response timestamp (ISO 8601) |\n\n### **Request Body Example (single line)**\n\n``` json\n{\n  \"script_body\": \"Write-Output \\\"PowerShell script is working!\\\"\"\n}\n\n ```\n\n### **Request Body Example (multi line)**\n\nMulti-line scripts are sent as a single JSON string with each line separated by an escaped newline (`\\n`):\n\n``` json\n{\n  \"script_body\": \"Write-Output \\\"OS            : $((Get-CimInstance Win32_OperatingSystem).Caption)\\\"\\nWrite-Output \\\"PS Version    : $($PSVersionTable.PSVersion)\\\"\\nWrite-Output \\\"Timestamp     : $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')\\\"\"\n}\n\n ```\n\n\nThe `script_body` above corresponds to the following PowerShell:\n\n``` powershell\nWrite-Output \"OS            : $((Get-CimInstance Win32_OperatingSystem).Caption)\" Write-Output \"PS Version    : $($PSVersionTable.PSVersion)\" Write-Output \"Timestamp     : $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')\"\n\n ```\n\n\n### **Request Body Example (Linux / bash)**\n\nOn Linux machines `script_body` is a bash script:\n\n``` json\n{\n  \"script_body\": \"echo \\\"OS        : $(uname -a)\\\"\\necho \\\"Timestamp : $(date '+%Y-%m-%d %H:%M:%S')\\\"\"\n}\n\n ```\n\n\n...which corresponds to the following bash:\n\n``` bash\necho \"OS        : $(uname -a)\" echo \"Timestamp : $(date '+%Y-%m-%d %H:%M:%S')\"\n\n ```\n\n### **Response Example**\n\n``` json\n{\n    \"result\": \"PowerShell script is working!\",\n    \"client_code\": 200,\n    \"message\": \"OK\",\n    \"timestamp\": \"2026-02-04T11:55:10Z\"\n}\n\n ```","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["script_body"],"properties":{"script_body":{"type":"string","description":"The script to execute on the machine: PowerShell on Windows machines, bash on Linux machines"}}}}}}}}},"components":{"schemas":{"RunScriptResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"result":{"type":"string","description":"The script output, or an empty string if the call timed out"}}}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````

## Bulk Create & Assign Computers

> Bulk-creates and assigns computers to users for the authenticated organization from a list of rows. Each row maps a region/area, an optional template, optional applications to pre-install, and an optional disk size to a user (by \`email\`). \`email\` is \*\*optional\*\*: a row sent without an email creates the computer \*\*unassigned\*\* — no user and no invitation — so you can pre-provision computers and assign them to people later.\
> \
> \> \*\*Availability\*\* > > This endpoint is available upon request for selected customers. Please > contact Vagon to enable bulk computer creation for your organization.\
> \
> The computer plan is the supplied \`plan\_id\`; when omitted, the organization's configured default computer plan is used. \`4706\` is returned \*\*only\*\* when neither is configured. If a plan id \*is\* resolved but does not exist for the organization, the request returns \`4202\` — resolved plans must belong to the organization (or be a global plan).\
> \
> Set \`dry\_run\` to \`true\` to preview the outcome without making any changes (no computers are assigned, no invitations are created). The response shape is identical for dry runs and real runs.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### \*\*Body Parameters\*\*\
> \
> \| Parameter | Type | Required | Description |\
> \| --- | --- | --- | --- |\
> \| \`rows\` | Array | Yes | List of assignment rows (see Row Fields) |\
> \| \`plan\_id\` | Integer | No | Computer plan to assign. Falls back to the organization's configured default computer plan when omitted |\
> \| \`dry\_run\` | Boolean | No | When \`true\`, preview only — no changes are persisted. Defaults to \`false\` |\
> \
> \### \*\*Row Fields\*\*\
> \
> \| Field | Type | Required | Description |\
> \| --- | --- | --- | --- |\
> \| \`email\` | String | No | Email of the user to assign the computer to. Leave blank to create the computer unassigned (no user, no invitation) |\
> \| \`os\` | String | No | Operating system for the row's computer: \`windows\` or \`linux\`. Per-row — set it on each row independently. Blank or invalid values fall back to \`windows\`. |\
> \| \`region\` | String | No | Target area. Supported values: \`europe\`, \`us\_east\`, \`us\_west\`, \`us\_central\`, \`canada\`, \`south\_america\`, \`south\_africa\`, \`australia\`, \`south\_asia\`, \`east\_asia\`, \`south\_east\_asia\`. Unknown values are rejected — see Per-row validation below |\
> \| \`template\_name\` | String | No | Name of the template (silver image) to assign. Available values can be collected from \[Get Images]\(<https://docs.vagon.io/teams/reference/images#get-images>) |\
> \| \`applications\` | Array | No | Application names to pre-install. Send values as an array of software names. Available values can be collected from \[Get Software]\(<https://docs.vagon.io/teams/reference/software#get-software>) |\
> \| \`disk\_size\` | String | No | Optional per-computer disk size override in GB. Supported values: \`125\`, \`175\`, \`225\`, \`275\`, \`325\`, \`375\`, \`425\`, \`475\`, \`525\`. Blank, zero, or non-positive values are ignored — the computer keeps its plan default. |\
> \
> \### \*\*Per-row validation\*\*\
> \
> Rows are validated independently — an invalid row is reported with an \`error\` message in its result entry and is \*\*not\*\* assigned (no invitation or computer is created for it), while valid rows in the same request are still processed. The validation applies in both \`dry\_run\` and execute modes, so a preview surfaces every error before you commit.\
> \
> \| Condition | \`error\` message |\
> \| --- | --- |\
> \| \`region\` is not one of the supported area values | \`Arbitrary region values aren't allowed.\` |\
> \| \`email\` already belongs to a team — member of this or another org, or has a pending invitation here or elsewhere | \`User is already on a team.\` |\
> \| The resolved template is larger than the computer's disk (override or plan default) | \`Template size cannot exceed disk storage.\` |\
> \
> \### \*\*Error Responses\*\*\
> \
> \| Status | Description |\
> \| --- | --- |\
> \| 4632 | Bulk computer creation is not enabled for this team |\
> \| 4706 | No \`plan\_id\` supplied \*\*and\*\* no default computer plan configured |\
> \| 4202 | Invalid parameters, or the resolved computer plan does not exist for the organization |\
> \| 400 | Bad request (e.g. missing \`rows\`) |\
> \| 4710 | Permission required |\
> \
> \### \*\*Response Fields\*\*\
> \
> \| Field | Type | Description |\
> \| --- | --- | --- |\
> \| \`results\` | Object | Per-row outcome of the assignment. Keyed by row email — rows without an email use a synthetic \`(no email #N)\` key; each value carries \`invitation\`, \`machine\_id\`, \`disk\_size\`, \`os\`, and \`template\`. A rejected row carries an \`error\` string instead (see Per-row validation) |\
> \| \`summary\` | Object | Aggregate counts: \`total\` (rows processed), \`invalid\` (rows rejected by per-row validation), and \`assigned\` (computers assigned) |\
> \
> \### \*\*Request Body Example\*\*\
> \
> \`\`\` json\
> {\
> &#x20; "plan\_id": 42,\
> &#x20; "dry\_run": true,\
> &#x20; "rows": \[\
> &#x20;   {\
> &#x20;     "email": "<user@example.com>",\
> &#x20;     "region": "europe",\
> &#x20;     "template\_name": "Design Template",\
> &#x20;     "disk\_size": "275",\
> &#x20;     "applications": \[\
> &#x20;       "Blender",\
> &#x20;       "Maya"\
> &#x20;     ]\
> &#x20;   },\
> &#x20;   {\
> &#x20;     "email": "<taken@example.com>",\
> &#x20;     "region": "europe"\
> &#x20;   },\
> &#x20;   {\
> &#x20;     "region": "europe",\
> &#x20;     "template\_name": "Design Template"\
> &#x20;   }\
> &#x20; ]\
> }\
> \
> &#x20;\`\`\`\
> \
> \### \*\*Response Example\*\*\
> \
> \`\`\` json\
> {\
> &#x20;   "results": {\
> &#x20;       "<user@example.com>": {\
> &#x20;           "invitation": "created",\
> &#x20;           "machine\_id": 8085,\
> &#x20;           "disk\_size": 275,\
> &#x20;           "template": "assigned: Design Template"\
> &#x20;       },\
> &#x20;       "<taken@example.com>": {\
> &#x20;           "invitation": "skipped (already on a team)",\
> &#x20;           "machine\_id": null,\
> &#x20;           "disk\_size": null,\
> &#x20;           "template": "User is already on a team.",\
> &#x20;           "error": "User is already on a team."\
> &#x20;       },\
> &#x20;       "(no email #3)": {\
> &#x20;           "invitation": "skipped (no email)",\
> &#x20;           "machine\_id": 8086,\
> &#x20;           "disk\_size": 275,\
> &#x20;           "template": "assigned: Design Template"\
> &#x20;       }\
> &#x20;   },\
> &#x20;   "summary": {\
> &#x20;       "total": 3,\
> &#x20;       "invalid": 1,\
> &#x20;       "assigned": 2\
> &#x20;   },\
> &#x20;   "client\_code": 200,\
> &#x20;   "message": "OK",\
> &#x20;   "timestamp": "2026-06-08T11:58:57Z"\
> }\
> \
> &#x20;\`\`\`

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/machines/bulk-create":{"post":{"summary":"Bulk Create & Assign Computers","responses":{"200":{"description":"Bulk computer assignment result","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","description":"Per-row outcome of the assignment. Each key is the row email; rows sent without an email are keyed with a synthetic `(no email #N)` placeholder (N is the 1-based row position). The value describes what happened for that row.","additionalProperties":{"type":"object","properties":{"invitation":{"type":"string","description":"Invitation outcome (e.g. `created`, `skipped (already member)`). Rows sent without an email report `skipped (no email)` — no user or invitation is created and the computer is left unassigned."},"machine_id":{"type":"integer","nullable":true,"description":"ID of the assigned computer; `null` when the row was not assigned"},"disk_size":{"type":"integer","nullable":true,"description":"Disk size (GB) of the assigned computer"},"os":{"type":"string","enum":["windows","linux"],"description":"Operating system applied to the row's computer. Echoes the row's `os` column; defaults to `windows` when the column is blank or invalid."},"template":{"type":"string","description":"Template/application assignment outcome (e.g. `assigned: Design Template`, `partial_assigned: Blender, Maya`)"},"error":{"type":"string","description":"Present only on invalid rows; the reason the row was not assigned"}}}},"summary":{"type":"object","description":"Aggregate counts of the assignment run","properties":{"total":{"type":"integer","description":"Total number of rows processed"},"invalid":{"type":"integer","description":"Number of rows rejected by per-row validation"},"assigned":{"type":"integer","description":"Number of computers assigned"}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Machines"],"description":"Bulk-creates and assigns computers to users for the authenticated organization from a list of rows. Each row maps a region/area, an optional template, optional applications to pre-install, and an optional disk size to a user (by `email`). `email` is **optional**: a row sent without an email creates the computer **unassigned** — no user and no invitation — so you can pre-provision computers and assign them to people later.\n\n> **Availability** > > This endpoint is available upon request for selected customers. Please > contact Vagon to enable bulk computer creation for your organization.\n\nThe computer plan is the supplied `plan_id`; when omitted, the organization's configured default computer plan is used. `4706` is returned **only** when neither is configured. If a plan id *is* resolved but does not exist for the organization, the request returns `4202` — resolved plans must belong to the organization (or be a global plan).\n\nSet `dry_run` to `true` to preview the outcome without making any changes (no computers are assigned, no invitations are created). The response shape is identical for dry runs and real runs.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### **Body Parameters**\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `rows` | Array | Yes | List of assignment rows (see Row Fields) |\n| `plan_id` | Integer | No | Computer plan to assign. Falls back to the organization's configured default computer plan when omitted |\n| `dry_run` | Boolean | No | When `true`, preview only — no changes are persisted. Defaults to `false` |\n\n### **Row Fields**\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `email` | String | No | Email of the user to assign the computer to. Leave blank to create the computer unassigned (no user, no invitation) |\n| `os` | String | No | Operating system for the row's computer: `windows` or `linux`. Per-row — set it on each row independently. Blank or invalid values fall back to `windows`. |\n| `region` | String | No | Target area. Supported values: `europe`, `us_east`, `us_west`, `us_central`, `canada`, `south_america`, `south_africa`, `australia`, `south_asia`, `east_asia`, `south_east_asia`. Unknown values are rejected — see Per-row validation below |\n| `template_name` | String | No | Name of the template (silver image) to assign. Available values can be collected from [Get Images](https://docs.vagon.io/teams/reference/images#get-images) |\n| `applications` | Array | No | Application names to pre-install. Send values as an array of software names. Available values can be collected from [Get Software](https://docs.vagon.io/teams/reference/software#get-software) |\n| `disk_size` | String | No | Optional per-computer disk size override in GB. Supported values: `125`, `175`, `225`, `275`, `325`, `375`, `425`, `475`, `525`. Blank, zero, or non-positive values are ignored — the computer keeps its plan default. |\n\n### **Per-row validation**\n\nRows are validated independently — an invalid row is reported with an `error` message in its result entry and is **not** assigned (no invitation or computer is created for it), while valid rows in the same request are still processed. The validation applies in both `dry_run` and execute modes, so a preview surfaces every error before you commit.\n\n| Condition | `error` message |\n| --- | --- |\n| `region` is not one of the supported area values | `Arbitrary region values aren't allowed.` |\n| `email` already belongs to a team — member of this or another org, or has a pending invitation here or elsewhere | `User is already on a team.` |\n| The resolved template is larger than the computer's disk (override or plan default) | `Template size cannot exceed disk storage.` |\n\n### **Error Responses**\n\n| Status | Description |\n| --- | --- |\n| 4632 | Bulk computer creation is not enabled for this team |\n| 4706 | No `plan_id` supplied **and** no default computer plan configured |\n| 4202 | Invalid parameters, or the resolved computer plan does not exist for the organization |\n| 400 | Bad request (e.g. missing `rows`) |\n| 4710 | Permission required |\n\n### **Response Fields**\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `results` | Object | Per-row outcome of the assignment. Keyed by row email — rows without an email use a synthetic `(no email #N)` key; each value carries `invitation`, `machine_id`, `disk_size`, `os`, and `template`. A rejected row carries an `error` string instead (see Per-row validation) |\n| `summary` | Object | Aggregate counts: `total` (rows processed), `invalid` (rows rejected by per-row validation), and `assigned` (computers assigned) |\n\n### **Request Body Example**\n\n``` json\n{\n  \"plan_id\": 42,\n  \"dry_run\": true,\n  \"rows\": [\n    {\n      \"email\": \"user@example.com\",\n      \"region\": \"europe\",\n      \"template_name\": \"Design Template\",\n      \"disk_size\": \"275\",\n      \"applications\": [\n        \"Blender\",\n        \"Maya\"\n      ]\n    },\n    {\n      \"email\": \"taken@example.com\",\n      \"region\": \"europe\"\n    },\n    {\n      \"region\": \"europe\",\n      \"template_name\": \"Design Template\"\n    }\n  ]\n}\n\n ```\n\n### **Response Example**\n\n``` json\n{\n    \"results\": {\n        \"user@example.com\": {\n            \"invitation\": \"created\",\n            \"machine_id\": 8085,\n            \"disk_size\": 275,\n            \"template\": \"assigned: Design Template\"\n        },\n        \"taken@example.com\": {\n            \"invitation\": \"skipped (already on a team)\",\n            \"machine_id\": null,\n            \"disk_size\": null,\n            \"template\": \"User is already on a team.\",\n            \"error\": \"User is already on a team.\"\n        },\n        \"(no email #3)\": {\n            \"invitation\": \"skipped (no email)\",\n            \"machine_id\": 8086,\n            \"disk_size\": 275,\n            \"template\": \"assigned: Design Template\"\n        }\n    },\n    \"summary\": {\n        \"total\": 3,\n        \"invalid\": 1,\n        \"assigned\": 2\n    },\n    \"client_code\": 200,\n    \"message\": \"OK\",\n    \"timestamp\": \"2026-06-08T11:58:57Z\"\n}\n\n ```","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["rows"],"properties":{"plan_id":{"type":"integer","description":"Computer plan to assign; falls back to the org default when omitted"},"dry_run":{"type":"boolean","description":"When true, preview only — no changes are persisted"},"rows":{"type":"array","description":"List of assignment rows","items":{"type":"object","properties":{"email":{"type":"string","description":"Email of the user to assign the computer to. Optional — omit or leave blank to create the computer unassigned (no user, no invitation)."},"region":{"type":"string","enum":["europe","us_east","us_west","us_central","canada","south_america","south_africa","australia","south_asia","east_asia","south_east_asia"],"description":"Area value. Unknown values are rejected"},"template_name":{"type":"string","description":"Template name. Available values can be collected from https://docs.vagon.io/teams/reference/images#get-images"},"applications":{"type":"array","description":"Application names. Available values can be collected from https://docs.vagon.io/teams/reference/software#get-software","items":{"type":"string"}},"disk_size":{"type":"string","enum":["125","175","225","275","325","375","425","475","525"],"description":"Optional per-computer disk size override in GB. Blank, zero, or non-positive values are ignored."}}}}}}}}}}}},"components":{"schemas":{"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````

## Get Machine Sessions

> Retrieves all sessions for a specific machine. Sessions are ordered by start time in descending order, most recent first.\
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### Path Parameters\
> \
> \| Parameter | Type | Description |\
> \| --- | --- | --- |\
> \| \`id\` | Integer | Machine ID |\
> \
> \### Response Fields\
> \
> \| Field | Type | Description |\
> \| --- | --- | --- |\
> \| \`sessions\` | Array | Array of session objects |\
> \| \`sessions\[].id\` | String | Session ID |\
> \| \`sessions\[].type\` | String | Always "machine\_session" |\
> \| \`sessions\[].attributes.start\_at\` | String | Session start time (ISO 8601 format) |\
> \| \`sessions\[].attributes.end\_at\` | String | Session end time (ISO 8601 format). null if still active |\
> \| \`sessions\[].attributes.duration\` | Integer | Session duration in minutes |\
> \| \`client\_code\` | Integer | Response code (200 for success) |\
> \| \`message\` | String | Response message |\
> \| \`timestamp\` | String | Response timestamp (ISO 8601) |\
> \
> \### Response Example\
> \
> \`\`\` json\
> {\
> &#x20;   "sessions": \[\
> &#x20;       {\
> &#x20;           "id": "2000",\
> &#x20;           "type": "machine\_session",\
> &#x20;           "attributes": {\
> &#x20;               "start\_at": "2026-01-23T11:02:41.902Z",\
> &#x20;               "end\_at": "2026-01-23T11:07:51.115Z",\
> &#x20;               "duration": 6\
> &#x20;           }\
> &#x20;       },\
> &#x20;       {\
> &#x20;           "id": "1999",\
> &#x20;           "type": "machine\_session",\
> &#x20;           "attributes": {\
> &#x20;               "start\_at": "2026-01-21T22:57:57.450Z",\
> &#x20;               "end\_at": "2026-01-21T22:59:58.408Z",\
> &#x20;               "duration": 3\
> &#x20;           }\
> &#x20;       }\
> &#x20;   ],\
> &#x20;   "client\_code": 200,\
> &#x20;   "message": "OK",\
> &#x20;   "timestamp": "2026-02-04T11:55:58Z"\
> }\
> \
> &#x20;\`\`\`

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/machines/{id}/sessions":{"get":{"summary":"Get Machine Sessions","responses":{"200":{"description":"List of machine sessions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineSessionsResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"Machine not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Machines"],"description":"Retrieves all sessions for a specific machine. Sessions are ordered by start time in descending order, most recent first.\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### Path Parameters\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `id` | Integer | Machine ID |\n\n### Response Fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `sessions` | Array | Array of session objects |\n| `sessions[].id` | String | Session ID |\n| `sessions[].type` | String | Always \"machine_session\" |\n| `sessions[].attributes.start_at` | String | Session start time (ISO 8601 format) |\n| `sessions[].attributes.end_at` | String | Session end time (ISO 8601 format). null if still active |\n| `sessions[].attributes.duration` | Integer | Session duration in minutes |\n| `client_code` | Integer | Response code (200 for success) |\n| `message` | String | Response message |\n| `timestamp` | String | Response timestamp (ISO 8601) |\n\n### Response Example\n\n``` json\n{\n    \"sessions\": [\n        {\n            \"id\": \"2000\",\n            \"type\": \"machine_session\",\n            \"attributes\": {\n                \"start_at\": \"2026-01-23T11:02:41.902Z\",\n                \"end_at\": \"2026-01-23T11:07:51.115Z\",\n                \"duration\": 6\n            }\n        },\n        {\n            \"id\": \"1999\",\n            \"type\": \"machine_session\",\n            \"attributes\": {\n                \"start_at\": \"2026-01-21T22:57:57.450Z\",\n                \"end_at\": \"2026-01-21T22:59:58.408Z\",\n                \"duration\": 3\n            }\n        }\n    ],\n    \"client_code\": 200,\n    \"message\": \"OK\",\n    \"timestamp\": \"2026-02-04T11:55:58Z\"\n}\n\n ```"}}},"components":{"schemas":{"MachineSessionsResponse":{"type":"object","properties":{"sessions":{"type":"array","items":{"$ref":"#/components/schemas/MachineSession"}},"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"MachineSession":{"type":"object","description":"Machine session record","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"$ref":"#/components/schemas/MachineSessionAttributes"}}},"MachineSessionAttributes":{"type":"object","properties":{"start_at":{"type":"string","format":"date-time","description":"Session start timestamp"},"end_at":{"type":"string","format":"date-time","nullable":true,"description":"Session end timestamp (null if session is ongoing)"},"duration":{"type":"integer","description":"Session duration in minutes (0 if session is ongoing)"}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````

## List Machine Tasks

> Returns all non-deleted tasks for the machine, ordered by \`created\_at\` descending.\
> \
> Each task maps a \`uid\` (folder name) to a specific Desktop source path and snapshot destination on the Windows machine. The currently active task determines which folder is monitored for snapshots when the machine starts.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### Path Parameters\
> \
> \| Parameter | Type | Description |\
> \| --- | --- | --- |\
> \| \`id\`\\\* | Integer | Machine ID |\
> \
> \### Query Parameters\
> \
> \| Parameter | Type | Required | Description |\
> \| --- | --- | --- | --- |\
> \| \`page\` | Integer | No | Page number (default: 1) |\
> \| \`per\_page\` | Integer | No | Results per page (default: Kaminari default) |\
> \
> \### Response Fields\
> \
> \| Field | Type | Description |\
> \| --- | --- | --- |\
> \| \`tasks\` | Array | Array of task objects |\
> \| \`tasks\[].id\` | String | Task ID |\
> \| \`tasks\[].type\` | String | Always \`"task"\` |\
> \| \`tasks\[].attributes.uid\` | String | Task identifier (Desktop folder name) |\
> \| \`tasks\[].attributes.status\` | String | \`"active"\` or \`"inactive"\` |\
> \| \`tasks\[].attributes.source\_path\` | String | Full Windows path monitored for snapshots |\
> \| \`tasks\[].attributes.snapshot\_destination\` | String | Full Windows path where snapshots are stored |\
> \| \`tasks\[].attributes.folder\_size\` | Integer or null | Cumulative size (bytes) of the task's folder, recorded when the machine last stopped. \`null\` until first recorded. |\
> \| \`tasks\[].attributes.created\_at\` | String | Task creation time (ISO 8601) |\
> \| \`count\` | Integer | Total number of tasks returned |\
> \| \`page\` | Integer | Current page number |\
> \| \`next\_page\` | Integer or null | Next page number (null if no more pages) |\
> \| \`client\_code\` | Integer | Response code (200 for success) |\
> \| \`message\` | String | Response message |\
> \
> \### Response Example\
> \
> \`\`\`json\
> {\
> &#x20; "tasks": \[\
> &#x20;   {\
> &#x20;     "id": "18",\
> &#x20;     "type": "task",\
> &#x20;     "attributes": {\
> &#x20;       "uid": "Outputs",\
> &#x20;       "created\_at": "2025-12-02T09:50:37.244Z",\
> &#x20;       "status": "active",\
> &#x20;       "source\_path": "C:\\\Users\\\Administrator\\\Desktop\\\Outputs",\
> &#x20;       "snapshot\_destination": "V:\\\Outputs",\
> &#x20;       "folder\_size": 713\
> &#x20;     }\
> &#x20;   }\
> &#x20; ],\
> &#x20; "count": 1,\
> &#x20; "page": 1,\
> &#x20; "next\_page": null,\
> &#x20; "client\_code": 200,\
> &#x20; "message": "OK",\
> &#x20; "timestamp": "2026-04-15T11:11:27Z"\
> }\
> \`\`\`

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/machines/{id}/tasks":{"get":{"summary":"List Machine Tasks","responses":{"200":{"description":"List of tasks for the machine","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListTasksResponse"}}}},"404":{"description":"Machine not found or does not belong to the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Machines"],"description":"Returns all non-deleted tasks for the machine, ordered by `created_at` descending.\n\nEach task maps a `uid` (folder name) to a specific Desktop source path and snapshot destination on the Windows machine. The currently active task determines which folder is monitored for snapshots when the machine starts.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### Path Parameters\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `id`\\* | Integer | Machine ID |\n\n### Query Parameters\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `page` | Integer | No | Page number (default: 1) |\n| `per_page` | Integer | No | Results per page (default: Kaminari default) |\n\n### Response Fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `tasks` | Array | Array of task objects |\n| `tasks[].id` | String | Task ID |\n| `tasks[].type` | String | Always `\"task\"` |\n| `tasks[].attributes.uid` | String | Task identifier (Desktop folder name) |\n| `tasks[].attributes.status` | String | `\"active\"` or `\"inactive\"` |\n| `tasks[].attributes.source_path` | String | Full Windows path monitored for snapshots |\n| `tasks[].attributes.snapshot_destination` | String | Full Windows path where snapshots are stored |\n| `tasks[].attributes.folder_size` | Integer or null | Cumulative size (bytes) of the task's folder, recorded when the machine last stopped. `null` until first recorded. |\n| `tasks[].attributes.created_at` | String | Task creation time (ISO 8601) |\n| `count` | Integer | Total number of tasks returned |\n| `page` | Integer | Current page number |\n| `next_page` | Integer or null | Next page number (null if no more pages) |\n| `client_code` | Integer | Response code (200 for success) |\n| `message` | String | Response message |\n\n### Response Example\n\n```json\n{\n  \"tasks\": [\n    {\n      \"id\": \"18\",\n      \"type\": \"task\",\n      \"attributes\": {\n        \"uid\": \"Outputs\",\n        \"created_at\": \"2025-12-02T09:50:37.244Z\",\n        \"status\": \"active\",\n        \"source_path\": \"C:\\\\Users\\\\Administrator\\\\Desktop\\\\Outputs\",\n        \"snapshot_destination\": \"V:\\\\Outputs\",\n        \"folder_size\": 713\n      }\n    }\n  ],\n  \"count\": 1,\n  \"page\": 1,\n  \"next_page\": null,\n  \"client_code\": 200,\n  \"message\": \"OK\",\n  \"timestamp\": \"2026-04-15T11:11:27Z\"\n}\n```"}}},"components":{"schemas":{"ListTasksResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"tasks":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"count":{"type":"integer","description":"Total number of tasks returned"},"page":{"type":"integer","description":"Current page number"},"next_page":{"type":"integer","nullable":true,"description":"Next page number (null if no more pages)"}}}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Task":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"$ref":"#/components/schemas/TaskAttributes"}}},"TaskAttributes":{"type":"object","properties":{"uid":{"type":"string","description":"Task identifier used as the Desktop folder name"},"status":{"type":"string","enum":["active","inactive"],"description":"Task status"},"source_path":{"type":"string","description":"Full Windows path monitored for snapshots"},"snapshot_destination":{"type":"string","description":"Full Windows path where snapshots are stored. For the default \"Outputs\" task this is `V:\\Outputs`; for all other tasks it is `V:\\{uid}-snapshots`."},"folder_size":{"type":"integer","nullable":true,"description":"Cumulative size in bytes of the task's corresponding folder, recorded when the machine last stopped gracefully. `null` until the machine stops for the first time with an active task and a matching folder."},"created_at":{"type":"string","format":"date-time","description":"Task creation time (ISO 8601)"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````

## Create or Activate Machine Task

> Creates or selects a task by UID and sets it as the active snapshot source for the seat. Any previously active task is automatically deactivated.\
> \
> The endpoint is idempotent with respect to the \`result\` field — three distinct outcomes are possible:\
> \
> \| Scenario | \`result\` |\
> \| --- | --- |\
> \| New task created | \`"created"\` |\
> \| Existing inactive task re-activated | \`"reactivated"\` |\
> \| Requested task is already active (no-op) | \`"already\_active"\` |\
> \
> \*\*UID rules:\*\* must be non-empty, at most 255 characters, and must not contain any Windows-reserved characters: \`\ / : \* ? " < > |\`\
> \
> \*\*Deleted task names cannot be reused\*\* — if a task with the given UID was previously deleted, the request returns \`4217\`. The only exception is a machine reset: task names deleted as part of a reset become available again after the reset completes.\
> \
> \*\*Backup must be enabled\*\* — the seat's backup setting must be active, otherwise returns \`4218\`.\
> \
> \*\*Machine must be \`off\`\*\* — tasks cannot be changed while the machine is running (returns \`4206\`).\
> \
> \### 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 | Required | Description |\
> \| --- | --- | --- | --- |\
> \| \`uid\`\\\* | String | Yes | Task identifier used as the Desktop folder name. Must be non-empty, ≤ 255 characters, and free of Windows-reserved characters (\`\ / : \* ? " < > |\`). |\
> \
> \### Response Fields\
> \
> \| Field | Type | Description |\
> \| --- | --- | --- |\
> \| \`task\` | Object | The created or activated task object |\
> \| \`task.id\` | String | Task ID |\
> \| \`task.type\` | String | Always \`"task"\` |\
> \| \`task.attributes.uid\` | String | Task identifier |\
> \| \`task.attributes.status\` | String | Always \`"active"\` after this call |\
> \| \`task.attributes.source\_path\` | String | Full Windows path monitored for snapshots |\
> \| \`task.attributes.snapshot\_destination\` | String | Full Windows path where snapshots are stored |\
> \| \`task.attributes.folder\_size\` | Integer or null | Cumulative size (bytes) of the task's folder. \`null\` until first recorded. |\
> \| \`task.attributes.created\_at\` | String | Task creation time (ISO 8601) |\
> \| \`result\` | String | Outcome: \`"created"\`, \`"reactivated"\`, or \`"already\_active"\` |\
> \| \`client\_code\` | Integer | Response code (200 for success) |\
> \| \`message\` | String | Response message |\
> \
> \### Response Examples\
> \
> \*\*result: "created"\*\*\
> \
> \`\`\`json\
> {\
> &#x20; "task": {\
> &#x20;   "id": "22",\
> &#x20;   "type": "task",\
> &#x20;   "attributes": {\
> &#x20;     "uid": "task-012",\
> &#x20;     "created\_at": "2026-04-15T11:16:44.534Z",\
> &#x20;     "status": "active",\
> &#x20;     "source\_path": "C:\\\Users\\\Administrator\\\Desktop\\\task-012",\
> &#x20;     "snapshot\_destination": "V:\\\task-012-snapshots",\
> &#x20;     "folder\_size": null\
> &#x20;   }\
> &#x20; },\
> &#x20; "result": "created",\
> &#x20; "client\_code": 200,\
> &#x20; "message": "OK",\
> &#x20; "timestamp": "2026-04-15T11:16:44Z"\
> }\
> \`\`\`\
> \
> \*\*result: "reactivated"\*\*\
> \
> \`\`\`json\
> {\
> &#x20; "task": {\
> &#x20;   "id": "18",\
> &#x20;   "type": "task",\
> &#x20;   "attributes": {\
> &#x20;     "uid": "Outputs",\
> &#x20;     "created\_at": "2025-12-02T09:50:37.244Z",\
> &#x20;     "status": "active",\
> &#x20;     "source\_path": "C:\\\Users\\\Administrator\\\Desktop\\\Outputs",\
> &#x20;     "snapshot\_destination": "V:\\\Outputs",\
> &#x20;     "folder\_size": 713\
> &#x20;   }\
> &#x20; },\
> &#x20; "result": "reactivated",\
> &#x20; "client\_code": 200,\
> &#x20; "message": "OK",\
> &#x20; "timestamp": "2026-04-15T11:17:20Z"\
> }\
> \`\`\`\
> \
> \*\*result: "already\_active"\*\*\
> \
> \`\`\`json\
> {\
> &#x20; "task": {\
> &#x20;   "id": "22",\
> &#x20;   "type": "task",\
> &#x20;   "attributes": {\
> &#x20;     "uid": "task-012",\
> &#x20;     "created\_at": "2026-04-15T11:16:44.534Z",\
> &#x20;     "status": "active",\
> &#x20;     "source\_path": "C:\\\Users\\\Administrator\\\Desktop\\\task-012",\
> &#x20;     "snapshot\_destination": "V:\\\task-012-snapshots",\
> &#x20;     "folder\_size": null\
> &#x20;   }\
> &#x20; },\
> &#x20; "result": "already\_active",\
> &#x20; "client\_code": 200,\
> &#x20; "message": "OK",\
> &#x20; "timestamp": "2026-04-15T11:17:03Z"\
> }\
> \`\`\`

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/machines/{id}/tasks":{"post":{"summary":"Create or Activate Machine Task","responses":{"200":{"description":"Task created, reactivated, or already active","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskActionResponse"}}}},"404":{"description":"Machine not found or does not belong to the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4206":{"description":"Machine is not off — tasks can only be modified when the machine is stopped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4206Response"}}}},"4216":{"description":"Invalid task UID (empty, exceeds 255 characters, or contains reserved characters)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4216Response"}}}},"4217":{"description":"Task UID was previously deleted and cannot be reused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4217Response"}}}},"4218":{"description":"Backup is not enabled for this seat","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4218Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Machines"],"description":"Creates or selects a task by UID and sets it as the active snapshot source for the seat. Any previously active task is automatically deactivated.\n\nThe endpoint is idempotent with respect to the `result` field — three distinct outcomes are possible:\n\n| Scenario | `result` |\n| --- | --- |\n| New task created | `\"created\"` |\n| Existing inactive task re-activated | `\"reactivated\"` |\n| Requested task is already active (no-op) | `\"already_active\"` |\n\n**UID rules:** must be non-empty, at most 255 characters, and must not contain any Windows-reserved characters: `\\ / : * ? \" < > |`\n\n**Deleted task names cannot be reused** — if a task with the given UID was previously deleted, the request returns `4217`. The only exception is a machine reset: task names deleted as part of a reset become available again after the reset completes.\n\n**Backup must be enabled** — the seat's backup setting must be active, otherwise returns `4218`.\n\n**Machine must be `off`** — tasks cannot be changed while the machine is running (returns `4206`).\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### Path Parameters\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `id`\\* | Integer | Machine ID |\n\n### Request Body\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `uid`\\* | String | Yes | Task identifier used as the Desktop folder name. Must be non-empty, ≤ 255 characters, and free of Windows-reserved characters (`\\ / : * ? \" < > |`). |\n\n### Response Fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `task` | Object | The created or activated task object |\n| `task.id` | String | Task ID |\n| `task.type` | String | Always `\"task\"` |\n| `task.attributes.uid` | String | Task identifier |\n| `task.attributes.status` | String | Always `\"active\"` after this call |\n| `task.attributes.source_path` | String | Full Windows path monitored for snapshots |\n| `task.attributes.snapshot_destination` | String | Full Windows path where snapshots are stored |\n| `task.attributes.folder_size` | Integer or null | Cumulative size (bytes) of the task's folder. `null` until first recorded. |\n| `task.attributes.created_at` | String | Task creation time (ISO 8601) |\n| `result` | String | Outcome: `\"created\"`, `\"reactivated\"`, or `\"already_active\"` |\n| `client_code` | Integer | Response code (200 for success) |\n| `message` | String | Response message |\n\n### Response Examples\n\n**result: \"created\"**\n\n```json\n{\n  \"task\": {\n    \"id\": \"22\",\n    \"type\": \"task\",\n    \"attributes\": {\n      \"uid\": \"task-012\",\n      \"created_at\": \"2026-04-15T11:16:44.534Z\",\n      \"status\": \"active\",\n      \"source_path\": \"C:\\\\Users\\\\Administrator\\\\Desktop\\\\task-012\",\n      \"snapshot_destination\": \"V:\\\\task-012-snapshots\",\n      \"folder_size\": null\n    }\n  },\n  \"result\": \"created\",\n  \"client_code\": 200,\n  \"message\": \"OK\",\n  \"timestamp\": \"2026-04-15T11:16:44Z\"\n}\n```\n\n**result: \"reactivated\"**\n\n```json\n{\n  \"task\": {\n    \"id\": \"18\",\n    \"type\": \"task\",\n    \"attributes\": {\n      \"uid\": \"Outputs\",\n      \"created_at\": \"2025-12-02T09:50:37.244Z\",\n      \"status\": \"active\",\n      \"source_path\": \"C:\\\\Users\\\\Administrator\\\\Desktop\\\\Outputs\",\n      \"snapshot_destination\": \"V:\\\\Outputs\",\n      \"folder_size\": 713\n    }\n  },\n  \"result\": \"reactivated\",\n  \"client_code\": 200,\n  \"message\": \"OK\",\n  \"timestamp\": \"2026-04-15T11:17:20Z\"\n}\n```\n\n**result: \"already_active\"**\n\n```json\n{\n  \"task\": {\n    \"id\": \"22\",\n    \"type\": \"task\",\n    \"attributes\": {\n      \"uid\": \"task-012\",\n      \"created_at\": \"2026-04-15T11:16:44.534Z\",\n      \"status\": \"active\",\n      \"source_path\": \"C:\\\\Users\\\\Administrator\\\\Desktop\\\\task-012\",\n      \"snapshot_destination\": \"V:\\\\task-012-snapshots\",\n      \"folder_size\": null\n    }\n  },\n  \"result\": \"already_active\",\n  \"client_code\": 200,\n  \"message\": \"OK\",\n  \"timestamp\": \"2026-04-15T11:17:03Z\"\n}\n```","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["uid"],"properties":{"uid":{"type":"string","description":"Task identifier used as the Desktop folder name. Must not contain Windows-reserved characters.","maxLength":255}}}}}}}}},"components":{"schemas":{"TaskActionResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"task":{"$ref":"#/components/schemas/Task"},"result":{"type":"string","enum":["created","reactivated","already_active","deleted"],"description":"Outcome of the operation"}}}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Task":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"$ref":"#/components/schemas/TaskAttributes"}}},"TaskAttributes":{"type":"object","properties":{"uid":{"type":"string","description":"Task identifier used as the Desktop folder name"},"status":{"type":"string","enum":["active","inactive"],"description":"Task status"},"source_path":{"type":"string","description":"Full Windows path monitored for snapshots"},"snapshot_destination":{"type":"string","description":"Full Windows path where snapshots are stored. For the default \"Outputs\" task this is `V:\\Outputs`; for all other tasks it is `V:\\{uid}-snapshots`."},"folder_size":{"type":"integer","nullable":true,"description":"Cumulative size in bytes of the task's corresponding folder, recorded when the machine last stopped gracefully. `null` until the machine stops for the first time with an active task and a matching folder."},"created_at":{"type":"string","format":"date-time","description":"Task creation time (ISO 8601)"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error4206Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4216Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4217Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4218Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````

## Delete Machine Task

> Deletes a task along with its Desktop source folder and its snapshot folder in the Vagon Files drive. Deletion permanently removes the task record and its files.\
> \
> \*\*Task UID/name reuse is reset-aware.\*\* A deleted task UID cannot be reused in a future \`POST /machines/{id}/tasks\` call unless the deleted record predates the machine's last reset (\`machine.last\_reset\_at\`). In practice, after a machine reset removes all non-default tasks and their files, those task UIDs become available again.\
> \
> \*\*The default "Outputs" task cannot be deleted\*\* — attempting to delete the task with \`uid: "Outputs"\` returns \`4219\`.\
> \
> If the deleted task was active, the default "Outputs" task is automatically activated (or created) before the response is returned.\
> \
> \*\*Machine must be \`off\`\*\* — tasks cannot be changed while the machine is running (returns \`4206\`).\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### Path Parameters\
> \
> \| Parameter | Type | Description |\
> \| --- | --- | --- |\
> \| \`id\`\\\* | Integer | Machine ID |\
> \| \`task\_id\`\\\* | Integer | Task ID |\
> \
> \### Response Fields\
> \
> \| Field | Type | Description |\
> \| --- | --- | --- |\
> \| \`task\` | Object | The deleted task object |\
> \| \`task.attributes.folder\_size\` | Integer or null | Cumulative folder size (bytes) at last stop. \`null\` if never recorded. |\
> \| \`result\` | String | Always \`"deleted"\` |\
> \| \`client\_code\` | Integer | Response code (200 for success) |\
> \| \`message\` | String | Response message |\
> \
> \### Response Example\
> \
> \`\`\`json\
> {\
> &#x20; "task": {\
> &#x20;   "id": "21",\
> &#x20;   "type": "task",\
> &#x20;   "attributes": {\
> &#x20;     "uid": "task-02",\
> &#x20;     "created\_at": "2026-04-15T11:11:35.142Z",\
> &#x20;     "status": "inactive",\
> &#x20;     "source\_path": "C:\\\Users\\\Administrator\\\Desktop\\\task-02",\
> &#x20;     "snapshot\_destination": "V:\\\task-02-snapshots",\
> &#x20;     "folder\_size": null\
> &#x20;   }\
> &#x20; },\
> &#x20; "result": "deleted",\
> &#x20; "client\_code": 200,\
> &#x20; "message": "OK",\
> &#x20; "timestamp": "2026-04-15T11:11:57Z"\
> }\
> \`\`\`

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/machines/{id}/tasks/{task_id}":{"delete":{"summary":"Delete Machine Task","responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskActionResponse"}}}},"404":{"description":"Task not found, already deleted, or belongs to a different seat","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4206":{"description":"Machine is not off — tasks can only be modified when the machine is stopped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4206Response"}}}},"4219":{"description":"Cannot delete the default \"Outputs\" task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4219Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Machines"],"description":"Deletes a task along with its Desktop source folder and its snapshot folder in the Vagon Files drive. Deletion permanently removes the task record and its files.\n\n**Task UID/name reuse is reset-aware.** A deleted task UID cannot be reused in a future `POST /machines/{id}/tasks` call unless the deleted record predates the machine's last reset (`machine.last_reset_at`). In practice, after a machine reset removes all non-default tasks and their files, those task UIDs become available again.\n\n**The default \"Outputs\" task cannot be deleted** — attempting to delete the task with `uid: \"Outputs\"` returns `4219`.\n\nIf the deleted task was active, the default \"Outputs\" task is automatically activated (or created) before the response is returned.\n\n**Machine must be `off`** — tasks cannot be changed while the machine is running (returns `4206`).\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### Path Parameters\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `id`\\* | Integer | Machine ID |\n| `task_id`\\* | Integer | Task ID |\n\n### Response Fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `task` | Object | The deleted task object |\n| `task.attributes.folder_size` | Integer or null | Cumulative folder size (bytes) at last stop. `null` if never recorded. |\n| `result` | String | Always `\"deleted\"` |\n| `client_code` | Integer | Response code (200 for success) |\n| `message` | String | Response message |\n\n### Response Example\n\n```json\n{\n  \"task\": {\n    \"id\": \"21\",\n    \"type\": \"task\",\n    \"attributes\": {\n      \"uid\": \"task-02\",\n      \"created_at\": \"2026-04-15T11:11:35.142Z\",\n      \"status\": \"inactive\",\n      \"source_path\": \"C:\\\\Users\\\\Administrator\\\\Desktop\\\\task-02\",\n      \"snapshot_destination\": \"V:\\\\task-02-snapshots\",\n      \"folder_size\": null\n    }\n  },\n  \"result\": \"deleted\",\n  \"client_code\": 200,\n  \"message\": \"OK\",\n  \"timestamp\": \"2026-04-15T11:11:57Z\"\n}\n```"}}},"components":{"schemas":{"TaskActionResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"task":{"$ref":"#/components/schemas/Task"},"result":{"type":"string","enum":["created","reactivated","already_active","deleted"],"description":"Outcome of the operation"}}}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Task":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"$ref":"#/components/schemas/TaskAttributes"}}},"TaskAttributes":{"type":"object","properties":{"uid":{"type":"string","description":"Task identifier used as the Desktop folder name"},"status":{"type":"string","enum":["active","inactive"],"description":"Task status"},"source_path":{"type":"string","description":"Full Windows path monitored for snapshots"},"snapshot_destination":{"type":"string","description":"Full Windows path where snapshots are stored. For the default \"Outputs\" task this is `V:\\Outputs`; for all other tasks it is `V:\\{uid}-snapshots`."},"folder_size":{"type":"integer","nullable":true,"description":"Cumulative size in bytes of the task's corresponding folder, recorded when the machine last stopped gracefully. `null` until the machine stops for the first time with an active task and a matching folder."},"created_at":{"type":"string","format":"date-time","description":"Task creation time (ISO 8601)"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error4206Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4219Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````

## Restore Machine Task Snapshot

> Rebuilds the task's \*\*latest snapshot\*\* as a browsable folder under the seat's Vagon Files root, named \`\<task uid>-restored-\<snapshot timestamp>\` (for example \`task-02-restored-20260902\_100000\`).\
> \
> Each backup cycle only copies the files that changed, but writes a \`Files.txt\` manifest listing \*\*every\*\* source file together with the cycle folder holding its newest copy. This endpoint reads the newest usable manifest and assembles the full file set from across the cycle folders. Nothing is copied in S3: every restored file references the same stored object as the snapshot file it came from.\
> \
> \*\*The restored folder is read-only.\*\* Its files and folders cannot be deleted, renamed, moved or overwritten, and nothing can be uploaded into it (every such attempt returns \`457\`). File objects inside it carry \`"virtual": true\`. The folder is removed together with its task (\`DELETE /machines/{id}/tasks/{task\_id}\`) and does not count against the seat's storage.\
> \
> \*\*Which snapshot is used.\*\* Cycle folders are tried newest first; a cycle whose manifest records a skipped backup (insufficient disk) is passed over. Files listed in the manifest whose snapshot copy no longer exists in Vagon Files are reported in \`missing\` and left out.\
> \
> \*\*Machine must be \`off\`\*\* (returns \`4206\`) and \*\*backup must be enabled\*\* for the seat (returns \`4218\`).\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### Path Parameters\
> \
> \| Parameter | Type | Description |\
> \| --- | --- | --- |\
> \| \`id\`\\\* | Integer | Machine ID |\
> \| \`task\_id\`\\\* | Integer | Task ID |\
> \
> \### Response Fields\
> \
> \| Field | Type | Description |\
> \| --- | --- | --- |\
> \| \`task\` | Object | The task object |\
> \| \`folder\` | Object | The new restored folder (file object, \`object\_type: "directory"\`, \`virtual: true\`) |\
> \| \`snapshot\` | String | Name of the cycle folder whose manifest was used (\`yyyyMMdd\_HHmmss\`, UTC) |\
> \| \`restored\_count\` | Integer | Number of files placed into the restored folder |\
> \| \`missing\` | Array of String | Relative paths listed in the manifest that could not be resolved |\
> \| \`result\` | String | Always \`"restored"\` |\
> \| \`client\_code\` | Integer | Response code (200 for success) |\
> \| \`message\` | String | Response message |\
> \
> \### Response Example\
> \
> \`\`\`json\
> {\
> &#x20; "task": {\
> &#x20;   "id": "21",\
> &#x20;   "type": "task",\
> &#x20;   "attributes": {\
> &#x20;     "uid": "task-02",\
> &#x20;     "created\_at": "2026-04-15T11:11:35.142Z",\
> &#x20;     "status": "inactive",\
> &#x20;     "source\_path": "C:\\\Users\\\Administrator\\\Desktop\\\task-02",\
> &#x20;     "snapshot\_destination": "V:\\\task-02-snapshots",\
> &#x20;     "folder\_size": 1048576\
> &#x20;   }\
> &#x20; },\
> &#x20; "folder": {\
> &#x20;   "id": "9812",\
> &#x20;   "type": "file",\
> &#x20;   "attributes": {\
> &#x20;     "name": "task-02-restored-20260902\_100000",\
> &#x20;     "object\_type": "directory",\
> &#x20;     "parent\_id": 4410,\
> &#x20;     "virtual": true\
> &#x20;   }\
> &#x20; },\
> &#x20; "snapshot": "20260902\_100000",\
> &#x20; "restored\_count": 128,\
> &#x20; "missing": \["Reports\\\old-draft.docx"],\
> &#x20; "result": "restored",\
> &#x20; "client\_code": 200,\
> &#x20; "message": "OK",\
> &#x20; "timestamp": "2026-09-28T10:00:00Z"\
> }\
> \`\`\`

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/machines/{id}/tasks/{task_id}/restore":{"post":{"summary":"Restore Machine Task Snapshot","responses":{"200":{"description":"Snapshot restored into a new read-only folder","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskRestoreResponse"}}}},"404":{"description":"Task not found, already deleted, or belongs to a different seat","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"451":{"description":"This snapshot was already restored (a folder with the restore name exists under the seat root)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error451Response"}}}},"4206":{"description":"Machine is not off — tasks can only be restored when the machine is stopped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4206Response"}}}},"4218":{"description":"Backup is not enabled for this seat","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4218Response"}}}},"4237":{"description":"No snapshot with a usable `Files.txt` manifest exists for this task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4237Response"}}}},"4238":{"description":"The manifest lists more files than can be restored in one request (20,000)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4238Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Machines"],"description":"Rebuilds the task's **latest snapshot** as a browsable folder under the seat's Vagon Files root, named `<task uid>-restored-<snapshot timestamp>` (for example `task-02-restored-20260902_100000`).\n\nEach backup cycle only copies the files that changed, but writes a `Files.txt` manifest listing **every** source file together with the cycle folder holding its newest copy. This endpoint reads the newest usable manifest and assembles the full file set from across the cycle folders. Nothing is copied in S3: every restored file references the same stored object as the snapshot file it came from.\n\n**The restored folder is read-only.** Its files and folders cannot be deleted, renamed, moved or overwritten, and nothing can be uploaded into it (every such attempt returns `457`). File objects inside it carry `\"virtual\": true`. The folder is removed together with its task (`DELETE /machines/{id}/tasks/{task_id}`) and does not count against the seat's storage.\n\n**Which snapshot is used.** Cycle folders are tried newest first; a cycle whose manifest records a skipped backup (insufficient disk) is passed over. Files listed in the manifest whose snapshot copy no longer exists in Vagon Files are reported in `missing` and left out.\n\n**Machine must be `off`** (returns `4206`) and **backup must be enabled** for the seat (returns `4218`).\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### Path Parameters\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `id`\\* | Integer | Machine ID |\n| `task_id`\\* | Integer | Task ID |\n\n### Response Fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `task` | Object | The task object |\n| `folder` | Object | The new restored folder (file object, `object_type: \"directory\"`, `virtual: true`) |\n| `snapshot` | String | Name of the cycle folder whose manifest was used (`yyyyMMdd_HHmmss`, UTC) |\n| `restored_count` | Integer | Number of files placed into the restored folder |\n| `missing` | Array of String | Relative paths listed in the manifest that could not be resolved |\n| `result` | String | Always `\"restored\"` |\n| `client_code` | Integer | Response code (200 for success) |\n| `message` | String | Response message |\n\n### Response Example\n\n```json\n{\n  \"task\": {\n    \"id\": \"21\",\n    \"type\": \"task\",\n    \"attributes\": {\n      \"uid\": \"task-02\",\n      \"created_at\": \"2026-04-15T11:11:35.142Z\",\n      \"status\": \"inactive\",\n      \"source_path\": \"C:\\\\Users\\\\Administrator\\\\Desktop\\\\task-02\",\n      \"snapshot_destination\": \"V:\\\\task-02-snapshots\",\n      \"folder_size\": 1048576\n    }\n  },\n  \"folder\": {\n    \"id\": \"9812\",\n    \"type\": \"file\",\n    \"attributes\": {\n      \"name\": \"task-02-restored-20260902_100000\",\n      \"object_type\": \"directory\",\n      \"parent_id\": 4410,\n      \"virtual\": true\n    }\n  },\n  \"snapshot\": \"20260902_100000\",\n  \"restored_count\": 128,\n  \"missing\": [\"Reports\\\\old-draft.docx\"],\n  \"result\": \"restored\",\n  \"client_code\": 200,\n  \"message\": \"OK\",\n  \"timestamp\": \"2026-09-28T10:00:00Z\"\n}\n```"}}},"components":{"schemas":{"TaskRestoreResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"task":{"$ref":"#/components/schemas/Task"},"folder":{"$ref":"#/components/schemas/FileObject"},"snapshot":{"type":"string","description":"Cycle folder (yyyyMMdd_HHmmss, UTC) whose manifest was restored"},"restored_count":{"type":"integer","description":"Files placed into the restored folder"},"missing":{"type":"array","items":{"type":"string"},"description":"Manifest entries whose snapshot copy could not be found"},"result":{"type":"string","enum":["restored"]}}}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Task":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"$ref":"#/components/schemas/TaskAttributes"}}},"TaskAttributes":{"type":"object","properties":{"uid":{"type":"string","description":"Task identifier used as the Desktop folder name"},"status":{"type":"string","enum":["active","inactive"],"description":"Task status"},"source_path":{"type":"string","description":"Full Windows path monitored for snapshots"},"snapshot_destination":{"type":"string","description":"Full Windows path where snapshots are stored. For the default \"Outputs\" task this is `V:\\Outputs`; for all other tasks it is `V:\\{uid}-snapshots`."},"folder_size":{"type":"integer","nullable":true,"description":"Cumulative size in bytes of the task's corresponding folder, recorded when the machine last stopped gracefully. `null` until the machine stops for the first time with an active task and a matching folder."},"created_at":{"type":"string","format":"date-time","description":"Task creation time (ISO 8601)"}}},"FileObject":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"$ref":"#/components/schemas/FileObjectAttributes"}}},"FileObjectAttributes":{"type":"object","properties":{"name":{"type":"string","description":"File or folder name"},"size":{"type":"integer","description":"File size in bytes (0 for directories)"},"content_type":{"type":"string","description":"MIME type of the file or \"directory\" for folders"},"region":{"type":"string","description":"Storage region"},"status":{"type":"string","enum":["pending_upload","upload_completed","upload_failed"],"description":"Upload status"},"object_type":{"type":"string","enum":["file","directory","root"],"description":"Type of object"},"path":{"type":"string","nullable":true,"description":"Path within the storage"},"parent_id":{"type":"integer","nullable":true,"description":"Parent folder ID"},"last_modified_date":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp"},"file_storage_size":{"type":"integer","nullable":true,"description":"Total storage size in bytes (only for root directories)"},"file_storage_usage":{"type":"integer","nullable":true,"description":"Used storage in bytes (only for root directories)"},"user":{"type":"object","nullable":true,"description":"User who owns this file/folder","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"}}}}},"machine_id":{"type":"integer","nullable":true,"description":"Associated machine ID (for machine-scoped files)"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error451Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4206Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4218Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4237Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4238Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````

## List Machine Task Snapshots

> Browses the snapshots restored for a task with \`POST /machines/{id}/tasks/{task\_id}/restore\`. Read-only: it works whatever the machine's state.\
> \
> \*\*Two modes on one route.\*\*\
> \
> \- \*\*Without \`parent\_id\`\*\*: the task's restored snapshots, newest snapshot first. Only fully built restores are returned; raw snapshot cycle folders and restores still being built are not. Each item carries what it was rebuilt from and how big it is, computed at restore time.\
> \- \*\*With \`parent\_id\`\*\*: the contents of that folder, shaped like \`GET /machines/{id}/files\` (\`files\`, \`current\`, \`count\`, \`page\`, \`next\_page\`) plus \`ancestors\`, the chain of folders from the restored snapshot's root down to the current folder, for a breadcrumb. \`parent\_id\` must be the id of a restored snapshot (from the list) or of a folder inside one belonging to \*\*this\*\* task; anything else is \`404\`. Supports \`q\` for a name search.\
> \
> Both modes are paginated with \`page\` / \`per\_page\` and report the total in \`count\`. Restored snapshots never appear in \`GET /machines/{id}/files\` or in the Vagon Files drive; this endpoint is the only way to browse them. Files inside are downloadable through the usual \`GET /files/{id}/download\` and ZIP download endpoints.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### Path Parameters\
> \
> \| Parameter | Type | Description |\
> \| --- | --- | --- |\
> \| \`id\`\\\* | Integer | Machine ID |\
> \| \`task\_id\`\\\* | Integer | Task ID |\
> \
> \### Query Parameters\
> \
> \| Parameter | Type | Description |\
> \| --- | --- | --- |\
> \| \`parent\_id\` | Integer | Folder to list. Omit for the list of restored snapshots. |\
> \| \`q\` | String | Name filter, only with \`parent\_id\` |\
> \| \`page\` | Integer | Page number (default 1) |\
> \| \`per\_page\` | Integer | Items per page (default 25) |\
> \
> \### Response Fields (without \`parent\_id\`)\
> \
> \| Field | Type | Description |\
> \| --- | --- | --- |\
> \| \`snapshots\` | Array | Restored snapshots, newest first |\
> \| \`snapshots\[].id\` | String | Folder ID — pass as \`parent\_id\` to browse it |\
> \| \`snapshots\[].type\` | String | Always \`"snapshot"\` |\
> \| \`snapshots\[].attributes.name\` | String | Folder name (\`\<task uid>-restored-\<snapshot>\`) |\
> \| \`snapshots\[].attributes.snapshot\` | String | Snapshot cycle it was rebuilt from (\`yyyyMMdd\_HHmmss\`, UTC) |\
> \| \`snapshots\[].attributes.restored\_at\` | String | When the restore was made |\
> \| \`snapshots\[].attributes.file\_count\` | Integer | Files in the restored snapshot |\
> \| \`snapshots\[].attributes.size\` | Integer | Total size of those files in bytes |\
> \| \`snapshots\[].attributes.missing\_count\` | Integer | Manifest entries that could not be resolved at restore time |\
> \| \`snapshots\[].attributes.parent\_id\` | Integer | The seat's Vagon Files root |\
> \| \`count\` | Integer | Total number of restored snapshots |\
> \| \`page\` | Integer | Current page |\
> \| \`next\_page\` | Integer or null | Next page number |\
> \
> \### Response Fields (with \`parent\_id\`)\
> \
> \| Field | Type | Description |\
> \| --- | --- | --- |\
> \| \`files\` | Array | Contents of the folder (directories first, then files by name), every item \`virtual: true\` |\
> \| \`current\` | Object | The folder being listed |\
> \| \`ancestors\` | Array | Folders from the restored snapshot's root down to (excluding) \`current\`; empty at the root |\
> \| \`count\` | Integer | Total number of items in the folder |\
> \| \`page\` | Integer | Current page |\
> \| \`next\_page\` | Integer or null | Next page number |\
> \
> \### Response Example (without \`parent\_id\`)\
> \
> \`\`\`json\
> {\
> &#x20; "snapshots": \[\
> &#x20;   {\
> &#x20;     "id": "9812",\
> &#x20;     "type": "snapshot",\
> &#x20;     "attributes": {\
> &#x20;       "name": "task-02-restored-20260902\_100000",\
> &#x20;       "parent\_id": 4410,\
> &#x20;       "snapshot": "20260902\_100000",\
> &#x20;       "restored\_at": "2026-09-28T10:00:00.000Z",\
> &#x20;       "file\_count": 9799,\
> &#x20;       "size": 24519823,\
> &#x20;       "missing\_count": 1\
> &#x20;     }\
> &#x20;   }\
> &#x20; ],\
> &#x20; "count": 1,\
> &#x20; "page": 1,\
> &#x20; "next\_page": null,\
> &#x20; "client\_code": 200,\
> &#x20; "message": "OK",\
> &#x20; "timestamp": "2026-09-29T10:00:00Z"\
> }\
> \`\`\`

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/machines/{id}/tasks/{task_id}/snapshots":{"get":{"summary":"List Machine Task Snapshots","responses":{"200":{"description":"Without `parent_id`, the task's restored snapshots; with `parent_id`, that folder's contents","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/TaskSnapshotListResponse"},{"$ref":"#/components/schemas/TaskSnapshotContentsResponse"}]}}}},"404":{"description":"Task not found, or `parent_id` is not a folder inside one of this task's restored snapshots","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4110":{"description":"Subscription is not active","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4110Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Machines"],"description":"Browses the snapshots restored for a task with `POST /machines/{id}/tasks/{task_id}/restore`. Read-only: it works whatever the machine's state.\n\n**Two modes on one route.**\n\n- **Without `parent_id`**: the task's restored snapshots, newest snapshot first. Only fully built restores are returned; raw snapshot cycle folders and restores still being built are not. Each item carries what it was rebuilt from and how big it is, computed at restore time.\n- **With `parent_id`**: the contents of that folder, shaped like `GET /machines/{id}/files` (`files`, `current`, `count`, `page`, `next_page`) plus `ancestors`, the chain of folders from the restored snapshot's root down to the current folder, for a breadcrumb. `parent_id` must be the id of a restored snapshot (from the list) or of a folder inside one belonging to **this** task; anything else is `404`. Supports `q` for a name search.\n\nBoth modes are paginated with `page` / `per_page` and report the total in `count`. Restored snapshots never appear in `GET /machines/{id}/files` or in the Vagon Files drive; this endpoint is the only way to browse them. Files inside are downloadable through the usual `GET /files/{id}/download` and ZIP download endpoints.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### Path Parameters\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `id`\\* | Integer | Machine ID |\n| `task_id`\\* | Integer | Task ID |\n\n### Query Parameters\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `parent_id` | Integer | Folder to list. Omit for the list of restored snapshots. |\n| `q` | String | Name filter, only with `parent_id` |\n| `page` | Integer | Page number (default 1) |\n| `per_page` | Integer | Items per page (default 25) |\n\n### Response Fields (without `parent_id`)\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `snapshots` | Array | Restored snapshots, newest first |\n| `snapshots[].id` | String | Folder ID — pass as `parent_id` to browse it |\n| `snapshots[].type` | String | Always `\"snapshot\"` |\n| `snapshots[].attributes.name` | String | Folder name (`<task uid>-restored-<snapshot>`) |\n| `snapshots[].attributes.snapshot` | String | Snapshot cycle it was rebuilt from (`yyyyMMdd_HHmmss`, UTC) |\n| `snapshots[].attributes.restored_at` | String | When the restore was made |\n| `snapshots[].attributes.file_count` | Integer | Files in the restored snapshot |\n| `snapshots[].attributes.size` | Integer | Total size of those files in bytes |\n| `snapshots[].attributes.missing_count` | Integer | Manifest entries that could not be resolved at restore time |\n| `snapshots[].attributes.parent_id` | Integer | The seat's Vagon Files root |\n| `count` | Integer | Total number of restored snapshots |\n| `page` | Integer | Current page |\n| `next_page` | Integer or null | Next page number |\n\n### Response Fields (with `parent_id`)\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `files` | Array | Contents of the folder (directories first, then files by name), every item `virtual: true` |\n| `current` | Object | The folder being listed |\n| `ancestors` | Array | Folders from the restored snapshot's root down to (excluding) `current`; empty at the root |\n| `count` | Integer | Total number of items in the folder |\n| `page` | Integer | Current page |\n| `next_page` | Integer or null | Next page number |\n\n### Response Example (without `parent_id`)\n\n```json\n{\n  \"snapshots\": [\n    {\n      \"id\": \"9812\",\n      \"type\": \"snapshot\",\n      \"attributes\": {\n        \"name\": \"task-02-restored-20260902_100000\",\n        \"parent_id\": 4410,\n        \"snapshot\": \"20260902_100000\",\n        \"restored_at\": \"2026-09-28T10:00:00.000Z\",\n        \"file_count\": 9799,\n        \"size\": 24519823,\n        \"missing_count\": 1\n      }\n    }\n  ],\n  \"count\": 1,\n  \"page\": 1,\n  \"next_page\": null,\n  \"client_code\": 200,\n  \"message\": \"OK\",\n  \"timestamp\": \"2026-09-29T10:00:00Z\"\n}\n```"}}},"components":{"schemas":{"TaskSnapshotListResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"snapshots":{"type":"array","items":{"$ref":"#/components/schemas/TaskSnapshot"}},"count":{"type":"integer"},"page":{"type":"integer"},"next_page":{"type":"integer","nullable":true}}}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"TaskSnapshot":{"type":"object","properties":{"id":{"type":"string","description":"Folder ID; pass as parent_id to browse the snapshot"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"integer"},"snapshot":{"type":"string","description":"Snapshot cycle the folder was rebuilt from (yyyyMMdd_HHmmss, UTC)"},"restored_at":{"type":"string","format":"date-time"},"file_count":{"type":"integer"},"size":{"type":"integer","description":"Total bytes referenced by the restored files"},"missing_count":{"type":"integer"}}}}},"TaskSnapshotContentsResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/FileObject"}},"current":{"$ref":"#/components/schemas/CurrentDirectory"},"ancestors":{"type":"array","description":"Folders from the restored snapshot's root down to (excluding) current","items":{"$ref":"#/components/schemas/FileObject"}},"count":{"type":"integer"},"page":{"type":"integer"},"next_page":{"type":"integer","nullable":true}}}]},"FileObject":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"$ref":"#/components/schemas/FileObjectAttributes"}}},"FileObjectAttributes":{"type":"object","properties":{"name":{"type":"string","description":"File or folder name"},"size":{"type":"integer","description":"File size in bytes (0 for directories)"},"content_type":{"type":"string","description":"MIME type of the file or \"directory\" for folders"},"region":{"type":"string","description":"Storage region"},"status":{"type":"string","enum":["pending_upload","upload_completed","upload_failed"],"description":"Upload status"},"object_type":{"type":"string","enum":["file","directory","root"],"description":"Type of object"},"path":{"type":"string","nullable":true,"description":"Path within the storage"},"parent_id":{"type":"integer","nullable":true,"description":"Parent folder ID"},"last_modified_date":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp"},"file_storage_size":{"type":"integer","nullable":true,"description":"Total storage size in bytes (only for root directories)"},"file_storage_usage":{"type":"integer","nullable":true,"description":"Used storage in bytes (only for root directories)"},"user":{"type":"object","nullable":true,"description":"User who owns this file/folder","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"}}}}},"machine_id":{"type":"integer","nullable":true,"description":"Associated machine ID (for machine-scoped files)"}}},"CurrentDirectory":{"type":"object","description":"Current directory information with the same structure as FileObject","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"$ref":"#/components/schemas/FileObjectAttributes"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error4110Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````
