Machines

List Machines

get

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

{
    "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": "[e-mail]",
                        "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)

Query parameters

pageintegerOptional

(Optional) Page number. Default: 1

Example: 1

per_pageintegerOptional

(Optional) Records per page. Default: 20

Example: 20

qstringOptional

(Optional) Search by user email or machine name

Example: string

Responses

200

List of machines

application/json

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-02-05T10:10:22Z

countintegerOptional

Total number of machines

Example: 9

pageintegerOptional

Current page number

Example: 1

next_pageinteger · nullableOptional

Next page number (null if no more pages)

400

Bad request

application/json

404

Not found

application/json

480

Insufficient funds

application/json

4201

Machine is not ready

application/json

4710

Permission required

application/json

get/machines

HTTPcURLJavaScriptPython

GET /organization-management/v1/machines HTTP/1.1
Host: api.vagon.io
Accept: */*

{
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:10:22Z",
  "machines": [
    {
      "id": "719",
      "type": "machine",
      "attributes": {
        "name": "Computer #719",
        "region": "dublin",
        "last_session_start_at": "2026-08-11T02:44:52.959Z",
        "friendly_status": "off",
        "auto_stop_threshold": 900,
        "file_storage_size": 25,
        "disk_size": 75,
        "network_credit": 10737418240,
        "assigned_image_id": 320,
        "assigned_image_name": "Template #320",
        "machine_type": "Planet",
        "remaining_usage": 0,
        "deposited_usage": 0,
        "user": {
          "id": "f1592625-edd0-48df-9bc0-de14910ec936",
          "type": "user",
          "attributes": {
            "email": "[e-mail]",
            "name": "Computer User"
          }
        },
        "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
        },
        "usage_source": "machine",
        "task": {
          "id": 42,
          "uid": "Project-Alpha",
          "created_at": "2026-04-20T09:15:00Z"
        },
        "latest_image_status": "ready"
      }
    }
  ],
  "count": 9,
  "page": 1,
  "next_page": null
}

Create Machines

post

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

{
  "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

{
    "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

Body

application/json

plan_idintegerRequired

Subscription plan ID

quantityintegerRequired

Number of machines to create

regionstringRequired

Region for the machine (e.g., dublin, frankfurt)

osstring · enumOptional

Operating system for the created machines. Optional; defaults to windows.

Default: windowsPossible values:

software_idsinteger[]Optional

List of software IDs to pre-install

base_image_idinteger · nullableOptional

Base image ID to use (null for default)

Responses

200

Machines created successfully

application/json

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-02-05T10:10:22Z

countintegerOptionalExample: 1

400

Bad request

application/json

404

Plan ID not found

application/json

480

Insufficient balance

application/json

4202

Region is required

application/json

4710

Permission required

application/json

post/machines

HTTPcURLJavaScriptPython

POST /organization-management/v1/machines HTTP/1.1
Host: api.vagon.io
Content-Type: application/json
Accept: */*
Content-Length: 349

{
  "plan_id": 235,
  "quantity": 1,
  "region": "dublin",
  "os": "windows",
  "software_ids": [],
  "base_image_id": null,
  "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
  }
}

{
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:10:22Z",
  "machines": [
    {
      "id": "719",
      "type": "machine",
      "attributes": {
        "name": "Computer #719",
        "region": "dublin",
        "last_session_start_at": "2026-08-11T02:44:52.959Z",
        "friendly_status": "off",
        "auto_stop_threshold": 900,
        "file_storage_size": 25,
        "disk_size": 75,
        "network_credit": 10737418240,
        "assigned_image_id": 320,
        "assigned_image_name": "Template #320",
        "machine_type": "Planet",
        "remaining_usage": 0,
        "deposited_usage": 0,
        "user": {
          "id": "f1592625-edd0-48df-9bc0-de14910ec936",
          "type": "user",
          "attributes": {
            "email": "[e-mail]",
            "name": "Computer User"
          }
        },
        "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
        },
        "usage_source": "machine",
        "task": {
          "id": 42,
          "uid": "Project-Alpha",
          "created_at": "2026-04-20T09:15:00Z"
        },
        "latest_image_status": "ready"
      }
    }
  ],
  "count": 1
}

