API Reference#

Base URL: http://127.0.0.1:8082 (default). Scene Understanding Service endpoints are served under the /api/v1/sus prefix and return JSON.

GET /health#

Liveness probe.

Response:

{"status": "healthy"}

GET /api/v1/sus/status#

Service readiness and runtime statistics (active sessions, resolved zones, connection state).

curl --noproxy '*' http://127.0.0.1:8082/api/v1/sus/status

Sessions#

GET /api/v1/sus/sessions#

Return active person sessions with a per-zone visit summary. By default, only sessions whose Scenescape re-id state has progressed beyond initial collection are returned. Pass ?include_pending=true to include transient tracks.

Query

Default

Description

include_pending

false

Include pending_collection tracks.

GET /api/v1/sus/sessions/count#

Count of active sessions.

GET /api/v1/sus/sessions/{object_id}#

Detail for a single person session.

Query

Default

Description

scene_id

(any)

Restrict to a specific scene UUID.

Zones#

GET /api/v1/sus/zones#

All resolved zones (region UUID → type mapping).

GET /api/v1/sus/zones/names#

Zone name → type mapping as defined in scene-config.yaml.

PUT /api/v1/sus/zones/{region_id}#

Manually register or update a zone mapping at runtime.

DELETE /api/v1/sus/zones/{region_id}#

Remove a zone mapping.

POST /api/v1/sus/zones/discover#

Trigger zone re-discovery from the Scenescape REST API.

Alerts#

GET /api/v1/sus/alerts#

Recent alerts, proxied from the alert-service.

Query

Default

Description

alert_type

(all)

Filter by alert type.

object_id

(all)

Filter by person object_id.

limit

50

Max results (1–500).

GET /api/v1/sus/alerts/count#

Total alert count.

The alert endpoints require a reachable alert-service. When alerting is disabled or the alert-service is unavailable, these return empty results.

Supporting Resources#