Vistralio — API Reference

This is the current runtime API surface for build 0.1.8 (Beta) Build 20260420.1.

The WebUI uses the same endpoints described here.

Conventions

• base URL: https://connect.vistralio.co.uk (primary external entry point) or https://saas.vistralio.co.uk (web UI host)
• auth: Bearer JWT unless otherwise noted
• media auth: short-lived media token accepted on media routes
• tenant context:
  • normal users use their current tenant
  • admins can override with X-Tenant-Id or ?tenant_id=

The interactive API Explorer is available at https://connect.vistralio.co.uk/api/ — authenticated, permission-aware, and lists every endpoint your account can access.

Public / pre-auth endpoints

• POST /api/auth/login
• POST /api/auth/login/2fa
• GET /api/branding
• GET /api/dns/probe

Auth and account

• POST /api/auth/login
  • username/password
  • returns either a normal access token or {requires_2fa, challenge_token}
• POST /api/auth/login/2fa
• GET /api/auth/me
• POST /api/auth/media-token
• PUT /api/auth/me
• GET /api/auth/2fa/status
• POST /api/auth/2fa/setup/start
• POST /api/auth/2fa/setup/enable
• POST /api/auth/2fa/disable
• POST /api/auth/switch-tenant

Devices

Product UI calls these “Devices”, API keeps /api/cameras.

• GET /api/cameras
• POST /api/cameras
• PUT /api/cameras/{camera_id}
• DELETE /api/cameras/{camera_id}
• GET /api/cameras/{camera_id}/config
• POST /api/cameras/{camera_id}/doorbell-press
• POST /api/cameras/add-test-cameras

Device payload highlights:

• device_type
• connection_method
• site_id
• edge_router_id
• paths.detect|live|record
• audio.talk_path|talk_codec
• detection.object_overrides
• zones
• masks
• clear_password
• onvif.clear_password

Streams and media

• GET /api/streams/{camera_id}/detections
• GET /api/streams/{camera_id}/snapshot
• GET /api/streams/internal/{camera_id}/stream-url
• websocket live stream routes are handled by the media service under /api/streams/...

Recording/media routes:

• GET /api/recordings/snapshot/{event_id}
• GET /api/recordings/clip/{event_id}
• GET /api/recordings/crop/{event_id}
• GET /api/recordings/plate-crop/{event_id}
• GET /api/recordings/segments
• GET /api/recordings/segment/{camera_id}/{name}
• POST /api/recordings/export
• GET /api/recordings/export
• GET /api/recordings/export/{id}
• GET /api/recordings/export/{id}/download

Events

• GET /api/events
• GET /api/events/{event_id}
• POST /api/events/{event_id}/ack

Event payloads now include:

• camera_name
• area_name
• device_type
• connection_method
• edge_router_name
• snapshot
• clip
• crop
• plate_crop
• metadata

Schedules

• GET /api/schedules
• POST /api/schedules
• PATCH /api/schedules/{id}
• DELETE /api/schedules/{id}

Schedule payloads support:

• camera_id
• camera_ids
• one_time
• enabled
• note

Users, groups, tenants

• GET /api/users

• GET /api/users/permissions/catalog

• POST /api/users

• PUT /api/users/{id}

• DELETE /api/users/{id}

• GET /api/groups

• POST /api/groups

• PUT /api/groups/{id}

• DELETE /api/groups/{id}

• GET /api/tenants

• POST /api/tenants

• PUT /api/tenants/{id}

• DELETE /api/tenants/{id}

Areas and edge routers

• GET /api/sites

• POST /api/sites

• DELETE /api/sites/{id}

• GET /api/edge-routers

• POST /api/edge-routers

• PUT /api/edge-routers/{id}

• POST /api/edge-routers/{id}/rotate-token

• DELETE /api/edge-routers/{id}

Bridge websocket:

• WS /api/edge/ws

AI registries and event types

• GET /api/faces

• POST /api/faces

• PUT /api/faces/{id}

• DELETE /api/faces/{id}

• GET /api/plates

• POST /api/plates

• PUT /api/plates/{id}

• DELETE /api/plates/{id}

• GET /api/event-types

• POST /api/event-types

• PUT /api/event-types/{id}

• DELETE /api/event-types/{id}

Dashboard and activity

• GET /api/dashboard/layout

• PUT /api/dashboard/layout

• GET /api/dashboard/data

• GET /api/activity

Settings and branding

• GET /api/settings

• PUT /api/settings/{key}

• GET /api/branding

• PUT /api/branding

• POST /api/branding/logo

• POST /api/branding/logo-url

• POST /api/branding/favicon

• POST /api/branding/favicon-url

PTZ

• GET /api/ptz/{camera_id}/info
• POST /api/ptz/{camera_id}/move
• POST /api/ptz/{camera_id}/stop
• GET /api/ptz/{camera_id}/presets
• POST /api/ptz/{camera_id}/preset/{token}

Licensing

• GET /api/licensing/status
• POST /api/licensing/apply
• POST /api/licensing/refresh

System

• GET /api/system/metrics
• GET /api/system/detectors/{detector}/labels
• GET /api/system/docs
• GET /api/system/docs/{doc_path:path}
• GET /api/system/cleanup/scan
• POST /api/system/cleanup/run
• GET /api/system/update/status
• GET /api/system/update/releases
• GET /api/system/update/local-packages
• POST /api/system/update/local-upload
• POST /api/system/update/check
• POST /api/system/update/apply
• POST /api/system/restart
• GET /api/system/services

DNS and hostname management

• GET /api/dns — current web hostname, API hostname, edge WebSocket URL, staging state
• POST /api/dns/set-api-hostname — set the API/Connect hostname directly (no nginx reload; takes effect immediately)
• POST /api/dns/stage — stage a new web UI hostname for dry-run verification
• GET /api/dns/probe — public endpoint; verifies DNS resolves here (used by the staged flow)
• POST /api/dns/promote — push staged → live (must be verified first)

The API hostname (dns.api_hostname) controls edge router enrollment commands and the API Explorer link. The web hostname (dns.current) requires nginx + TLS changes; use scripts/apply-dns.sh after promoting.

Notes

• /api/system/docs powers the in-app documentation browser at Admin -> Advanced -> Documentation
• /api/system/restart is permission-gated by system.restart or settings.admin
• media-serving routes accept short-lived media tokens because browsers cannot attach normal auth headers to every media surface cleanly