Update Machine

patch

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)

Path parameters

idintegerRequiredExample: 1

Body

application/json

auto_stop_thresholdintegerOptional

Auto-stop threshold in seconds. 0 to disable.

usage_sourcestring · enumOptional

Usage source - team_balance or machine

Possible values:

Responses

200

Machine updated successfully

application/json

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-02-05T10:10:22Z

idstringOptionalExample: 719

typestringOptionalExample: machine

400

Bad request (e.g. invalid usage_source)

application/json

404

Machine not found

application/json

4710

Permission required

application/json

patch/machines/{id}

HTTPcURLJavaScriptPython

PATCH /organization-management/v1/machines/{id} HTTP/1.1
Host: api.vagon.io
Content-Type: application/json
Accept: */*
Content-Length: 55

{
  "auto_stop_threshold": 1,
  "usage_source": "team_balance"
}

{
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:10:22Z",
  "id": "719",
  "type": "machine",
  "attributes": {
    "name": "Computer #719",
    "region": "dublin",
    "last_session_start_at": "2026-08-11T02:44:52.959Z",
    "friendly_status": "off",
    "auto_stop_threshold": 900,
    "file_storage_size": 25,
    "disk_size": 75,
    "network_credit": 10737418240,
    "assigned_image_id": 320,
    "assigned_image_name": "Template #320",
    "machine_type": "Planet",
    "remaining_usage": 0,
    "deposited_usage": 0,
    "user": {
      "id": "f1592625-edd0-48df-9bc0-de14910ec936",
      "type": "user",
      "attributes": {
        "email": "[e-mail]",
        "name": "Computer User"
      }
    },
    "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
    },
    "usage_source": "machine",
    "task": {
      "id": 42,
      "uid": "Project-Alpha",
      "created_at": "2026-04-20T09:15:00Z"
    },
    "latest_image_status": "ready"
  }
}

Start Machine

post

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

{
    "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

Path parameters

idanyRequired

(Required) Machine ID

Example: 1

Responses

200

Machine started successfully

application/json

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-02-05T10:10:22Z

400

Bad request

application/json

404

Machine not found

application/json

480

Insufficient balance

application/json

4710

Permission required

application/json

post/machines/{id}/start

HTTPcURLJavaScriptPython

POST /organization-management/v1/machines/{id}/start HTTP/1.1
Host: api.vagon.io
Accept: */*

{
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:10:22Z"
}

Get Available Machine Performances

get

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

{
    "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"
}

Path parameters

idintegerRequired

(Required) Machine ID

Example: 1

Responses

200

List of available machine types

application/json

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-02-05T10:10:22Z

400

Bad request

application/json

404

Machine not found

application/json

4710

Permission required

application/json

get/machines/{id}/available-machine-types

HTTPcURLJavaScriptPython

GET /organization-management/v1/machines/{id}/available-machine-types HTTP/1.1
Host: api.vagon.io
Accept: */*

{
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:10:22Z",
  "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"
      }
    }
  ]
}

Set Machine Performance

post

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:

{
    "client_code": 200,
    "message": "OK",
    "timestamp": "2026-02-04T11:16:28Z"
}

Path parameters

idanyRequired

(Required) Machine ID

Example: 1

Body

application/json

machine_type_idintegerOptional

Responses

200

Machine type updated successfully

application/json

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-02-05T10:10:22Z

400

Bad request

application/json

404

Machine not found

application/json

4205

Machine type is not available for this seat plan

application/json

4710

Permission required

application/json

post/machines/{id}/machine-type

HTTPcURLJavaScriptPython

POST /organization-management/v1/machines/{id}/machine-type HTTP/1.1
Host: api.vagon.io
Content-Type: application/json
Accept: */*
Content-Length: 21

{
  "machine_type_id": 2
}

{
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:10:22Z"
}

Stop Machine

post

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

