> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://americancloud.com/docs/api/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://americancloud.com/docs/api/_mcp/server. # Create a new virtual machine POST https://api.americancloud.com/api/v1/compute/vms Content-Type: application/json Creates a new VM and returns it. To preview pricing without creating anything, use `POST /compute/vms/cost-estimate` instead. Reference: https://americancloud.com/docs/api/api-reference/vms/create-vms ## Authentication - `X-API-Client-ID` header (required) — API Client ID - `X-API-Client-Secret` header (required) — API Client Secret ## Request ### Body (application/json) This endpoint expects a CreateVMDto. - `name` (string, required) — VM name. It must be 1 to 63 characters, start with a letter, end with a letter or a digit, and hold only letters, digits and hyphens. - `region` (string, required) — Region label - `vmPackage` (string, required) — VM package label - `vmSpecs` (VMSpecsDto, required) — VM specifications - `image` (string, required) — Image label to use for the VM - `subscriptionPeriod` (enum, required) — Subscription period - Allowed values: `hourly`, `monthly` - `network` (string, optional) — UUID of a pre-existing network to attach the VM to. Omit to have an isolated network auto-created for the VM (post-create access is then configured via `networkAccess`). An auto-created network is deleted with the VM once its last VM is removed; a network you supply is not. - `tags` (list of string, optional) — List of tags to add to the VM - `keypairs` (list of string, optional) — Names of SSH key pairs to use (optional) - `userdata` (string, optional) — Base64-encoded cloud-init userdata script (optional) - `networkAccess` (NetworkAccessDto, optional) — Optional network access configuration applied after the VM is created. Only honored when no `network` is provided (i.e. an isolated network is auto-created). Applies the requested outbound traffic setting and adds port forwarding + firewall rules for the requested inbound ports against the network's public IP. ## Response ### 201 The virtual machine has been created - `id` (string, required) — Unique identifier for this virtual machine. - `name` (string, required) — Human-readable name for the VM. Shown in dashboards and CLI output. - `status` (string, required) — Current lifecycle state of the VM. Observed values include CREATING, STARTING, CREATED, STARTED, STOPPING, STOPPED, and DESTROYED. Treat this as an open set — new states may be introduced over time. - `region` (string, required) — Region the VM is provisioned in. References a region label from /v1/compute/regions. - `cpu` (integer, required) — Number of virtual CPUs allocated to the VM. - `memoryMb` (integer, required) — Memory allocated to the VM, in megabytes. - `rootDiskGb` (integer, required) — Root disk size, in gigabytes. - `subscriptionPeriod` (string, required) — Billing cadence applied to this VM. - `image` (string, required) — Image label the VM was provisioned from. References /v1/compute/images. - `ipAddress` (string, required) — Primary IP address assigned to the VM on its network. - `networkName` (string, required, nullable) — Name of the network or VPC tier this VM is attached to. Null while the VM is still provisioning. - `networkId` (string, required, nullable) — Identifier of the network or VPC tier this VM is attached to. Null while the VM is still provisioning. - `rootVolumeId` (string, required, nullable) — Identifier of the VM root volume. Null while the VM is still provisioning. - `createdAt` (datetime, required) — When the VM was first provisioned. - `passwordMessage` (string, required) — Human-readable note explaining how the initial VM password will be delivered. - `vmPackage` (string, optional) — Package label identifying the CPU/memory/disk preset this VM uses. - `tags` (list of string, optional) — Tags assigned to this VM for grouping and filtering. - `imageDisplayName` (string, optional) — Friendly name of the source image. - `versionStartedAt` (datetime, optional) — When the current billing version started (set when the VM is scaled or its disk is resized). Only present if the VM has been modified since creation. - `marketplaceApp` (MarketplaceAppDto, optional) — Source marketplace app, when the VM was deployed from one. Absent for OS-only deploys. ## Errors ### 400 Bad Request Error The request was malformed or failed validation. - `statusCode` (double, required) — HTTP status code. - `message` (ApiErrorDtoMessage, required) — Human-readable error message. A single string for most errors, or an array of strings when the request failed multiple validation checks. - `error` (string, optional) — Short HTTP error label. - `code` (string, optional) — Machine-readable reason for the error. Match on this value rather than on `message`, which can be reworded at any time. Present on the errors that have more than one cause for the same status code; omitted otherwise. - `errors` (list of ValidationErrorItemDto, optional) — Per-field validation details. Present on 400 responses produced by request-body validation; omitted otherwise. - `snapshots` (list of BlockingSnapshotDto, optional) — The snapshots that block a delete. Present on a 409 whose `code` is `volume_has_snapshots`; omitted otherwise. ### 401 Unauthorized Error Authentication credentials were missing or invalid. - `statusCode` (double, required) — HTTP status code. - `message` (ApiErrorDtoMessage, required) — Human-readable error message. A single string for most errors, or an array of strings when the request failed multiple validation checks. - `error` (string, optional) — Short HTTP error label. - `code` (string, optional) — Machine-readable reason for the error. Match on this value rather than on `message`, which can be reworded at any time. Present on the errors that have more than one cause for the same status code; omitted otherwise. - `errors` (list of ValidationErrorItemDto, optional) — Per-field validation details. Present on 400 responses produced by request-body validation; omitted otherwise. - `snapshots` (list of BlockingSnapshotDto, optional) — The snapshots that block a delete. Present on a 409 whose `code` is `volume_has_snapshots`; omitted otherwise. ### 403 Forbidden Error The authenticated principal is not permitted to perform this action. - `statusCode` (double, required) — HTTP status code. - `message` (ApiErrorDtoMessage, required) — Human-readable error message. A single string for most errors, or an array of strings when the request failed multiple validation checks. - `error` (string, optional) — Short HTTP error label. - `code` (string, optional) — Machine-readable reason for the error. Match on this value rather than on `message`, which can be reworded at any time. Present on the errors that have more than one cause for the same status code; omitted otherwise. - `errors` (list of ValidationErrorItemDto, optional) — Per-field validation details. Present on 400 responses produced by request-body validation; omitted otherwise. - `snapshots` (list of BlockingSnapshotDto, optional) — The snapshots that block a delete. Present on a 409 whose `code` is `volume_has_snapshots`; omitted otherwise. ### 404 Not Found Error The requested resource does not exist or is not accessible to the caller. - `statusCode` (double, required) — HTTP status code. - `message` (ApiErrorDtoMessage, required) — Human-readable error message. A single string for most errors, or an array of strings when the request failed multiple validation checks. - `error` (string, optional) — Short HTTP error label. - `code` (string, optional) — Machine-readable reason for the error. Match on this value rather than on `message`, which can be reworded at any time. Present on the errors that have more than one cause for the same status code; omitted otherwise. - `errors` (list of ValidationErrorItemDto, optional) — Per-field validation details. Present on 400 responses produced by request-body validation; omitted otherwise. - `snapshots` (list of BlockingSnapshotDto, optional) — The snapshots that block a delete. Present on a 409 whose `code` is `volume_has_snapshots`; omitted otherwise. ### 500 Internal Server Error An unexpected error occurred on the server. - `statusCode` (double, required) — HTTP status code. - `message` (ApiErrorDtoMessage, required) — Human-readable error message. A single string for most errors, or an array of strings when the request failed multiple validation checks. - `error` (string, optional) — Short HTTP error label. - `code` (string, optional) — Machine-readable reason for the error. Match on this value rather than on `message`, which can be reworded at any time. Present on the errors that have more than one cause for the same status code; omitted otherwise. - `errors` (list of ValidationErrorItemDto, optional) — Per-field validation details. Present on 400 responses produced by request-body validation; omitted otherwise. - `snapshots` (list of BlockingSnapshotDto, optional) — The snapshots that block a delete. Present on a 409 whose `code` is `volume_has_snapshots`; omitted otherwise. ## Types ### VMSpecsDto - `vcpu` (double, required) — Number of virtual CPUs - `memoryMb` (integer, required) — Memory in MB - `rootDiskGb` (integer, required) — Root disk size in GB ### NetworkAccessDto - `allowEgressAll` (boolean, required) — Allow all outbound traffic from the VM, so it can reach the internet. Set to `false` to block all outbound traffic instead. - `inboundPorts` (list of InboundPortDto, optional) — Inbound ports to open on the network's public IP. Omit or empty for no inbound. When provided, port forwarding and firewall rules are created on the source NAT IP. - `sourceCidr` (string, optional) — Source CIDR(s) allowed to reach the inbound ports. Comma-separated for multiple. ### MarketplaceAppDto - `label` (string, required) — Marketplace app slug (URL-safe identifier) - `name` (string, required) — Marketplace app display name - `docsUrl` (string, required, nullable) — Link to the app's docs page. May be null if not configured. ### ApiErrorDtoMessage Human-readable error message. A single string for most errors, or an array of strings when the request failed multiple validation checks. ### ValidationErrorItemDto - `field` (string, required) — Dotted path to the field that failed validation. - `message` (string, required) — Human-readable validation message for this field. ### BlockingSnapshotDto - `id` (string, required) — Snapshot ID. - `name` (string, required) — Snapshot name. ### InboundPortDto - `port` (integer, required) — Port number to open for inbound traffic - `protocol` (enum, required) - Allowed values: `TCP`, `UDP` ## Examples **Request** ```json { "name": "my-new-vm", "region": "us-west-0", "vmPackage": "standard-custom", "vmSpecs": { "vcpu": 2, "memoryMb": 2048, "rootDiskGb": 50 }, "image": "ubuntu-22.04", "subscriptionPeriod": "hourly" } ``` **Response** ```json { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "my-vm", "status": "STARTED", "region": "sjc0", "cpu": 4, "memoryMb": 8192, "rootDiskGb": 50, "subscriptionPeriod": "monthly", "image": "ubuntu-22.04", "ipAddress": "192.168.1.10", "networkName": "production-network", "networkId": "123e4567-e89b-12d3-a456-426614174000", "rootVolumeId": "123e4567-e89b-12d3-a456-426614174000", "createdAt": "2026-05-29T12:34:56Z", "passwordMessage": "The root password will be emailed to the account owner shortly.", "vmPackage": "standard-2-4", "tags": [ "production", "web-tier" ], "imageDisplayName": "Ubuntu 22.04 LTS", "versionStartedAt": "2026-05-29T12:34:56Z", "marketplaceApp": { "label": "coolify", "name": "Coolify", "docsUrl": "https://coolify.io/docs" } } ``` **SDK Code** ```python import requests url = "https://api.americancloud.com/api/v1/compute/vms" payload = { "name": "my-new-vm", "region": "us-west-0", "vmPackage": "standard-custom", "vmSpecs": { "vcpu": 2, "memoryMb": 2048, "rootDiskGb": 50 }, "image": "ubuntu-22.04", "subscriptionPeriod": "hourly" } headers = { "X-API-Client-ID": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.americancloud.com/api/v1/compute/vms'; const options = { method: 'POST', headers: {'X-API-Client-ID': '', 'Content-Type': 'application/json'}, body: '{"name":"my-new-vm","region":"us-west-0","vmPackage":"standard-custom","vmSpecs":{"vcpu":2,"memoryMb":2048,"rootDiskGb":50},"image":"ubuntu-22.04","subscriptionPeriod":"hourly"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.americancloud.com/api/v1/compute/vms" payload := strings.NewReader("{\n \"name\": \"my-new-vm\",\n \"region\": \"us-west-0\",\n \"vmPackage\": \"standard-custom\",\n \"vmSpecs\": {\n \"vcpu\": 2,\n \"memoryMb\": 2048,\n \"rootDiskGb\": 50\n },\n \"image\": \"ubuntu-22.04\",\n \"subscriptionPeriod\": \"hourly\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-API-Client-ID", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.americancloud.com/api/v1/compute/vms") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["X-API-Client-ID"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"name\": \"my-new-vm\",\n \"region\": \"us-west-0\",\n \"vmPackage\": \"standard-custom\",\n \"vmSpecs\": {\n \"vcpu\": 2,\n \"memoryMb\": 2048,\n \"rootDiskGb\": 50\n },\n \"image\": \"ubuntu-22.04\",\n \"subscriptionPeriod\": \"hourly\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.americancloud.com/api/v1/compute/vms") .header("X-API-Client-ID", "") .header("Content-Type", "application/json") .body("{\n \"name\": \"my-new-vm\",\n \"region\": \"us-west-0\",\n \"vmPackage\": \"standard-custom\",\n \"vmSpecs\": {\n \"vcpu\": 2,\n \"memoryMb\": 2048,\n \"rootDiskGb\": 50\n },\n \"image\": \"ubuntu-22.04\",\n \"subscriptionPeriod\": \"hourly\"\n}") .asString(); ``` ```php request('POST', 'https://api.americancloud.com/api/v1/compute/vms', [ 'body' => '{ "name": "my-new-vm", "region": "us-west-0", "vmPackage": "standard-custom", "vmSpecs": { "vcpu": 2, "memoryMb": 2048, "rootDiskGb": 50 }, "image": "ubuntu-22.04", "subscriptionPeriod": "hourly" }', 'headers' => [ 'Content-Type' => 'application/json', 'X-API-Client-ID' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.americancloud.com/api/v1/compute/vms"); var request = new RestRequest(Method.POST); request.AddHeader("X-API-Client-ID", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"name\": \"my-new-vm\",\n \"region\": \"us-west-0\",\n \"vmPackage\": \"standard-custom\",\n \"vmSpecs\": {\n \"vcpu\": 2,\n \"memoryMb\": 2048,\n \"rootDiskGb\": 50\n },\n \"image\": \"ubuntu-22.04\",\n \"subscriptionPeriod\": \"hourly\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "X-API-Client-ID": "", "Content-Type": "application/json" ] let parameters = [ "name": "my-new-vm", "region": "us-west-0", "vmPackage": "standard-custom", "vmSpecs": [ "vcpu": 2, "memoryMb": 2048, "rootDiskGb": 50 ], "image": "ubuntu-22.04", "subscriptionPeriod": "hourly" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.americancloud.com/api/v1/compute/vms")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```