API surface¶

The browser uses a narrow command API. The backend returns a complete validated snapshot after a successful command.

Runtime¶

GET /api/v1/runtime

This returns safe capability labels. It does not return a provider key or database value.

Session¶

POST   /api/v1/sessions
GET    /api/v1/sessions/{session_id}/snapshot
POST   /api/v1/sessions/{session_id}/commands
DELETE /api/v1/sessions/{session_id}
GET    /api/v1/sessions/{session_id}/counterfactual

Live session routes require the signed session token in X-Orion-Session-Token.

Passport¶

GET /api/v1/passports/{passport_id}
GET /api/v1/sessions/{session_id}/passports/{passport_id}

The unscoped route is not available in live mode. The session-scoped route is the live route. The server returns a manifest-backed Passport projection. The browser does not receive an S3 credential.

Command envelope¶

Commands include:

a command type;
validated input;
an expected snapshot version;
an idempotency key.

The expected version prevents two stale browser views from silently overwriting each other. A version conflict is an explicit error. Refresh the workspace and retry the action.

Command types¶

Command	Purpose
`propose-learning-map`	Create a goal-specific map proposal.
`approve-learning-map`	Approve the learner-edited map.
`reject-learning-map`	Discard the current map proposal.
`select-quest`	Select the quest for an actual teach-back.
`select-hypothesis`	Select one candidate for learner review.
`submit-attempt`	Submit the learner response and confidence.
`decide-gap`	Confirm, correct, defer, or dismiss a hypothesis.
`request-node-proposals`	Ask for a bounded practice proposal.
`approve-node-proposal`	Add one practice proposal to the active map.
`reject-node-proposal`	Keep a practice proposal out of the active map.
`restart`	Rebuild the next mission from durable state.
`forget-gap`	Tombstone one memory and its embedding.

View quest details is a frontend preview. It does not send select-quest. Begin teach-back is the transition to the actual command flow.

Error rule¶

The API returns typed errors for stale versions, unavailable providers, invalid commands, missing sessions, authorization failures, and incomplete deletion. The frontend must show the error and keep learner input when safe.