Live controls and observations

Read /v1/session and /v1/snapshot first. Capabilities describe what this adapter can do; snapshot health, run ID, revisions, native phase, pause/replay and expected preimages determine whether it can do it now. Schema enum membership alone does not establish availability.

Mutating command pattern

Acquire POST /v1/control/lease with your client_id and bounded ttl_seconds.
Read the current snapshot and the relevant settings/control catalog.
Persist a unique command_id with the intended operation before sending POST /v1/commands. Include the lease token, same client/run identity and all required expected values/revisions/period preconditions.
Read the command receipt. Applied, rejected, queued and indeterminate have different meanings. Recover a lost response through GET /v1/commands/{id} using the same identity.
Release POST /v1/control/release with the lease token when done. Do not retain leases while idle.

The generated HTTP reference and OpenAPI contain every command variant and required field. Mutation requests are never automatically retried by the SDK. A 409 precondition failure requires a fresh read and an explicit decision, not blind resubmission.

Supported families

Family	Behavior and boundary
Clocks	Guarded game/shot-clock edits with expected period/value; inspect active profile first.
Sliders/options	Named settings and exposed ranges, separate user/CPU slider banks. Runtime changes do not promise disk persistence.
Camera	Named supported exhibition camera and that camera's configurable controls. Not every camera/resolution is visually certified.
Controller preferences	Stored input preferences; distinct from connected device discovery and side assignment.
Coaching	Nine settings per team through original handlers. Live commands require the documented frozen simulation/pause state.
Defense	Six fields per instantiated opponent, including preferred defender. Preferred defender is configuration, not observed physical guarding.
Simulation pause	Owned bounded pause/resume with expected revision and expiry. Existing user pause is not claimed or resumed. Verify frozen-clock state before changing paused-only settings.
Substitution	Native queue/cancel plus separately observed actual entry. A queue receipt does not mean the player is on court.
Rotations	Game-clock lineup plans with native opportunity/entry reporting; not arbitrary frame-exact substitutions.
Timeouts	Original native timeout calls with current eligibility/preconditions; timeout phase and award semantics remain separately observed.
Inputs	Connected logical inputs and team assignment; physical multi-controller certification remains open.
Session stop	Only the original broker-owned matching game/run; finished requires finalized result, cancelled abandons.

Use /v1/substitutions/requests and /v1/rotations/plans to inspect ongoing intent. Native cancellation, supersession, injury/foul/lineup changes and match transitions can prevent a requested entry. Surface that status to the user instead of claiming success from queue acceptance.

Data interpretation

Snapshots include team/player statistics, clocks, physical holder and pause/replay/presentation observations. Physical attachment is not legal team possession; presentation phases are not an authoritative live/dead-ball rule state. Scoped legal state is provided separately through /v1/ball-state with validity, evidence and profile applicability. Preserve unknown/inapplicable fields.

Event cursor continuity, counter deltas, semantic rule observations and reconciled final totals are separate sources. Do not count a rule observation and its correlated counter event as two statistical credits. Do not infer every foul subtype from a numeric value in another domain. Final results retain capture gaps, corrections and verification provenance.