Query API
84 pages.
| Name | Summary |
|---|---|
| GET /contacts | |
| GET /entities | Still a bare array however it is narrowed; how many matched and where the next page starts are the x-argus-total and x-argus-next-cursor headers. |
| GET /entity/{id} | |
| GET /environment | The sky as it resolved, for an agent that wants to know what it is looking at before it decides whether to change it. |
| GET /events | |
| GET /feel | What an agent that cannot look or listen needs to judge how the game feels: animator state and pose, whether the camera's near plane is inside a collider, whether the player is in view, sounds started and animator names that resolved to nothing. |
| GET /frame.png | The cached frame, or ?fresh=1 for one rendered now. |
| GET /input | Where a press goes. |
| GET /navmesh | GET /navmesh — ?bounds= and ?limit= window it; see crate::types::NavMeshQuery. |
| GET /perf | |
| GET /snapshot | |
| GET /state | The committed state this server is serving, and what it will take on. |
| GET /trace | The body is the frozen Vec<FrameDelta>. |
| GET /ui | An exact read, like GET /entities: it takes ?at= and reports the state it answered at, so an agent that pressed something, waited for the stamp, and then read the tree is looking at the tick it thinks it is. |
| GET /ui/schema | The machine-readable support table (§3). |
| GET /ui/stats | The UI's cost on the last frame (time, draw calls, quads, texts) and, per screen, layout passes and what last dirtied layout. |
| POST /capture | |
| POST /entity/{id}/teleport | Move one entity outright: the same path as a behaviour's ctx.entity.teleport, answered after the move is published. |
| POST /environment | A partial sky merged onto the live one. |
| POST /input | |
| POST /path | |
| POST /raycast | One ray { from, dir, … }, or several under { "rays": [...] }. |
| POST /scene | Switch the running world to another scene of the project. |
| POST /snapshot | Put the world back into a previously captured state. |
| POST /step | : inputs, ticks and an entity read in one call. |
| POST /time |
GET /
Since 0.6
What this server answers, for an agent that arrives without the docs.
Example
curl "http://127.0.0.1:7700/"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /camera/project
Since 0.7
A world point (or an entity's position) as a pixel of a view's cell.
Example
curl "http://127.0.0.1:7700/camera/project"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /camera/ray
Since 0.7
The world ray through a pixel of a view's cell.
Example
curl "http://127.0.0.1:7700/camera/ray"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /cameras
Since next
The scene's cameras.
Example
curl "http://127.0.0.1:7700/cameras"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /character/{id}
Since next
What the engine measured about one animated character: rig, clips, colliders, advice.
Path parameters
| Name | Type | Description |
|---|---|---|
id | string | Taken from the path: id. |
Example
curl "http://127.0.0.1:7700/character/<id>"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /desync
Since next
The last desync report (C1-DESIGN r2 §4).
Example
curl "http://127.0.0.1:7700/desync"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /desync/dump
Since next
One system's state for one entity, as its hash covers it.
Example
curl "http://127.0.0.1:7700/desync/dump"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /desync/record
Since next
The per-system state hashes this run has recorded (netcode C1's desync finder).
Example
curl "http://127.0.0.1:7700/desync/record"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /frame
Since 0.6
A bare JSON number, exactly as the SPEC table writes it.
Response
Response: FrameIndex
GET /frame — the current frame index.
| Field | Type | Present | Description |
|---|
Example
curl "http://127.0.0.1:7700/frame"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /fx
Since next
Every live effect instance: its effect, class, state (active, held off and why, finished), distance and live count, with the quality tier and how the GPU budget stands (docs/VFX.md, Effect classes).
Example
curl "http://127.0.0.1:7700/fx"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /journal
Since next
The session journal's entries.
Request
Query parameters
| Parameter | Shape | Meaning |
|---|---|---|
from_tick, to_tick | integer | only entries in [from_tick, to_tick) |
kind | string | only this kind; a trailing * matches a prefix (hazard.*) |
entity | string | only entries naming this entity, in any role |
after_seq | integer | only entries with a journal seq above this: the polling cursor |
limit | integer | at most this many, keeping the most recent |
Example
curl "http://127.0.0.1:7700/journal"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /journal/kinds
Since next
The kinds declared (the instructor's palette with ?injectable=true).
Request
Query parameters
| Parameter | Shape | Meaning |
|---|---|---|
from_tick, to_tick | integer | only entries in [from_tick, to_tick) |
kind | string | only this kind; a trailing * matches a prefix (hazard.*) |
entity | string | only entries naming this entity, in any role |
after_seq | integer | only entries with a journal seq above this: the polling cursor |
limit | integer | at most this many, keeping the most recent |
Example
curl "http://127.0.0.1:7700/journal/kinds"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /metrics
Since next
Every metric now.
Example
curl "http://127.0.0.1:7700/metrics"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /metrics/{id}/series
Since next
One metric over time.
Path parameters
| Name | Type | Description |
|---|---|---|
id | string | Taken from the path: id. |
Example
curl "http://127.0.0.1:7700/metrics/<id>/series"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /npc/log
Since 0.7
The last decisions of one NPC, oldest first.
400 without id; 404 when id is not an NPC of the running scene.
Example
curl "http://127.0.0.1:7700/npc/log"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /npc/pending
Since 0.7
The script commands (npc.damaged, npc.talk, npc.reputation...) and stimuli queued for the NPCs' next tick, in the order they were raised (lane rule 35: the queue is visible).
Example
curl "http://127.0.0.1:7700/npc/pending"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /plugins
Since next
The running project's plugins (docs/PLUGINS.md): each one's id, name, version, capabilities, page and files.
A page served under /plugins/<id>/ may call this server (loopback's same-origin rule).
Example
curl "http://127.0.0.1:7700/plugins"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /plugins/{id}/
Since next
A plugin's web app: its index.html.
Path parameters
| Name | Type | Description |
|---|---|---|
id | string | Taken from the path: id. |
Example
curl "http://127.0.0.1:7700/plugins/<id>/"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /plugins/{id}/files
Since next
The project files the plugin's own files rules name, [{path, bytes}], read-only.
Path parameters
| Name | Type | Description |
|---|---|---|
id | string | Taken from the path: id. |
Example
curl "http://127.0.0.1:7700/plugins/<id>/files"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /plugins/{id}/files/{*path}
Since next
One project file the plugin's files rules name; 404 for anything else.
Path parameters
| Name | Type | Description |
|---|---|---|
id | string | Taken from the path: id. |
Example
curl "http://127.0.0.1:7700/plugins/<id>/files/{*path}"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /plugins/{id}/status
Since next
What a plugin's compiled-in part last reported (DIS: entities published and heard, PDUs sent and received, the last error), refreshed every half second of sim time.
Path parameters
| Name | Type | Description |
|---|---|---|
id | string | Taken from the path: id. |
Example
curl "http://127.0.0.1:7700/plugins/<id>/status"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /plugins/{id}/{*path}
Since next
A file of a plugin's web app, with its media type; nothing outside the plugin's web folder.
Path parameters
| Name | Type | Description |
|---|---|---|
id | string | Taken from the path: id. |
Example
curl "http://127.0.0.1:7700/plugins/<id>/{*path}"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /profile
Since 0.6
Whether the flight recorder is on, how full its ring is, and what captures are on disk.
Example
curl "http://127.0.0.1:7700/profile"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /profile/capture/{id}
Since 0.6
One saved capture's header and shape.
Path parameters
| Name | Type | Description |
|---|---|---|
id | string | Taken from the path: id. |
Example
curl "http://127.0.0.1:7700/profile/capture/<id>"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /profile/captures
Since 0.6
The saved captures on disk, newest first.
Example
curl "http://127.0.0.1:7700/profile/captures"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /profile/frames
Since 0.6
One row per recent frame (cost, phases, spike flag): what the frame-time strip draws.
Example
curl "http://127.0.0.1:7700/profile/frames"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /profile/trace
Since 0.6
Chrome trace JSON of the ring or of a saved capture, for ui.perfetto.dev.
Example
curl "http://127.0.0.1:7700/profile/trace"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /recording
Since next
The recording being written or reviewed.
Example
curl "http://127.0.0.1:7700/recording"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /recording/ext
Since next
A recording's plugin lines.
Example
curl "http://127.0.0.1:7700/recording/ext"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /recording/file
Since next
The recording's bytes, to save.
Example
curl "http://127.0.0.1:7700/recording/file"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /recordings
Since next
The recordings beside it.
Example
curl "http://127.0.0.1:7700/recordings"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /roads
Since 0.7
Each road entity's centre line, width and gates, in world space.
Example
curl "http://127.0.0.1:7700/roads"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /save
Since 0.7
Every key of the running game's ctx.save store.
Example
curl "http://127.0.0.1:7700/save"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /schema
Since 0.6
The names of every response schema.
Example
curl "http://127.0.0.1:7700/schema"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /schema/{name}
Since 0.6
One JSON Schema, draft 2020-12.
Path parameters
| Name | Type | Description |
|---|---|---|
name | string | Taken from the path: name. |
Example
curl "http://127.0.0.1:7700/schema/<name>"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /session/control
Since next
The clock, the queue and the clients.
Example
curl "http://127.0.0.1:7700/session/control"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /stream
Since 0.6
Example
curl "http://127.0.0.1:7700/stream"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /timeline
Since next
The review's playhead and markers.
Example
curl "http://127.0.0.1:7700/timeline"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
GET /ui/screens
Since 0.6
Example
curl "http://127.0.0.1:7700/ui/screens"Start a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
POST /desync
Since next
Turn the hashing on or off.
Example
curl -X POST "http://127.0.0.1:7700/desync" --json @body.jsonStart a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
POST /desync/compare
Since next
Another run's hashes against this one's.
Example
curl -X POST "http://127.0.0.1:7700/desync/compare" --json @body.jsonStart a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
POST /profile/capture
Since 0.6
Save the last few seconds of the ring now; an optional {"reason": "..."} body names it.
Example
curl -X POST "http://127.0.0.1:7700/profile/capture" --json @body.jsonStart a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
POST /recording/ext
Since next
Writes a plugin line into the recording.
Example
curl -X POST "http://127.0.0.1:7700/recording/ext" --json @body.jsonStart a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
POST /save
Since 0.7
Set and remove keys of the running game's ctx.save store.
Example
curl -X POST "http://127.0.0.1:7700/save" --json @body.jsonStart a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
POST /session/camera
Since next
The view, presentation only.
Example
curl -X POST "http://127.0.0.1:7700/session/camera" --json @body.jsonStart a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
POST /session/clients
Since next
Registers a client.
Example
curl -X POST "http://127.0.0.1:7700/session/clients" --json @body.jsonStart a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
POST /session/command
Since next
One session command.
Example
curl -X POST "http://127.0.0.1:7700/session/command" --json @body.jsonStart a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
POST /timeline
Since next
Load, seek, play, pause, step, loop.
Example
curl -X POST "http://127.0.0.1:7700/timeline" --json @body.jsonStart a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
POST /timeline/branch
Since next
Go live from the review's tick.
Example
curl -X POST "http://127.0.0.1:7700/timeline/branch" --json @body.jsonStart a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
POST /ui/activate
Since 0.6
Press a node by id.
Example
curl -X POST "http://127.0.0.1:7700/ui/activate" --json @body.jsonStart a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
POST /ui/focus
Since 0.6
Move focus by id or by direction.
Example
curl -X POST "http://127.0.0.1:7700/ui/focus" --json @body.jsonStart a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
POST /ui/input
Since 0.6
Pointer, key and nav events in UI logical pixels.
Example
curl -X POST "http://127.0.0.1:7700/ui/input" --json @body.jsonStart a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
POST /ui/locale
Since 0.6
Force a locale for a screenshot matrix.
Example
curl -X POST "http://127.0.0.1:7700/ui/locale" --json @body.jsonStart a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
POST /ui/pop
Since 0.6
Pop the top screen.
Takes no body at all, so a caller need not send {}; anything sent is ignored, which is the one place in this API where that is true and is the difference between a one-line curl and a puzzle.
Example
curl -X POST "http://127.0.0.1:7700/ui/pop" --json @body.jsonStart a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
POST /ui/push
Since 0.6
Put a registered screen on the stack.
Example
curl -X POST "http://127.0.0.1:7700/ui/push" --json @body.jsonStart a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
POST /ui/scale
Since 0.6
Force the player's UI-scale setting for a screenshot matrix.
Example
curl -X POST "http://127.0.0.1:7700/ui/scale" --json @body.jsonStart a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
POST /ui/theme
Since 0.6
Force a theme for a screenshot matrix.
Example
curl -X POST "http://127.0.0.1:7700/ui/theme" --json @body.jsonStart a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.
POST /ui/viewport
Since 0.6
Put the surface at a size and lay the UI out at it.
The resolution axis of docs/PLAN-UI.md §3's matrix, over one engine. See UiViewportRequest for why it needs capture rather than input.
Example
curl -X POST "http://127.0.0.1:7700/ui/viewport" --json @body.jsonStart a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.