---
title: "Concepts"
description: "Metalhost API concepts — resource names, authentication, operations, and the Connect HTTP protocol."
url: "https://metalhost.net/docs/developers/concepts"
---

# 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](https://metalhost.net/docs/dashboard/overview.md).

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

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. For safe HTTP retries and a complete polling pattern, see [Operations & idempotency](https://metalhost.net/docs/developers/guides/operations-idempotency.md).

## 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)](https://metalhost.net/docs/developers/guides/cli-vms.md#yaml-manifest). Field tables: [Go SDK → VMs](https://metalhost.net/docs/developers/guides/sdk-vms.md#manifest).

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

{"projectName": "projects/my-app"}
```

Bodies use **proto-JSON** (camelCase). Browse every method in the [API reference](https://metalhost.net/docs/developers/api.md) or copy from [Examples](https://metalhost.net/docs/developers/examples.md).

> **other languages**
>
> Generate clients from `/openapi.yaml`. The Go module is `github.com/AES-Services/metalhost-sdk` — see the [SDK guide](https://metalhost.net/docs/developers/sdk.md).

## What's next

- [CLI quickstart](https://metalhost.net/docs/developers/quickstart.md)
- [Examples cookbook](https://metalhost.net/docs/developers/examples.md)
- [Go SDK — Getting started](https://metalhost.net/docs/developers/sdk.md)
- [Go SDK — VMs](https://metalhost.net/docs/developers/guides/sdk-vms.md)
- [API reference](https://metalhost.net/docs/developers/api.md)