API Reference#

Base path: /api/v1. The OpenAPI schema is served at /openapi.json and the interactive documentation at /docs.

GET /health#

Returns {"healthy": true} when the service is running.

GET /sensors#

Returns all USB cameras (enumerated on each request), ONVIF cameras (from the latest WS-Discovery sweep) and GigE Vision cameras (from the latest Aravis sweep). ONVIF profiles loaded earlier are preserved.

[
  {
    "device_id": "usb-camera-integrated-camera-0",
    "device_name": "Integrated Camera",
    "device_type": "USB",
    "details": {
      "device_path": "/dev/video0",
      "best_capture": {
        "fourcc": "MJPG",
        "width": 1920,
        "height": 1080,
        "fps": 30.0
      }
    }
  },
  {
    "device_id": "network-camera-192.168.1.100-80",
    "device_name": "ONVIF Camera 192.168.1.100",
    "device_type": "NETWORK",
    "details": {
      "ip": "192.168.1.100",
      "port": 80,
      "profiles": [],
      "best_profile": null
    }
  },
  {
    "device_id": "gige-camera-basler-aca1300-30gm-21234567",
    "device_name": "Basler acA1300-30gm",
    "device_type": "GIGE",
    "details": {
      "ip": "192.168.10.20",
      "vendor": "Basler",
      "model": "acA1300-30gm",
      "serial": "21234567",
      "current_capture": {
        "pixel_format": "Mono8",
        "width": 1280,
        "height": 1024,
        "fps": 30.0
      }
    }
  }
]

For GIGE sensors, vendor, model, serial and current_capture are null when the camera could not be opened (for example, because another application controls it).

Code

Description

200

List of sensors (possibly empty)

500

{"message": "..."} – unexpected error

GET /sensors/{sensor_id}#

Returns a single sensor. If the sensor is not cached yet, discovery is refreshed once.

Code

Description

200

Sensor

404

Sensor not found

422

Invalid sensor_id (allowed characters: A-Z a-z 0-9 . _ : -, max. 256)

POST /sensors/{sensor_id}/profiles#

Connects to an ONVIF camera and reads its media profiles.

Request body (username and password up to 256 characters each):

{ "username": "<user>", "password": "<password>" }

Response:

{
  "camera": {
    "device_id": "network-camera-192.168.1.100-80",
    "device_name": "ONVIF Camera 192.168.1.100",
    "device_type": "NETWORK",
    "details": {
      "ip": "192.168.1.100",
      "port": 80,
      "profiles": [
        {
          "name": "MainStream",
          "rtsp_url": "rtsp://192.168.1.100:554/stream1",
          "resolution": "1920x1080",
          "encoding": "H264",
          "framerate": 30,
          "bitrate": 4096
        }
      ],
      "best_profile": {
        "name": "MainStream",
        "rtsp_url": "rtsp://192.168.1.100:554/stream1",
        "resolution": "1920x1080",
        "encoding": "H264",
        "framerate": 30,
        "bitrate": 4096
      }
    }
  }
}

Code

Description

200

Profiles loaded

400

sensor_id is not a valid network camera identifier or camera not discovered

401

Credentials rejected by the camera

404

Camera not reachable

422

Invalid request body

500

Unexpected ONVIF error