# API Overview

The API is the control plane for ZLH customer infrastructure. It accepts authenticated Portal requests, validates ownership and plan limits, talks to Proxmox and platform services, and coordinates work with per-container agents.

## Core responsibilities

- authenticate users and issue access, refresh, and short-lived IDE proxy tokens
- enforce plan limits before provisioning new game or dev containers
- provision containers through Proxmox and configure the in-container agent
- poll agents for liveness, readiness, status, version, update, and player data
- expose normalized server state to the Portal from API-owned cache/state
- forward game control actions, console commands, file operations, mod operations, backup operations, and dev code-server controls to agents
- publish and tear down public routing, DNS, Velocity, Prometheus SD, and hosted IDE integration points
- handle Stripe billing checkout, plan changes, webhooks, portal sessions, and limited reconciliation
- provide hosted IDE reverse proxy and websocket handling for dev containers

## Active route boundaries

- `/api/instances` is the active instance list/create surface
- `GET /api/instances` currently exposes `ContainerInstance` rows and is still used for lookup/discovery by some Portal-side code paths
- `POST /api/instances` is the agent-driven provisioning entrypoint
- `/api/containers/:vmid` is the cleanup/delete/orphan-remediation surface for partially created, manually deleted, or otherwise orphaned containers
- `/api/servers`, `/api/game`, `/api/dev`, and console proxy routes remain the main Portal-facing runtime/control surfaces

## Agent relationship

Agents own container-local behavior. The API owns the external contract.

The API polls agents instead of waiting for pushed state. `/health` is liveness, `/ready` is semantic readiness, and `/status` is the detailed runtime snapshot. The Portal should read API-normalized state rather than contacting agents directly.

There is no API-native `/api/agent/:serverId/:action` route in `zpack-api`. The reviewed Portal repo contained a Portal-side bridge route with that shape, but it is Portal-owned compatibility behavior rather than an API feature.

## Response and proxy behavior

Most non-streaming agent calls go through `agentClient.js`. Streaming upload and websocket console proxying stay outside that helper because they need raw socket or request-stream handling.

Backup responses are currently forwarded with the agent HTTP status. Successful bodies pass through. Non-OK bodies use the shared envelope `{ error, details }` until the backup response contract is normalized.

## Legacy / retired paths

- the older worker-based provisioning chain is no longer treated as a live API path and has been archived for reference
- legacy port allocation / slot reservation is no longer treated as part of the active provisioning model and has been removed from the live route mounts
- current provisioning and edge publish behavior should be understood as request-driven rather than allocator-driven

## Not owned here

- Portal-only UI behavior
- agent-local implementation details
- infrastructure backup strategy such as PBS
- manual platform operations that do not change API behavior