{
    "client_code": 200,
    "message": "OK",
    "timestamp": "2026-02-04T11:18:42Z"
}

Path parameters

idintegerRequired

(Required) Machine ID

Example: 1

Body

application/json

gracefullybooleanOptional

Responses

200

Machine stopped successfully

application/json

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-02-05T10:10:22Z

400

Bad request

application/json

404

Machine not found

application/json

4204

Machine is not running

application/json

4710

Permission required

application/json

post/machines/{id}/stop

HTTPcURLJavaScriptPython

POST /organization-management/v1/machines/{id}/stop HTTP/1.1
Host: api.vagon.io
Content-Type: application/json
Accept: */*
Content-Length: 19

{
  "gracefully": true
}

{
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:10:22Z"
}

Get Access Link for a Machine

post

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

{
    "id": "77",
    "type": "machine_external_access",
    "attributes": {
        "expires_at": "2026-02-05T11:12:42.677Z",
        "connection_link": "https://app.vagon.io/team/session/62ba2d60-5ee2-11aa-aa64-957da90ef117"
    },
    "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)

Path parameters

idintegerRequired

(Required) Machine ID

Example: 1

Body

application/json

expires_inintegerOptional

Responses

200

Access link created successfully

application/json

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-02-05T10:10:22Z

idstringOptionalExample: 77

typestringOptionalExample: machine_external_access

400

Bad request

application/json

404

Machine not found

application/json

4710

Permission required

application/json

post/machines/{id}/access

HTTPcURLJavaScriptPython

POST /organization-management/v1/machines/{id}/access HTTP/1.1
Host: api.vagon.io
Content-Type: application/json
Accept: */*
Content-Length: 17

{
  "expires_in": 60
}

{
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:10:22Z",
  "id": "77",
  "type": "machine_external_access",
  "attributes": {
    "expires_at": "2026-02-05T11:12:42.677Z",
    "connection_link": "https://stg-app.vagon.io/team/session/102aa5ae-2e94-4ea5-846b-f6465482cbbe"
  }
}

Reset Machine to Initial State

post

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

{
    "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

Path parameters

idintegerRequired

(Required) Machine ID

Example: 1

Body

application/json

remove_filesbooleanOptional

When true, the VagonFiles folder (computer files) is also wiped as part of the reset. When false (default), VagonFiles are preserved.

Default: false

Responses

200

Machine reset successfully

application/json

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-02-05T10:10:22Z

400

Bad request

application/json

404

Machine not found

application/json

4206

Machine is running

application/json

4710

Permission required

application/json

post/machines/{id}/reset

HTTPcURLJavaScriptPython

POST /organization-management/v1/machines/{id}/reset HTTP/1.1
Host: api.vagon.io
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "remove_files": false
}

{
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:10:22Z"
}

Manage Permissions

post

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

