Using the API

Choosing an auth method

Scenario	Recommended method
Browser-based user session	OIDC login → session cookie
CLI tool or script running as you	Personal Access Token
Third-party app acting on a user’s behalf	OAuth 2.0
CI/CD pipeline	Personal Access Token

Example: list containers with a PAT

curl https://api.hzel.org/api/v1/containers \
  -H "Authorization: Bearer hzel_AbCdEfGhIj…"

Example: create and start a container

# Create
curl -X POST https://api.hzel.org/api/v1/containers \
  -H "Authorization: Bearer hzel_…" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"dev-box","cpu_cores":2,"memory_mb":1024,"disk_gb":20}'

# Start (use the id from the create response)
curl -X POST https://api.hzel.org/api/v1/containers/<id>/start \
  -H "Authorization: Bearer hzel_…"

No CSRF header is needed when using a PAT.

Example: run a command and stream output

# Enqueue
JOB=$(curl -sX POST https://api.hzel.org/api/v1/containers/<id>/commands \
  -H "Authorization: Bearer hzel_…" \
  -H "Content-Type: application/json" \
  -d '{"command":"uname -a"}' | jq -r '.data.id')

# Poll result
curl https://api.hzel.org/api/v1/commands/$JOB \
  -H "Authorization: Bearer hzel_…"

Or stream in real time over WebSocket:

wss://api.hzel.org/ws/jobs/<job_id>?token=hzel_…

Error handling

Always check for an error key before reading data:

const res = await fetch('/api/v1/containers', { headers: { Authorization: `Bearer ${token}` } });
const body = await res.json();
if (body.error) {
  console.error(body.error.code, body.error.message);
} else {
  console.log(body.data);
}