API overview

VirtConsole exposes one REST API with three access levels, plus two ready-made clients: an OpenTofu/Terraform provider and an MCP server for AI agents. Every surface authenticates with a bearer token sent in the Authorization header.

Access surfaces

Surface	Who it is for	Base path	Token comes from
User API	Customers automating their own resources	`/api`	User panel, API
Admin API	Operators automating the whole platform	`/api/v1`	`vcli api:admin-token generate`
Billing API	External billing systems (WHMCS, Blesta, HostBill, Paymenter)	`/api/v1/billing`	`vcli api:billing-token generate`
OpenTofu/Terraform provider	Infrastructure as code	speaks the user API	User panel, API
MCP server	AI agents	speaks the user and admin APIs	depends on the tools you need

User API

The user API is the customer-facing surface. It manages everything a customer can do in the user panel: instances and power actions, SSH keys, profiles, tasks and more. It lives under the /api path.

Create a token in the user panel under API, a standalone sidebar item (not grouped under Account). Tokens can carry an optional IP allow-list; a token with an empty allow-list works from any address. See API tokens for the customer-side guide.

curl https://panel.example.com/api/connect \
  -H "Authorization: Bearer <TOKEN>"

A successful response confirms the token. From there, list instances with GET /api/instances, or act on one instance under /api/instance/{id}/.

Admin API

The admin API is the operator surface. It covers the whole platform: users, hypervisors, plans, subnets, instances, tasks and everything else the admin panel manages. It lives under the /api/v1 path.

Create a token on the management server:

vcli api:admin-token generate

The command asks for an IP address, a name and a description, then prints the token once. Admin tokens are locked to the IP they were registered with; requests from any other address are rejected. See API tokens.

curl https://panel.example.com/api/v1/auth \
  -H "Authorization: Bearer <TOKEN>"

Every admin endpoint, request field and response shape is generated straight from the panel’s route definitions: see the Admin API reference, or download the raw spec at /api/admin/openapi.yaml.

Billing API

The billing API is a narrow surface reserved for external billing systems. It provisions panel users and instances, suspends and terminates them, adds credit, and generates SSO links. It lives under the /api/v1/billing path and is what the WHMCS, Blesta, HostBill and Paymenter modules call.

Create a token on the management server with vcli api:billing-token generate. Like admin tokens, billing tokens are locked to a registered IP: register the outbound IP of your billing system. See API tokens.

curl https://panel.example.com/api/v1/billing/auth \
  -H "Authorization: Bearer <TOKEN>"

OpenTofu/Terraform provider

The iaas provider manages VirtConsole resources as Infrastructure-as-Code over the user API: instances, VPCs and subnets, load balancers, Kubernetes, managed databases, volumes, object storage, DNS, VPN and autoscaling. It ships 35 resources and 10 data sources.

The provider authenticates with a user API token that is locked to the egress IP of the machine running tofu or terraform. Run it from a static IP (a CI runner with a fixed address, a bastion host or a workstation); dynamic-IP environments fail authentication.

provider "iaas" {
  endpoint = "https://panel.example.com/api" # or IAAS_API_ENDPOINT
  token    = var.iaas_token                  # or IAAS_API_TOKEN (prefer the env var)
}

Set endpoint to your panel URL including the /api suffix. See the provider repository at github.com/hypervisor-io/terraform-provider-iaas for the full resource reference.

MCP server

iaas-mcp-server exposes the platform to AI agents as a remote, stateless MCP server using the Streamable-HTTP transport. It registers 380 tools: 309 user tools and 71 curated admin tools, named like user.instance.create and admin.hypervisor.list. Destructive tools require an explicit confirm flag, and create tools wait for the underlying task to finish before returning.

The server passes your bearer token through to the panel, which authorizes it. Use a user token for user.* tools; admin.* tools additionally need an admin token registered to the MCP server’s egress IP. Point the server at your panel and run it:

export IAAS_API_ENDPOINT="https://panel.example.com/api"
./iaas-mcp-server

Then connect any MCP client to https://<mcp-host>/mcp with the header Authorization: Bearer <TOKEN>. See the server repository at github.com/hypervisor-io/iaas-mcp-server for client configuration examples.

OpenAPI reference

The full generated OpenAPI reference ships with the panel. The user API reference is available in the user panel under API, at /user/api/documentation. The endpoint list on this page is intentionally short; use the generated reference for request and response shapes rather than a hand-written list.

Reference on your own installation

Every install generates and ships its own admin and user API references — no separate download, no version mismatch with whatever release you’re running. Open them at:

https://<your-panel>/api/docs — the admin API reference (Scalar UI over the generated OpenAPI spec)
https://<your-panel>/api/docs/user — the user API reference

Both pages are unauthenticated, generated documentation about the API shape (the same content the raw openapi.yaml file already serves), so they’re safe to link from internal runbooks or a support ticket. If you’d rather browse a hosted copy without touching your own panel, docs.virtconsole.com/api/admin and /api/user carry the reference for the latest release.

Common problems

401 or 403 on every request. The token is wrong, disabled, or locked to a different IP than the one you call from. Admin and billing tokens are IP-locked; user tokens with an IP allow-list are too.
The provider or MCP server fails authentication from CI. The runner’s egress IP is not the IP the token is registered with. Use a static-IP runner or register the runner’s IP on a fresh token.