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"
            }
        },
        {
            "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"
            }
        }
    ],
    "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)
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-03-31T16:40:09.859Z",
        "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"
      }
    }
  ],
  "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
                }
            }
        }
    ],
    "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
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-03-31T16:40:09.859Z",
        "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"
      }
    }
  ],
  "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)
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-03-31T16:40:09.859Z",
    "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"
  }
}

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.

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

objectOptional

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

{}

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