> ## 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.

# Início rápido

> Do zero a uma VM em execução em menos de cinco minutos.

## 1. Crie um token de API

<Steps>
  <Step title="Acesse o painel">
    Entre em [vmarea.com/dashboard](https://vmarea.com/dashboard) e navegue até **Configurações → API Keys**.
  </Step>

  <Step title="Crie a chave">
    Clique em **New API Key**, dê um nome descritivo, selecione os escopos necessários e, opcionalmente, defina uma data de validade.
  </Step>

  <Step title="Salve o segredo">
    **O segredo é exibido apenas uma vez.** Copie-o imediatamente e armazene em uma variável de ambiente ou gerenciador de segredos.

    ```bash theme={null}
    export VMAREA_TOKEN="vmk_..."
    ```
  </Step>
</Steps>

Consulte [Escopos e permissões](/pt/scopes) para a lista completa de escopos disponíveis.

## 2. Liste planos e regiões disponíveis

Antes de criar uma VM, consulte o catálogo para encontrar um `planId`, `regionId` e `osTemplateId` válidos. Leituras do catálogo não exigem nenhum escopo específico — qualquer token válido funciona.

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

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

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

## 3. Crie uma 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>

Uma resposta bem-sucedida retorna `201` com `{ success: true, data: { id, status, ... } }`. O provisionamento começa imediatamente.

## 4. Aguarde o status

A criação de VM é assíncrona. Faça polling até que `status` chegue a `RUNNING` (ou `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>
  Outra opção é assinar um webhook para `vm.created` e eliminar o polling por completo.
</Tip>

## 5. Ações de ciclo de vida

Com a VM em execução, controle-a com os endpoints de ação:

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

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

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

Todas as ações de ciclo de vida exigem o escopo `vms:write`.

## Próximos passos

<Columns cols={2}>
  <Card title="Referência da API" href="/api">
    Surface completa: regras de firewall, redes privadas, chaves SSH, backups, snapshots e endpoints de faturamento.
  </Card>

  <Card title="Escopos e permissões" href="/pt/scopes">
    Entenda quais escopos cada operação exige.
  </Card>
</Columns>