Concepts
The CLI, Go SDK, and raw HTTP all talk to
https://api.metalhost.net. This page covers what you need
to integrate: resource naming, auth, async operations, and the request
format. Dashboard UI concepts live in
How it works.
Resource names
Every object has a fully-qualified resource name — a slash-separated path. The CLI accepts bare slugs; the SDK should use full names.
| Kind | Pattern | Slug example |
|---|---|---|
| Project | projects/{slug} | my-app |
| Organization | organizations/{slug} | acme |
| Datacenter | datacenters/{slug} | us-dal-1 |
| VM | projects/{p}/virtual-machines/{id} | web-1 |
| SSH key | projects/{p}/ssh-keys/{id} | laptop |
| Disk | projects/{p}/disks/{id} | data-1 |
| File share | projects/{p}/file-shares/{id} | shared-data |
| Network | projects/{p}/networks/{id} | — |
| Firewall rule | projects/{p}/firewall-rules/{id} | — |
| Bare metal instance | bare-metal-instances/{slug} | my-box |
| Available host | hosts/{slug} | dal-r740-01 |
| Operation | operations/{id} | op_abc123 |
| API key | api-keys/{id} | — |
| Webhook subscription | webhook-subscriptions/{slug} | deploy-hook |
| Wallet | organizations/{o}/wallets/default | — |
Authentication
Mint an API key in the dashboard (Developers → API keys). Send it on every request:
Authorization: Bearer mh_live_...Environment variables the CLI and SDK share:
| Variable | Purpose |
|---|---|
METALHOST_API_KEY | Bearer token (required) |
METALHOST_ENDPOINT | Default https://api.metalhost.net |
METALHOST_PROJECT | Default projects/… scope |
METALHOST_REGION | Default datacenters/… |
Long-running operations
VM create, delete, resize, clone, and reimage return an
operation field. Poll GetOperation until state
is SUCCEEDED, FAILED, or CANCELLED.
| State | Meaning |
|---|---|
PENDING | Queued |
RUNNING | In progress |
SUCCEEDED | Done — read metadata |
FAILED | Read errorMessage |
On successful VM create, metadata.virtual_machine_name is the
full VM resource name. CLI: metalhost ops wait operations/…
or --wait on mutating commands.
VM manifests
CreateVirtualMachine takes a declarative
VirtualMachineManifest — region, compute, boot, network,
users. Same schema for CLI flags, YAML (vm apply -f), and
SDK structs. Full YAML reference:
CLI → VMs (YAML manifest).
Field tables:
Go SDK → VMs.
HTTP protocol
Connect-RPC over JSON. Every RPC is POST to:
https://api.metalhost.net/aes.<service>.v1.<Service>/<Method>Example:
POST /aes.compute.v1.ComputeService/ListVirtualMachines
Content-Type: application/json
Authorization: Bearer mh_live_...
{"projectName": "projects/my-app"}Bodies use proto-JSON (camelCase). Browse every method in the API reference or copy from Examples.