REST API reference

The Aetheris control panel exposes a JSON REST API. This page summarizes the platform endpoints; the machine-readable contract is the bundled OpenAPI 3.1 specification.

Conventions

• Base URL: https://app.example.com/api.
• Authentication: Authorization: Bearer <session> for platform endpoints; payment webhooks use provider signatures.
• Content type: application/json on requests and responses.
• Errors: { "error": { "code": string, "message": string, "details"?: object } } with appropriate HTTP status codes.

Endpoints

Whitelabel

Servers

Billing

Invoice creation bodies use { "client", "currency", "due_days", "coupon_code", "lines": [{ "description", "quantity", "unit_cents", "tax_rate_pct" }] }. Webhook bodies use { "event", "payment_id", "invoice_number" | "invoice_id", "amount_cents", "currency" } with event one of payment.succeeded, payment.failed, payment.refunded.

Catalog (game hosting)

See Game hosting for the full catalog and the provisioning flow.

Admin

System

Cron job bodies use the shape { "name", "schedule", "task", "enabled" } where schedule is a five-field cron expression and task is one of backup, invoice.dunning, snapshot.prune, sync.pterodactyl, sync.proxmox, sync.virtfusion, report.daily. SFTP user bodies use { "server_id", "username", "home_path", "enabled" }.

// GET /system/status
{
  "version": "1.0.0",
  "latest_release": { "tag": "v1.1.0", "url": "...", "published_at": "2026-08-15T10:00:00Z" },
  "update_available": true,
  "environment": "production",
  "healthy": true
}

Webhooks

Webhook handlers verify signatures, enqueue billing jobs and return 200 quickly; processing happens in the aetheris.billing queue.

Status codes

Authentication

Sessions (interactive clients)

1. POST /auth/login with { "email": string, "password": string }.
2. The response contains an access token (15 minute lifetime) and a refresh token (rotation on every use, revocable).
3. Send the access token as Authorization: Bearer <token> on every request. When it expires, exchange the refresh token at POST /auth/refresh.

API keys (machines and scripts)

Create an API key in the Admin Panel or via POST /admin/api-keys:

Authorization: Bearer <admin-jwt>
 
POST /admin/api-keys
Content-Type: application/json
 
{ "label": "deploy-bot", "scopes": ["servers:write", "billing:read"] }

API keys never expire by default but can be revoked at any time; the audit log records every use. Keep them in your secret manager.

Pagination and filtering

List endpoints are paginated. Query parameters:

Example:

GET /billing/invoices?page=2&per_page=25&sort=due_date:asc&filter=status=open

Responses include a pagination envelope:

{
  "data": [],
  "meta": { "page": 2, "per_page": 25, "total": 312, "total_pages": 13 }
}

Idempotency

Write operations accept an Idempotency-Key header. Retrying the same request with the same key returns the original result instead of executing again - essential for provisioning and payments from scripts with retries.

POST /servers
Idempotency-Key: deploy-2026-08-20-01
Content-Type: application/json

Rate limits

Exceeding a limit returns 429 with a Retry-After header.

Error format

All errors use a consistent shape:

{
  "error": {
    "code": "node_unreachable",
    "message": "Node fra-01 did not respond",
    "details": { "node_id": "fra-01", "attempts": 3 }
  }
}

Machine-readable code values are stable across versions; message is human-facing and may change.

Example: provision a server

TOKEN=$(curl -sS -X POST http://app.example.com/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"ops@example.com","password":"secret"}' \
  | jq -r '.accessToken')
 
curl -sS -X POST http://app.example.com/api/servers \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Idempotency-Key: deploy-001' \
  -H 'Content-Type: application/json' \
  -d '{"plan":"vps-4","node":"fra-01","egg":"nodejs-20"}'

SDK clients

Generated clients can be produced from openapi.yaml with any OpenAPI generator (openapi-generator, orval, openapi-typescript). The typed driver contracts in src/lib/adapters/hypervisors/types.ts are the canonical TypeScript source for hypervisor-facing shapes.