Open interface
ANet4D exposes two HTTP interfaces and one realtime protocol:
Interface |
Prefix |
Served by |
For |
|---|---|---|---|
Sandbox REST v1 |
|
sandbox-api (8002 locally; routed by path through nginx on the public instance) |
Visitors, scripts and external agents creating and operating their own sandboxes |
Local runtime API |
|
api (8000 locally) |
Operators and administrators of the local shared show: worlds, fleet, commands, scenarios, runs and system |
Realtime protocol |
WebSocket |
Both api processes |
State streams, command calls, velocity setpoints and events |
The interface and the API have the same rights: every action in the browser maps onto the same interface and passes the same admission and
safety checks. The server provides the OpenAPI 3.1 document of the sandbox interface at /api/sandbox/v1/openapi.json, and the public
instance renders it with copyable examples at /sandbox/api. Python programs should use
the Python SDK, which handles queueing, proof of work, renewal, resume after power saving and decoding of binary frames.
Authentication
Method |
Applies to |
Notes |
|---|---|---|
Public |
|
No credentials, cacheable |
Session token |
|
Issued when the session is created, |
Queue ticket |
|
Issued on entering the queue, |
Token in body |
|
Sent by the browser as a beacon when the page closes, with the token in the request body |
Admin token |
Protected endpoints of the local runtime API |
Generated per run in |
In public mode, creating a session may require a proof of work: fetch a challenge with GET /challenge, solve it and submit it with the
create request; when required, the server returns the challenge with reason code 509.
Error format
Errors are returned as application/problem+json; code is the project reason code (packages/contracts/rt/reasons.json). Sandbox reason
codes are in the range 500 to 599 and are unrelated to HTTP 5xx. The real response of the local shared show to GET /api/worlds without a
token:
{"type":"urn:awr:reason:301","title":"AUTH_REQUIRED","status":401,"code":301,"name":"AUTH_REQUIRED","reason":"AUTH_REQUIRED","message":"缺少 token","detail":null,"remedy":"先签发 token","request_id":"01a135ae-3540-7d01-88af-813820ac3b51"}
Field |
Meaning |
|---|---|
|
Reason code and name, for example 110 |
|
Human-readable description (the server answers in Chinese; this example reads "token missing") |
|
Structured details, for example `{"field": "nest_id |
|
Suggested action (here "issue a token first") |
|
Precise wait in milliseconds when rate limited; the |
|
Request ID; include it when reporting a problem |
Idempotency and rate limits
Create requests (sessions, drones, targets, nests, tasks) accept an Idempotency-Key header, and retries with the same key return the same
result; the SDK generates keys automatically. In public mode each request category is rate limited per session with a token bucket:
Category |
Rate |
Burst |
|---|---|---|
General REST |
10 per second |
30 |
Command calls |
20 per second |
40 |
Clock |
2 per second |
— |
Entity changes |
5 per second |
— |
Tasks |
1 per second |
— |
Velocity setpoints |
50 Hz |
— |
Exceeding a limit returns 429 with reason code 111, and the SDK retries automatically after retry_after_ms. Task inputs have their own
quotas; see Sandbox.
Realtime protocol
The sandbox realtime connection is a WebSocket on GET /api/sandbox/v1/sessions/{sid}/rt with the subprotocols awr.rt.v1 and
bearer.<token>. After connecting, the client subscribes to topics (for example the session state sandbox/session, fleet state and
per-drone perception), and the server sends data according to each client's interest set and credit: the fleet as 32-byte Lite32 records and
the focused drone as 64-byte Full64 records in batches, with structured messages encoded as msgpack. Commands are issued as a call and
return accepted, running and the result in turn; velocity control sends setpoints over the client data channel at up to 50 Hz after the
call. The byte layouts are specified in the design document
docs/17 interface and realtime protocol.
The connection closes with code 4410 when the session ends; power-save parking disconnects with code 4430, and the client resubscribes after resuming the session; switching the world disconnects with 1012, and the client reconnects to the new world.
Sandbox REST v1 endpoints
The table below is generated from packages/contracts/rest/sandbox.openapi.snapshot.json when the documentation is built. Paths are relative
to the prefix /api/sandbox/v1; under "Priority", P1 marks optional capabilities, and endpoints that are not deployed return 404.
Sessions, queue and lifecycle
ID |
Method |
Path |
Description |
Auth |
Priority |
|---|---|---|---|---|---|
SB-00 |
|
|
API version, contract version, access mode, session and queue overview |
Public |
P0 |
SB-01 |
|
|
Availability and admission of the seven worlds |
Public |
P0 |
SB-02 |
|
|
Scenario templates |
Public |
P0 |
SB-03 |
|
|
Fetch a proof-of-work challenge |
Public |
P0 |
SB-04 |
|
|
Create, queue or idempotently return a session |
Public |
P0 |
SB-05 |
|
|
Long-poll the queue state |
Queue ticket |
P0 |
SB-06 |
|
|
Claim an offered slot |
Queue ticket |
P0 |
SB-07 |
|
|
Leave the queue |
Queue ticket |
P0 |
SB-08 |
|
|
Session object (optionally long-polls to a given state) |
Session token |
P0 |
SB-09 |
|
|
End the session |
Session token |
P0 |
SB-10 |
|
|
Renew and reissue the token |
Session token |
P0 |
SB-11 |
|
|
Export a configuration snapshot (available for 10 min after the end) |
Session token |
P0 |
SB-12 |
|
|
Import a configuration snapshot (same world) |
Session token |
P0 |
SB-13 |
|
|
Load a scenario template |
Session token |
P0 |
SB-14 |
|
|
Switch the base world |
Session token |
P0 |
SB-15 |
|
|
Play, pause, rate (through the governor), single step |
Session token |
P0 |
SB-16 |
|
|
Fetch missed events |
Session token |
P0 |
SB-17 |
|
|
End the session when the page closes (token in body) |
Token in body |
P1 |
SB-18 |
|
|
Batch evaluation (local and LAN; 404 on the public site) |
Session token |
P0 |
SB-19 |
|
|
Batch progress and result |
Session token |
P0 |
SB-69 |
|
|
Power-save parking (checkpoint to disk, release the slot) |
Session token |
P0 |
SB-70 |
|
|
Resume from parking (resume ticket when full) |
Session token |
P0 |
SB-71 |
|
|
Public capacity (visible during loading and queueing) |
Public |
P0 |
SB-72 |
|
|
Park beacon (pagehide, token in body) |
Token in body |
P0 |
SB-76 |
|
|
Commander pairing code (P1) |
Session token |
P1 |
SB-77 |
|
|
Join the same sandbox with a pairing code (P1) |
Public |
P1 |
API document and realtime connection
ID |
Method |
Path |
Description |
Auth |
Priority |
|---|---|---|---|---|---|
SB-20 |
|
|
Sandbox OpenAPI 3.1 |
Public |
P0 |
SB-64 |
|
|
Sandbox realtime connection (WebSocket upgrade, subprotocol awr.rt.v1 + bearer.<token>) |
Session token |
P0 |
Airframe and sensor catalog
ID |
Method |
Path |
Description |
Auth |
Priority |
|---|---|---|---|---|---|
SB-21 |
|
|
Airframe catalog (presets) |
Public |
P0 |
SB-22 |
|
|
Full airframe parameters, parameter table and derived quantities |
Public |
P0 |
SB-23 |
|
|
Sensor catalog |
Public |
P0 |
SB-24 |
|
|
Airframes cloned in this session |
Session token |
P0 |
SB-25 |
|
|
Clone and edit an airframe |
Session token |
P0 |
SB-26 |
|
|
Modify a cloned airframe |
Session token |
P0 |
SB-27 |
|
|
Delete a cloned airframe |
Session token |
P0 |
Fleet and commands
ID |
Method |
Path |
Description |
Auth |
Priority |
|---|---|---|---|---|---|
SB-28 |
|
|
Fleet instances |
Session token |
P0 |
SB-29 |
|
|
Add a drone |
Session token |
P0 |
SB-30 |
|
|
Instance and state snapshot |
Session token |
P0 |
SB-31 |
|
|
Modify label, nest, payload or limit profile |
Session token |
P0 |
SB-32 |
|
|
Remove |
Session token |
P0 |
SB-33 |
|
|
Full state |
Session token |
P0 |
SB-34 |
|
|
Payload, specifications, working state, gimbal and zoom |
Session token |
P0 |
SB-35 |
|
|
Issue a command (same as the WebSocket call) |
Session token |
P0 |
SB-36 |
|
|
Acquire a lease |
Session token |
P0 |
SB-37 |
|
|
Release a lease |
Session token |
P0 |
Targets
ID |
Method |
Path |
Description |
Auth |
Priority |
|---|---|---|---|---|---|
SB-40 |
|
|
Targets |
Session token |
P0 |
SB-41 |
|
|
Add a target |
Session token |
P0 |
SB-42 |
|
|
Full target configuration |
Session token |
P0 |
SB-43 |
|
|
Modify a target (JSON Merge Patch) |
Session token |
P0 |
SB-44 |
|
|
Delete a target |
Session token |
P0 |
SB-45 |
|
|
Perception state, effective sensitivity volume, counters, acoustic phase |
Session token |
P0 |
SB-46 |
|
|
Suggested radius from the physical model |
Session token |
P0 |
SB-65 |
|
|
Target class templates |
Public |
P1 |
Perception
ID |
Method |
Path |
Description |
Auth |
Priority |
|---|---|---|---|---|---|
SB-38 |
|
|
Current perception result |
Session token |
P0 |
SB-39 |
|
|
Fetch detection history |
Session token |
P0 |
SB-66 |
|
|
Target tracks (ground truth not exposed) |
Session token |
P1 |
SB-67 |
|
|
Server-side feasibility window query |
Session token |
P1 |
SB-73 |
|
|
Per-pair perception readings |
Session token |
P0 |
SB-74 |
|
|
Emission field profile |
Session token |
P0 |
SB-75 |
|
|
Target perception volumes |
Session token |
P0 |
SB-78 |
|
|
Explicit sample points of a field (cross-check) |
Session token |
P1 |
Tasks, nests and relay
ID |
Method |
Path |
Description |
Auth |
Priority |
|---|---|---|---|---|---|
SB-47 |
|
|
Nests |
Session token |
P0 |
SB-48 |
|
|
Add a nest (optionally with drones inside) |
Session token |
P0 |
SB-49 |
|
|
Nest configuration and state |
Session token |
P0 |
SB-50 |
|
|
Modify a nest |
Session token |
P0 |
SB-51 |
|
|
Delete a nest |
Session token |
P0 |
SB-52 |
|
|
Tasks |
Session token |
P0 |
SB-53 |
|
|
Create a task or preview the allocation (dry run) |
Session token |
P0 |
SB-54 |
|
|
Task, state and planned geometry |
Session token |
P0 |
SB-55.cancel |
|
|
Task control: cancel |
Session token |
P0 |
SB-55.pause |
|
|
Task control: pause |
Session token |
P0 |
SB-55.resume |
|
|
Task control: resume |
Session token |
P0 |
SB-55.start |
|
|
Task control: start |
Session token |
P0 |
SB-56 |
|
|
Continuous (7x24) sustainability assessment |
Session token |
P0 |
SB-57 |
|
|
Allocator snapshot |
Session token |
P0 |
SB-58 |
|
|
Submit an external allocation plan |
Session token |
P0 |
SB-59 |
|
|
Relay statistics |
Session token |
P0 |
SB-68 |
|
|
Asynchronous retrieval after a queued dry run times out |
Session token |
P0 |
Environment and calendar
ID |
Method |
Path |
Description |
Auth |
Priority |
|---|---|---|---|---|---|
SB-60 |
|
|
Environment keyframe (calendar, sun, illuminance band) |
Session token |
P0 |
SB-61 |
|
|
Weather preset (same as call env/preset) |
Session token |
P0 |
SB-62 |
|
|
Simulation calendar (call env/calendar) |
Session token |
P0 |
SB-63 |
|
|
Point query of the environment field |
Session token |
P0 |
Local runtime API endpoints
The table below is generated from packages/contracts/rest/openapi.snapshot.json. These endpoints serve the local shared show (loopback
access); apart from health, readiness and version information they require a token. The public instance serves the viewing-related subset
read-only.
System and health
Method |
Path |
Description |
|---|---|---|
|
|
Fetch missed events |
|
|
Health and build information (public) |
|
|
Liveness probe |
|
|
Readiness probe (simulation, state ring and world) |
|
|
Audit log tail (admin) |
|
|
Effective configuration (secrets masked) |
|
|
Version, protocol and access mode |
|
|
Server performance window aggregate |
|
|
Submit a client performance report |
|
|
Performance reports |
|
|
Performance report |
|
|
Process states |
|
|
Restart a process or reset its breaker (admin) |
Authentication and identity
Method |
Path |
Description |
|---|---|---|
|
|
Issue a single-use confirmation token (bound to action and target, valid 10 s) |
|
|
Internal identity verification (deployment passphrase, rate limited with lockout) |
|
|
Revoke the internal identity token |
|
|
Issue an access token |
|
|
Current principal and role |
Worlds
Method |
Path |
Description |
|---|---|---|
|
|
Geometry query (height, clearance, line of sight, ray hit, path check) |
|
|
Worlds |
|
|
World detail |
Fleet
Method |
Path |
Description |
|---|---|---|
|
|
Fleet capabilities and limits |
|
|
Airframe profiles |
|
|
Airframe profile detail |
|
|
Drones |
|
|
Add a drone |
|
|
Drone detail |
|
|
Remove a drone |
|
|
Inject a fault |
|
|
Clear a fault |
Commands
Method |
Path |
Description |
|---|---|---|
|
|
Commands |
|
|
Issue a command |
|
|
Command state |
|
|
Cancel a command |
Scenarios and missions
Method |
Path |
Description |
|---|---|---|
|
|
Missions |
|
|
Create a mission |
|
|
Preview a mission |
|
|
Retrieve a mission preview |
|
|
Mission detail |
|
|
Mission control (start, pause, resume, cancel) |
|
|
Load state and result of the current scenario |
|
|
Scenarios |
|
|
Scenario detail |
Environment
Method |
Path |
Description |
|---|---|---|
|
|
Apply a weather preset |
|
|
Weather presets |
|
|
Point query of the environment field |
|
|
Set environment parameters |
|
|
Environment state |
|
|
Wind streamlines |
Runs, recordings and bookmarks
Method |
Path |
Description |
|---|---|---|
|
|
Runs |
|
|
Run detail |
|
|
Delete a run |
|
|
Bookmarks |
|
|
Add a bookmark |
|
|
Edit a bookmark |
|
|
Delete a bookmark |
|
|
Run events |
|
|
Keep a run (exempt from quota reclamation) |
|
|
Recording segment file |
Jobs
Method |
Path |
Description |
|---|---|---|
|
|
Jobs |
|
|
Job detail |
|
|
Cancel a job |
|
|
Job log |
|
|
Retry a job |
|
|
Build a world (job) |
Reconstruction
Method |
Path |
Description |
|---|---|---|
|
|
Reconstruction engines |
|
|
Submit a reconstruction job |
Agents
Method |
Path |
Description |
|---|---|---|
|
|
Agent tasks |
|
|
Submit an agent task |
|
|
Agent task detail |
|
|
Assign a task |
|
|
Bid board of a task |
|
|
Cancel an agent task |
|
|
Task evidence and receipts |
|
|
Agents |
|
|
Agent capability manifest |
Realtime protocol
Method |
Path |
Description |
|---|---|---|
|
|
Inspect realtime connections |
|
|
Realtime topic catalog |
Sessions
Method |
Path |
Description |
|---|---|---|
|
|
Current session |
Viewer queue
Method |
Path |
Description |
|---|---|---|
|
|
Take a viewer queue ticket |
|
|
Long-poll the viewer queue state |
|
|
Leave the viewer queue |