API documentation

Talk to every simulated robot

Every Botopia simulator can be driven by a program. This page lists every robot with every command it accepts, shows the Python to send it, and lets you try each command live: open a robot from here and send its commands from this page.

Two ways in

	Website API (PHP)	Training API (Node)
Use it for	remote control, trying things, classroom demos	reinforcement learning, fast experiments
Runs	on this website, next to the simulators (`api/index.php`)	on your own PC: `node server.mjs` from the robotSimulatorAPI repository
The simulator	runs in real time in a browser tab opened with `?remote=CODE`	runs headless, and only moves when you call `step`
Python	`RemoteSession(url, code)`	`BotopiaAPI("http://localhost:8780")`

Both take the same actions and return the same observation, so a script moves from one to the other by changing two lines. The Python client is python/botopia.py in the robotSimulatorAPI repository (standard library only).

Quick start

On the website

Pick a robot below and press Open simulator in the live panel. Or open any simulator yourself with ?remote=CODE added to its address. The tab shows Remote session CODE in its corner. Keep it visible: a browser pauses hidden tabs.
Send commands from this page, or from Python:

On your own PC (training)

node server.mjs          # http://localhost:8780/api/ (Node 22, Chrome)

import sys; sys.path.append("python")
from botopia import BotopiaAPI
api = BotopiaAPI("http://localhost:8780")
env = api.create("go2", lane="stairs")                  # any robot id from the list below
r = api.step(env["id"], {"drive": {"fwd": 0.6}}, dt=0.05)
print(r["obs"]["pose"], r["events"])

The action

An action is one JSON object. Every robot understands drive and motors where it has them; robots with a real-robot interface also take the messages of that interface, with exactly the names and fields of the real robot.

Field	Robots	Meaning	Example

Several fields can be combined, and a field may hold a list of messages: {"ros": [msg1, msg2]}. The answer of an interface message comes back as an event with the same name (webrtc, ros, serial, …). A reset is separate: {"reset": {"lane": "stairs", "seed": 1}} (website) or api.reset(id, lane="stairs") (training).

Observation and events

Field	What it holds
`t`, `robot`, `lane`	simulation time (s), robot id, lane
`pose`	`{x, y, z, yaw, pitch, roll}`: world frame, y up, angles in rad
`velocity`	`{vx, vy, wz}` in the robot frame (m/s, rad/s)
`imu`	`{accel: [x, y, z], gyro: [x, y, z]}` robot frame (x forward, y left, z up)
`motors`	per motor: DC `{pwm, dir, duty, rpm, encoder, current}`, servo `{deg, target}`
`progress`	`{distance, goal}`: metres along the lane, past the obstacle
`stuck`	why the robot can't go on ('' if it can)
`extra`	robot-specific telemetry: see each robot below (topics, states, sensors…)
`done`	true after a terminal event (fell, goal)

Events every robot can raise: collision, blocked, stall, goal. Robot-specific events are listed per robot. Pictures: frame?view=scene (3D view), robot (the robot's own camera), mask (the track as a mask) and extra cameras some robots have.

Lanes

The shared obstacle course; every robot starts in front of the obstacle of the lane you choose.

All robots

Choose a robot: you get its facts, every command it accepts (the buttons of its simulator page, as API actions), the Python for each, and a live panel to try them.

Endpoints

Website API: `api/index.php`

Method	Query	Body	Answer
GET	`?r=sessions`		active sessions `[{session, robot, name, lastSeenSeconds}]`
GET	`?r=state&session=CODE&since=N`		`{info, obs, events, next, active}`; pass `next` as `since` next time
POST	`?r=command&session=CODE`	`{"action": {…}}` and/or `{"reset": {"lane": …}}`	`{seq}`

Training API: `http://localhost:8780/api/`

Method	Path	Body	Answer
GET	`/api/robots`		robot ids and their pages
POST	`/api/envs`	`{robot, lane, seed, options}`	`{id, info, obs}`
POST	`/api/envs/ID/reset`	`{lane, seed}`	`{obs}`
POST	`/api/envs/ID/step`	`{action, dt}`	`{obs, events, reward, done}`
POST	`/api/envs/step`	`{steps: [{id, action, dt}]}`	all environments in one call
GET	`/api/envs/ID/info`, `/obs`, `/frame?view=robot`		info (with `commands`), observation, JPEG
DELETE	`/api/envs/ID`		closes it

The full reference, with Gymnasium wrappers, rewards and the observation vector, is README.md of the API repository. The robot list on this page is api/robots.json, made by python/make_api_docs.py (robotSimulatorAPI) from the simulators themselves.