List all persisted scenes in the signed-in Open Reality account (newest first). Also reports which scan_ids are NEW since this machine last listed — the account is the sync layer: scans made on the phone or the web appear here. Use scene_card next for anything you want context on.

Upload a local video file (.mp4/.mov/.avi/.mkv/.webm, ≤1 GB) into the account and start a reconstruction job. Returns {job_id, scan_id} immediately (202); follow with workspace_job_wait. The scene appears in workspace_list_scenes when the job is done.

Upload a robot recording (DimOS memory2 .db, ≤2 GB) into the account. Runs the recordings pipeline (recon → odometry-consistency score → QC gate); the scene persists as source="robot_recording" with the QC report under derived/demo/recordings/. Returns {job_id, scan_id}; follow with workspace_job_wait.

Import a local .ply/.spz Gaussian splat as a scene (source="imported_splat", honestly degraded report). ≤64 MiB uploads inline and returns {scan_id, gaussian_count} synchronously; larger files go through the chunked lane and return {job_id, scan_id} to poll with workspace_job_wait. Non-gaussian PLYs are refused (422 not_a_gaussian_splat).

One status read of an ingest/export job (GET /api/workspace/jobs/): {status: queued|running|done|error, stage?, scan_id?, error?}.

Poll an ingest/export job until it is done or errored (or the timeout passes). Returns the final status plus the stage trail observed.

The Tier-1 context card for a scene: source, metric/anchor state, room + summary, closed-world object inventory, ground frame, and workspace artifacts (agent runs, measurements, paths). Small by design — pull details with the other scene tools.

The closed-world object inventory from the persisted record (facts.objects): model query, operator relabel, confidence, world center/extent. These uids/labels are the ONLY objects that exist — never invent others.

Distance between two WORLD-frame points (POST /measure). The response units are "m" ONLY when the scene has a metric anchor — otherwise "relative". ALWAYS report the units and scale_source with the value; never say metres for relative units.

Angle at the vertex (second point) of three WORLD-frame points (POST /measure, kind=angle). Returns degrees.

Plan a path through scanned free space to an object (by uid) or a world point (POST /nav/plan). Provide exactly one of object_uid | point_world. Honest failures: 422 no_geometry / no_floor / unreachable_goal (with a nearest-reachable suggestion). The response provenance line ("not certified navigation") must ride along with any use. The per-frame camera flythrough (poses) is left on disk by default and the waypoint list comes back as an evenly-sampled preview — both counts and the full-trajectory artifact key ride along; artifact_fetch(doc_key) for the whole thing.

Floor + wall plane candidates from the scene geometry (POST /planes; cached per-scene). Used for restyle scoping and understanding room structure.

Read the recorded floor/ceiling frame (GET /ground_frame). If vertical_axis_known is false, the numbers are ABSENT on purpose — say so rather than guessing heights.

(Re)fit the floor plane and write the result onto the scene metrics (POST /ground_frame). dry_run=true computes without persisting.

Metric-anchor calibration (POST /anchor): two picked world points + their real distance in metres. Non-destructive (writes NEW derived/anchor/* artifacts + the derived_latest pointer) and it is what unlocks units:"m" for measure/nav/export. materialize:"job" returns 202 with a job_id to poll via workspace_job_wait.

One capture keyframe as an image (GET /keyframes/). blob_key comes from the scene detail keyframes[] refs. Real capture photos — cite as photo evidence.

Renders of the scene's own splat registered as evidence (GET /synthetic_views). These are NOT photographs — always carry the "synthetic view" provenance when citing.

One synthetic view PNG (a RENDER of the splat, not a photo — say so when citing).

Level-of-detail index status for the scene splat (GET /lod). Always 200 — read status (ready|none|running|error|not_needed).

Spawn the LOD decimation job (POST /lod → 202 {job_id}; 409 lod_job_active when one is already running). Poll with workspace_job_wait.

Status of geometry-derived objects for an imported splat (GET /imported_objects).

Cluster an imported splat's geometry into facts.objects (POST /imported_objects). Labels carry geometry/synthetic-view provenance — confidence 0.0 is honest, not a bug.

SAM-3D-Objects mesh completion for a segmented object (POST /objects//complete → 202 {job_id}, broker-thread lane). Poll with scene_job_wait. Output is GENERATED geometry (honesty envelope in the artifact meta.json).

TRELLIS variant generation for a completed object (POST /objects//variants → 202 {job_id}). Optional body fields pass through (see server docs). GENERATED assets.

SAM-3 click segmentation (POST /segment). Advanced: the body must match the server contract (click point + view selection — see routes_sam3d.py / the OS UI). Provided as a raw passthrough so the full surface stays reachable.

One status read of a broker-thread scene job (SAM-3D completion, variants, view renders). NOTE: these jobs honestly 404 across a broker restart.

Poll a broker-thread scene job until done/error/timeout.

Owner-only read of the share-link access log (GET /share/access): per minted link (access_id) — opened, request count, visits (new visit after 30 min idle), first/last seen, returned (a visit >= 24 h after the first), devices, and the Q&A questions the viewer asked. This is the behavioural evidence for customer discovery (L5 = returned). Match access_id to the person you sent the link to. events:true appends the raw event list.

Mint a read-only, single-scene share token + embed URL (POST /share; default TTL 30 days). Share tokens can NEVER reach the OS feature routes — viewer only.

Start the five-phase scene annotation run (survey → labels → description → dimensions → key features) on the server-side scene agent. 202 {run_id}; one active run per scene (409 agent_run_active carries active_run_id — or set attach_if_active). Costs bounded server-side LLM calls. Follow with agent_run_events wait_for_done.

Re-serve a recorded run's persisted event log as a new (replay-badged, $0) run. Use for reviewing what an earlier run found without spending LLM calls.

Give the pilot agent a free-text instruction (navigate/inspect flows; tools: list_scene_objects, plan_path, measure_distance). 202 {run_id}; poll agent_run_events.

One chat turn with the scene agent (its own bounded run; the server agent may call its scene tools mid-turn). By default waits for the run to finish and returns the event transcript. The agent's numbers carry units/scale_source — repeat them honestly.

Read a run's event log from a cursor (GET /runs//events?after=). With wait_for_done, polls at ~1 Hz (the web client's cadence) until the run finishes.

The scene's run index (newest first) + which run is live: kind, status, cost_usd, llm_calls, findings. Persisted runs can be replayed for $0 with agent_replay.

What an export WOULD contain (GET /demo/export/manifest): file tree + sizes, complete/absent components, and whether the zip route would work. No build, no writes. Formats: openreality | groot_lerobot_v2 | isaac_usd (isaac is metric-gated — needs an anchor).

Build the export zip as a background job (POST /demo/export/prepare → 202 {job_id}; 409 export_job_active when one is running). With wait=true (default) polls the job and returns the prepared artifact (including download_path). Then artifact_fetch it.

What is prepared for scene+format (GET /demo/export/prepared). Always 200 with {status: ready|running|error|none}; ready carries the artifact + download_path.

Download any derived/... artifact (export zips, LOD levels, agent run logs, QC reports, masks) to a local file and return the path — bytes NEVER go into context. Default target: //.

Download the scene's original splat.ply to a local file and return the path. For a render-sized variant prefer the LOD levels (scene_lod → artifact_fetch of a level key).

Download the scene's cloud.ply to a local file and return the path.