Open interface

ANet4D exposes two HTTP interfaces and one realtime protocol:

Interface

Prefix

Served by

For

Sandbox REST v1

/api/sandbox/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

api (8000 locally)

Operators and administrators of the local shared show: worlds, fleet, commands, scenarios, runs and system

Realtime protocol awr.rt.v1

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

meta, worlds, templates, capacity, airframe and sensor catalogs, challenge and similar

No credentials, cacheable

Session token

/sessions/{sid}/...

Issued when the session is created, Authorization: Bearer v1.<payload>.<sig>, valid for that sid only; reissued on renewal

Queue ticket

/queue/{ticket_id}...

Issued on entering the queue, Authorization: Bearer q1.<...>, for the queue endpoints only

Token in body

end-beacon, park-beacon

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 runs/<run>/admin.token (0600) and exchanged for an access token through POST /api/auth/token

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

code, name

Reason code and name, for example 110 PARAM_OUT_OF_RANGE, 506 SANDBOX_GONE, 525 NEST_INCOMPATIBLE, 581 NO_FEASIBLE_STATION, 585 PLAN_INPUT_TOO_LARGE

message

Human-readable description (the server answers in Chinese; this example reads "token missing")

detail

Structured details, for example `{"field": "nest_id

remedy

Suggested action (here "issue a token first")

retry_after_ms

Precise wait in milliseconds when rate limited; the Retry-After header carries whole seconds

request_id

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.

Snapshot: AWR sandbox REST v1, contracts 1.3.0, 82 operations. Source: packages/contracts/rest/sandbox.openapi.snapshot.json. Path prefix: /api/sandbox/v1.

Sessions, queue and lifecycle

ID

Method

Path

Description

Auth

Priority

SB-00

GET

/meta

API version, contract version, access mode, session and queue overview

Public

P0

SB-01

GET

/worlds

Availability and admission of the seven worlds

Public

P0

SB-02

GET

/templates

Scenario templates

Public

P0

SB-03

GET

/challenge

Fetch a proof-of-work challenge

Public

P0

SB-04

POST

/sessions

Create, queue or idempotently return a session

Public

P0

SB-05

GET

/queue/{ticket_id}

Long-poll the queue state

Queue ticket

P0

SB-06

POST

/queue/{ticket_id}/claim

Claim an offered slot

Queue ticket

P0

SB-07

DELETE

/queue/{ticket_id}

Leave the queue

Queue ticket

P0

SB-08

GET

/sessions/{sid}

Session object (optionally long-polls to a given state)

Session token

P0

SB-09

DELETE

/sessions/{sid}

End the session

Session token

P0

SB-10

POST

/sessions/{sid}/keepalive

Renew and reissue the token

Session token

P0

SB-11

GET

/sessions/{sid}/snapshot

Export a configuration snapshot (available for 10 min after the end)

Session token

P0

SB-12

POST

/sessions/{sid}/restore

Import a configuration snapshot (same world)

Session token

P0

SB-13

POST

/sessions/{sid}/template

Load a scenario template

Session token

P0

SB-14

POST

/sessions/{sid}/world

Switch the base world

Session token

P0

SB-15

POST

/sessions/{sid}/clock

Play, pause, rate (through the governor), single step

Session token

P0

SB-16

GET

/sessions/{sid}/events

Fetch missed events

Session token

P0

SB-17

POST

/sessions/{sid}/end-beacon

End the session when the page closes (token in body)

Token in body

P1

SB-18

POST

/sessions/{sid}/batch

Batch evaluation (local and LAN; 404 on the public site)

Session token

P0

SB-19

GET

/sessions/{sid}/batch/{batch_id}

Batch progress and result

Session token

P0

SB-69

POST

/sessions/{sid}/park

Power-save parking (checkpoint to disk, release the slot)

Session token

P0

SB-70

POST

/sessions/{sid}/resume

Resume from parking (resume ticket when full)

Session token

P0

SB-71

GET

/capacity

Public capacity (visible during loading and queueing)

Public

P0

SB-72

POST

/sessions/{sid}/park-beacon

Park beacon (pagehide, token in body)

Token in body

P0

SB-76

POST

/sessions/{sid}/pair-code

Commander pairing code (P1)

Session token

P1

SB-77

POST

/sessions/{sid}/pair

Join the same sandbox with a pairing code (P1)

Public

P1

API document and realtime connection

ID

Method

Path

Description

Auth

Priority

SB-20

GET

/openapi.json

Sandbox OpenAPI 3.1

Public

P0

SB-64

GET

/sessions/{sid}/rt

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

GET

/catalog/models

Airframe catalog (presets)

Public

P0

SB-22

GET

/catalog/models/{model_id}

Full airframe parameters, parameter table and derived quantities

Public

P0

SB-23

GET

/catalog/sensors

Sensor catalog

Public

P0

SB-24

GET

/sessions/{sid}/models

Airframes cloned in this session

Session token

P0

SB-25

POST

/sessions/{sid}/models

Clone and edit an airframe

Session token

P0

SB-26

PATCH

/sessions/{sid}/models/{model_id}

Modify a cloned airframe

Session token

P0

SB-27

DELETE

/sessions/{sid}/models/{model_id}

Delete a cloned airframe

Session token

P0

Fleet and commands

ID

Method

Path

Description

Auth

Priority

SB-28

GET

/sessions/{sid}/vehicles

Fleet instances

Session token

P0

SB-29

POST

/sessions/{sid}/vehicles

Add a drone

Session token

P0

SB-30

GET

/sessions/{sid}/vehicles/{vid}

Instance and state snapshot

Session token

P0

SB-31

PATCH

/sessions/{sid}/vehicles/{vid}

Modify label, nest, payload or limit profile

Session token

P0

SB-32

DELETE

/sessions/{sid}/vehicles/{vid}

Remove

Session token

P0

SB-33

GET

/sessions/{sid}/vehicles/{vid}/state

Full state

Session token

P0

SB-34

GET

/sessions/{sid}/vehicles/{vid}/sensors

Payload, specifications, working state, gimbal and zoom

Session token

P0

SB-35

POST

/sessions/{sid}/vehicles/{vid}/commands

Issue a command (same as the WebSocket call)

Session token

P0

SB-36

POST

/sessions/{sid}/vehicles/{vid}:acquire

Acquire a lease

Session token

P0

SB-37

POST

/sessions/{sid}/vehicles/{vid}:release

Release a lease

Session token

P0

Targets

ID

Method

Path

Description

Auth

Priority

SB-40

GET

/sessions/{sid}/targets

Targets

Session token

P0

SB-41

POST

/sessions/{sid}/targets

Add a target

Session token

P0

SB-42

GET

/sessions/{sid}/targets/{id}

Full target configuration

Session token

P0

SB-43

PATCH

/sessions/{sid}/targets/{id}

Modify a target (JSON Merge Patch)

Session token

P0

SB-44

DELETE

/sessions/{sid}/targets/{id}

Delete a target

Session token

P0

SB-45

GET

/sessions/{sid}/targets/{id}/state

Perception state, effective sensitivity volume, counters, acoustic phase

Session token

P0

SB-46

GET

/sessions/{sid}/targets/{id}/suggested_radius

Suggested radius from the physical model

Session token

P0

SB-65

GET

/target_classes

Target class templates

Public

P1

Perception

ID

Method

Path

Description

Auth

Priority

SB-38

GET

/sessions/{sid}/vehicles/{vid}/perception

Current perception result

Session token

P0

SB-39

GET

/sessions/{sid}/detections

Fetch detection history

Session token

P0

SB-66

GET

/sessions/{sid}/tracks

Target tracks (ground truth not exposed)

Session token

P1

SB-67

POST

/sessions/{sid}/perception/feasibility

Server-side feasibility window query

Session token

P1

SB-73

GET

/sessions/{sid}/perception/quant

Per-pair perception readings

Session token

P0

SB-74

GET

/sessions/{sid}/perception/field/{kind}

Emission field profile

Session token

P0

SB-75

GET

/sessions/{sid}/perception/volumes

Target perception volumes

Session token

P0

SB-78

POST

/sessions/{sid}/perception/field/{kind}/samples

Explicit sample points of a field (cross-check)

Session token

P1

Tasks, nests and relay

ID

Method

Path

Description

Auth

Priority

SB-47

GET

/sessions/{sid}/nests

Nests

Session token

P0

SB-48

POST

/sessions/{sid}/nests

Add a nest (optionally with drones inside)

Session token

P0

SB-49

GET

/sessions/{sid}/nests/{id}

Nest configuration and state

Session token

P0

SB-50

PATCH

/sessions/{sid}/nests/{id}

Modify a nest

Session token

P0

SB-51

DELETE

/sessions/{sid}/nests/{id}

Delete a nest

Session token

P0

SB-52

GET

/sessions/{sid}/tasks

Tasks

Session token

P0

SB-53

POST

/sessions/{sid}/tasks

Create a task or preview the allocation (dry run)

Session token

P0

SB-54

GET

/sessions/{sid}/tasks/{tid}

Task, state and planned geometry

Session token

P0

SB-55.cancel

POST

/sessions/{sid}/tasks/{tid}:cancel

Task control: cancel

Session token

P0

SB-55.pause

POST

/sessions/{sid}/tasks/{tid}:pause

Task control: pause

Session token

P0

SB-55.resume

POST

/sessions/{sid}/tasks/{tid}:resume

Task control: resume

Session token

P0

SB-55.start

POST

/sessions/{sid}/tasks/{tid}:start

Task control: start

Session token

P0

SB-56

GET

/sessions/{sid}/tasks/{tid}/sustainability

Continuous (7x24) sustainability assessment

Session token

P0

SB-57

GET

/sessions/{sid}/tasking/snapshot

Allocator snapshot

Session token

P0

SB-58

POST

/sessions/{sid}/tasking/plans

Submit an external allocation plan

Session token

P0

SB-59

GET

/sessions/{sid}/relay/{tid}/stats

Relay statistics

Session token

P0

SB-68

GET

/sessions/{sid}/tasks/previews/{preview_id}

Asynchronous retrieval after a queued dry run times out

Session token

P0

Environment and calendar

ID

Method

Path

Description

Auth

Priority

SB-60

GET

/sessions/{sid}/env/state

Environment keyframe (calendar, sun, illuminance band)

Session token

P0

SB-61

POST

/sessions/{sid}/env/preset

Weather preset (same as call env/preset)

Session token

P0

SB-62

POST

/sessions/{sid}/env/calendar

Simulation calendar (call env/calendar)

Session token

P0

SB-63

POST

/sessions/{sid}/env/query

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.

Snapshot: ANet4D World Runtime API v1, 82 operations. Source: packages/contracts/rest/openapi.snapshot.json.

System and health

Method

Path

Description

GET

/api/events

Fetch missed events

GET

/api/health

Health and build information (public)

GET

/api/health/live

Liveness probe

GET

/api/health/ready

Readiness probe (simulation, state ring and world)

GET

/api/sys/audit

Audit log tail (admin)

GET

/api/sys/config

Effective configuration (secrets masked)

GET

/api/sys/info

Version, protocol and access mode

GET

/api/sys/perf

Server performance window aggregate

POST

/api/sys/perf-report

Submit a client performance report

GET

/api/sys/perf-reports

Performance reports

GET

/api/sys/perf-reports/{rid}

Performance report

GET

/api/sys/procs

Process states

POST

/api/sys/restart

Restart a process or reset its breaker (admin)

Authentication and identity

Method

Path

Description

POST

/api/auth/confirm

Issue a single-use confirmation token (bound to action and target, valid 10 s)

POST

/api/auth/identity

Internal identity verification (deployment passphrase, rate limited with lockout)

DELETE

/api/auth/identity

Revoke the internal identity token

POST

/api/auth/token

Issue an access token

GET

/api/auth/whoami

Current principal and role

Worlds

Method

Path

Description

POST

/api/world/{world_id}/query

Geometry query (height, clearance, line of sight, ray hit, path check)

GET

/api/worlds

Worlds

GET

/api/worlds/{world_id}

World detail

Fleet

Method

Path

Description

GET

/api/fleet/caps

Fleet capabilities and limits

GET

/api/fleet/profiles

Airframe profiles

GET

/api/fleet/profiles/{profile_id}

Airframe profile detail

GET

/api/fleet/vehicles

Drones

POST

/api/fleet/vehicles

Add a drone

GET

/api/fleet/vehicles/{vid}

Drone detail

DELETE

/api/fleet/vehicles/{vid}

Remove a drone

POST

/api/fleet/vehicles/{vid}/faults

Inject a fault

DELETE

/api/fleet/vehicles/{vid}/faults/{fault_id}

Clear a fault

Commands

Method

Path

Description

GET

/api/commands

Commands

POST

/api/commands

Issue a command

GET

/api/commands/{cid}

Command state

POST

/api/commands/{cid}/cancel

Cancel a command

Scenarios and missions

Method

Path

Description

GET

/api/missions

Missions

POST

/api/missions

Create a mission

POST

/api/missions/preview

Preview a mission

GET

/api/missions/preview/{preview_id}

Retrieve a mission preview

GET

/api/missions/{mid}

Mission detail

POST

/api/missions/{mid}/{op}

Mission control (start, pause, resume, cancel)

GET

/api/scenario

Load state and result of the current scenario

GET

/api/scenarios

Scenarios

GET

/api/scenarios/{sid}

Scenario detail

Environment

Method

Path

Description

POST

/api/env/preset

Apply a weather preset

GET

/api/env/presets

Weather presets

POST

/api/env/query

Point query of the environment field

POST

/api/env/set

Set environment parameters

GET

/api/env/state

Environment state

GET

/api/env/streamlines/{lib}/{name}

Wind streamlines

Runs, recordings and bookmarks

Method

Path

Description

GET

/api/runs

Runs

GET

/api/runs/{run}

Run detail

DELETE

/api/runs/{run}

Delete a run

GET

/api/runs/{run}/bookmarks

Bookmarks

POST

/api/runs/{run}/bookmarks

Add a bookmark

PATCH

/api/runs/{run}/bookmarks/{bid}

Edit a bookmark

DELETE

/api/runs/{run}/bookmarks/{bid}

Delete a bookmark

GET

/api/runs/{run}/events

Run events

POST

/api/runs/{run}/keep

Keep a run (exempt from quota reclamation)

GET

/api/runs/{run}/segments/{name}

Recording segment file

Jobs

Method

Path

Description

GET

/api/jobs

Jobs

GET

/api/jobs/{job_id}

Job detail

POST

/api/jobs/{job_id}/cancel

Cancel a job

GET

/api/jobs/{job_id}/log

Job log

POST

/api/jobs/{job_id}/retry

Retry a job

POST

/api/worlds/{world_id}/build

Build a world (job)

Reconstruction

Method

Path

Description

GET

/api/recon/engines

Reconstruction engines

POST

/api/recon/jobs

Submit a reconstruction job

Agents

Method

Path

Description

GET

/api/agent-tasks

Agent tasks

POST

/api/agent-tasks

Submit an agent task

GET

/api/agent-tasks/{task_id}

Agent task detail

POST

/api/agent-tasks/{task_id}/assign

Assign a task

GET

/api/agent-tasks/{task_id}/board

Bid board of a task

POST

/api/agent-tasks/{task_id}/cancel

Cancel an agent task

GET

/api/agent-tasks/{task_id}/evidence

Task evidence and receipts

GET

/api/agents

Agents

GET

/api/agents/{aid}/manifest

Agent capability manifest

Realtime protocol

Method

Path

Description

GET

/api/rt/inspect

Inspect realtime connections

GET

/api/rt/topics

Realtime topic catalog

Sessions

Method

Path

Description

GET

/api/sessions/current

Current session

Viewer queue

Method

Path

Description

POST

/api/viewer/queue

Take a viewer queue ticket

GET

/api/viewer/queue/{ticket_id}

Long-poll the viewer queue state

DELETE

/api/viewer/queue/{ticket_id}

Leave the viewer queue