Launch a metered machine for your org, or price one first with dryRun

POST /v1/visor/machines

Provisions a machine owned by the caller's org and answers 201 with the machine. Send dryRun: true to get a PRICE QUOTE instead: 200 with the upstream quote passed through verbatim, nothing launched and nothing spent. Two response shapes on one address is the rule to know, and it is why this is not a typed op.

Metering is not this plane's: the launch fronts the compute provider's resell endpoint, which owns the balance gate and the per-hour meter, and cloud only forwards the tenant. Ownership is the validated principal's org and is never read from the body, so a launch always lands in the caller's OWN tenant and the machine it creates is only ever visible to that tenant. Fails closed: a validated principal is required (403 without one) and size (or its instanceType alias) is required (400).

Request

The document declares no body for POST /v1/visor/machines. The handler is typed in cloud but its shape is not yet emitted, so the fields are not listed here — ask the MCP door's describe for post_visor_machines, which answers from the running route.

Response

The document declares no response body for this operation. It answers 200 on success and the platform error shape on failure — see Errors.

Examples

import { Configuration, VisorApi } from 'hanzoai';

const api = new VisorApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postVisorMachines();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import VisorApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = VisorApi(client).post_visor_machines()

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.VisorAPI.PostVisorMachines(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, visor_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = visor_api::post_visor_machines(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.VisorApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new VisorApi(client).postVisorMachines();

curl -X POST https://api.hanzo.ai/v1/visor/machines \
  -H "Authorization: Bearer $HANZO_API_KEY"

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_compute_regions"
         }
       }
     }'

Visor API · All Hanzo APIs · Interactive reference