{
  "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

{
    "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

Path parameters

idintegerRequired

(Required) Machine ID

Example: 717

Body

application/json

Responses

200

Permissions updated successfully

application/json

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-02-05T10:10:22Z

400

Bad request

application/json

404

Machine not found

application/json

4710

Permission required

application/json

post/machines/{id}/permissions

HTTPcURLJavaScriptPython

POST /organization-management/v1/machines/{id}/permissions HTTP/1.1
Host: api.vagon.io
Content-Type: application/json
Accept: */*
Content-Length: 250

{
  "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
  }
}

{
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:10:22Z"
}

Run Remote Script

post

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)

{
  "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):

{
  "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:

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:

{
  "script_body": "echo \"OS        : $(uname -a)\"\necho \"Timestamp : $(date '+%Y-%m-%d %H:%M:%S')\""
}

...which corresponds to the following bash:

echo "OS        : $(uname -a)" echo "Timestamp : $(date '+%Y-%m-%d %H:%M:%S')"

Response Example

{
    "result": "PowerShell script is working!",
    "client_code": 200,
    "message": "OK",
    "timestamp": "2026-02-04T11:55:10Z"
}

Path parameters

idintegerRequired

(Required) Machine ID

Example: 1

Body

application/json

script_bodystringRequired

The script to execute on the machine: PowerShell on Windows machines, bash on Linux machines

Responses

200

Script execution result

application/json

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-02-05T10:10:22Z

resultstringOptional

The script output, or an empty string if the call timed out

Example: Wednesday, February 4, 2026 11:55:10 AM

400

Bad request

application/json

404

Machine not found

application/json

4710

Permission required

application/json

post/machines/{id}/run-script

HTTPcURLJavaScriptPython

POST /organization-management/v1/machines/{id}/run-script HTTP/1.1
Host: api.vagon.io
Content-Type: application/json
Accept: */*
Content-Length: 64

{
  "script_body": "Write-Output \"PowerShell script is working!\""
}

{
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:10:22Z",
  "result": "Wednesday, February 4, 2026 11:55:10 AM"
}

Bulk Create & Assign Computers

post

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

{
  "plan_id": 42,
  "dry_run": true,
  "rows": [
    {
      "email": "[e-mail]",
      "region": "europe",
      "template_name": "Design Template",
      "disk_size": "275",
      "applications": [
        "Blender",
        "Maya"
      ]
    },
    {
      "email": "[e-mail]",
      "region": "europe"
    },
    {
      "region": "europe",
      "template_name": "Design Template"
    }
  ]
}

Response Example

{
    "results": {
        "[e-mail]": {
            "invitation": "created",
            "machine_id": 8085,
            "disk_size": 275,
            "template": "assigned: Design Template"
        },
        "[e-mail]": {
            "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"
}

Body

application/json

plan_idintegerOptional

Computer plan to assign; falls back to the org default when omitted

dry_runbooleanOptional

When true, preview only — no changes are persisted

Responses

200

Bulk computer assignment result

application/json

400

Bad request

application/json

4710

Permission required

application/json

post/machines/bulk-create

HTTPcURLJavaScriptPython

POST /organization-management/v1/machines/bulk-create HTTP/1.1
Host: api.vagon.io
Content-Type: application/json
Accept: */*
Content-Length: 171

{
  "plan_id": 42,
  "dry_run": true,
  "rows": [
    {
      "email": "[e-mail]",
      "region": "europe",
      "template_name": "Design Template",
      "disk_size": "275",
      "applications": [
        "Blender",
        "Maya"
      ]
    }
  ]
}

{
  "results": {
    "[e-mail]": {
      "invitation": "created",
      "machine_id": 8085,
      "disk_size": 175,
      "os": "windows",
      "template": "partial_assigned: Unreal Engine, Figma"
    },
    "[e-mail]": {
      "invitation": "created",
      "machine_id": 8086,
      "disk_size": 275,
      "os": "linux",
      "template": "assigned: ASANA"
    },
    "[e-mail]": {
      "invitation": "created",
      "machine_id": 8087,
      "disk_size": 225,
      "os": "windows",
      "template": "partial_assigned: Figma, Blender"
    }
  },
  "summary": {
    "total": 3,
    "invalid": 0,
    "assigned": 3
  }
}

Get Machine Sessions

get

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

{
    "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"
}

Path parameters

idintegerRequired

(Required) Machine ID

Example: 1

Responses

200

List of machine sessions

application/json

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-01-28T13:41:54Z

400

Bad request

application/json

404

Machine not found

application/json

4710

Permission required

application/json

get/machines/{id}/sessions

HTTPcURLJavaScriptPython

GET /organization-management/v1/machines/{id}/sessions HTTP/1.1
Host: api.vagon.io
Accept: */*

{
  "sessions": [
    {
      "id": "2107",
      "type": "machine_session",
      "attributes": {
        "start_at": "2026-02-04T11:51:57.736Z",
        "end_at": "2026-02-03T13:22:32.016Z",
        "duration": 7
      }
    }
  ],
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-01-28T13:41:54Z"
}

List Machine Tasks

get

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

{
  "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"
}

Path parameters

idintegerRequired

Machine ID

Example: 1

Query parameters

pageintegerOptional

Page number (default: 1)

Example: 1

per_pageintegerOptional

Results per page

Example: 20

Responses

200

List of tasks for the machine

application/json

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-02-05T10:10:22Z

countintegerOptional

Total number of tasks returned

Example: 1

pageintegerOptional

Current page number

Example: 1

next_pageinteger · nullableOptional

Next page number (null if no more pages)

404

Machine not found or does not belong to the organization

application/json

4710

Permission required

application/json

get/machines/{id}/tasks

HTTPcURLJavaScriptPython

GET /organization-management/v1/machines/{id}/tasks HTTP/1.1
Host: api.vagon.io
Accept: */*

{
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:10:22Z",
  "tasks": [
    {
      "id": "42",
      "type": "task",
      "attributes": {
        "uid": "my-research-project",
        "status": "active",
        "source_path": "C:\\Users\\Administrator\\Desktop\\my-research-project",
        "snapshot_destination": "V:\\my-research-project-snapshots",
        "folder_size": 104857600,
        "created_at": "2026-03-30T10:00:00Z"
      }
    }
  ],
  "count": 1,
  "page": 1,
  "next_page": null
}

Create or Activate Machine Task

post

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"

{
  "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"

{
  "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"

{
  "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"
}

Path parameters

idintegerRequired

Machine ID

Example: 1

Query parameters

pageintegerOptional

Page number (default: 1)

Example: 1

per_pageintegerOptional

Results per page

Example: 20

Body

application/json

uidstring · max: 255Required

Task identifier used as the Desktop folder name. Must not contain Windows-reserved characters.

Example: my-research-project

Responses

200

Task created, reactivated, or already active

application/json

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-02-05T10:10:22Z

resultstring · enumOptional

Outcome of the operation

Example: createdPossible values:

404

Machine not found or does not belong to the organization

application/json

4206

Machine is not off — tasks can only be modified when the machine is stopped

application/json

4216

Invalid task UID (empty, exceeds 255 characters, or contains reserved characters)

application/json

4217

Task UID was previously deleted and cannot be reused

application/json

4218

Backup is not enabled for this seat

application/json

4710

Permission required

application/json

post/machines/{id}/tasks

HTTPcURLJavaScriptPython

POST /organization-management/v1/machines/{id}/tasks HTTP/1.1
Host: api.vagon.io
Content-Type: application/json
Accept: */*
Content-Length: 29

{
  "uid": "my-research-project"
}

{
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:10:22Z",
  "task": {
    "id": "42",
    "type": "task",
    "attributes": {
      "uid": "my-research-project",
      "status": "active",
      "source_path": "C:\\Users\\Administrator\\Desktop\\my-research-project",
      "snapshot_destination": "V:\\my-research-project-snapshots",
      "folder_size": 104857600,
      "created_at": "2026-03-30T10:00:00Z"
    }
  },
  "result": "created"
}

Delete Machine Task

delete

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

{
  "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"
}

Path parameters

idintegerRequired

Machine ID

Example: 1

task_idintegerRequired

Task ID

Example: 42

Responses

200

Task deleted successfully

application/json

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-02-05T10:10:22Z

resultstring · enumOptional

Outcome of the operation

Example: createdPossible values:

404

Task not found, already deleted, or belongs to a different seat

application/json

4206

Machine is not off — tasks can only be modified when the machine is stopped

application/json

4219

Cannot delete the default "Outputs" task

application/json

4710

Permission required

application/json

delete/machines/{id}/tasks/{task_id}

HTTPcURLJavaScriptPython

DELETE /organization-management/v1/machines/{id}/tasks/{task_id} HTTP/1.1
Host: api.vagon.io
Accept: */*

{
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:10:22Z",
  "task": {
    "id": "42",
    "type": "task",
    "attributes": {
      "uid": "my-research-project",
      "status": "active",
      "source_path": "C:\\Users\\Administrator\\Desktop\\my-research-project",
      "snapshot_destination": "V:\\my-research-project-snapshots",
      "folder_size": 104857600,
      "created_at": "2026-03-30T10:00:00Z"
    }
  },
  "result": "created"
}