diff --git a/Codex/API/DECISIONS.md b/Codex/API/DECISIONS.md
new file mode 100644
index 0000000..d08fd55
--- /dev/null
+++ b/Codex/API/DECISIONS.md
@@ -0,0 +1,13 @@
+# API — Decisions
+
+## Settled
+- API is the heartbeat authority by polling agents.
+- Agent does not push heartbeat/state into API.
+- Semantic readiness uses `/ready`, not plain HTTP 200.
+- Portal should consume API-normalized state, not call agents directly for normal state/actions.
+- streaming upload proxy behavior should remain separate from generic non-streaming `agentClient.js` transport.
+- websocket console proxy behavior should remain separate from generic non-streaming `agentClient.js` transport.
+
+## Tracking rule
+- when API work completes, remove it from `OPEN_ITEMS.md`
+- if it changes the long-lived architecture, update `CURRENT_STATE.md` or this file