# VMArea Developer Docs

## Docs

- [Create a manual backup](https://docs.vmarea.com/api-reference/backups/create-a-manual-backup.md): Enqueue a manual backup job for the VM. The VM must have daily backups enabled and remain under the per-VM backup cap. Requires the `backups:write` scope.
- [Delete a backup](https://docs.vmarea.com/api-reference/backups/delete-a-backup.md): Delete the backup from Proxmox storage and remove its database record. Backups still in `CREATING` cannot be deleted. Requires the `backups:write` scope.
- [Get a single backup](https://docs.vmarea.com/api-reference/backups/get-a-single-backup.md): Fetch one backup by id, scoped to the parent VM. Requires the `backups:read` scope.
- [List backups for a VM](https://docs.vmarea.com/api-reference/backups/list-backups-for-a-vm.md): Paginated list of backups for the given VM. Requires the `backups:read` scope.
- [Restore a backup over the source VM](https://docs.vmarea.com/api-reference/backups/restore-a-backup-over-the-source-vm.md): Enqueue a restore action that overwrites the parent VM's disk(s) with the backup contents. Returns 202 with an action id to poll. Requires the `backups:write` scope.
- [Download invoice PDF](https://docs.vmarea.com/api-reference/billing/download-invoice-pdf.md): Download the invoice as a PDF file.
- [Get bandwidth usage](https://docs.vmarea.com/api-reference/billing/get-bandwidth-usage.md): Returns current billing-cycle bandwidth usage for every VM on the account.
- [Get invoice](https://docs.vmarea.com/api-reference/billing/get-invoice.md): Retrieve a single invoice by ID, including line items.
- [Get wallet](https://docs.vmarea.com/api-reference/billing/get-wallet.md): Returns the current wallet balance and metadata for the authenticated account.
- [List invoices](https://docs.vmarea.com/api-reference/billing/list-invoices.md): Paginated list of monthly invoices for the authenticated account.
- [List VM bandwidth packs](https://docs.vmarea.com/api-reference/billing/list-vm-bandwidth-packs.md): Paginated list of bandwidth pack purchases for a specific VM.
- [List wallet transactions](https://docs.vmarea.com/api-reference/billing/list-wallet-transactions.md): Paginated ledger of wallet credits and debits, optionally filtered by type, date range, or keyword.
- [Get OS template](https://docs.vmarea.com/api-reference/catalog/get-os-template.md): Look up an OS distribution or template by slug. Distribution slugs return all versions; template slugs return the specific version with its distribution.
- [Get plan](https://docs.vmarea.com/api-reference/catalog/get-plan.md): Retrieve a single active plan by its slug.
- [Get region](https://docs.vmarea.com/api-reference/catalog/get-region.md): Retrieve a single active region by its slug.
- [List OS templates](https://docs.vmarea.com/api-reference/catalog/list-os-templates.md): Returns all active OS distributions grouped with their available version templates.
- [List plans](https://docs.vmarea.com/api-reference/catalog/list-plans.md): Returns all active VM plans with pricing and resource specifications.
- [List regions](https://docs.vmarea.com/api-reference/catalog/list-regions.md): Returns all active deployment regions with availability status.
- [Add a rule to a firewall](https://docs.vmarea.com/api-reference/firewalls/add-a-rule-to-a-firewall.md): Creates a rule and re-syncs the security group. The rule is rolled back if the upstream sync fails.
- [Bind a firewall to a VM](https://docs.vmarea.com/api-reference/firewalls/bind-a-firewall-to-a-vm.md): Binds the firewall's security group to the named VM and re-syncs the VM's group references upstream.
- [Create a firewall](https://docs.vmarea.com/api-reference/firewalls/create-a-firewall.md): Creates a firewall with an optional initial rule set and pushes it to the upstream provider. Rolls the DB row back if the upstream sync fails.
- [Delete a firewall](https://docs.vmarea.com/api-reference/firewalls/delete-a-firewall.md): Removes the firewall from the database and the upstream provider. Fails with 409 if any VM bindings remain.
- [Delete a firewall rule](https://docs.vmarea.com/api-reference/firewalls/delete-a-firewall-rule.md): Removes a rule and re-syncs the security group. Returns 502 if the upstream sync fails.
- [Get a firewall](https://docs.vmarea.com/api-reference/firewalls/get-a-firewall.md): Fetches a single firewall including its full rule set and the VMs it is bound to.
- [List firewalls](https://docs.vmarea.com/api-reference/firewalls/list-firewalls.md): Returns the authenticated user's firewalls with rule/binding counts, paginated.
- [List rules for a firewall](https://docs.vmarea.com/api-reference/firewalls/list-rules-for-a-firewall.md): Returns every rule on the firewall, ordered by position ascending.
- [Rename or re-describe a firewall](https://docs.vmarea.com/api-reference/firewalls/rename-or-re-describe-a-firewall.md): Updates the name and/or description. Rule and binding edits use their dedicated sub-resources.
- [Unbind a firewall from a VM](https://docs.vmarea.com/api-reference/firewalls/unbind-a-firewall-from-a-vm.md): Removes the binding and re-syncs the VM's group references upstream.
- [Update a firewall rule](https://docs.vmarea.com/api-reference/firewalls/update-a-firewall-rule.md): Patches an existing rule and re-syncs the security group. Returns 502 if the upstream sync fails.
- [Attach a VM to a private network](https://docs.vmarea.com/api-reference/networks/attach-a-vm-to-a-private-network.md): Adds a NIC on the VM tied to this network's VNet and reserves a DHCP-assigned private IP. VM and network must reside in the same region.
- [Create a private network](https://docs.vmarea.com/api-reference/networks/create-a-private-network.md): Provisions a new SDN zone + VNet on the chosen Proxmox node. Rolls back the DB row if the upstream provisioning call fails.
- [Delete a private network](https://docs.vmarea.com/api-reference/networks/delete-a-private-network.md): Removes the network from the database and tears it down on Proxmox. Fails with 409 if any VMs are still attached.
- [Detach a VM from a private network](https://docs.vmarea.com/api-reference/networks/detach-a-vm-from-a-private-network.md): Removes the VM's NIC on this network. Best-effort on the Proxmox side: the DB row is always removed even if the upstream detach fails.
- [Get a private network](https://docs.vmarea.com/api-reference/networks/get-a-private-network.md): Fetches a single private network owned by the caller.
- [List private networks](https://docs.vmarea.com/api-reference/networks/list-private-networks.md): Returns the authenticated user's private networks, paginated.
- [List VMs attached to a network](https://docs.vmarea.com/api-reference/networks/list-vms-attached-to-a-network.md): Returns every VM attached to the given private network, including the assigned private IP.
- [Rename a private network](https://docs.vmarea.com/api-reference/networks/rename-a-private-network.md): Updates the human-readable name of a private network. Other fields are immutable in v1.
- [Create a snapshot](https://docs.vmarea.com/api-reference/snapshots/create-a-snapshot.md): Enqueue a snapshot job for the VM. The VM must be provisioned and remain under the per-VM snapshot cap. Snapshot storage is billed daily by a background worker. Requires the `backups:write` scope.
- [Delete a snapshot](https://docs.vmarea.com/api-reference/snapshots/delete-a-snapshot.md): Remove the snapshot from Proxmox and the database. Requires the parent VM to be provisioned. Requires the `backups:write` scope.
- [Get a single snapshot](https://docs.vmarea.com/api-reference/snapshots/get-a-single-snapshot.md): Fetch one snapshot by id, scoped to the parent VM. Requires the `backups:read` scope.
- [List snapshots for a VM](https://docs.vmarea.com/api-reference/snapshots/list-snapshots-for-a-vm.md): Paginated list of snapshots for the given VM. Requires the `backups:read` scope.
- [Roll a VM back to a snapshot](https://docs.vmarea.com/api-reference/snapshots/roll-a-vm-back-to-a-snapshot.md): Enqueue a snapshot rollback action. The VM disk state is restored to the snapshot. Returns 202 with an action id to poll. Requires the `backups:write` scope.
- [Add SSH key](https://docs.vmarea.com/api-reference/ssh-keys/add-ssh-key.md): Register a new SSH public key on the account.
- [Delete SSH key](https://docs.vmarea.com/api-reference/ssh-keys/delete-ssh-key.md): Remove an SSH key from the account. Fails if the key is attached to any VM.
- [Get SSH key](https://docs.vmarea.com/api-reference/ssh-keys/get-ssh-key.md): Retrieve a single SSH key by ID.
- [List SSH keys](https://docs.vmarea.com/api-reference/ssh-keys/list-ssh-keys.md): Paginated list of SSH public keys registered on the account.
- [Rename SSH key](https://docs.vmarea.com/api-reference/ssh-keys/rename-ssh-key.md): Update the display name of an SSH key.
- [Create a virtual machine](https://docs.vmarea.com/api-reference/vms/create-a-virtual-machine.md): Provision a new VM. Charges the user wallet immediately for the first cycle (plus any addons) and enqueues the create action. Returns 202 with the VM detail and the action id to poll. Requires the `vms:write` scope.
- [Delete a virtual machine](https://docs.vmarea.com/api-reference/vms/delete-a-virtual-machine.md): Soft-delete a VM and enqueue the destroy action. Returns 409 if the VM is protected. Requires the `vms:write` scope.
- [Get a single VM action](https://docs.vmarea.com/api-reference/vms/get-a-single-vm-action.md): Fetch one lifecycle action by id, scoped to the parent VM. Used for polling the result of a 202 response. Requires the `vms:read` scope.
- [Get a virtual machine](https://docs.vmarea.com/api-reference/vms/get-a-virtual-machine.md): Fetch a single VM by id, including SSH keys, firewalls, and attached private networks. Requires the `vms:read` scope.
- [List actions for a VM](https://docs.vmarea.com/api-reference/vms/list-actions-for-a-vm.md): Paginated history of lifecycle actions (start, stop, rebuild, etc.) executed against the VM. Requires the `vms:read` scope.
- [List virtual machines](https://docs.vmarea.com/api-reference/vms/list-virtual-machines.md): Paginated list of VMs owned by the authenticated token's user. Requires the `vms:read` scope.
- [Rebuild a virtual machine](https://docs.vmarea.com/api-reference/vms/rebuild-a-virtual-machine.md): Reinstall the VM from the chosen OS template. Optionally replace the SSH key set and/or the root password. Returns 409 if the VM is protected. Requires the `vms:write` scope.
- [Reset a VM's root password](https://docs.vmarea.com/api-reference/vms/reset-a-vms-root-password.md): Enqueue a root password reset. If `password` is omitted a strong random one is generated and surfaced via the action result. Requires the `vms:write` scope.
- [Restart a virtual machine](https://docs.vmarea.com/api-reference/vms/restart-a-virtual-machine.md): Enqueue a reboot action for the VM. Requires the `vms:write` scope.
- [Start a virtual machine](https://docs.vmarea.com/api-reference/vms/start-a-virtual-machine.md): Enqueue a power-on action for a stopped VM. Requires the `vms:write` scope.
- [Stop a virtual machine](https://docs.vmarea.com/api-reference/vms/stop-a-virtual-machine.md): Enqueue a graceful shutdown action for a running VM. Requires the `vms:write` scope.
- [Update a virtual machine](https://docs.vmarea.com/api-reference/vms/update-a-virtual-machine.md): Rename a VM and/or toggle deletion protection. At least one of `name` or `isProtected` must be provided. Requires the `vms:write` scope.
- [Upgrade a VM to a larger plan](https://docs.vmarea.com/api-reference/vms/upgrade-a-vm-to-a-larger-plan.md): Enqueue an upgrade to the specified plan. Downgrades (smaller cpu/ram/disk) are rejected. The vm-action worker handles proration at cycle boundary. Requires the `vms:write` scope.
- [Create a webhook subscription](https://docs.vmarea.com/api-reference/webhooks/create-a-webhook-subscription.md): Creates a new webhook subscription. The signing secret is returned exactly once in this response and never again — store it immediately.
- [Delete a webhook subscription](https://docs.vmarea.com/api-reference/webhooks/delete-a-webhook-subscription.md): Permanently removes the webhook subscription and all associated delivery history.
- [Get a single webhook delivery](https://docs.vmarea.com/api-reference/webhooks/get-a-single-webhook-delivery.md): Returns the full delivery record including the signed payload body and the upstream response text.
- [Get a webhook subscription](https://docs.vmarea.com/api-reference/webhooks/get-a-webhook-subscription.md): Fetches a single webhook subscription. The signing secret is never returned here; it is only available in the create response.
- [List delivery history for a webhook](https://docs.vmarea.com/api-reference/webhooks/list-delivery-history-for-a-webhook.md): Returns the recent delivery attempts for the webhook, paginated. Payload bodies are omitted; use the per-delivery endpoint for the full record.
- [List webhook subscriptions](https://docs.vmarea.com/api-reference/webhooks/list-webhook-subscriptions.md): Returns the authenticated user's webhook subscriptions, paginated. Secrets are never included in list responses.
- [Send a test event](https://docs.vmarea.com/api-reference/webhooks/send-a-test-event.md): Dispatches a synthetic `test` event to every active webhook on the account. Useful for verifying signature handling end-to-end.
- [Update a webhook subscription](https://docs.vmarea.com/api-reference/webhooks/update-a-webhook-subscription.md): Updates URL, events, active flag, or description. Re-enabling a webhook resets its consecutive failure counter.
- [Authentication](https://docs.vmarea.com/en/authentication.md): How to authenticate with the VMArea Public API using API tokens.
- [Errors](https://docs.vmarea.com/en/errors.md): How the VMArea API signals errors: the response envelope, HTTP status codes, and validation error shape.
- [Idempotency](https://docs.vmarea.com/en/idempotency.md): Use the Idempotency-Key header to safely retry write requests without creating duplicate resources.
- [Introduction](https://docs.vmarea.com/en/introduction.md): VMArea is an HTTP API for provisioning and managing virtual machines, networks, firewalls, and billing.
- [Quickstart](https://docs.vmarea.com/en/quickstart.md): Get from zero to a running VM in under five minutes.
- [Rate limits](https://docs.vmarea.com/en/rate-limits.md): The VMArea API enforces two stacked rate-limit buckets. Learn the thresholds, response headers, and how to handle 429s gracefully.
- [Scopes & permissions](https://docs.vmarea.com/en/scopes.md): API tokens carry a subset of permissions chosen at creation. This page lists every available scope and what it grants.
- [Versioning](https://docs.vmarea.com/en/versioning.md): How VMArea versions the Public API and what backwards-compatibility guarantees you can rely on.
- [Webhooks](https://docs.vmarea.com/en/webhooks.md): Subscribe to VMArea events and receive real-time HTTP POST notifications at your own HTTPS endpoint.

## OpenAPI Specs

- [openapi](https://docs.vmarea.com/api-reference/openapi.json)