diff --git a/Codex/API/OVERVIEW.md b/Codex/API/OVERVIEW.md
new file mode 100644
index 0000000..befced3
--- /dev/null
+++ b/Codex/API/OVERVIEW.md
@@ -0,0 +1,34 @@
+# 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, and backup operations 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
+
+## 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.
+
+## 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.
+
+## 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