PUBLIC ALPHABiztraak is now in public alpha. Share feedback
Biztraak
API Docs
Getting Started Authentication Authorization GraphQL REST API API Errors Compliance API Error Codes Swagger/OpenAPI and REST API Operations Virtual Machine API

Virtual Machine API

Biztraak exposes both GraphQL and REST surfaces for virtual machine runtime operations and managed VM-hosted workload deploys.

Use this guide when you need to:

  • automate VM runtime actions
  • configure or inspect VM-hosted workloads
  • trigger a managed deploy to a specific VM provider
  • integrate a VM agent with the platform runtime contract

What is exposed

VM Runtime Operations

Available operations include:

  • start a virtual machine
  • stop a virtual machine
  • read runtime status
  • update the shutdown timer
  • extend the shutdown timer
  • fetch system logs
  • create a browser session

VM-hosted Workload Operations

Available operations include:

  • create or update a project component with VM-hosting fields
  • deploy a VM-hosted workload to one explicit VM provider
  • inspect hosted workload desired state on the project component
  • inspect hosted workload runtime state on the project component provider

VM Agent Operations

The VM agent API is intended for platform integration running inside a VM. It supports:

  • agent registration
  • command claiming
  • heartbeats
  • command completion
  • command failure reporting

REST Endpoints

Virtual machine runtime

  • POST /api/virtual-machines/{serviceProviderId}/start
  • POST /api/virtual-machines/{serviceProviderId}/stop
  • GET /api/virtual-machines/{serviceProviderId}/status
  • POST /api/virtual-machines/{serviceProviderId}/timer
  • POST /api/virtual-machines/{serviceProviderId}/timer/extend
  • GET /api/virtual-machines/{serviceProviderId}/system-logs
  • POST /api/virtual-machines/{serviceProviderId}/session

Project components with VM-hosting fields

  • POST /api/projects/v1/projects/{projectId}/components
  • PUT /api/projects/v1/projects/{projectId}/components/{projectComponentId}
  • GET /api/projects/v1/projects/{projectId}/components
  • GET /api/projects/v1/projects/{projectId}/components/{projectComponentId}

Relevant VM-hosting fields include:

  • HostedOnVirtualMachine component dependency on the workload component
  • virtualMachineHostingMode
  • virtualMachineExposureMode
  • virtualMachineIsPublic
  • virtualMachineRoutePrefix
  • teamDomainId
  • virtualMachineContainerPort
  • virtualMachineCpuLimit
  • virtualMachineMemoryLimitMb
  • virtualMachineHealthCheckProtocol
  • virtualMachineHealthCheckPath
  • virtualMachineHealthCheckPort
  • virtualMachineUseManagedPipelineDeploy

Deploy a VM-hosted workload

  • POST /api/projects/v1/projects/{projectId}/components/{projectComponentId}/deploy-hosted-workload

Request body:

  • hostProjectComponentServiceProviderId

VM agent integration

  • POST /api/virtual-machine-agent/register
  • POST /api/virtual-machine-agent/commands/claim
  • POST /api/virtual-machine-agent/commands/{commandId}/heartbeat
  • POST /api/virtual-machine-agent/commands/{commandId}/complete
  • POST /api/virtual-machine-agent/commands/{commandId}/fail

GraphQL Surface

VirtualMachineQuery

  • availableInstanceTypes
  • virtualMachineSystemLogs
  • virtualMachineBrowserSession

VirtualMachineMutation

  • pendingVirtualMachineAccessPassword
  • confirmVirtualMachineAccessPasswordSaved
  • regenerateVirtualMachineAccessPassword
  • startVirtualMachine
  • stopVirtualMachine
  • updateVirtualMachineShutdownTimer
  • extendVirtualMachineShutdownTimer

VirtualMachineHostedWorkloadMutation

  • deployHostedWorkload

The deploy mutation requires an explicit host VM provider selection. It does not assume a default provider when several exist.

Integration Rules

Host selection

A VM-hosted workload must always reference a host VM project component.

Provider selection

Managed deploys must target one explicit VM provider. If the host VM has multiple deployed providers, the caller must choose one.

Capability gating

The selected VM composition must advertise the capabilities required by the requested workload behavior. Examples:

  • HostedContainerRuntime
  • ReverseProxyPathRouting
  • ReverseProxyHostnameRouting
  • TlsTermination
  • ManagedHostedWorkloadDeploy

Current managed deploy path

The current managed runtime path requires the workload to already have a container image configured.

Common Failure Cases

  • host component is missing or is not a virtual machine
  • host VM belongs to a different project
  • route prefix is already in use on the selected VM
  • route prefix is reserved by the VM template or add-ons
  • selected domain is already in use on the selected VM
  • selected VM does not support the required ingress or deploy capability
  • managed deploy was requested without an image-backed workload

Related docs

Use the VM API surface when you need explicit control over VM lifecycle, VM-hosted workload targeting, and managed runtime execution.