From 1967b3b1bfd15cb50f96653fdb39bb9538fe3d6d Mon Sep 17 00:00:00 2001 From: jester Date: Fri, 24 Apr 2026 18:14:40 +0000 Subject: [PATCH] Update API overview with active route boundaries and retired legacy flows --- Codex/API/OVERVIEW.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/Codex/API/OVERVIEW.md b/Codex/API/OVERVIEW.md index cf9771f..ba39a79 100644 --- a/Codex/API/OVERVIEW.md +++ b/Codex/API/OVERVIEW.md @@ -14,18 +14,34 @@ The API is the control plane for ZLH customer infrastructure. It accepts authent - 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