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
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",
                "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": "[email protected]",
                        "name": "Computer User"
                    }
                },
                "permissions": {
                    "public_internet_access": true,
                    "can_download_from_vagon_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"
                }
            }
        },
        {
            "id": "101",
            "type": "machine",
            "attributes": {
                "name": "Computer #101",
                "last_session_start_at": "2026-01-23T14:12:18.943Z",
                "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,
                    "analytics_collection_enabled": true,
                    "clipboard_enabled": true,
                    "screen_recording_enabled": true,
                    "input_recording_enabled": true
                },
                "friendly_status": "off",
                "usage_source": "machine",
                "task": null
            }
        }
    ],
    "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.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)
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-05-07T17:57:25.497Z",
        "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": "[email protected]",
            "name": "Computer User"
          }
        },
        "permissions": {
          "public_internet_access": true,
          "can_download_from_vagon_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"
        }
      }
    }
  ],
  "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.
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.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",
  "software_ids": [],
  "base_image_id": 100,
  "permissions": {
    "public_internet_access": true,
    "can_download_from_vagon_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,
                "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,
                    "analytics_collection_enabled": false,
                    "clipboard_enabled": true,
                    "screen_recording_enabled": false,
                    "input_recording_enabled": false
                },
                "task": 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.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)
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)

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: 301

{
  "plan_id": 235,
  "quantity": 1,
  "region": "dublin",
  "software_ids": [],
  "base_image_id": null,
  "permissions": {
    "public_internet_access": true,
    "can_download_from_vagon_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-05-07T17:57:25.497Z",
        "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": "[email protected]",
            "name": "Computer User"
          }
        },
        "permissions": {
          "public_internet_access": true,
          "can_download_from_vagon_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"
        }
      }
    }
  ],
  "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.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)
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-05-07T17:57:25.497Z",
    "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": "[email protected]",
        "name": "Computer User"
      }
    },
    "permissions": {
      "public_internet_access": true,
      "can_download_from_vagon_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"
    }
  }
}

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 Vagon machine
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,
    "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: 217

{
  "permissions": {
    "public_internet_access": true,
    "can_download_from_vagon_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"
}

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