> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vmarea.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get from zero to a running VM in under five minutes.

## Prerequisites

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

<Steps>
  <Step title="Create an API token">
    Sign in to [vmarea.com/dashboard](https://vmarea.com/dashboard) and navigate to **Settings → API Keys**. Create a new token, select the scopes you need, and optionally set an expiry date.

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

    ```bash theme={null}
    export VMAREA_TOKEN="vmk_..."
    ```

    See [Scopes & permissions](/en/scopes) for a full list of available scopes and what they grant.
  </Step>

  <Step title="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.

    <CodeGroup>
      ```bash Plans theme={null}
      curl https://api.vmarea.com/api/public/v1/plans \
        -H "x-api-key: $VMAREA_TOKEN"
      ```

      ```bash Regions theme={null}
      curl https://api.vmarea.com/api/public/v1/regions \
        -H "x-api-key: $VMAREA_TOKEN"
      ```

      ```bash OS templates theme={null}
      curl https://api.vmarea.com/api/public/v1/os-templates \
        -H "x-api-key: $VMAREA_TOKEN"
      ```
    </CodeGroup>
  </Step>

  <Step title="Create a VM">
    <CodeGroup>
      ```bash curl theme={null}
      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>"
        }'
      ```

      ```js JavaScript theme={null}
      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;
      ```
    </CodeGroup>

    <Check>
      A successful response returns `201` with `{ "success": true, "data": { "id", "status", ... } }`. The VM starts provisioning immediately.
    </Check>
  </Step>

  <Step title="Poll for status">
    VM creation is asynchronous. Poll until `status` reaches `RUNNING` (or `FAILED`):

    <CodeGroup>
      ```bash curl theme={null}
      curl https://api.vmarea.com/api/public/v1/vms/<vm-id> \
        -H "x-api-key: $VMAREA_TOKEN"
      ```

      ```js JavaScript theme={null}
      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));
        }
      }
      ```
    </CodeGroup>

    <Tip>
      Subscribe to a `vm.created` webhook to avoid polling entirely. See [Webhooks](/en/webhooks).
    </Tip>
  </Step>

  <Step title="Run lifecycle actions">
    Once running, control your VM with action endpoints:

    ```bash theme={null}
    # 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.
  </Step>
</Steps>

## Next steps

See the [API reference](/api) for the full surface: firewall rules, private networks, SSH keys, backups, snapshots, and billing endpoints.