Visual map API

These routes are available only in the composed visual pilot. They are not a stable public SDK release. Use the same loopback origin through SSH; sign in with POST /login, retain its HttpOnly session cookie and send the returned CSRF value in X-CSRF-Token on subsequent JSON POSTs. Never embed credentials in connection profiles, URLs, exported artifacts or application source.

An exact reference uses string revisions, avoiding JavaScript integer truncation:

{"project_id":"example","asset_id":"stable-asset-id","revision":"2"}

POST route	Body	Result
/api/maps/import	project_id, command_id, name, unit, base64 geotiff	Published asset and exact revision
/api/maps/scene	reference	Dimensions, range, unit, digest and scientific metadata; no array
/api/maps/frame	reference, optional size, x, y, span	PNG, with X-Asset-Revision
/api/maps/pick	reference, integer x, y	Exact scalar or null and revision
/api/maps/operate	reference, command_id, operator: "scalar-offset/1", numeric delta	New asset revision
/api/maps/snapshot	reference	Base64 GeoTIFF, source text, manifest and reference
/api/maps/watch	project_id, asset_id, after, timeout	Authorized current revision and availability

Use the same command ID and input after an interrupted mutation. IDs are 16–80 alphanumeric/hyphen characters. Reusing an ID for different input is rejected. An operator requires project edit/compute access and source publisher ownership. The current operator supports Workspace imports only; it preserves grid shape, units, nulls and coordinates and records exact input lineage.

Requests are capped at 2.1 MB; import file size is 1.5 MB, one floating-point band, 100,000 cells. Frames are 16–512 pixels square. Watch timeout is 0–20 seconds and may return early on an update. Render coordinates are cell indices; geographic reprojection belongs to a declared representation/host display policy.

Errors include 400 for invalid scientific/request contracts, 401 for an expired session, 403 for denied access, 404 for unavailable resources, 409 for publication conflict, and 503 for bounded capacity or an unavailable backend. Retry transport failures with the same mutation identity; do not turn a conflict into an implicit rebase. Follow clients may reconcile directly with the current head after a reconnect. Notifications never replace authorization or exact snapshot reads.

The Python Pydantic models live in Platform’s services/project_gateway/models.py. QGIS’s standard-library client lives in Connectors’ scalar_maps/qgis_plugin/gateway.py. The integration runbook documents composition and private deployment.