> 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\ > {\ > "machines": \[\ > {\ > "id": "100",\ > "type": "machine",\ > "attributes": {\ > "name": "Computer #100",\ > "last\_session\_start\_at": "2026-01-23T11:02:41.902Z",\ > "os": "windows",\ > "auto\_stop\_threshold": 900,\ > "file\_storage\_size": 25,\ > "disk\_size": 75,\ > "network\_credit": 10233505675,\ > "assigned\_image\_id": 990,\ > "assigned\_image\_name": "Template #990",\ > "region": "dublin",\ > "machine\_type": "Planet",\ > "remaining\_usage": 0,\ > "deposited\_usage": 0,\ > "friendly\_status": "off",\ > "user": {\ > "id": "f1592625-edd0-48df-9bc0-de14910ec936",\ > "type": "user",\ > "attributes": {\ > "email": "",\ > "name": "Computer User"\ > }\ > },\ > "permissions": {\ > "public\_internet\_access": true,\ > "can\_download\_from\_vagon\_workstation": true,\ > "can\_upload\_to\_workstation": true,\ > "analytics\_collection\_enabled": true,\ > "clipboard\_enabled": true,\ > "screen\_recording\_enabled": true,\ > "input\_recording\_enabled": true\ > },\ > "usage\_source": "machine",\ > "task": {\ > "id": 42,\ > "uid": "Project-Alpha",\ > "created\_at": "2026-04-20T09:15:00Z"\ > },\ > "latest\_image\_status": "ready"\ > }\ > },\ > {\ > "id": "101",\ > "type": "machine",\ > "attributes": {\ > "name": "Computer #101",\ > "last\_session\_start\_at": "2026-01-23T14:12:18.943Z",\ > "os": "linux",\ > "auto\_stop\_threshold": 900,\ > "file\_storage\_size": 250,\ > "disk\_size": 125,\ > "network\_credit": 10338256517,\ > "assigned\_image\_id": 991,\ > "assigned\_image\_name": "Template #991",\ > "region": "dublin",\ > "machine\_type": "Planet",\ > "remaining\_usage": 2400,\ > "deposited\_usage": 0,\ > "user": null,\ > "permissions": {\ > "public\_internet\_access": true,\ > "can\_download\_from\_vagon\_workstation": true,\ > "can\_upload\_to\_workstation": true,\ > "analytics\_collection\_enabled": true,\ > "clipboard\_enabled": true,\ > "screen\_recording\_enabled": true,\ > "input\_recording\_enabled": true\ > },\ > "friendly\_status": "off",\ > "usage\_source": "machine",\ > "task": null,\ > "latest\_image\_status": "processing"\ > }\ > }\ > ],\ > "count": 2,\ > "page": 1,\ > "next\_page": null,\ > "client\_code": 200,\ > "message": "OK",\ > "timestamp": "2026-02-05T10:08:09Z"\ > }\ > \ > \`\`\`\ > \ > \### \*\*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.12"},"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"]},"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\ > {\ > "plan\_id": 1,\ > "quantity": 1,\ > "region": "dublin",\ > "os": "windows",\ > "software\_ids": \[],\ > "base\_image\_id": 100,\ > "permissions": {\ > "public\_internet\_access": true,\ > "can\_download\_from\_vagon\_workstation": true,\ > "can\_upload\_to\_workstation": true,\ > "analytics\_collection\_enabled": false,\ > "clipboard\_enabled": true,\ > "screen\_recording\_enabled": false,\ > "input\_recording\_enabled": false\ > }\ > }\ > \ > \`\`\`\ > \ > \### \*\*Success Response Example\*\*\ > \ > \`\`\` json\ > {\ > "machines": \[\ > {\ > "id": "100",\ > "type": "machine",\ > "attributes": {\ > "name": "Computer #100",\ > "last\_session\_start\_at": null,\ > "os": "windows",\ > "auto\_stop\_threshold": 900,\ > "file\_storage\_size": 25,\ > "disk\_size": 75,\ > "network\_credit": 10737418240,\ > "assigned\_image\_id": 100,\ > "assigned\_image\_name": "Template #100",\ > "region": "dublin",\ > "machine\_type": "Planet",\ > "remaining\_usage": 0,\ > "deposited\_usage": 0,\ > "user": null,\ > "friendly\_status": "off",\ > "permissions": {\ > "public\_internet\_access": true,\ > "can\_download\_from\_vagon\_workstation": true,\ > "can\_upload\_to\_workstation": true,\ > "analytics\_collection\_enabled": false,\ > "clipboard\_enabled": true,\ > "screen\_recording\_enabled": false,\ > "input\_recording\_enabled": false\ > },\ > "task": null,\ > "latest\_image\_status": null\ > }\ > }\ > ],\ > "count": 1,\ > "client\_code": 200,\ > "message": "OK",\ > "timestamp": "2026-02-05T10:10:22Z"\ > }\ > \ > \`\`\`\ > \ > \### \*\*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.12"},"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"]},"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.12"},"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"]},"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\ > {\ > "client\_code": 200,\ > "message": "OK",\ > "timestamp": "2026-02-05T10:11:54Z"\ > }\ > \ > \`\`\`\ > \ > \### 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.12"},"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\ > {\ > "machine\_types": \[\ > {\ > "id": "11",\ > "type": "machine\_type",\ > "attributes": {\ > "name": "g4dn.xlarge",\ > "friendly\_name": "Planet",\ > "cpu": 4,\ > "memory": "16.0",\ > "gpu": 1,\ > "gpu\_memory": "16.0"\ > }\ > },\ > {\ > "id": "15",\ > "type": "machine\_type",\ > "attributes": {\ > "name": "g5.xlarge",\ > "friendly\_name": "Spark",\ > "cpu": 4,\ > "memory": "16.0",\ > "gpu": 1,\ > "gpu\_memory": "24.0"\ > }\ > }\ > ],\ > "client\_code": 200,\ > "message": "OK",\ > "timestamp": "2026-02-04T11:13:07Z"\ > }\ > \ > \`\`\` ````json {"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.12"},"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\ > {\ > "client\_code": 200,\ > "message": "OK",\ > "timestamp": "2026-02-04T11:16:28Z"\ > }\ > \ > \`\`\` ````json {"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.12"},"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. \
\
\`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\ > {\ > "client\_code": 200,\ > "message": "OK",\ > "timestamp": "2026-02-04T11:18:42Z"\ > }\ > \ > \`\`\` ````json {"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.12"},"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.

`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\ > {\ > "id": "77",\ > "type": "machine\_external\_access",\ > "attributes": {\ > "expires\_at": "2026-02-05T11:12:42.677Z",\ > "connection\_link": " > },\ > "client\_code": 200,\ > "message": "OK",\ > "timestamp": "2026-02-05T10:12:42Z"\ > }\ > \ > \`\`\`\ > \ > \### 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.12"},"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\ > {\ > "client\_code": 200,\ > "message": "OK",\ > "timestamp": "2026-02-04T11:31:12Z"\ > }\ > \ > \`\`\`\ > \ > \### 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.12"},"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\ > {\ > "permissions": {\ > "public\_internet\_access": true,\ > "can\_download\_from\_vagon\_workstation": true,\ > "can\_upload\_to\_workstation": true,\ > "analytics\_collection\_enabled": false,\ > "clipboard\_enabled": true,\ > "screen\_recording\_enabled": false,\ > "input\_recording\_enabled": false\ > }\ > }\ > \ > \`\`\`\ > \ > \### Success Response\ > \ > \`\`\` json\ > {\ > "client\_code": 200,\ > "message": "OK",\ > "timestamp": "2026-02-04T11:41:34Z"\ > }\ > \ > \`\`\`\ > \ > \### 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.12"},"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\ > {\ > "script\_body": "Write-Output \\"PowerShell script is working!\\""\ > }\ > \ > \`\`\`\ > \ > \### \*\*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\ > {\ > "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')\\""\ > }\ > \ > \`\`\`\ > \ > \ > 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')"\ > \ > \`\`\`\ > \ > \ > \### \*\*Request Body Example (Linux / bash)\*\*\ > \ > On Linux machines \`script\_body\` is a bash script:\ > \ > \`\`\` json\ > {\ > "script\_body": "echo \\"OS : $(uname -a)\\"\necho \\"Timestamp : $(date '+%Y-%m-%d %H:%M:%S')\\""\ > }\ > \ > \`\`\`\ > \ > \ > ...which corresponds to the following bash:\ > \ > \`\`\` bash\ > echo "OS : $(uname -a)" echo "Timestamp : $(date '+%Y-%m-%d %H:%M:%S')"\ > \ > \`\`\`\ > \ > \### \*\*Response Example\*\*\ > \ > \`\`\` json\ > {\ > "result": "PowerShell script is working!",\ > "client\_code": 200,\ > "message": "OK",\ > "timestamp": "2026-02-04T11:55:10Z"\ > }\ > \ > \`\`\` ````json {"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.12"},"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]\() |\ > \| \`applications\` | Array | No | Application names to pre-install. Send values as an array of software names. Available values can be collected from \[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\ > {\ > "plan\_id": 42,\ > "dry\_run": true,\ > "rows": \[\ > {\ > "email": "",\ > "region": "europe",\ > "template\_name": "Design Template",\ > "disk\_size": "275",\ > "applications": \[\ > "Blender",\ > "Maya"\ > ]\ > },\ > {\ > "email": "",\ > "region": "europe"\ > },\ > {\ > "region": "europe",\ > "template\_name": "Design Template"\ > }\ > ]\ > }\ > \ > \`\`\`\ > \ > \### \*\*Response Example\*\*\ > \ > \`\`\` json\ > {\ > "results": {\ > "": {\ > "invitation": "created",\ > "machine\_id": 8085,\ > "disk\_size": 275,\ > "template": "assigned: Design Template"\ > },\ > "": {\ > "invitation": "skipped (already on a team)",\ > "machine\_id": null,\ > "disk\_size": null,\ > "template": "User is already on a team.",\ > "error": "User is already on a team."\ > },\ > "(no email #3)": {\ > "invitation": "skipped (no email)",\ > "machine\_id": 8086,\ > "disk\_size": 275,\ > "template": "assigned: Design Template"\ > }\ > },\ > "summary": {\ > "total": 3,\ > "invalid": 1,\ > "assigned": 2\ > },\ > "client\_code": 200,\ > "message": "OK",\ > "timestamp": "2026-06-08T11:58:57Z"\ > }\ > \ > \`\`\` ````json {"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.12"},"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\ > {\ > "sessions": \[\ > {\ > "id": "2000",\ > "type": "machine\_session",\ > "attributes": {\ > "start\_at": "2026-01-23T11:02:41.902Z",\ > "end\_at": "2026-01-23T11:07:51.115Z",\ > "duration": 6\ > }\ > },\ > {\ > "id": "1999",\ > "type": "machine\_session",\ > "attributes": {\ > "start\_at": "2026-01-21T22:57:57.450Z",\ > "end\_at": "2026-01-21T22:59:58.408Z",\ > "duration": 3\ > }\ > }\ > ],\ > "client\_code": 200,\ > "message": "OK",\ > "timestamp": "2026-02-04T11:55:58Z"\ > }\ > \ > \`\`\` ````json {"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.12"},"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\ > {\ > "tasks": \[\ > {\ > "id": "18",\ > "type": "task",\ > "attributes": {\ > "uid": "Outputs",\ > "created\_at": "2025-12-02T09:50:37.244Z",\ > "status": "active",\ > "source\_path": "C:\\\Users\\\Administrator\\\Desktop\\\Outputs",\ > "snapshot\_destination": "V:\\\Outputs",\ > "folder\_size": 713\ > }\ > }\ > ],\ > "count": 1,\ > "page": 1,\ > "next\_page": null,\ > "client\_code": 200,\ > "message": "OK",\ > "timestamp": "2026-04-15T11:11:27Z"\ > }\ > \`\`\` ````json {"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.12"},"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\ > {\ > "task": {\ > "id": "22",\ > "type": "task",\ > "attributes": {\ > "uid": "task-012",\ > "created\_at": "2026-04-15T11:16:44.534Z",\ > "status": "active",\ > "source\_path": "C:\\\Users\\\Administrator\\\Desktop\\\task-012",\ > "snapshot\_destination": "V:\\\task-012-snapshots",\ > "folder\_size": null\ > }\ > },\ > "result": "created",\ > "client\_code": 200,\ > "message": "OK",\ > "timestamp": "2026-04-15T11:16:44Z"\ > }\ > \`\`\`\ > \ > \*\*result: "reactivated"\*\*\ > \ > \`\`\`json\ > {\ > "task": {\ > "id": "18",\ > "type": "task",\ > "attributes": {\ > "uid": "Outputs",\ > "created\_at": "2025-12-02T09:50:37.244Z",\ > "status": "active",\ > "source\_path": "C:\\\Users\\\Administrator\\\Desktop\\\Outputs",\ > "snapshot\_destination": "V:\\\Outputs",\ > "folder\_size": 713\ > }\ > },\ > "result": "reactivated",\ > "client\_code": 200,\ > "message": "OK",\ > "timestamp": "2026-04-15T11:17:20Z"\ > }\ > \`\`\`\ > \ > \*\*result: "already\_active"\*\*\ > \ > \`\`\`json\ > {\ > "task": {\ > "id": "22",\ > "type": "task",\ > "attributes": {\ > "uid": "task-012",\ > "created\_at": "2026-04-15T11:16:44.534Z",\ > "status": "active",\ > "source\_path": "C:\\\Users\\\Administrator\\\Desktop\\\task-012",\ > "snapshot\_destination": "V:\\\task-012-snapshots",\ > "folder\_size": null\ > }\ > },\ > "result": "already\_active",\ > "client\_code": 200,\ > "message": "OK",\ > "timestamp": "2026-04-15T11:17:03Z"\ > }\ > \`\`\` ````json {"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.12"},"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\ > {\ > "task": {\ > "id": "21",\ > "type": "task",\ > "attributes": {\ > "uid": "task-02",\ > "created\_at": "2026-04-15T11:11:35.142Z",\ > "status": "inactive",\ > "source\_path": "C:\\\Users\\\Administrator\\\Desktop\\\task-02",\ > "snapshot\_destination": "V:\\\task-02-snapshots",\ > "folder\_size": null\ > }\ > },\ > "result": "deleted",\ > "client\_code": 200,\ > "message": "OK",\ > "timestamp": "2026-04-15T11:11:57Z"\ > }\ > \`\`\` ````json {"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.12"},"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"}]}}}} ````