HTTP API

The interactive OpenAPI documentation lives at /api/docs and the schema at /api/openapi.json. Request and response models are the Pydantic classes in openworld_radio_twin.models and openworld_radio_twin.batch (API reference). All examples below assume the default loopback address.

Health and catalogs

GET /api/health

Version, API revision, capability flags and whether the Sionna runtime is available.

GET /api/building-sources

auto, global and every registered building source with title, version, attribution and whether it takes part in automatic routing.

GET /api/search?q=<text>

Location search through the configured provider. Returns 502 when the provider is unavailable.

Buildings for browsing

GET /api/buildings?latitude=&longitude=&radius_m=&building_source=

Buildings around a point for display, limited to OWRT_MAX_VIEW_BUILDINGS. The response carries the features, their native or extruded geometry context, warnings and a provenance record with the resolved source, release, counts and limit status. 422 for an invalid source or a source that does not cover the point, 502 for a provider failure or for source geometry that cannot be placed.

Compiled scenes

POST /api/scenes

Body: a SceneRequest with latitude, longitude, radius_m, include_buildings, building_source, include_terrain, material_profile and terrain_resolution_m, the same inputs as owrt.load_scene. Compiles into the shared scene cache, or reuses the directory for identical inputs, and returns a SceneResponse: the scene_id (the cache directory name), whether it was a cache hit, the bounds with WGS84 corners, the persisted buildings and their native geometry, the terrain grid and surface classes, warnings and provenance. 422 for invalid inputs or a source that does not cover the centre, 502 for a provider failure.

GET /api/scenes/{scene_id}

The same payload for a scene already in the cache; 404 when it is not there.

Simulations

POST /api/simulations

Body: a SimulationRequest (Sionna RT lists the engine_config keys). The optional scene_center sets the centre of the compiled square; without it the first transmitter is the centre, which is what dataset generation always uses. Every transmitter must lie inside the square, otherwise the request is rejected with 422.

curl -s http://127.0.0.1:8765/api/simulations \
  -H 'Content-Type: application/json' \
  -d '{
    "engine": "preview",
    "radius_m": 500,
    "resolution_m": 25,
    "include_terrain": false,
    "transmitters": [
      {"position": {"latitude": 52.3762, "longitude": 4.8993, "altitude_m": 25},
       "frequency_ghz": 3.5, "power_dbm": 30, "antenna_pattern": "sector"}
    ]
  }'

The service first compiles or reuses the scene centred on scene_center, exactly as POST /api/scenes would, then runs the solve on the persisted scene assets. The SimulationResponse contains the simulation ID, the selected engine, elapsed time, a coverage grid with the display layers and grid mapping, the buildings and geometry context, warnings, solver details, provenance (including scene_id and scene_cache_hit), the environment context and the full scene payload. Errors: 409 when the Sionna runtime is unavailable, 422 for invalid parameters, 502 for provider failures, 500 when the solve fails.

GET /api/simulations/{id}/raster.png?metric=rss&mask_buildings=true&feather_edges=true

A PNG of one metric (path_gain, rss, sinr, association) rendered from the stored arrays.

GET /api/simulations/{id}/artifacts.zip

The artifact bundle (Exports).

The service keeps the 16 most recent results in memory; older IDs return 404.

Batches

POST /api/batches/plan

Body: a BatchDatasetRequest. Returns the expanded BatchPlan without touching providers.

POST /api/batches?resume=false

Starts generation and returns 202 with a job record. 409 when the dataset exists without resume, when the same dataset is already running, or when Sionna cases are requested without the runtime.

GET /api/batches

All jobs known to this process, newest first.

GET /api/batches/{job_id}

One job: status (queued, running, completed, completed_with_errors, failed), completed and total cases, message, output directory, error.

GET /api/batches/{job_id}/manifest

The dataset manifest once the job has completed.

Python client sketch

import httpx

with httpx.Client(base_url="http://127.0.0.1:8765") as client:
    health = client.get("/api/health").json()
    response = client.post("/api/simulations", json=request, timeout=600).json()
    png = client.get(f"/api/simulations/{response['simulation_id']}/raster.png",
                     params={"metric": "sinr"}).content