Agent REST API

​

Base URL

http://<node>:8080

​

Authentication

curl http://localhost:8080/api/status \
  -H "X-ADOS-Key: $KEY"

• Public routes. A few routes answer without a key so an unpaired node can be found and paired: /api/pairing/info, /api/pairing/claim, /api/pairing/code, /api/ping, /api/version, /healthz and the dashboard PIN routes. The full list is in Public routes.
• The unpaired gate. While a node is unpaired, its data routes answer on-box callers and the first-boot lifelines (link-local, the node’s own hotspot at 192.168.4.1 and USB tether at 192.168.7.1), require a dashboard PIN session from other callers on the operator LAN, and refuse remote callers. The pairing claim is refused to remote callers.
• Dashboard PIN session. The browser dashboard exchanges its PIN at POST /api/dashboard/pin/verify and then sends the session in the x-ados-dashboard-session header instead of a key. The dashboard PIN itself is covered on Agent dashboard overview.

​

Conventions

• JSON. Requests and responses are JSON unless a route says otherwise (for example GET /api/video/snapshot returns image/jpeg).
• Armed guard. Actions that can drop the link or change how the vehicle flies (reboot, supervisor restart, link-carrying unit restarts, radio hop, TX power and unpair, profile or role changes, signing enrolment, parameter writes, extension install and lifecycle) answer 409 while the vehicle is armed:
  {"error": "E_ARMED", "message": "Vehicle is armed", "override": "force"}
  
  Override with "force": true in the JSON body, or ?force=1 on a bodiless request.
• Residual routes. A residual prefix answers 501 rather than 404 on a profile that does not run that feature.
• Relay-forbidden routes. Pairing, unpair, MCP token, dashboard PIN set, signing disable and some setup routes refuse requests that arrive through a ground station’s relay proxy. Call them on the node’s own network.
• Extension errors. The extension lifecycle routes use one envelope: {"ok": false, "code": N, "kind": "...", "detail": "..."}.

​

Route domains

​

Examples

​

Status

curl http://localhost:8080/api/status \
  -H "X-ADOS-Key: $KEY"

# Everything the dashboard needs in one request
curl http://localhost:8080/api/status/full \
  -H "X-ADOS-Key: $KEY"

​

Configuration

curl http://localhost:8080/api/config \
  -H "X-ADOS-Key: $KEY"

curl -X PUT http://localhost:8080/api/config \
  -H "X-ADOS-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "video.camera.fps", "value": 25}'

​

Video snapshot

curl -o snap.jpg -H "X-ADOS-Key: $KEY" \
  http://localhost:8080/api/video/snapshot

​

WFB-ng link and parameters

curl http://localhost:8080/api/wfb -H "X-ADOS-Key: $KEY"
curl http://localhost:8080/api/params/RC1_MIN -H "X-ADOS-Key: $KEY"

​

Pairing

# No key needed
curl http://localhost:8080/api/pairing/info

curl -X POST http://localhost:8080/api/pairing/unpair \
  -H "X-ADOS-Key: $KEY"

​

Ground station

curl http://localhost:8080/api/v1/ground-station/status \
  -H "X-ADOS-Key: $KEY"

curl -X POST http://localhost:8080/api/v1/ground-station/pic/heartbeat \
  -H "X-ADOS-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"client_id": "gcs-session-1"}'

​

Extension HTTP passthrough

curl -s -H "X-ADOS-Key: $KEY" \
  http://localhost:8080/api/plugins/com.altnautica.world-engine/x/atlas/readiness

​

Video attention profile

curl -s -X POST http://localhost:8080/api/video/profile \
  -H "X-ADOS-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile": "hero", "holder": "gcs-1", "lease_s": 30}'

​

CORS

security:
  api:
    cors_enabled: true
    cors_origins_extra: ["https://gcs.example.com"]

​

Machine-readable surfaces

• GET /api/config/schema for the build-time-embedded shape of the config surface, to drive a settings UI.
• docs/api-surface.md in the agent repository, the generated table of every route and the process that serves it. The route reference below mirrors it.
• ados logs status --openapi for the OpenAPI document of the Black Box query API.

​

Route reference

​

Public routes

​

Native routes

​

Residual routes

​

Next steps