Quickstart

Prerequisites

You need a VMArea account and at least one available billing credit to provision a VM.

Create an API token

Sign in to vmarea.com/dashboard and navigate to Settings → API Keys. Create a new token, select the scopes you need, and optionally set an expiry date.

The secret is shown only once. Copy it immediately and store it in an environment variable or secrets manager.

export VMAREA_TOKEN="vmk_..."

See Scopes & permissions for a full list of available scopes and what they grant.

List available plans and regions

Before creating a VM, fetch the catalog to find a valid planId, regionId, and osTemplateId. Catalog reads require any valid token — no specific scope needed.

curl https://api.vmarea.com/api/public/v1/plans \
  -H "x-api-key: $VMAREA_TOKEN"

curl https://api.vmarea.com/api/public/v1/regions \
  -H "x-api-key: $VMAREA_TOKEN"

curl https://api.vmarea.com/api/public/v1/os-templates \
  -H "x-api-key: $VMAREA_TOKEN"

Create a VM

curl -X POST https://api.vmarea.com/api/public/v1/vms \
  -H "x-api-key: $VMAREA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-server",
    "hostname": "my-server",
    "planId": "<plan-id>",
    "regionId": "<region-id>",
    "osTemplateId": "<os-template-id>"
  }'

const res = await fetch("https://api.vmarea.com/api/public/v1/vms", {
  method: "POST",
  headers: {
    "x-api-key": process.env.VMAREA_TOKEN,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "my-server",
    hostname: "my-server",
    planId: "<plan-id>",
    regionId: "<region-id>",
    osTemplateId: "<os-template-id>",
  }),
});
const { data } = await res.json();
const vmId = data.id;

A successful response returns 201 with { "success": true, "data": { "id", "status", ... } }. The VM starts provisioning immediately.

Poll for status

VM creation is asynchronous. Poll until status reaches RUNNING (or FAILED):

curl https://api.vmarea.com/api/public/v1/vms/<vm-id> \
  -H "x-api-key: $VMAREA_TOKEN"

async function waitForRunning(vmId) {
  while (true) {
    const res = await fetch(
      `https://api.vmarea.com/api/public/v1/vms/${vmId}`,
      { headers: { "x-api-key": process.env.VMAREA_TOKEN } }
    );
    const { data } = await res.json();
    if (data.status === "RUNNING") return data;
    if (data.status === "FAILED") throw new Error("VM provisioning failed");
    await new Promise((r) => setTimeout(r, 5000));
  }
}

Subscribe to a vm.created webhook to avoid polling entirely. See Webhooks.

Run lifecycle actions

Once running, control your VM with action endpoints:

# Start
curl -X POST https://api.vmarea.com/api/public/v1/vms/<vm-id>/start \
  -H "x-api-key: $VMAREA_TOKEN"

# Stop
curl -X POST https://api.vmarea.com/api/public/v1/vms/<vm-id>/stop \
  -H "x-api-key: $VMAREA_TOKEN"

# Restart
curl -X POST https://api.vmarea.com/api/public/v1/vms/<vm-id>/restart \
  -H "x-api-key: $VMAREA_TOKEN"

All lifecycle actions require the vms:write scope.

Next steps

See the API reference for the full surface: firewall rules, private networks, SSH keys, backups, snapshots, and billing endpoints.

Get started

Authentication

API conventions

Resources

Prerequisites

Next steps

​Prerequisites

​Next steps

Prerequisites

Next steps