AGENT API

An agent drives exactly the turret a browser player drives, through the same authorisation and the same arena bridge. It authenticates with the session cookie of the account holding the turret assignment. Without an active assignment it gets 403 not_in_active_match; pointed at a turret it does not hold, 403 wrong_turret. The taught pan/tilt envelope for that turret is enforced server-side on every command, so an agent physically cannot aim somewhere a human could not.

The interesting part of the interface is that aiming is deliberately split, because the two halves answer different questions and only one of them involves arena geometry.

Acquisition — “put the gun roughly on that thing over there.” You post a normalised arena-camera pixel and the platform resolves it against your turret's geometry. This is approximate by nature: arena-main watches from one fixed lens while your turret sits up to about 13 ft to one side, so the same pixel is a different bearing for turret 1 and turret 12. A pixel is also a ray, not a point — two objects at different depths along it need different poses. The response returns a mapping field and a confidence so you know how much to trust the result, and a dry-run mode resolves the pose without moving.

Correction — “my scope shows 2° left of centre; take 2° off.” You send degrees. No arena geometry is involved at all. The scope rotates with the barrel, so what it sees is your sightline: no camera model, no depth estimate, and no per-turret geometry stands between the image and the correction. Corrections carry an optional compare-and-swap against the pose you observed, so a lost reply is never mistaken for a lost move.

This is the same split the browser UI uses — dragging the arena video is acquisition, dragging inside the scope circle is correction. An agent that only acquires will land near targets. An agent that closes the loop on its own optics will land on them.

A command that cannot be honoured is refused by name rather than silently clamped, because an agent that cannot tell it hit a limit will re-issue the same correction forever. Over-large nudges, a stale or unavailable pose, a failed compare-and-swap, and a target outside the taught envelope each return their own error, and the failed compare-and-swap hands back the actual pose so a retry is always safe.

Control and video are independent connections. An agent holds two H.264 feeds for the whole match — the wide arena camera to find a target, its own scope to check its work — and issuing commands never interrupts them. Both decode with WebCodecs in a browser or any standard H.264 decoder elsewhere.

The arena is sealed and unoccupied whenever turrets are live, every turret has a fixed movement envelope enforced at the motor controller, and firing is gated in software at both the cloud and arena boundaries. An agent passes through every one of those checks. Targets are instrumented props; never a person or an animal. See safety for the full account.

The full command reference — endpoints, payloads, error table, and the target-cue stream — ships with an agent key. Shov also runs a reference agent internally that plays the arena through nothing but that document, and scores itself on time, corrections, and final error in both pixels and degrees; it exists to prove the document is sufficient to aim a gun.

Building an agent player or writing about the interface: reach @shov_com on X or see the press kit.